@gurezo/web-serial-rxjs 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.ja.md +19 -172
  2. package/README.md +20 -191
  3. package/package.json +1 -1
  4. package/web-serial-rxjs-icon.png +0 -0
package/README.ja.md CHANGED
@@ -1,57 +1,15 @@
1
- <p align="center">
2
- <img src="https://raw.githubusercontent.com/gurezo/web-serial-rxjs/main/assets/icon/web-serial-rxjs-icon.png" alt="web-serial-rxjs プロジェクトアイコン" width="512" />
3
- </p>
4
-
5
- Web Serial API を最小限の Session 指向 RxJS API でラップする TypeScript ライブラリです。v2 では単一の `SerialSession` を公開し、アプリケーション側は `state$` / `isConnected$` / `receive$` / `lines$` / `errors$` を購読するだけで UI を駆動できます。BehaviorSubject による状態再構築・read loop・送信キューの自前実装は一切不要です。
6
-
7
- ## 目次
8
-
9
- - [SerialSession（v2）の全体像](#serialsessionv2の全体像)
10
- - [機能](#機能)
11
- - [対応フレームワーク](#対応フレームワーク)
12
- - [ブラウザサポート](#ブラウザサポート)
13
- - [インストール](#インストール)
14
- - [ドキュメント](#ドキュメント)
15
- - [サンプル](#サンプル)
16
- - [プロジェクトアイコンについて](#プロジェクトアイコンについて)
17
- - [開発とリリース戦略](#開発とリリース戦略)
18
- - [貢献](#貢献)
19
- - [ライセンス](#ライセンス)
20
- - [リンク](#リンク)
21
-
22
- ## 機能
23
-
24
- - **Session 指向のリアクティブ API**: 1 つの `SerialSession` が `state$` / `isConnected$` / `receive$` / `lines$` / `errors$` と `connect$` / `disconnect$` / `send$` を公開
25
- - **UTF-8 テキストストリーム**: `receive$` は内部でストリーミング `TextDecoder` を用いてデコード済み。マルチバイト文字がチャンクにまたがっても正しく結合されます
26
- - **順序保証された送信キュー**: 並行する `send$` 呼び出しも内部キューで FIFO 処理され、呼び出し順に書き込まれます
27
- - **統一エラーチャネル**: すべての I/O エラーは `SerialError` に正規化され `errors$` に多重化されます
28
- - **明示的なライフサイクル**: `state$` は `idle` / `connecting` / `connected` / `disconnecting` / `unsupported` / `error` を emit するので UI から直接駆動できます
29
- - **TypeScript サポート**: 完全な TypeScript 型定義を同梱
30
- - **フレームワーク非依存**: 任意の JavaScript/TypeScript フレームワークまたはバニラ JavaScript で利用可能
31
-
32
- ## 対応フレームワーク
33
-
34
- このライブラリはフレームワーク非依存で、以下の環境で利用できます。
35
-
36
- - Angular
37
- - React
38
- - Svelte
39
- - Vanilla JavaScript / TypeScript
1
+ # @gurezo/web-serial-rxjs
40
2
 
41
- ## ブラウザサポート
3
+ Web Serial API を最小限の Session 指向 RxJS 表面でラップする TypeScript ライブラリです。v2 では単一の `SerialSession` を公開し、`state$` / `isConnected$` / `receive$` / `lines$` / `errors$` を購読するだけで UI を駆動できます。read loop や送信キューの自前実装は不要です。
42
4
 
43
- Web Serial API は現在、Chromium ベースのブラウザでのみサポートされています：
5
+ ## ブラウザサポート
44
6
 
45
- - **Chrome** 89+
46
- - **Edge** 89+
47
- - **Opera** 75+
7
+ Web Serial API は **Chromium 系**のブラウザ（**Chrome** 89+、**Edge** 89+、**Opera** 75+）でのみ利用できます。
48
8
 
49
- `connect$` を呼ぶ前の feature detection には `SerialSession.isBrowserSupported()` が使えます（同期的に `boolean` を返します）。
9
+ `connect$` の前の feature detection には `SerialSession.isBrowserSupported()`（同期的に `boolean`）を使います。
50
10
 
51
11
  ## インストール
52
12
 
53
- npm または pnpm を使用してパッケージをインストールします：
54
-
55
13
  ```bash
56
14
  npm install @gurezo/web-serial-rxjs
57
15
  # または
@@ -60,7 +18,7 @@ pnpm add @gurezo/web-serial-rxjs
60
18
 
61
19
  ### ピア依存関係
62
20
 
63
- このライブラリは RxJS をピア依存関係として必要とします：
21
+ **RxJS** `^7.8.0` をピア依存関係として必要とします。
64
22
 
65
23
  ```bash
66
24
  npm install rxjs
@@ -68,139 +26,28 @@ npm install rxjs
68
26
  pnpm add rxjs
69
27
  ```
70
28
 
71
- **最小要件バージョン**: RxJS ^7.8.0
72
-
73
- ## SerialSession（v2）の全体像
74
-
75
- `createSerialSession` が返す **SerialSession** だけを使います。公開 API は意図的に小さく、**標準の改行区切り**は組み込み `lines$`、独自区切りが必要なときだけ `receive$` 上に RxJS で組み立てます（[高度な使用方法](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.ja.md)）。接続真偽は `isConnected$` も利用できます。
76
-
77
- | 公開面 | 役割 |
78
- | --- | --- |
79
- | `state$` | **接続ライフサイクル** — `idle` / `connecting` / `connected` / `disconnecting` / `error` / `unsupported`。購読時に現在値をリプレイ。分岐は文字列直書きではなく **`SerialSessionState`** との比較を推奨。 |
80
- | `SerialSessionState` | **状態定数** — エクスポートされる const object（例: `SerialSessionState.Connected`, `SerialSessionState.Idle`）。`state$` が emit する値と同じ。 |
81
- | `isConnected$` | **接続中かどうか** — `state$` が `SerialSessionState.Connected` のときだけ `true`、それ以外は `false`（`state$` から `distinctUntilChanged` 付きで派生）。 |
82
- | `receive$` | **受信 UTF-8 テキスト**（デコード済みの**チャンク**列。行区切りではない。マルチバイト安全）。 |
83
- | `lines$` | **行単位の受信** — 1 行完了ごとに emit。内部バッファで改行（`\n` / `\r\n` 等）を解釈。 |
84
- | `errors$` | **すべての `SerialError`**（接続・読み取り・書き込み・クローズ）の主チャネル。 |
85
- | `connect$()` | ポート選択 → オープン → 内部 read pump 開始。 |
86
- | `disconnect$()` | ポートを閉じ、pump を停止。 |
87
- | `send$(string \| Uint8Array)` | 送信を **FIFO** で直列化（並行 `send$` も呼び出し順）。 |
88
- | `isBrowserSupported()` | `connect$` の前に使う、Web Serial 利用可否の同期的な `boolean`。 |
89
-
90
- ### SerialSessionState（早見表）
91
-
92
- `state$` が emit する文字列のユニオンです。コードでは **const オブジェクト**（例: `SerialSessionState.Connected` → `'connected'`）での比較を推奨します。有効な遷移・例外系の扱いの詳細は [API リファレンスの SerialSessionState](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/API_REFERENCE.ja.md#serialsessionstate) を参照してください。
93
-
94
- | 定数 | 値 | 意味 |
95
- | --- | --- | --- |
96
- | `SerialSessionState.Idle` | `'idle'` | ポート未接続。Web Serial 利用可能な場合の初期値。 |
97
- | `SerialSessionState.Connecting` | `'connecting'` | `connect$` 実行中。 |
98
- | `SerialSessionState.Connected` | `'connected'` | ポートが開き、内部 read pump が動作中。 |
99
- | `SerialSessionState.Disconnecting` | `'disconnecting'` | `disconnect$` 実行中。 |
100
- | `SerialSessionState.Unsupported` | `'unsupported'` | セッション生成時点で Web Serial が利用できない。 |
101
- | `SerialSessionState.Error` | `'error'` | 接続まわりの致命エラー。`disconnect$` か新しいセッションで復帰。 |
102
-
103
- **`receive$` と `lines$`:** 改行区切りの定番利用では **`lines$`** を優先。**`receive$`** はチャンクの到着タイミングをそのまま扱う場合や、独自区切り・自前バッファが必要なとき向け（[行単位のフレーミング](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.ja.md#行単位のフレーミング)）。
104
-
105
- **`isConnected$`（UI 用）** — 読み取り専用の `Observable<boolean>` です。`state$` を `SerialSessionState.Connected` と毎回比較しなくても接続有無の UI 分岐に使えます。独自ルールが必要な場合は、従来どおり `state$` から `map` で派生しても構いません。
106
-
107
- **`lines$`（行区切り）** — 組み込みです。独自区切りが欲しい場合のみ `receive$` でフレーミングします（[行単位のフレーミング](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.ja.md#行単位のフレーミング)）。
108
-
109
- ### 最小サンプル
110
-
111
- ```typescript
112
- import { createSerialSession, SerialSessionState } from '@gurezo/web-serial-rxjs';
113
- import { filter } from 'rxjs';
114
-
115
- const session = createSerialSession({ baudRate: 115200 });
116
-
117
- if (!session.isBrowserSupported()) {
118
- throw new Error('このブラウザでは Web Serial を利用できません');
119
- }
120
-
121
- session.lines$.subscribe(console.log);
122
- session.errors$.subscribe(console.error);
123
- session.state$
124
- .pipe(filter((s) => s === SerialSessionState.Connected))
125
- .subscribe(() => {
126
- /* 例: ポートが開いてから有効化する UI */
127
- });
128
- session.connect$().subscribe();
129
- session.send$('hello\r\n').subscribe();
130
- ```
29
+ ## 次に読むもの
131
30
 
132
- 実アプリでは `connect$` / `send$` の `subscribe` で `error` も扱ってください（`errors$` にも流れます）。手順の全体は [クイックスタート](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.ja.md) を参照してください。
31
+ - **v2 の全体像**（機能一覧、`SerialSession` 早見表、`SerialSessionState`、最小サンプル）: [SerialSession（v2）の概要](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.ja.md)（[English](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.md)）
32
+ - 最短でポートを開く手順: [クイックスタート](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.ja.md)
133
33
 
134
34
  ## ドキュメント
135
35
 
136
36
  | ドキュメント | 用途 |
137
37
  | --- | --- |
138
- | **リポジトリ [README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.ja.md)** | モノレポ全体の目次、サンプル索引、貢献の導線。 |
139
- | **[クイックスタート](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.ja.md)** | 最短でポートを開いて購読するところまで。 |
140
- | **[高度な使用方法](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.ja.md)** | 行フレーミング、擬似リクエスト／レスポンス、リカバリ。 |
141
- | **[API リファレンス](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/API_REFERENCE.ja.md)** | オプション、`SerialSessionState`、`SerialError` の詳細。 |
142
- | **[v1 → v2 マイグレーション](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/MIGRATION_V2.ja.md)**（[English](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/MIGRATION_V2.md)） | 削除された v1 API からの対応表。 |
143
- | **[Phase 5（アーカイブ）](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/archive/MIGRATION_PHASE5.ja.md)** | 旧 v1 ドキュメントの参照用。 |
144
-
145
- ## サンプル
146
-
147
- 以下の環境向けのサンプルを用意しています。
148
-
149
- - **[Angular](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-angular)** - Service を使用した Angular の例
150
- - **[React](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-react)** - カスタムフック（`useSerialSession`）を使用した React の例
151
- - **[Svelte](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-svelte)** - Svelte Store を使用した Svelte の例
152
- - **[Vanilla JavaScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-js)** - バニラ JavaScript での基本的な使用方法
153
- - **[Vanilla TypeScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-ts)** - RxJS を使用した TypeScript の例
154
- - **[Vue](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vue)** - Composition API を使用した Vue 3 の例
155
-
156
- 各サンプルは **connect・受信（多くの例は `lines$` または `receive$` 派生の行区切り）・send・disconnect** の最小動作確認用です。応用は [高度な使用方法](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.ja.md) を参照してください。
157
-
158
- 各例には、セットアップと使用方法の説明を含む README が含まれています。
159
-
160
- ## プロジェクトアイコンについて
161
-
162
- このプロジェクトのアイコンには、[RxJS](https://rxjs.dev/) のロゴから着想を得たデザインに、
163
- Web Serial を表すシリアルコネクタのモチーフを組み合わせたものを使用しています。
164
-
165
- このアイコンは、本ライブラリが Web Serial API を RxJS ベースで扱うための
166
- ライブラリであることを示す目的でのみ使用しています。
167
-
168
- 本プロジェクトは **[ReactiveX](http://reactivex.io/) / [RxJS](https://rxjs.dev/) 公式とは関係のない独立したオープンソースプロジェクト** であり、
169
- 公式な提携・承認・スポンサー関係はありません。
170
-
171
- ## 開発とリリース戦略
172
-
173
- このプロジェクトは**trunk-based開発**アプローチに従います：
174
-
175
- - **`main`ブランチ**: 常にリリース可能な状態
176
- - **短命ブランチ**: `feature/*`, `fix/*`, `docs/*` はプルリクエスト用
177
- - **リリース**: ブランチではなくGitタグ（例: `v1.0.0`）で管理
178
- - **バージョン保守**: 複数のメジャーバージョンを保守する必要がある場合のみ `release/v*` ブランチを追加
179
-
180
- 詳細な貢献ガイドラインについては、[CONTRIBUTING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.ja.md) を参照してください。
181
-
182
- 詳細なリリース手順については、[RELEASING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.ja.md) を参照してください。
183
-
184
- ## 貢献
185
-
186
- 貢献を歓迎します！詳細については、[貢献ガイド](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.ja.md)を参照してください：
187
-
188
- - 開発環境のセットアップ
189
- - コードスタイルガイドライン
190
- - コミットメッセージの規約
191
- - プルリクエストのプロセス
192
- - リリースプロセス
193
-
194
- 英語版の貢献ガイドは [CONTRIBUTING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md) を参照してください。
195
-
196
- リリース手順については、[RELEASING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.ja.md)（または英語版は [RELEASING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.md)）を参照してください。
38
+ | [全体像](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.ja.md) | 機能と v2 `SerialSession` / `SerialSessionState` の対応表 |
39
+ | [クイックスタート](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.ja.md) | ポートを開いて購読までを最短で |
40
+ | [高度な使用方法](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.ja.md) | 行フレーミング、擬似リクエスト/レス、リカバリ |
41
+ | [API リファレンス](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/API_REFERENCE.ja.md) | オプション、`SerialError`、型の詳細 |
42
+ | [v1 → v2 マイグレーション](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/MIGRATION_V2.ja.md) | 廃止された v1 API の置き換え |
43
+ | **リポジトリ [README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.ja.md)** | モノレポ構成、**`apps/` のサンプル**、貢献、MCP、プロジェクトアイコン |
197
44
 
198
45
  ## ライセンス
199
46
 
200
- このプロジェクトは MIT ライセンスの下で公開されています。詳細は [LICENSE](https://github.com/gurezo/web-serial-rxjs/blob/main/LICENSE) ファイルを参照してください。
47
+ MIT。詳細はリポジトリの [LICENSE](https://github.com/gurezo/web-serial-rxjs/blob/main/LICENSE) を参照してください。
201
48
 
202
49
  ## リンク
203
50
 
204
- - **GitHub リポジトリ**: [https://github.com/gurezo/web-serial-rxjs](https://github.com/gurezo/web-serial-rxjs)
205
- - **イシュー**: [https://github.com/gurezo/web-serial-rxjs/issues](https://github.com/gurezo/web-serial-rxjs/issues)
206
- - **Web Serial API 仕様**: [https://wicg.github.io/serial/](https://wicg.github.io/serial/)
51
+ - **リポジトリ**: [github.com/gurezo/web-serial-rxjs](https://github.com/gurezo/web-serial-rxjs)
52
+ - **イシュー**: [github.com/gurezo/web-serial-rxjs/issues](https://github.com/gurezo/web-serial-rxjs/issues)
53
+ - **Web Serial API 仕様**: [wicg.github.io/serial](https://wicg.github.io/serial/)
package/README.md CHANGED
@@ -1,67 +1,24 @@
1
- <p align="center">
2
- <img src="https://raw.githubusercontent.com/gurezo/web-serial-rxjs/main/assets/icon/web-serial-rxjs-icon.png" alt="web-serial-rxjs project icon" width="512" />
3
- </p>
1
+ # @gurezo/web-serial-rxjs
4
2
 
5
- A TypeScript library that wraps the Web Serial API with a minimal, session-oriented RxJS surface. The v2 API exposes a single `SerialSession` so applications can drive their UI entirely from `state$` + `isConnected$` + `receive$` + `lines$` + `errors$`, without rebuilding state, read loops, or send queues themselves.
3
+ A TypeScript library that wraps the Web Serial API with a minimal, session-oriented RxJS surface. The v2 API exposes a single `SerialSession` so applications can drive their UI from `state$` + `isConnected$` + `receive$` + `lines$` + `errors$`, without rebuilding read loops or send queues themselves.
6
4
 
7
- ## Table of Contents
5
+ ## Browser support
8
6
 
9
- - [SerialSession (v2) at a glance](#serialsession-v2-at-a-glance)
10
- - [Features](#features)
11
- - [Framework Support](#framework-support)
12
- - [Browser Support](#browser-support)
13
- - [Installation](#installation)
14
- - [Documentation](#documentation)
15
- - [Examples](#examples)
16
- - [Project Icon](#project-icon)
17
- - [AI Assistant (MCP)](#ai-assistant-mcp)
18
- - [Development and Release Strategy](#development-and-release-strategy)
19
- - [Contributing](#contributing)
20
- - [License](#license)
21
- - [Links](#links)
7
+ The Web Serial API is only available in **Chromium-based** browsers: **Chrome** 89+, **Edge** 89+, **Opera** 75+.
22
8
 
23
- ## Features
24
-
25
- - **Session-oriented reactive API**: a single `SerialSession` exposes `state$`, `isConnected$`, `receive$`, `lines$`, `errors$`, plus `connect$`, `disconnect$`, and `send$`
26
- - **UTF-8 text stream**: `receive$` is already decoded with a streaming `TextDecoder`, so multi-byte characters split across chunks are joined correctly
27
- - **Ordered send queue**: concurrent `send$` calls are serialized internally in call order, without the caller having to manage a writer
28
- - **Unified error channel**: every I/O error is normalised into `SerialError` and multiplexed on `errors$`
29
- - **Explicit lifecycle**: `state$` emits `idle` / `connecting` / `connected` / `disconnecting` / `unsupported` / `error` so UIs can drive directly from it
30
- - **TypeScript support**: full TypeScript type definitions included
31
- - **Framework agnostic**: works with any JavaScript/TypeScript framework or vanilla JavaScript
32
-
33
- ## Framework Support
34
-
35
- This library is framework-agnostic and can be used with:
36
-
37
- - Angular
38
- - React
39
- - Svelte
40
- - Vanilla JavaScript / TypeScript
41
-
42
- ## Browser Support
43
-
44
- The Web Serial API is currently only supported in Chromium-based browsers:
45
-
46
- - **Chrome** 89+
47
- - **Edge** 89+
48
- - **Opera** 75+
49
-
50
- `SerialSession.isBrowserSupported()` returns a synchronous boolean for feature detection before calling `connect$`.
9
+ `SerialSession.isBrowserSupported()` returns a synchronous `boolean` for feature detection before `connect$`.
51
10
 
52
11
  ## Installation
53
12
 
54
- Install the package using npm or pnpm:
55
-
56
13
  ```bash
57
14
  npm install @gurezo/web-serial-rxjs
58
15
  # or
59
16
  pnpm add @gurezo/web-serial-rxjs
60
17
  ```
61
18
 
62
- ### Peer Dependencies
19
+ ### Peer dependency
63
20
 
64
- This library requires RxJS as a peer dependency:
21
+ This library requires **RxJS** `^7.8.0` as a peer dependency:
65
22
 
66
23
  ```bash
67
24
  npm install rxjs
@@ -69,156 +26,28 @@ npm install rxjs
69
26
  pnpm add rxjs
70
27
  ```
71
28
 
72
- **Minimum required version**: RxJS ^7.8.0
73
-
74
- ## SerialSession (v2) at a glance
29
+ ## Where to go next
75
30
 
76
- `createSerialSession` returns a single **SerialSession**. All interaction goes through the fields below. The public API is intentionally small; when you need **custom** framing, compose plain RxJS on `receive$` (see [Advanced Usage](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.md)).
77
-
78
- | Surface | Role |
79
- | --- | --- |
80
- | `state$` | **Connection lifecycle** — `idle` / `connecting` / `connected` / `disconnecting` / `error` / `unsupported`. Replays the current state on subscribe. Compare with **`SerialSessionState`** instead of string literals. |
81
- | `SerialSessionState` | **State constants** — exported const object (e.g. `SerialSessionState.Connected`, `SerialSessionState.Idle`) with the same values `state$` emits. |
82
- | `isConnected$` | **Connected flag** — `true` only when `state$` is `SerialSessionState.Connected`; `false` in every other state (derived from `state$` with `distinctUntilChanged`). |
83
- | `receive$` | **Raw incoming UTF-8 text** as decoded string **chunks** (not line-delimited; multi-byte safe). |
84
- | `lines$` | **Line-delimited UTF-8 text** — one string per complete line, using the built-in newline buffer (`\n` / `\r\n`). |
85
- | `errors$` | **All `SerialError` instances** from connect / read / write / close (primary error channel). |
86
- | `connect$()` | **Open** a user-selected port and start the internal read pump. |
87
- | `disconnect$()` | **Close** the port and stop the pump. |
88
- | `send$(string \| Uint8Array)` | **Enqueue** outgoing data; writes are **FIFO-ordered** when multiple `send$` run concurrently. |
89
- | `isBrowserSupported()` | Synchronous `boolean` for Web Serial availability before `connect$`. |
90
-
91
- ### SerialSessionState (quick reference)
92
-
93
- `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](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/API_REFERENCE.md#serialsessionstate).
94
-
95
- | Constant | Value | Meaning |
96
- | --- | --- | --- |
97
- | `SerialSessionState.Idle` | `'idle'` | No open port; initial state when the browser supports Web Serial. |
98
- | `SerialSessionState.Connecting` | `'connecting'` | `connect$` in progress. |
99
- | `SerialSessionState.Connected` | `'connected'` | Port is open; internal read pump is running. |
100
- | `SerialSessionState.Disconnecting` | `'disconnecting'` | `disconnect$` in progress. |
101
- | `SerialSessionState.Unsupported` | `'unsupported'` | Web Serial was not available when the session was created. |
102
- | `SerialSessionState.Error` | `'error'` | Fatal I/O or lifecycle failure; call `disconnect$` or build a new session. |
103
-
104
- **`receive$` vs `lines$`:** prefer **`lines$`** for typical newline-framed text; use **`receive$`** when you need raw chunk timing, a custom delimiter, or a rolling buffer you control (recipes in [Advanced Usage](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.md#line-framing)).
105
-
106
- **`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.
107
-
108
- **`lines$` (newline framing)** — built in; for non-standard delimiters, frame on `receive$` (recipes in [Advanced Usage](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.md#line-framing)).
109
-
110
- ### Minimal example
111
-
112
- ```typescript
113
- import { createSerialSession, SerialSessionState } from '@gurezo/web-serial-rxjs';
114
- import { filter } from 'rxjs';
115
-
116
- const session = createSerialSession({ baudRate: 115200 });
117
-
118
- if (!session.isBrowserSupported()) {
119
- throw new Error('Web Serial is not available in this browser');
120
- }
121
-
122
- session.lines$.subscribe(console.log);
123
- session.errors$.subscribe(console.error);
124
- session.state$
125
- .pipe(filter((s) => s === SerialSessionState.Connected))
126
- .subscribe(() => {
127
- /* e.g. enable UI that must wait until the port is open */
128
- });
129
- session.connect$().subscribe();
130
- session.send$('hello\r\n').subscribe();
131
- ```
132
-
133
- In real apps, handle `connect$().subscribe({ next, error })` and `send$().subscribe({ error })` (errors are also on `errors$`). A fuller walkthrough is in [Quick Start](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.md).
31
+ - Full **v2 API map** (features, `SerialSession` table, `SerialSessionState`, minimal example): [SerialSession (v2) overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.md) ([日本語](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.ja.md))
32
+ - Shortest path to an open port: [Quick Start](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.md)
134
33
 
135
34
  ## Documentation
136
35
 
137
36
  | Doc | Use it for |
138
37
  | --- | --- |
139
- | **Repository [README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.md)** | Monorepo overview, examples index, and contribution links. |
140
- | **[Quick Start](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.md)** | Shortest path to a working open port and subscriptions. |
141
- | **[Advanced Usage](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.md)** | Line framing, request/response-style flows, and recovery. |
142
- | **[API Reference](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/API_REFERENCE.md)** | Options, `SerialSessionState`, and `SerialError` details. |
143
- | **[v1 → v2 Migration Guide](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/MIGRATION_V2.md)** | Replacing the removed v1 `SerialClient` / `ShellClient` API. |
144
- | **[Phase 5 archive (legacy v1 doc)](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/archive/MIGRATION_PHASE5.md)** | Historical v1 context only. |
145
-
146
- ## Examples
147
-
148
- Examples are available for the following environments:
149
-
150
- - **[Angular](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-angular)** - Angular example using a Service
151
- - **[React](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-react)** - React example with custom hook (`useSerialSession`)
152
- - **[Svelte](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-svelte)** - Svelte example using Svelte Store
153
- - **[Vanilla JavaScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-js)** - Basic usage with vanilla JavaScript
154
- - **[Vanilla TypeScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-ts)** - TypeScript example with RxJS
155
- - **[Vue](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vue)** - Vue 3 example using Composition API
156
-
157
- Each sample is a **minimal smoke test** for **connect**, **receive** (typically newline-delimited lines via `lines$` or a stream derived from `receive$`), **send**, and **disconnect**. See [Advanced Usage](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.md) for richer patterns.
158
-
159
- Each example includes a README with setup and usage instructions.
160
-
161
- ## Project Icon
162
-
163
- The project icon includes a modified design inspired by the [RxJS](https://rxjs.dev/) logo,
164
- combined with a serial connector motif to represent Web Serial communication.
165
-
166
- The icon is used only to indicate that this library provides
167
- RxJS-based abstractions for the Web Serial API.
168
-
169
- This project is an independent open source project and is **not affiliated with,
170
- endorsed by, or sponsored by the [ReactiveX](http://reactivex.io/) or [RxJS](https://rxjs.dev/) project**.
171
-
172
- ## AI Assistant (MCP)
173
-
174
- This project includes [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server configuration for AI-assisted development. The following MCP servers are available:
175
-
176
- | Server | Purpose |
177
- | --------------- | -------------------------------------------------------------------------------------- |
178
- | **nx-mcp** | Nx workspace analysis, project graph, CI monitoring, and documentation |
179
- | **angular-cli** | Angular CLI tools for example-angular (code generation, documentation, best practices) |
180
- | **svelte** | Svelte/SvelteKit documentation and code analysis for example-svelte |
181
-
182
- **Configuration files:**
183
-
184
- - `.mcp.json` - Standard MCP configuration (Cursor, VS Code, Claude, etc.)
185
- - `.cursor/mcp.json` - Cursor-specific configuration
186
-
187
- To use MCP servers in Cursor, the configuration is automatically loaded from `.cursor/mcp.json`. For VS Code, add the MCP extension and configure it to use `.mcp.json`, or add the server definitions to your MCP settings.
188
-
189
- ## Development and Release Strategy
190
-
191
- This project follows a **trunk-based development** approach:
192
-
193
- - **`main` branch**: Always in a release-ready state
194
- - **Short-lived branches**: `feature/*`, `fix/*`, `docs/*` for pull requests
195
- - **Releases**: Managed via Git tags (e.g., `v1.0.0`), not branches
196
- - **Version maintenance**: `release/v*` branches are added only when needed for maintaining multiple major versions
197
-
198
- For detailed contribution guidelines, see [CONTRIBUTING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md).
199
-
200
- For detailed release instructions, see [RELEASING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.md).
201
-
202
- ## Contributing
203
-
204
- We welcome contributions! Please see our [Contributing Guide](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md) for details on:
205
-
206
- - Development setup
207
- - Code style guidelines
208
- - Commit message conventions
209
- - Pull request process
210
- - Release process
211
-
212
- For Japanese contributors, please see [CONTRIBUTING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.ja.md).
213
-
214
- For release instructions, see [RELEASING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.md) (or [RELEASING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.ja.md) for Japanese).
38
+ | [Overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.md) | Features and the v2 `SerialSession` / `SerialSessionState` map |
39
+ | [Quick Start](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.md) | Open a port and wire subscriptions end-to-end |
40
+ | [Advanced Usage](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.md) | Line framing, request/response-style flows, recovery |
41
+ | [API Reference](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/API_REFERENCE.md) | `SerialSessionOptions`, `SerialError`, and formal details |
42
+ | [v1 → v2 migration](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/MIGRATION_V2.md) | Replacing the removed v1 `SerialClient` / `ShellClient` API |
43
+ | [Repository README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.md) | Monorepo layout, **examples** under `apps/`, contributing, MCP, and project icon |
215
44
 
216
45
  ## License
217
46
 
218
- This project is licensed under the MIT License - see the [LICENSE](https://github.com/gurezo/web-serial-rxjs/blob/main/LICENSE) file for details.
47
+ MIT — see the [LICENSE](https://github.com/gurezo/web-serial-rxjs/blob/main/LICENSE) file in the repository.
219
48
 
220
49
  ## Links
221
50
 
222
- - **GitHub Repository**: [https://github.com/gurezo/web-serial-rxjs](https://github.com/gurezo/web-serial-rxjs)
223
- - **Issues**: [https://github.com/gurezo/web-serial-rxjs/issues](https://github.com/gurezo/web-serial-rxjs/issues)
224
- - **Web Serial API Specification**: [https://wicg.github.io/serial/](https://wicg.github.io/serial/)
51
+ - **Repository**: [github.com/gurezo/web-serial-rxjs](https://github.com/gurezo/web-serial-rxjs)
52
+ - **Issues**: [github.com/gurezo/web-serial-rxjs/issues](https://github.com/gurezo/web-serial-rxjs/issues)
53
+ - **Web Serial API (spec)**: [wicg.github.io/serial](https://wicg.github.io/serial/)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gurezo/web-serial-rxjs",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "description": "RxJS-based utilities for the Web Serial API, usable from Angular, React, Svelte, and Vanilla JavaScript/TypeScript.",
5
5
  "author": "Akihiko Kigure <akihiko.kigure@gmail.com>",
6
6
  "license": "MIT",
package/web-serial-rxjs-icon.png CHANGED
Binary file