@gurezo/web-serial-rxjs 4.0.2 → 4.0.3

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 (5) hide show
  1. package/README.ja.md +25 -7
  2. package/README.md +25 -7
  3. package/dist/session/serial-session.d.ts +8 -0
  4. package/dist/session/serial-session.d.ts.map +1 -1
  5. package/package.json +2 -1
package/README.ja.md CHANGED
@@ -6,6 +6,8 @@
6
6
 
7
7
  Web Serial API を最小限の Session 指向 RxJS 表面でラップする TypeScript ライブラリです。公開 API は単一の `SerialSession` を提供し、`state$`（canonical lifecycle state）/ `errors$`（error event channel）/ `receive$` / `lines$` を購読するだけで UI を駆動できます。read loop や送信キューの自前実装は不要です。
8
8
 
9
+ **主対象は UTF-8 テキスト通信です。** 受信データは常にストリーミング UTF-8 `TextDecoder` でデコードされます。`receive$` が返すのは**デコード済みテキストチャンク**（行未分割）であり、ワイヤ上の生バイトではありません。バイナリ**送信**（`send$(Uint8Array)`）は対応しますが、バイナリ**受信**・UTF-8 以外の文字コード・プロトコルフレーミング（Modbus / COBS / SLIP など）は対象外です。詳細は下記の [対応範囲](#対応範囲テキスト--バイナリ--文字コード) と [API の概念](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/concepts.md#対応範囲テキスト--バイナリ--文字コード) を参照してください。
10
+
9
11
  ## ブラウザサポート
10
12
 
11
13
  Web Serial API は**デスクトップ**ブラウザでのみサポートされています。スマートフォンなどのモバイルブラウザには対応していません。
@@ -23,21 +25,36 @@ Web Serial API は**デスクトップ**ブラウザでのみサポートされ
23
25
 
24
26
  ## 接続状態（ライフサイクル UI）
25
27
 
26
- ライフサイクル UI には **`state$`** の `state.status` narrowing を canonical API として使用してください。boolean だけ必要な場合は `state$` から derive してください。セッション破棄には **`dispose$()`** を使用します（購読により実行されます）。詳細は [v4 への移行](./docs/guide/ja/migration-v4.md) を参照してください。
28
+ ライフサイクル UI には **`state$`** の `state.status` narrowing を canonical API として使用してください。boolean だけ必要な場合は `state$` から derive してください。セッション破棄には **`dispose$()`** を使用します（購読により実行されます）。詳細は [v4 への移行](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/migration-v4.md) を参照してください。
27
29
 
28
30
  ## 接続中のポート情報（デバイス識別）
29
31
 
30
- `connect$` 成功後、`state$` を `state.status === SerialSessionStatus.Connected` で handling する場合は **`state.portInfo`** を canonical API として使用してください。生の `SerialPort` は公開しません。削除された convenience API（`isConnected$`、`portInfo$`、`getPortInfo()`、`destroy$()`、`getCurrentPort()`、`receiveReplay$`、`isBrowserSupported()`）と置換先は [v4 への移行](./docs/guide/ja/migration-v4.md) を参照してください。
32
+ `connect$` 成功後、`state$` を `state.status === SerialSessionStatus.Connected` で handling する場合は **`state.portInfo`** を canonical API として使用してください。生の `SerialPort` は公開しません。削除された convenience API（`isConnected$`、`portInfo$`、`getPortInfo()`、`destroy$()`、`getCurrentPort()`、`receiveReplay$`、`isBrowserSupported()`）と置換先は [v4 への移行](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/migration-v4.md) を参照してください。
33
+
34
+ ## 対応範囲（テキスト / バイナリ / 文字コード）
35
+
36
+ | 項目 | 現在の対応 |
37
+ | --- | --- |
38
+ | UTF-8 テキスト送受信 | 対応 |
39
+ | チャンク単位の文字列受信 | `receive$`（デコード済みチャンク。生バイトではない） |
40
+ | 改行区切りの文字列受信 | `lines$` |
41
+ | `\r` を含むターミナル表示 | `receive$` / `terminalText$` |
42
+ | バイナリ送信 | `send$(Uint8Array)` で対応 |
43
+ | バイナリ受信 | **非対応**（生 `Uint8Array` 受信ストリームなし） |
44
+ | UTF-8 以外の文字コード | **非対応** |
45
+ | 特定プロトコル（Modbus / COBS / SLIP など） | **利用側で実装** |
46
+
47
+ 詳細と将来検討時の設計論点: [API の概念 — 対応範囲](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/concepts.md#対応範囲テキスト--バイナリ--文字コード)。
31
48
 
32
49
  ## `receive$` と `lines$`
33
50
 
34
51
  購読するストリームはユースケースに合わせて選んでください。**`lines$`** をターミナル表示に使うと `\r` が失われ再描画できず、シェル出力（例: `ls -la` の整形）が崩れます。詳細は [概要](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/overview.md) を参照してください。
35
52
 
36
- ### `receive$`（raw ストリーム）
53
+ ### `receive$`（デコード済みチャンク）
37
54
 
38
- - UTF-8 の**デコードチャンク**をそのまま届く順に（行揃えではありません）。
39
- - `\r` や行途中の断片など制御文字も保持します。
40
- - **ターミナル表示**、**プロンプト判定**、自前の**バッファ**/スクロールバック、raw を前提にした処理に使います。
55
+ - UTF-8 の**デコードチャンク**をそのまま届く順に（行揃えではありません）。**ワイヤ上の生バイトではありません**。
56
+ - デコード後のテキストとして `\r` や行途中の断片など制御文字も保持します。
57
+ - **ターミナル表示**、**プロンプト判定**、自前の**バッファ**/スクロールバック、未フレーミングのデコードストリーム処理に使います。
41
58
 
42
59
  ### `lines$`（行単位のイベント）
43
60
 
@@ -101,7 +118,8 @@ pnpm add rxjs
101
118
  | [v3 → v4 マイグレーション](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/migration-v4.md) | Phase 1+2 の削除（`receiveReplay$`、`isBrowserSupported()`、オプション整理） |
102
119
  | [v2 → v3 マイグレーション](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/migration-v3.md) | `state$` discriminated union、`SerialSessionStatus`、`context.cause` |
103
120
  | [v1 → v2 マイグレーション](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/migration-v2.md) | 廃止された v1 API の置き換え |
104
- | **リポジトリ [README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.ja.md)** | モノレポ構成、**`apps/` のサンプル**、貢献、MCP、プロジェクトアイコン |
121
+ | **リポジトリ [README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.ja.md)** | モノレポのハブ：**`apps/` のサンプル**、貢献入口、開発ツール案内 |
122
+ | **[CONTRIBUTING](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.ja.md#5-ai-アシスタントmcp--任意)** | リポジトリ貢献者向けの MCP / Cursor 設定 |
105
123
 
106
124
  ## ライセンス
107
125
 
package/README.md CHANGED
@@ -6,6 +6,8 @@
6
6
 
7
7
  A TypeScript library that wraps the Web Serial API with a minimal, session-oriented RxJS surface. The public API exposes a single `SerialSession` so applications can drive their UI from `state$` (canonical lifecycle state) + `errors$` (error event channel) + `receive$` + `lines$`, without rebuilding read loops or send queues themselves.
8
8
 
9
+ **Primary focus: UTF-8 text.** Incoming data is always decoded with a streaming UTF-8 `TextDecoder`. `receive$` emits **decoded text chunks** (unframed), not raw wire bytes. Binary **send** via `send$(Uint8Array)` is supported; binary **receive**, non-UTF-8 charsets, and protocol framing (Modbus, COBS, SLIP, …) are out of scope. See [Supported data](#supported-data-text--binary--charset) below and [API concepts](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/concepts.md#supported-data-text--binary--charset).
10
+
9
11
  ## Browser support
10
12
 
11
13
  The Web Serial API is supported on **desktop** browsers only. Smartphones and other mobile browsers are not supported.
@@ -23,21 +25,36 @@ Supported desktop browsers:
23
25
 
24
26
  ## Connection state (lifecycle UI)
25
27
 
26
- Prefer **`state$`** with `state.status` narrowing as the canonical API for lifecycle UI. Derive a boolean from `state$` when you only need a connected flag. Session teardown uses **`dispose$()`** (subscribe to run it). See [Migrating to v4](./docs/guide/en/migration-v4.md).
28
+ Prefer **`state$`** with `state.status` narrowing as the canonical API for lifecycle UI. Derive a boolean from `state$` when you only need a connected flag. Session teardown uses **`dispose$()`** (subscribe to run it). See [Migrating to v4](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/migration-v4.md).
27
29
 
28
30
  ## Port info (device identification)
29
31
 
30
- After a successful `connect$`, use `state.portInfo` when handling `state$` with `state.status === SerialSessionStatus.Connected` — this is the canonical API. Raw `SerialPort` is not exposed. Removed convenience APIs (`isConnected$`, `portInfo$`, `getPortInfo()`, `destroy$()`, `getCurrentPort()`, `receiveReplay$`, `isBrowserSupported()`) and their replacements are documented in [Migrating to v4](./docs/guide/en/migration-v4.md).
32
+ After a successful `connect$`, use `state.portInfo` when handling `state$` with `state.status === SerialSessionStatus.Connected` — this is the canonical API. Raw `SerialPort` is not exposed. Removed convenience APIs (`isConnected$`, `portInfo$`, `getPortInfo()`, `destroy$()`, `getCurrentPort()`, `receiveReplay$`, `isBrowserSupported()`) and their replacements are documented in [Migrating to v4](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/migration-v4.md).
33
+
34
+ ## Supported data (text / binary / charset)
35
+
36
+ | Item | Current support |
37
+ | --- | --- |
38
+ | UTF-8 text send / receive | Supported |
39
+ | Chunk-oriented string receive | `receive$` (decoded chunks, not wire bytes) |
40
+ | Newline-delimited string receive | `lines$` |
41
+ | Terminal display with `\r` redraws | `receive$` / `terminalText$` |
42
+ | Binary send | `send$(Uint8Array)` |
43
+ | Binary receive | **Not supported** (no raw `Uint8Array` receive stream) |
44
+ | Non-UTF-8 charsets | **Not supported** |
45
+ | Protocol framing (Modbus, COBS, SLIP, …) | **Application-side** |
46
+
47
+ Full notes and future design considerations: [API concepts — Supported data](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/concepts.md#supported-data-text--binary--charset).
31
48
 
32
49
  ## `receive$` vs `lines$`
33
50
 
34
51
  Pick the stream that matches your use case. Using **`lines$`** for a terminal mirror drops `\r` and redraw behaviour, which breaks shells and tools that rely on carriage-return updates ([overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/overview.md)).
35
52
 
36
- ### `receive$` (raw stream)
53
+ ### `receive$` (decoded chunks)
37
54
 
38
- - UTF-8 **decoder chunks** as they arrive—not line-aligned.
39
- - Preserves `\r`, partial lines, and other control characters.
40
- - Use for: **terminal display**, **prompt detection**, **buffering** / scrollback you control, and other **raw-stream** handling.
55
+ - UTF-8 **decoder chunks** as they arrive—not line-aligned, and **not** raw wire bytes.
56
+ - Preserves `\r`, partial lines, and other control characters from the decoded text.
57
+ - Use for: **terminal display**, **prompt detection**, **buffering** / scrollback you control, and other unframed decoded-stream handling.
41
58
 
42
59
  ### `lines$` (line-delimited events)
43
60
 
@@ -105,7 +122,8 @@ pnpm add rxjs
105
122
  | [v3 → v4 migration](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/migration-v4.md) | Phase 1+2 removals (`receiveReplay$`, `isBrowserSupported()`, options cleanup) |
106
123
  | [v2 → v3 migration](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/migration-v3.md) | `state$` discriminated union, `SerialSessionStatus`, `context.cause` |
107
124
  | [v1 → v2 migration](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/migration-v2.md) | Replacing the removed v1 `SerialClient` / `ShellClient` API |
108
- | [Repository README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.md) | Monorepo layout, **examples** under `apps/`, contributing, MCP, and project icon |
125
+ | [Repository README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.md) | Monorepo hub: **examples** under `apps/`, contribution entry, development-tool pointers |
126
+ | [CONTRIBUTING](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md#5-ai-assistant-mcp---optional) | MCP / Cursor setup for repository contributors |
109
127
 
110
128
  ## License
111
129
 
package/dist/session/serial-session.d.ts CHANGED
@@ -6,6 +6,13 @@ import type { SerialSessionState } from './serial-session-state';
6
6
  * Public API for interacting with the Web Serial API through a
7
7
  * minimal, session-oriented surface.
8
8
  *
9
+ * This interface is the **swappable public contract** for dependency injection
10
+ * and test fakes. Prefer typing application code against `SerialSession` and
11
+ * calling {@link createSerialSession} only at composition boundaries. Any
12
+ * object that structurally matches this shape (including a hand-written fake)
13
+ * is assignable to `SerialSession`; a separate `SerialSessionLike`-style
14
+ * alias is intentionally not exported.
15
+ *
9
16
  * The session is intentionally slim so that apps (Angular, Vue, React, etc.)
10
17
  * can drive their UI from `state$` (canonical lifecycle state) + `errors$`
11
18
  * (error event channel) + `receive$` + `terminalText$` + `lines$` and never
@@ -49,6 +56,7 @@ import type { SerialSessionState } from './serial-session-state';
49
56
  * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/199 | Issue #199}
50
57
  * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/200 | Issue #200}
51
58
  * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/203 | Issue #203}
59
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/536 | Issue #536}
52
60
  */
53
61
  export interface SerialSession {
54
62
  /**
package/dist/session/serial-session.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"serial-session.d.ts","sourceRoot":"","sources":["../../src/session/serial-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;;OASG;IACH,WAAW,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;CAC9C"}
1
+ {"version":3,"file":"serial-session.d.ts","sourceRoot":"","sources":["../../src/session/serial-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;;OASG;IACH,WAAW,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;CAC9C"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gurezo/web-serial-rxjs",
3
- "version": "4.0.2",
3
+ "version": "4.0.3",
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",
@@ -27,6 +27,7 @@
27
27
  "build:copy-files": "cp ../../LICENSE . 2>/dev/null || true",
28
28
  "build:cleanup": "rm -rf dist/packages dist/package.json 2>/dev/null || true",
29
29
  "verify:dist": "node scripts/verify-dist.mjs",
30
+ "verify:pack": "node scripts/verify-pack.mjs",
30
31
  "clean": "rm -rf dist",
31
32
  "prepublishOnly": "pnpm run build"
32
33
  },