Module index

web-serial-rxjs

A TypeScript library that wraps the Web Serial API with a minimal, RxJS-based session surface.

Public API

The public API exposes a single, session-oriented surface so that apps (Angular, Vue, React, Svelte, vanilla JS/TS) can drive their UI from state$ (canonical lifecycle discriminated union) + errors$ (error event channel) + receive$ + terminalText$ + lines$ without rebuilding state, read loops, or write queues. Derive convenience booleans from state$ narrowing.

createSerialSession - factory for a SerialSession
createTerminalBuffer - terminal-style display text from SerialSession.receive$
TerminalBufferOptions - memory limits for terminal display text
LineBufferOptions - memory limits for lines$ incomplete line tail
SerialSession - the runtime interface
SerialSessionOptions - factory options (connection + features)
SerialPayload - payload accepted by SerialSession.send$
SerialConnectionOptions - port.open connection parameters (excluding filters)
SerialSessionFeatureOptions - library-specific session feature options
SerialSessionStatus - lifecycle status literals for state$.status
SerialSessionState - discriminated union emitted by state$
isConnectedSessionState - type predicate for connected state$ narrowing in RxJS pipelines
SerialError / SerialErrorCode - unified error surface
SerialErrorContextMap - structured metadata per error code
ValidationErrorContext - machine-readable validation error metadata

Browser Support

Separates Web Serial API availability (what the browser implements) from this project's official support policy (what we test and guarantee).

Web Serial API availability

Where navigator.serial exists, this library can use the Web Serial API. Typical desktop availability: Chrome 89+, Edge 89+, Opera 75+, Firefox 151+. Safari does not currently implement the Web Serial API. Many mobile browsers also lack navigator.serial; when missing, isWebSerialSupported returns false.

Project support policy

Official support covers the desktop browsers listed above. Mobile browsers are untested and out of official support. Untested does not mean the library rejects them — behavior is not guaranteed.

isWebSerialSupported

Synchronous feature detection (navigator.serial present) before SerialSession.connect$. It is not a compatibility or official-support guarantee. Secure context is a separate requirement.

Example

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

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

if (!isWebSerialSupported()) {
  console.error('Web Serial API is not supported in this browser');
} else {
  session.state$.subscribe((state) => {
    if (state.status === SerialSessionStatus.Connected) {
      console.log('port:', state.portInfo);
    }
  });
  session.state$
    .pipe(filter(isConnectedSessionState))
    .subscribe((state) => {
      console.log('port:', state.portInfo);
    });
  session.receive$.subscribe((chunk) => console.log('rx:', chunk));
  session.errors$.subscribe((error) => {
    if (error.is(SerialErrorCode.READ_FAILED)) {
      console.error(error.context.cause);
    }
  });

  session.connect$().subscribe();
  session.send$('hello\r\n').subscribe();
}