web-serial-rxjs API Documentation

SerialSession overview

This page is the mental model for the public API: what each SerialSession surface does, how SerialSessionState maps to state$, and how to choose among receive$, lines$, and terminalText$ (see stream selection). state$ is the canonical lifecycle source; errors$ is the canonical error event channel. For options, error codes, and formal type details, see API Reference (TypeDoc).

Documentation
Features
Framework support
SerialSession at a glance
Documentation index

Documentation

Start here:

Standalone guides (HTML):

Features

Session-oriented reactive API: a single SerialSession exposes state$ (canonical lifecycle discriminated union), errors$ (error event channel), receive$, lines$, and connect$, disconnect$, dispose$, 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 a discriminated union with status (idle / connecting / connected / disconnecting / unsupported / error / disposed) so UIs can narrow on state.status and access per-state data
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
Vue
Svelte
Vanilla JavaScript / TypeScript

SerialSession at a glance

createSerialSession returns a single SerialSession. All interaction goes through the fields below. The public API is intentionally small; receive$ is for unframed UTF-8 decoder chunks (including terminals and \r redraws — not wire bytes), lines$ for newline-delimited logs and parsers. When you need custom framing, compose plain RxJS on receive$ (see Advanced Usage). Data scope: Supported data.

Surface	Role
`state$`	Canonical connection lifecycle — discriminated union (`status` plus optional `portInfo` / `error`). Replays on subscribe. Compare `state.status` with `SerialSessionStatus`.
`SerialSessionStatus`	Status constants — const object (e.g. `SerialSessionStatus.Connected` → `'connected'`). Compare with `state$.status`.
`SerialSessionState`	Payload type for `state$` (discriminated union).
`receive$`	Decoded text chunks — UTF-8 text as emitted by the pump (not line-aligned; multi-byte safe; not wire bytes). Preserves `\r` and other control characters. Use for terminal-like mirrors and progress output that relies on carriage-return redraws.
`terminalText$`	Terminal-ready cumulative text — display-oriented text derived from `receive$` that folds carriage-return redraws while keeping normal newline behavior. By default strips ANSI escape sequences for plain-text UIs; use `receive$` for raw output. Use when you want to bind one string directly to a terminal-like viewport. By default retains at most 10,000 lines and 1,048,576 characters (configure via `SerialSessionOptions.terminalBuffer`).
`lines$`	Line-delimited UTF-8 text — one string per complete line via the built-in buffer (`\n`, `\r\n`, interior `\r`). Use for logs and line-by-line parsing, not for mirroring unframed terminal streams where `\r` must stay intact.
`errors$`	Canonical error event channel — all `SerialError` instances from connect / read / write / close (fatal and non-fatal).
`connect$()`	Open a user-selected port and start the internal read pump.
`disconnect$()`	Close the port and stop the pump. The session stays reusable (`idle`).
`dispose$()`	Permanently tear down the session: close any active connection, complete all observables, and prevent reuse.
`send$(string \| Uint8Array)`	Enqueue outgoing data; writes are FIFO-ordered when multiple `send$` run concurrently.

Top-level (not a SerialSession member): isWebSerialSupported() — synchronous boolean for Web Serial availability before creating a session or calling connect$.

SerialSessionStatus (quick reference)

Each state$ emission has a status field. Prefer the const object (e.g. SerialSessionStatus.Connected → 'connected').

Constant	Value	Meaning
`SerialSessionStatus.Idle`	`'idle'`	No open port; initial when Web Serial is supported.
`SerialSessionStatus.Connecting`	`'connecting'`	`connect$` in progress.
`SerialSessionStatus.Connected`	`'connected'`	Port open; read pump running (`portInfo` included).
`SerialSessionStatus.Disconnecting`	`'disconnecting'`	`disconnect$` in progress.
`SerialSessionStatus.Unsupported`	`'unsupported'`	Web Serial unavailable at session creation.
`SerialSessionStatus.Error`	`'error'`	Fatal failure (`error` included).
`SerialSessionStatus.Disposed`	`'disposed'`	Session permanently torn down via `dispose$`.

receive$ / lines$ / terminalText$: pick by use case — newline logs and parsers → lines$; unframed decoder chunks and custom framing → receive$; terminal-style UI binding → terminalText$. Full decision table: Choosing receive$ / lines$ / terminalText$. Supported data scope: Supported data.

Connected boolean for UI — when you only need a flag, derive it from state$ (see Advanced Usage) or narrow on state.status === SerialSessionStatus.Connected. Removed convenience APIs are documented in Migrating to v4 – Phase 1 API removals.

Minimal example

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

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

if (!isWebSerialSupported()) {
  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(isConnectedSessionState))
  .subscribe((state) => {
    console.log(state.portInfo);
  });
session
  .connect$()
  .pipe(concatMap(() => session.send$('hello\r\n')))
  .subscribe({ error: console.error });

send$() before connect$() completes fails with PORT_NOT_OPEN. Start connect$() from a user gesture (for example a button click); otherwise the browser will not show the port picker. In real apps, handle error on this subscription (errors are also on errors$). A fuller walkthrough is in Quick Start.

Documentation index

The full page index is the English Guide, grouped into Getting Started, How-to, Reference, and Project.

Doc	Use it for
English Guide index	Full index: Getting Started, How-to, Reference, and Project.
日本語 Guide 索引	同じ4区分の日本語索引。
Repository README	Monorepo overview, examples index, and contribution links.