@gurezo/web-serial-rxjs 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 gurezo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.ja.md

@@ -0,0 +1,599 @@
+# web-serial-rxjs
+
+Web Serial API を RxJS ベースのリアクティブなラッパーで提供する TypeScript ライブラリです。Web アプリケーションでシリアルポート通信を簡単に実現できます。
+
+## 目次
+
+- [機能](#機能)
+- [ブラウザサポート](#ブラウザサポート)
+- [インストール](#インストール)
+- [クイックスタート](#クイックスタート)
+- [使用例](#使用例)
+- [API リファレンス](#api-リファレンス)
+- [フレームワーク別の例](#フレームワーク別の例)
+- [高度な使用方法](#高度な使用方法)
+- [貢献](#貢献)
+- [ライセンス](#ライセンス)
+- [リンク](#リンク)
+
+## 機能
+
+- **RxJS ベースのリアクティブ API**: RxJS Observables を活用したリアクティブなシリアルポート通信
+- **TypeScript サポート**: 完全な TypeScript 型定義を含む
+- **ブラウザ検出**: ブラウザサポートの検出とエラーハンドリング機能を内蔵
+- **エラーハンドリング**: カスタムエラークラスとエラーコードによる包括的なエラーハンドリング
+- **フレームワーク非依存**: 任意の JavaScript/TypeScript フレームワークまたはバニラ JavaScript で使用可能
+
+## ブラウザサポート
+
+Web Serial API は現在、Chromium ベースのブラウザでのみサポートされています：
+
+- **Chrome** 89+
+- **Edge** 89+
+- **Opera** 75+
+
+このライブラリには、使用前に Web Serial API のサポートを確認するためのブラウザ検出ユーティリティが含まれています。
+
+## インストール
+
+npm または pnpm を使用してパッケージをインストールします：
+
+```bash
+npm install @gurezo/web-serial-rxjs
+# または
+pnpm add @gurezo/web-serial-rxjs
+```
+
+### ピア依存関係
+
+このライブラリは RxJS をピア依存関係として必要とします：
+
+```bash
+npm install rxjs
+# または
+pnpm add rxjs
+```
+
+**最小要件バージョン**: RxJS ^7.8.0
+
+## クイックスタート
+
+簡単な使用例：
+
+```typescript
+import {
+  createSerialClient,
+  isBrowserSupported,
+} from '@gurezo/web-serial-rxjs';
+
+// ブラウザサポートをチェック
+if (!isBrowserSupported()) {
+  console.error('このブラウザは Web Serial API をサポートしていません');
+  return;
+}
+
+// シリアルクライアントを作成
+const client = createSerialClient({ baudRate: 9600 });
+
+// シリアルポートに接続
+client.connect().subscribe({
+  next: () => {
+    console.log('シリアルポートに接続しました');
+
+    // シリアルポートからデータを読み取る
+    client.getReadStream().subscribe({
+      next: (data: Uint8Array) => {
+        const decoder = new TextDecoder('utf-8');
+        const text = decoder.decode(data);
+        console.log('受信:', text);
+      },
+      error: (error) => {
+        console.error('読み取りエラー:', error);
+      },
+    });
+
+    // シリアルポートにデータを書き込む
+    const encoder = new TextEncoder();
+    const data = encoder.encode('Hello, Serial Port!\n');
+    client.write(data).subscribe({
+      next: () => console.log('データを書き込みました'),
+      error: (error) => console.error('書き込みエラー:', error),
+    });
+  },
+  error: (error) => {
+    console.error('接続エラー:', error);
+  },
+});
+```
+
+## 使用例
+
+### 基本的な接続
+
+```typescript
+import { createSerialClient } from '@gurezo/web-serial-rxjs';
+
+const client = createSerialClient({
+  baudRate: 115200,
+  dataBits: 8,
+  stopBits: 1,
+  parity: 'none',
+});
+
+// 接続（ユーザーにポート選択を促す）
+client.connect().subscribe({
+  next: () => console.log('接続しました'),
+  error: (error) => console.error('接続に失敗しました:', error),
+});
+```
+
+### データの読み取り
+
+```typescript
+import { createSerialClient } from '@gurezo/web-serial-rxjs';
+import { map } from 'rxjs/operators';
+
+const client = createSerialClient({ baudRate: 9600 });
+
+client.connect().subscribe({
+  next: () => {
+    // データを読み取ってデコード
+    client
+      .getReadStream()
+      .pipe(
+        map((data: Uint8Array) => {
+          const decoder = new TextDecoder('utf-8');
+          return decoder.decode(data);
+        }),
+      )
+      .subscribe({
+        next: (text) => console.log('受信:', text),
+        error: (error) => console.error('読み取りエラー:', error),
+      });
+  },
+});
+```
+
+### データの書き込み
+
+```typescript
+import { createSerialClient } from '@gurezo/web-serial-rxjs';
+import { from } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+const client = createSerialClient({ baudRate: 9600 });
+
+client.connect().subscribe({
+  next: () => {
+    // 単一のチャンクを書き込む
+    const encoder = new TextEncoder();
+    const data = encoder.encode('Hello\n');
+    client.write(data).subscribe({
+      next: () => console.log('書き込みました'),
+      error: (error) => console.error('書き込みエラー:', error),
+    });
+
+    // Observable ストリームから書き込む
+    const messages = ['メッセージ 1\n', 'メッセージ 2\n', 'メッセージ 3\n'];
+    const dataStream$ = from(messages).pipe(
+      map((msg) => new TextEncoder().encode(msg)),
+    );
+    client.writeStream(dataStream$).subscribe({
+      next: () => console.log('すべてのメッセージを書き込みました'),
+      error: (error) => console.error('ストリーム書き込みエラー:', error),
+    });
+  },
+});
+```
+
+### エラーハンドリング
+
+```typescript
+import {
+  createSerialClient,
+  SerialError,
+  SerialErrorCode,
+} from '@gurezo/web-serial-rxjs';
+
+const client = createSerialClient({ baudRate: 9600 });
+
+client.connect().subscribe({
+  next: () => console.log('接続しました'),
+  error: (error) => {
+    if (error instanceof SerialError) {
+      switch (error.code) {
+        case SerialErrorCode.BROWSER_NOT_SUPPORTED:
+          console.error('ブラウザが Web Serial API をサポートしていません');
+          break;
+        case SerialErrorCode.PORT_NOT_AVAILABLE:
+          console.error('シリアルポートが利用できません');
+          break;
+        case SerialErrorCode.CONNECTION_LOST:
+          console.error('接続が切断されました');
+          break;
+        default:
+          console.error('シリアルエラー:', error.message);
+      }
+    } else {
+      console.error('不明なエラー:', error);
+    }
+  },
+});
+```
+
+### ポートフィルタリング
+
+```typescript
+import { createSerialClient } from '@gurezo/web-serial-rxjs';
+
+// USB ベンダー ID でポートをフィルタリング
+const client = createSerialClient({
+  baudRate: 9600,
+  filters: [{ usbVendorId: 0x1234 }, { usbVendorId: 0x5678 }],
+});
+
+// 特定のポートをリクエスト
+client.requestPort().subscribe({
+  next: (port) => {
+    console.log('ポートが選択されました:', port);
+    // 選択されたポートに接続
+    client.connect(port).subscribe({
+      next: () => console.log('フィルタリングされたポートに接続しました'),
+      error: (error) => console.error('接続エラー:', error),
+    });
+  },
+  error: (error) => console.error('ポートリクエストエラー:', error),
+});
+```
+
+## API リファレンス
+
+### `createSerialClient(options?)`
+
+新しい `SerialClient` インスタンスを作成します。
+
+**パラメータ:**
+
+- `options?` (オプション): `SerialClientOptions` - シリアルクライアントの設定オプション
+
+**戻り値:** `SerialClient` - 新しい SerialClient インスタンス
+
+**例:**
+
+```typescript
+const client = createSerialClient({
+  baudRate: 9600,
+  dataBits: 8,
+  stopBits: 1,
+  parity: 'none',
+});
+```
+
+### `SerialClient` インターフェース
+
+シリアルポートと対話するためのメインインターフェースです。
+
+#### メソッド
+
+##### `requestPort(): Observable<SerialPort>`
+
+ユーザーからシリアルポートをリクエストします。ポート選択のためのブラウザダイアログを開きます。
+
+**戻り値:** `Observable<SerialPort>` - 選択された `SerialPort` インスタンスを発行
+
+##### `getPorts(): Observable<SerialPort[]>`
+
+ユーザーが以前にアクセスを許可したすべての利用可能なシリアルポートを取得します。
+
+**戻り値:** `Observable<SerialPort[]>` - 利用可能な `SerialPort` インスタンスの配列を発行
+
+##### `connect(port?: SerialPort): Observable<void>`
+
+シリアルポートに接続します。ポートが提供されない場合、ユーザーにリクエストします。
+
+**パラメータ:**
+
+- `port?` (オプション): `SerialPort` - 接続するポート
+
+**戻り値:** `Observable<void>` - ポートが開かれたときに完了
+
+##### `disconnect(): Observable<void>`
+
+シリアルポートから切断します。
+
+**戻り値:** `Observable<void>` - ポートが閉じられたときに完了
+
+##### `getReadStream(): Observable<Uint8Array>`
+
+シリアルポートから読み取ったデータを発行する Observable を取得します。
+
+**戻り値:** `Observable<Uint8Array>` - データが受信されると `Uint8Array` チャンクを発行
+
+##### `writeStream(data$: Observable<Uint8Array>): Observable<void>`
+
+Observable ストリームからシリアルポートにデータを書き込みます。
+
+**パラメータ:**
+
+- `data$`: `Observable<Uint8Array>` - 書き込む `Uint8Array` チャンクを発行する Observable
+
+**戻り値:** `Observable<void>` - 書き込みが完了したときに完了
+
+##### `write(data: Uint8Array): Observable<void>`
+
+シリアルポートに単一のデータチャンクを書き込みます。
+
+**パラメータ:**
+
+- `data`: `Uint8Array` - 書き込むデータ
+
+**戻り値:** `Observable<void>` - データが書き込まれたときに完了
+
+#### プロパティ
+
+- `connected: boolean` - ポートが現在開いているかどうかを示す読み取り専用プロパティ
+- `currentPort: SerialPort | null` - 現在の `SerialPort` インスタンス、または接続されていない場合は `null` の読み取り専用プロパティ
+
+### `SerialClientOptions` インターフェース
+
+`SerialClient` を作成するための設定オプションです。
+
+```typescript
+interface SerialClientOptions {
+  baudRate?: number; // デフォルト: 9600
+  dataBits?: 7 | 8; // デフォルト: 8
+  stopBits?: 1 | 2; // デフォルト: 1
+  parity?: 'none' | 'even' | 'odd'; // デフォルト: 'none'
+  bufferSize?: number; // デフォルト: 255
+  flowControl?: 'none' | 'hardware'; // デフォルト: 'none'
+  filters?: SerialPortFilter[]; // オプションのポートフィルター
+}
+```
+
+**オプション:**
+
+- `baudRate` (オプション): 通信速度（ビット/秒）。デフォルト: `9600`
+- `dataBits` (オプション): 文字あたりのデータビット数。`7` または `8`。デフォルト: `8`
+- `stopBits` (オプション): ストップビット数。`1` または `2`。デフォルト: `1`
+- `parity` (オプション): パリティチェックモード。`'none'`、`'even'`、または `'odd'`。デフォルト: `'none'`
+- `bufferSize` (オプション): 読み取りバッファのサイズ。デフォルト: `255`
+- `flowControl` (オプション): フロー制御モード。`'none'` または `'hardware'`。デフォルト: `'none'`
+- `filters` (オプション): 利用可能なポートをフィルタリングする `SerialPortFilter` オブジェクトの配列
+
+### エラーハンドリング
+
+#### `SerialError` クラス
+
+シリアルポート操作のためのカスタムエラークラスです。
+
+```typescript
+class SerialError extends Error {
+  readonly code: SerialErrorCode;
+  readonly originalError?: Error;
+
+  is(code: SerialErrorCode): boolean;
+}
+```
+
+**プロパティ:**
+
+- `code`: `SerialErrorCode` - エラーコード
+- `originalError?`: `Error` - このエラーを引き起こした元のエラー（存在する場合）
+
+**メソッド:**
+
+- `is(code: SerialErrorCode): boolean` - エラーが特定のエラーコードと一致するかチェック
+
+#### `SerialErrorCode` 列挙型
+
+さまざまなタイプのシリアルポートエラーのエラーコード：
+
+- `BROWSER_NOT_SUPPORTED` - ブラウザが Web Serial API をサポートしていない
+- `PORT_NOT_AVAILABLE` - シリアルポートが利用できない
+- `PORT_OPEN_FAILED` - シリアルポートを開くのに失敗した
+- `PORT_ALREADY_OPEN` - シリアルポートは既に開いている
+- `PORT_NOT_OPEN` - シリアルポートが開いていない
+- `READ_FAILED` - シリアルポートからの読み取りに失敗した
+- `WRITE_FAILED` - シリアルポートへの書き込みに失敗した
+- `CONNECTION_LOST` - シリアルポート接続が切断された
+- `INVALID_FILTER_OPTIONS` - 無効なフィルターオプション
+- `OPERATION_CANCELLED` - 操作がキャンセルされた
+- `UNKNOWN` - 不明なエラー
+
+### ブラウザ検出ユーティリティ
+
+#### `isBrowserSupported(): boolean`
+
+ブラウザが Web Serial API をサポートしているかチェックします（例外を投げないバージョン）。
+
+**戻り値:** `boolean` - サポートされている場合は `true`、それ以外は `false`
+
+#### `checkBrowserSupport(): void`
+
+ブラウザが Web Serial API をサポートしているかチェックします。サポートされていない場合は `SerialError` を投げます。
+
+**例外:** Web Serial API をサポートしていない場合、`BROWSER_NOT_SUPPORTED` コードを持つ `SerialError` を投げます
+
+#### `detectBrowserType(): BrowserType`
+
+ユーザーエージェントからブラウザタイプを検出します。
+
+**戻り値:** `BrowserType` - `CHROME`、`EDGE`、`OPERA`、または `UNKNOWN` のいずれか
+
+#### `hasWebSerialSupport(): boolean`
+
+機能検出を使用してブラウザが Web Serial API サポートを持っているかチェックします。
+
+**戻り値:** `boolean` - Web Serial API が利用可能な場合は `true`、それ以外は `false`
+
+### I/O ユーティリティ
+
+#### `readableToObservable(stream: ReadableStream<Uint8Array>): Observable<Uint8Array>`
+
+`ReadableStream` を RxJS `Observable` に変換します。
+
+**パラメータ:**
+
+- `stream`: `ReadableStream<Uint8Array>` - 変換するストリーム
+
+**戻り値:** `Observable<Uint8Array>` - データチャンクを発行する Observable
+
+#### `observableToWritable(observable: Observable<Uint8Array>): WritableStream<Uint8Array>`
+
+RxJS `Observable` を `WritableStream` に変換します。
+
+**パラメータ:**
+
+- `observable`: `Observable<Uint8Array>` - 変換する observable
+
+**戻り値:** `WritableStream<Uint8Array>` - observable からデータを書き込む書き込み可能なストリーム
+
+#### `subscribeToWritable(observable: Observable<Uint8Array>, stream: WritableStream<Uint8Array>): { unsubscribe: () => void }`
+
+Observable を購読し、その値を WritableStream に書き込みます。
+
+**パラメータ:**
+
+- `observable`: `Observable<Uint8Array>` - 購読する observable
+- `stream`: `WritableStream<Uint8Array>` - 書き込むストリーム
+
+**戻り値:** `unsubscribe()` メソッドを持つ購読オブジェクト
+
+## フレームワーク別の例
+
+このリポジトリには、さまざまなフレームワークで web-serial-rxjs を使用する方法を示すサンプルアプリケーションが含まれています：
+
+- **[Vanilla JavaScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-js)** - バニラ JavaScript での基本的な使用方法
+- **[Vanilla TypeScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-ts)** - RxJS を使用した TypeScript の例
+- **[React](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-react)** - カスタムフック（`useSerialClient`）を使用した React の例
+- **[Vue](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vue)** - Composition API を使用した Vue 3 の例
+- **[Svelte](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-svelte)** - Svelte Store を使用した Svelte の例
+- **[Angular](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-angular)** - Service を使用した Angular の例
+
+各例には、セットアップと使用方法の説明を含む README が含まれています。
+
+## 高度な使用方法
+
+### Observable パターン
+
+RxJS オペレーターを使用してシリアルデータを処理できます：
+
+```typescript
+import { map, filter, bufferTime } from 'rxjs/operators';
+
+client
+  .getReadStream()
+  .pipe(
+    map((data: Uint8Array) => {
+      const decoder = new TextDecoder('utf-8');
+      return decoder.decode(data);
+    }),
+    filter((text) => text.trim().length > 0),
+    bufferTime(1000), // 1 秒間メッセージをバッファリング
+  )
+  .subscribe({
+    next: (messages) => {
+      console.log('バッファリングされたメッセージ:', messages);
+    },
+  });
+```
+
+### ストリーム処理
+
+RxJS オペレーターでデータストリームを処理：
+
+```typescript
+import { map, scan, debounceTime } from 'rxjs/operators';
+
+// 受信データを累積
+client
+  .getReadStream()
+  .pipe(
+    map((data: Uint8Array) => {
+      const decoder = new TextDecoder('utf-8');
+      return decoder.decode(data);
+    }),
+    scan((acc, current) => acc + current, ''),
+    debounceTime(500),
+  )
+  .subscribe({
+    next: (accumulated) => {
+      console.log('累積データ:', accumulated);
+    },
+  });
+```
+
+### カスタムフィルター
+
+ポートフィルターを使用して利用可能なポートを制限：
+
+```typescript
+const client = createSerialClient({
+  baudRate: 9600,
+  filters: [
+    { usbVendorId: 0x1234, usbProductId: 0x5678 },
+    { usbVendorId: 0xabcd },
+  ],
+});
+```
+
+### エラー回復
+
+エラー回復パターンを実装：
+
+```typescript
+import { retry, catchError } from 'rxjs/operators';
+import { of } from 'rxjs';
+
+client
+  .getReadStream()
+  .pipe(
+    retry({
+      count: 3,
+      delay: 1000,
+    }),
+    catchError((error) => {
+      console.error('リトライ後も失敗:', error);
+      return of(null); // 空の observable を返す
+    }),
+  )
+  .subscribe({
+    next: (data) => {
+      if (data) {
+        console.log('受信:', data);
+      }
+    },
+  });
+```
+
+## 開発とリリース戦略
+
+このプロジェクトは**trunk-based開発**アプローチに従います：
+
+- **`main`ブランチ**: 常にリリース可能な状態
+- **短命ブランチ**: `feature/*`, `fix/*`, `docs/*` はプルリクエスト用
+- **リリース**: ブランチではなくGitタグ（例: `v1.0.0`）で管理
+- **バージョン保守**: 複数のメジャーバージョンを保守する必要がある場合のみ `release/v*` ブランチを追加
+
+詳細な貢献ガイドラインについては、[CONTRIBUTING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.ja.md) を参照してください。
+
+## 貢献
+
+貢献を歓迎します！詳細については、[貢献ガイド](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.ja.md)を参照してください：
+
+- 開発環境のセットアップ
+- コードスタイルガイドライン
+- コミットメッセージの規約
+- プルリクエストのプロセス
+
+英語版の貢献ガイドは [CONTRIBUTING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md) を参照してください。
+
+## ライセンス
+
+このプロジェクトは MIT ライセンスの下で公開されています。詳細は [LICENSE](https://github.com/gurezo/web-serial-rxjs/blob/main/LICENSE) ファイルを参照してください。
+
+## リンク
+
+- **GitHub リポジトリ**: [https://github.com/gurezo/web-serial-rxjs](https://github.com/gurezo/web-serial-rxjs)
+- **イシュー**: [https://github.com/gurezo/web-serial-rxjs/issues](https://github.com/gurezo/web-serial-rxjs/issues)
+- **Web Serial API 仕様**: [https://wicg.github.io/serial/](https://wicg.github.io/serial/)

package/README.md

@@ -0,0 +1,598 @@
+# web-serial-rxjs
+
+A TypeScript library that provides a reactive RxJS-based wrapper for the Web Serial API, enabling easy serial port communication in web applications.
+
+## Table of Contents
+
+- [Features](#features)
+- [Browser Support](#browser-support)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage Examples](#usage-examples)
+- [API Reference](#api-reference)
+- [Framework Examples](#framework-examples)
+- [Advanced Usage](#advanced-usage)
+- [Contributing](#contributing)
+- [License](#license)
+- [Links](#links)
+
+## Features
+
+- **RxJS-based reactive API**: Leverage the power of RxJS Observables for reactive serial port communication
+- **TypeScript support**: Full TypeScript type definitions included
+- **Browser detection**: Built-in browser support detection and error handling
+- **Error handling**: Comprehensive error handling with custom error classes and error codes
+- **Framework agnostic**: Works with any JavaScript/TypeScript framework or vanilla JavaScript
+
+## Browser Support
+
+The Web Serial API is currently only supported in Chromium-based browsers:
+
+- **Chrome** 89+
+- **Edge** 89+
+- **Opera** 75+
+
+The library includes built-in browser detection utilities to check for Web Serial API support before attempting to use it.
+
+## Installation
+
+Install the package using npm or pnpm:
+
+```bash
+npm install @gurezo/web-serial-rxjs
+# or
+pnpm add @gurezo/web-serial-rxjs
+```
+
+### Peer Dependencies
+
+This library requires RxJS as a peer dependency:
+
+```bash
+npm install rxjs
+# or
+pnpm add rxjs
+```
+
+**Minimum required version**: RxJS ^7.8.0
+
+## Quick Start
+
+Here's a simple example to get you started:
+
+```typescript
+import {
+  createSerialClient,
+  isBrowserSupported,
+} from '@gurezo/web-serial-rxjs';
+
+// Check browser support
+if (!isBrowserSupported()) {
+  console.error('Web Serial API is not supported in this browser');
+  return;
+}
+
+// Create a serial client
+const client = createSerialClient({ baudRate: 9600 });
+
+// Connect to a serial port
+client.connect().subscribe({
+  next: () => {
+    console.log('Connected to serial port');
+
+    // Read data from the serial port
+    client.getReadStream().subscribe({
+      next: (data: Uint8Array) => {
+        const decoder = new TextDecoder('utf-8');
+        const text = decoder.decode(data);
+        console.log('Received:', text);
+      },
+      error: (error) => {
+        console.error('Read error:', error);
+      },
+    });
+
+    // Write data to the serial port
+    const encoder = new TextEncoder();
+    const data = encoder.encode('Hello, Serial Port!\n');
+    client.write(data).subscribe({
+      next: () => console.log('Data written'),
+      error: (error) => console.error('Write error:', error),
+    });
+  },
+  error: (error) => {
+    console.error('Connection error:', error);
+  },
+});
+```
+
+## Usage Examples
+
+### Basic Connection
+
+```typescript
+import { createSerialClient } from '@gurezo/web-serial-rxjs';
+
+const client = createSerialClient({
+  baudRate: 115200,
+  dataBits: 8,
+  stopBits: 1,
+  parity: 'none',
+});
+
+// Connect (will prompt user to select a port)
+client.connect().subscribe({
+  next: () => console.log('Connected'),
+  error: (error) => console.error('Connection failed:', error),
+});
+```
+
+### Reading Data
+
+```typescript
+import { createSerialClient } from '@gurezo/web-serial-rxjs';
+import { map } from 'rxjs/operators';
+
+const client = createSerialClient({ baudRate: 9600 });
+
+client.connect().subscribe({
+  next: () => {
+    // Read and decode data
+    client
+      .getReadStream()
+      .pipe(
+        map((data: Uint8Array) => {
+          const decoder = new TextDecoder('utf-8');
+          return decoder.decode(data);
+        }),
+      )
+      .subscribe({
+        next: (text) => console.log('Received:', text),
+        error: (error) => console.error('Read error:', error),
+      });
+  },
+});
+```
+
+### Writing Data
+
+```typescript
+import { createSerialClient } from '@gurezo/web-serial-rxjs';
+import { from } from 'rxjs';
+
+const client = createSerialClient({ baudRate: 9600 });
+
+client.connect().subscribe({
+  next: () => {
+    // Write a single chunk
+    const encoder = new TextEncoder();
+    const data = encoder.encode('Hello\n');
+    client.write(data).subscribe({
+      next: () => console.log('Written'),
+      error: (error) => console.error('Write error:', error),
+    });
+
+    // Write from an Observable stream
+    const messages = ['Message 1\n', 'Message 2\n', 'Message 3\n'];
+    const dataStream$ = from(messages).pipe(
+      map((msg) => new TextEncoder().encode(msg)),
+    );
+    client.writeStream(dataStream$).subscribe({
+      next: () => console.log('All messages written'),
+      error: (error) => console.error('Stream write error:', error),
+    });
+  },
+});
+```
+
+### Error Handling
+
+```typescript
+import {
+  createSerialClient,
+  SerialError,
+  SerialErrorCode,
+} from '@gurezo/web-serial-rxjs';
+
+const client = createSerialClient({ baudRate: 9600 });
+
+client.connect().subscribe({
+  next: () => console.log('Connected'),
+  error: (error) => {
+    if (error instanceof SerialError) {
+      switch (error.code) {
+        case SerialErrorCode.BROWSER_NOT_SUPPORTED:
+          console.error('Browser does not support Web Serial API');
+          break;
+        case SerialErrorCode.PORT_NOT_AVAILABLE:
+          console.error('Serial port is not available');
+          break;
+        case SerialErrorCode.CONNECTION_LOST:
+          console.error('Connection lost');
+          break;
+        default:
+          console.error('Serial error:', error.message);
+      }
+    } else {
+      console.error('Unknown error:', error);
+    }
+  },
+});
+```
+
+### Port Filtering
+
+```typescript
+import { createSerialClient } from '@gurezo/web-serial-rxjs';
+
+// Filter ports by USB vendor ID
+const client = createSerialClient({
+  baudRate: 9600,
+  filters: [{ usbVendorId: 0x1234 }, { usbVendorId: 0x5678 }],
+});
+
+// Request a specific port
+client.requestPort().subscribe({
+  next: (port) => {
+    console.log('Port selected:', port);
+    // Connect to the selected port
+    client.connect(port).subscribe({
+      next: () => console.log('Connected to filtered port'),
+      error: (error) => console.error('Connection error:', error),
+    });
+  },
+  error: (error) => console.error('Port request error:', error),
+});
+```
+
+## API Reference
+
+### `createSerialClient(options?)`
+
+Creates a new `SerialClient` instance.
+
+**Parameters:**
+
+- `options?` (optional): `SerialClientOptions` - Configuration options for the serial client
+
+**Returns:** `SerialClient` - A new SerialClient instance
+
+**Example:**
+
+```typescript
+const client = createSerialClient({
+  baudRate: 9600,
+  dataBits: 8,
+  stopBits: 1,
+  parity: 'none',
+});
+```
+
+### `SerialClient` Interface
+
+The main interface for interacting with serial ports.
+
+#### Methods
+
+##### `requestPort(): Observable<SerialPort>`
+
+Requests a serial port from the user. Opens a browser dialog for port selection.
+
+**Returns:** `Observable<SerialPort>` - Emits the selected `SerialPort` instance
+
+##### `getPorts(): Observable<SerialPort[]>`
+
+Gets all available serial ports that the user has previously granted access to.
+
+**Returns:** `Observable<SerialPort[]>` - Emits an array of available `SerialPort` instances
+
+##### `connect(port?: SerialPort): Observable<void>`
+
+Connects to a serial port. If no port is provided, will request one from the user.
+
+**Parameters:**
+
+- `port?` (optional): `SerialPort` - The port to connect to
+
+**Returns:** `Observable<void>` - Completes when the port is opened
+
+##### `disconnect(): Observable<void>`
+
+Disconnects from the serial port.
+
+**Returns:** `Observable<void>` - Completes when the port is closed
+
+##### `getReadStream(): Observable<Uint8Array>`
+
+Gets an Observable that emits data read from the serial port.
+
+**Returns:** `Observable<Uint8Array>` - Emits `Uint8Array` chunks as data is received
+
+##### `writeStream(data$: Observable<Uint8Array>): Observable<void>`
+
+Writes data to the serial port from an Observable stream.
+
+**Parameters:**
+
+- `data$`: `Observable<Uint8Array>` - Observable that emits `Uint8Array` chunks to write
+
+**Returns:** `Observable<void>` - Completes when writing is finished
+
+##### `write(data: Uint8Array): Observable<void>`
+
+Writes a single chunk of data to the serial port.
+
+**Parameters:**
+
+- `data`: `Uint8Array` - Data to write
+
+**Returns:** `Observable<void>` - Completes when the data is written
+
+#### Properties
+
+- `connected: boolean` - Read-only property indicating if the port is currently open
+- `currentPort: SerialPort | null` - Read-only property with the current `SerialPort` instance, or `null` if not connected
+
+### `SerialClientOptions` Interface
+
+Configuration options for creating a `SerialClient`.
+
+```typescript
+interface SerialClientOptions {
+  baudRate?: number; // Default: 9600
+  dataBits?: 7 | 8; // Default: 8
+  stopBits?: 1 | 2; // Default: 1
+  parity?: 'none' | 'even' | 'odd'; // Default: 'none'
+  bufferSize?: number; // Default: 255
+  flowControl?: 'none' | 'hardware'; // Default: 'none'
+  filters?: SerialPortFilter[]; // Optional port filters
+}
+```
+
+**Options:**
+
+- `baudRate` (optional): Communication speed in bits per second. Default: `9600`
+- `dataBits` (optional): Number of data bits per character. Either `7` or `8`. Default: `8`
+- `stopBits` (optional): Number of stop bits. Either `1` or `2`. Default: `1`
+- `parity` (optional): Parity checking mode. `'none'`, `'even'`, or `'odd'`. Default: `'none'`
+- `bufferSize` (optional): Size of the read buffer. Default: `255`
+- `flowControl` (optional): Flow control mode. `'none'` or `'hardware'`. Default: `'none'`
+- `filters` (optional): Array of `SerialPortFilter` objects to filter available ports
+
+### Error Handling
+
+#### `SerialError` Class
+
+Custom error class for serial port operations.
+
+```typescript
+class SerialError extends Error {
+  readonly code: SerialErrorCode;
+  readonly originalError?: Error;
+
+  is(code: SerialErrorCode): boolean;
+}
+```
+
+**Properties:**
+
+- `code`: `SerialErrorCode` - The error code
+- `originalError?`: `Error` - The original error that caused this error (if any)
+
+**Methods:**
+
+- `is(code: SerialErrorCode): boolean` - Check if the error matches a specific error code
+
+#### `SerialErrorCode` Enum
+
+Error codes for different types of serial port errors:
+
+- `BROWSER_NOT_SUPPORTED` - Browser does not support Web Serial API
+- `PORT_NOT_AVAILABLE` - Serial port is not available
+- `PORT_OPEN_FAILED` - Failed to open serial port
+- `PORT_ALREADY_OPEN` - Serial port is already open
+- `PORT_NOT_OPEN` - Serial port is not open
+- `READ_FAILED` - Failed to read from serial port
+- `WRITE_FAILED` - Failed to write to serial port
+- `CONNECTION_LOST` - Serial port connection lost
+- `INVALID_FILTER_OPTIONS` - Invalid filter options
+- `OPERATION_CANCELLED` - Operation was cancelled
+- `UNKNOWN` - Unknown error
+
+### Browser Detection Utilities
+
+#### `isBrowserSupported(): boolean`
+
+Checks if the browser supports the Web Serial API (non-throwing version).
+
+**Returns:** `boolean` - `true` if supported, `false` otherwise
+
+#### `checkBrowserSupport(): void`
+
+Checks if the browser supports the Web Serial API. Throws a `SerialError` if not supported.
+
+**Throws:** `SerialError` with code `BROWSER_NOT_SUPPORTED` if the browser doesn't support Web Serial API
+
+#### `detectBrowserType(): BrowserType`
+
+Detects the browser type from the user agent.
+
+**Returns:** `BrowserType` - One of `CHROME`, `EDGE`, `OPERA`, or `UNKNOWN`
+
+#### `hasWebSerialSupport(): boolean`
+
+Checks if the browser has Web Serial API support using feature detection.
+
+**Returns:** `boolean` - `true` if Web Serial API is available, `false` otherwise
+
+### I/O Utilities
+
+#### `readableToObservable(stream: ReadableStream<Uint8Array>): Observable<Uint8Array>`
+
+Converts a `ReadableStream` to an RxJS `Observable`.
+
+**Parameters:**
+
+- `stream`: `ReadableStream<Uint8Array>` - The stream to convert
+
+**Returns:** `Observable<Uint8Array>` - Observable that emits data chunks
+
+#### `observableToWritable(observable: Observable<Uint8Array>): WritableStream<Uint8Array>`
+
+Converts an RxJS `Observable` to a `WritableStream`.
+
+**Parameters:**
+
+- `observable`: `Observable<Uint8Array>` - The observable to convert
+
+**Returns:** `WritableStream<Uint8Array>` - Writable stream that writes data from the observable
+
+#### `subscribeToWritable(observable: Observable<Uint8Array>, stream: WritableStream<Uint8Array>): { unsubscribe: () => void }`
+
+Subscribes to an Observable and writes its values to a WritableStream.
+
+**Parameters:**
+
+- `observable`: `Observable<Uint8Array>` - The observable to subscribe to
+- `stream`: `WritableStream<Uint8Array>` - The stream to write to
+
+**Returns:** Subscription object with `unsubscribe()` method
+
+## Framework Examples
+
+This repository includes example applications demonstrating how to use web-serial-rxjs with different frameworks:
+
+- **[Vanilla JavaScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-js)** - Basic usage with vanilla JavaScript
+- **[Vanilla TypeScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-ts)** - TypeScript example with RxJS
+- **[React](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-react)** - React example with custom hook (`useSerialClient`)
+- **[Vue](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vue)** - Vue 3 example using Composition API
+- **[Svelte](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-svelte)** - Svelte example using Svelte Store
+- **[Angular](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-angular)** - Angular example using a Service
+
+Each example includes a README with setup and usage instructions.
+
+## Advanced Usage
+
+### Observable Patterns
+
+You can use RxJS operators to process serial data:
+
+```typescript
+import { map, filter, bufferTime } from 'rxjs/operators';
+
+client
+  .getReadStream()
+  .pipe(
+    map((data: Uint8Array) => {
+      const decoder = new TextDecoder('utf-8');
+      return decoder.decode(data);
+    }),
+    filter((text) => text.trim().length > 0),
+    bufferTime(1000), // Buffer messages for 1 second
+  )
+  .subscribe({
+    next: (messages) => {
+      console.log('Buffered messages:', messages);
+    },
+  });
+```
+
+### Stream Processing
+
+Process data streams with RxJS operators:
+
+```typescript
+import { map, scan, debounceTime } from 'rxjs/operators';
+
+// Accumulate received data
+client
+  .getReadStream()
+  .pipe(
+    map((data: Uint8Array) => {
+      const decoder = new TextDecoder('utf-8');
+      return decoder.decode(data);
+    }),
+    scan((acc, current) => acc + current, ''),
+    debounceTime(500),
+  )
+  .subscribe({
+    next: (accumulated) => {
+      console.log('Accumulated data:', accumulated);
+    },
+  });
+```
+
+### Custom Filters
+
+Use port filters to limit available ports:
+
+```typescript
+const client = createSerialClient({
+  baudRate: 9600,
+  filters: [
+    { usbVendorId: 0x1234, usbProductId: 0x5678 },
+    { usbVendorId: 0xabcd },
+  ],
+});
+```
+
+### Error Recovery
+
+Implement error recovery patterns:
+
+```typescript
+import { retry, catchError } from 'rxjs/operators';
+import { of } from 'rxjs';
+
+client
+  .getReadStream()
+  .pipe(
+    retry({
+      count: 3,
+      delay: 1000,
+    }),
+    catchError((error) => {
+      console.error('Failed after retries:', error);
+      return of(null); // Return empty observable
+    }),
+  )
+  .subscribe({
+    next: (data) => {
+      if (data) {
+        console.log('Received:', data);
+      }
+    },
+  });
+```
+
+## Development and Release Strategy
+
+This project follows a **trunk-based development** approach:
+
+- **`main` branch**: Always in a release-ready state
+- **Short-lived branches**: `feature/*`, `fix/*`, `docs/*` for pull requests
+- **Releases**: Managed via Git tags (e.g., `v1.0.0`), not branches
+- **Version maintenance**: `release/v*` branches are added only when needed for maintaining multiple major versions
+
+For detailed contribution guidelines, see [CONTRIBUTING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md).
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md) for details on:
+
+- Development setup
+- Code style guidelines
+- Commit message conventions
+- Pull request process
+
+For Japanese contributors, please see [CONTRIBUTING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.ja.md).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/gurezo/web-serial-rxjs/blob/main/LICENSE) file for details.
+
+## Links
+
+- **GitHub Repository**: [https://github.com/gurezo/web-serial-rxjs](https://github.com/gurezo/web-serial-rxjs)
+- **Issues**: [https://github.com/gurezo/web-serial-rxjs/issues](https://github.com/gurezo/web-serial-rxjs/issues)
+- **Web Serial API Specification**: [https://wicg.github.io/serial/](https://wicg.github.io/serial/)

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@gurezo/web-serial-rxjs",
+  "version": "0.1.0",
+  "description": "A TypeScript library that provides a reactive RxJS-based wrapper for the Web Serial API, enabling easy serial port communication in web applications.",
+  "author": "Akihiko Kigure <akihiko.kigure@gmail.com>",
+  "license": "MIT",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "README.ja.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "rxjs": "^7.8.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gurezo/web-serial-rxjs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gurezo/web-serial-rxjs/issues"
+  },
+  "homepage": "https://github.com/gurezo/web-serial-rxjs#readme",
+  "keywords": [
+    "rxjs",
+    "serial",
+    "web-serial",
+    "serial-port",
+    "reactive",
+    "observable",
+    "typescript",
+    "web-serial-api"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm run build:bundle && pnpm run build:copy-files",
+    "build:types": "tsc --project tsconfig.lib.json",
+    "build:bundle": "node esbuild.config.mjs",
+    "build:copy-files": "cp ../../LICENSE . 2>/dev/null || true",
+    "clean": "rm -rf dist"
+  }
+}