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; isConnected$ is deprecated in v3.x.

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

The Web Serial API is supported on desktop browsers only. Smartphones and other mobile browsers are not supported.

Supported desktop browsers:

Chrome 89+
Edge 89+
Opera 75+
Firefox 151+

Safari does not currently support the Web Serial API.

Use SerialSession.isBrowserSupported for a synchronous feature check before calling SerialSession.connect$.

Example

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

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

if (!session.isBrowserSupported()) {
  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();
}