SerialSession (v2) overview

This page is the mental model for the v2 public API: what each SerialSession surface does, how SerialSessionState maps to state$, and how to choose between receive$ and lines$. For options, error codes, and formal type details, see API Reference.

Table of Contents

• Features
• Framework support
• SerialSession (v2) at a glance
• Documentation index

Features

• Session-oriented reactive API: a single SerialSession exposes state$, isConnected$, receive$, lines$, errors$, plus connect$, disconnect$, and send$
• UTF-8 text stream: receive$ is already decoded with a streaming TextDecoder, so multi-byte characters split across chunks are joined correctly
• Ordered send queue: concurrent send$ calls are serialized internally in call order, without the caller having to manage a writer
• Unified error channel: every I/O error is normalised into SerialError and multiplexed on errors$
• Explicit lifecycle: state$ emits idle / connecting / connected / disconnecting / unsupported / error so UIs can drive directly from it
• TypeScript support: full TypeScript type definitions included
• Framework agnostic: works with any JavaScript/TypeScript framework or vanilla JavaScript

Framework support

This library is framework-agnostic and can be used with:

• Angular
• React
• Svelte
• Vanilla JavaScript / TypeScript

SerialSession (v2) at a glance

createSerialSession returns a single SerialSession. All interaction goes through the fields below. The public API is intentionally small; receive$ is for raw decoder output (including terminals and \r redraws), lines$ for newline-delimited logs and parsers. When you need custom framing, compose plain RxJS on receive$ (see Advanced Usage).

SerialSessionState (quick reference)

state$ uses the string union below. Prefer the const object (e.g. SerialSessionState.Connected → 'connected') in code. Full lifecycle diagram, transitions, and edge cases: API Reference – SerialSessionState.

receive$ vs lines$: use receive$ when the UI must show exactly what the device sent (e.g. interactive shells, ls progress, any stream using \r to redraw a line). Use lines$ for newline-oriented consumers—logs, one-line replies, parsers. Feeding lines$ into a terminal widget can drop or split on \r and break redraw semantics. For custom delimiters beyond the built-in line buffer, compose on receive$ (Advanced Usage).

isConnected$ (for simple UIs) — a read-only Observable<boolean>. Use it for “port open?” toggles without comparing state$ to SerialSessionState.Connected yourself. You can still derive your own boolean from state$ with map if you need different rules.

lines$ (newline framing) — built-in line splitting; for non-line protocols or terminal mirrors, subscribe to receive$ instead (recipes in Advanced Usage).

Minimal example

import { createSerialSession, SerialSessionState } from '@gurezo/web-serial-rxjs';
import { filter } from 'rxjs';

const session = createSerialSession({ baudRate: 115200 });

if (!session.isBrowserSupported()) {
  throw new Error('Web Serial is not available in this browser');
}

session.lines$.subscribe(console.log);
session.errors$.subscribe(console.error);
session.state$
  .pipe(filter((s) => s === SerialSessionState.Connected))
  .subscribe(() => {
    /* e.g. enable UI that must wait until the port is open */
  });
session.connect$().subscribe();
session.send$('hello\r\n').subscribe();
Copy

In real apps, handle connect$().subscribe({ next, error }) and send$().subscribe({ error }) (errors are also on errors$). A fuller walkthrough is in Quick Start.

Documentation index