SerialSession の概要

このページは公開 API の考え方をまとめたものです。各 SerialSession 面の役割、SerialSessionState と state$ の対応、receive$ と lines$ の使い分け。state$ が canonical lifecycle source、errors$ が canonical error event channel です。オプション、エラーコード、型の詳細は API Reference（TypeDoc）を参照してください。

ドキュメント

まず以下を参照してください。

機能

Session 指向のリアクティブ API: 1 つの SerialSession が state$（canonical lifecycle discriminated union）/ errors$（error event channel）/ receive$ / lines$ と connect$ / disconnect$ / dispose$ / send$ を公開（isConnected$ は v3.x で非推奨の convenience stream）
UTF-8 テキストストリーム: receive$ は内部でストリーミング TextDecoder を用いてデコード済み。マルチバイト文字がチャンクにまたがっても正しく結合されます
順序保証された送信キュー: 並行する send$ 呼び出しも内部キューで FIFO 処理され、呼び出し順に書き込まれます
統一エラーチャネル: すべての I/O エラーは SerialError に正規化され errors$ に多重化されます
明示的なライフサイクル: state$ は status を持つ discriminated union（idle / connecting / connected / disconnecting / unsupported / error / disposed）を emit するので、state.status で narrowing できます
TypeScript サポート: 完全な TypeScript 型定義を同梱
フレームワーク非依存: 任意の JavaScript/TypeScript フレームワークまたはバニラ JavaScript で利用可能

対応フレームワーク

このライブラリはフレームワーク非依存で、以下の環境で利用できます。

Angular
React
Svelte
Vanilla JavaScript / TypeScript

SerialSession の全体像

createSerialSession が返す SerialSession だけを使います。公開 API は意図的に小さく、ターミナルにそのまま出す出力は receive$、改行区切りのログや解析は lines$ が担当します。ライフサイクル UI には state$ の state.status narrowing を優先してください。

公開面	役割
`state$`	Canonical 接続ライフサイクル — discriminated union（`status` + 必要に応じ `portInfo` / `error`）。購読時に現在値をリプレイ。分岐は `SerialSessionStatus` との比較を推奨。
`SerialSessionStatus`	状態定数 — エクスポートされる const object（例: `SerialSessionStatus.Connected` → `'connected'`）。`state$.status` と比較する。
`SerialSessionState`	`state$` の payload 型 — discriminated union。
`isConnected$`	非推奨（convenience） — `state$.status` が `SerialSessionStatus.Connected` のときだけ `true`。`state$` narrowing または derive を優先。
`receive$`	生のデコードチャンク — UTF-8 テキストを read pump が返すとおりに受け取る（行揃えではない。マルチバイト安全）。`\r` 等も保持。ターミナル風の表示や `\r` による上書き表示向け。
`terminalText$`	ターミナル表示向けの累積テキスト — `receive$` 由来の表示用テキスト。`\r` による上書きを折りたたみつつ通常の改行挙動は維持します。既定ではプレーンテキスト UI 向けに ANSI エスケープを除去します（生データは `receive$`）。ターミナル風ビューへ 1 つの文字列をそのままバインドしたい場合に使います。既定では完了行 10,000 行・文字数 1,048,576 文字まで保持します（`SerialSessionOptions.terminalBuffer` で変更可能）。
`lines$`	行単位の受信 — `\n` / `\r\n` / 内部の `\r` など実装に従い 1 行ずつ emit。ログ・1 行ごとの解析向け。`\r` をそのまま残す必要がある raw ターミナル表示には向かない。
`errors$`	Canonical error event channel — 接続・読み取り・書き込み・クローズのすべての `SerialError`（fatal / non-fatal）。
`connect$()`	ポート選択 → オープン → 内部 read pump 開始。
`disconnect$()`	ポートを閉じ、pump を停止。セッションは `idle` に戻り再利用可能。
`dispose$()`	セッションを永久破棄。接続を閉じ、すべての Observable を complete し、再利用不可にする。
`send$(string \| Uint8Array)`	送信を FIFO で直列化（並行 `send$` も呼び出し順）。
`isBrowserSupported()`	`connect$` の前に使う、Web Serial 利用可否の同期的な `boolean`。

SerialSessionStatus（早見表）

state$ の各 variant は status フィールドを持ちます。コードでは const オブジェクト（例: SerialSessionStatus.Connected → 'connected'）での比較を推奨します。

定数	値	意味
`SerialSessionStatus.Idle`	`'idle'`	ポート未接続。Web Serial 利用可能な場合の初期値。
`SerialSessionStatus.Connecting`	`'connecting'`	`connect$` 実行中。
`SerialSessionStatus.Connected`	`'connected'`	ポートが開き、内部 read pump が動作中。`portInfo` 付き。
`SerialSessionStatus.Disconnecting`	`'disconnecting'`	`disconnect$` 実行中。
`SerialSessionStatus.Unsupported`	`'unsupported'`	セッション生成時点で Web Serial が利用できない。
`SerialSessionStatus.Error`	`'error'`	接続まわりの致命エラー。`error` 付き。
`SerialSessionStatus.Disposed`	`'disposed'`	`dispose$` により永久破棄。すべての Observable が complete。

receive$ と lines$: 機器から来たバイト列をそのまま画面に反映する（シェル、ls のプログレス、\r で行を描き直す出力など）ときは receive$ を使います。改行区切りのログや1 行ずつ処理するプロトコルでは lines$ が適しています。ターミナル表示に lines$ を繋ぐと、内部で \r を行境界として扱うため 上書き表示が壊れることがあります。独自区切りは receive$ 上で RxJS を合成します（高度な使用方法 — 行単位のフレーミング）。

isConnected$（非推奨 convenience） — 読み取り専用の Observable<boolean> です。v3.x では後方互換のため残っていますが、次回 major version で削除予定です。boolean だけ欲しい UI 分岐では state$ から derive するか、state.status === SerialSessionStatus.Connected で narrowing してください。詳細は v3 移行ガイドを参照してください。

lines$（行区切り） — 組み込みの行分割。ターミナルのミラーや \r を保持したいときは receive$ を購読します（高度な使用方法 — 行単位のフレーミング）。

最小サンプル

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

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

if (!session.isBrowserSupported()) {
  throw new Error('このブラウザでは Web Serial を利用できません');
}

session.lines$.subscribe(console.log);
session.errors$.subscribe(console.error);
session.state$
  .pipe(filter(isConnectedSessionState))
  .subscribe((state) => {
    console.log(state.portInfo);
  });
session.connect$().subscribe();
session.send$('hello\r\n').subscribe();

実アプリでは connect$ / send$ の subscribe で error も扱ってください（errors$ にも流れます）。手順の全体はクイックスタートを参照してください。

ドキュメント索引

ドキュメント	用途
日本語 Guide 索引	Getting Started の読み順と一覧。
English Guide 索引	Getting Started reading order and full index.
リポジトリ README	モノレポ全体の目次、サンプル索引、貢献の導線。
クイックスタート	最短でポートを開いて購読するところまで。
高度な使用方法	行フレーミング、擬似リクエスト／レスポンス、リカバリ。
API Reference（TypeDoc）	オプション、`SerialSessionState`、`SerialError` の詳細。表・図は概念と設計メモも参照。
v2 → v3 マイグレーション（English）	`state$` discriminated union、`SerialSessionStatus`、`context.cause`。
v1 → v2 マイグレーション（English）	削除された v1 API からの対応表。
Phase 5（アーカイブ）	旧 v1 ドキュメントの参照用。