semantic-typescript 0.6.0 → 0.7.1

package/readme.jp.md

@@ -1,204 +1,267 @@
-# Semantic-TypeScript: パラダイムを転換するストリーム処理ライブラリ
+# **Semantic‑TypeScript**
+**ストリーム処理、インデックス化。** あなたのデータを精密に制御。
 
-## はじめに
-Semantic-TypeScriptは、ストリーム処理技術における大きな進歩を表しており、JavaScriptのジェネレーター関数、Javaストリーム、およびデータベースのインデックス作成パラダイムから最も効果的な概念を統合しています。その基本的な設計原則は、洗練された遅延評価とインテリジェントなインデックス作成を通じて、非常に効率的なデータ処理パイプラインを構築することに焦点を当てています。このライブラリは、現代のTypeScriptおよびJavaScript開発向けに特別に設計された、厳密に型安全で関数型的に純粋なストリーミング操作体験を提供します。
+---
 
-従来の同期処理アーキテクチャとは対照的に、Semantic-TypeScriptは同期（Iterable）と非同期（AsyncIterable）の両方のデータソースを優雅に扱う統一モデルを実装しています。ストリーム生成中、データの流れと終了はコールバックメカニズムによって正確に制御され、これにより、ライブラリは例外的な優雅さを持って以下の処理を可能にします：
-- 確定的な制御を伴うリアルタイムデータストリーム（DOMイベント、WebSocket、インターバル）
-- メモリ効率の良い遅延パイプラインによる大規模データセット
-- 流暢で宣言的なAPIによる複雑なデータ変換
+### 概要
 
-このライブラリの革新的なアプローチは、開発者がデータのシーケンスとどのように対話するかを根本的に再構想し、単一のまとまりのあるパッケージの中で、前例のないパフォーマンス特性と開発者の人間工学の両方を提供します。
+Semantic‑TypeScriptは、ストリーム処理における重要な進化を表しており、JavaScriptジェネレーター、Java Streams、MySQLスタイルのインデックス作成から最も効果的なパラダイムを優雅に**統合**しています。その基本理念は強力かつ意図的です：従来の力任せの反復処理ではなく、インテリジェントなインデックス作成を通じて、非常に効率的なデータ処理パイプラインを構築します。
 
-## コア哲学：定義と実行の分離
-Semantic-TypeScriptの主要なアーキテクチャ的洞察は、ストリームの定義とその実行の明確な分離です：
-- **Semantic<E>**: データ変換パイプラインの不変で遅延的な青写真。どのような操作（フィルター、マップなど）が実行されるかを定義します。
-- **Collectable<E>**: ストリームの実体化された実行可能なビュー。Semanticから取得され、パイプラインを実行して結果を生成するためのすべての終端操作（collect、forEachなど）を提供します。
+従来のライブラリが同期ループや煩雑なPromiseチェーンを強いるのに対し、Semantic‑TypeScriptは、現代のアプリケーション開発の要求に特化して設計された、**完全非同期**、機能的に純粋、かつ厳密に型安全な体験を提供します。
 
-この分離は明確なメンタルモデルを強制し、最大速度のために不要なソートをスキップするためにUnorderedCollectableを選択するなどの強力な最適化を可能にします。
+このモデルは洗練された制御フローを体現しています：データは、上流パイプラインが明示的に`accept`コールバックを呼び出す時だけ、下流のコンシューマーに渡されます。処理のタイミングについて、完全かつ細やかなコントロールを保持できます。処理は、必要とされる時、そしてその時にのみ正確に実行されます。
 
-## なぜSemantic-TypeScriptを選ぶのか？
-データストリーム処理に適切なライブラリを選択することは、パフォーマンス、型安全性、表現力のバランスを取ることを伴います。Semantic-TypeScriptは、これらすべての次元で優れるように設計されています。
+---
 
-### 1. すべてのデータシーケンスのための統一された型安全パラダイム
-静的配列、リアルタイムイベント、非同期チャンクなど、あらゆるデータシーケンスを処理するための一貫した宣言的APIを提供し、エンドツーエンドの型安全性を確保するためにTypeScriptの完全な力を活用します。これにより、ランタイムエラーの全クラスを排除し、ストリーム操作を予測可能でコンパイラ検証済みのアクティビティに変えます。
+### 開発者がSemantic‑TypeScriptを選ぶ理由
 
-### 2. インテリジェントな遅延性による妥協のないパフォーマンス
-中核的には、このライブラリは遅延評価に基づいて構築されています。フィルター、マップ、flatMapなどの操作は単に処理パイプラインを構成するだけで、終端操作が呼び出されるまで実際の作業は行われません。これは、limit、anyMatch、またはカスタム中断コールバックを介した短絡評価機能と組み合わされ、処理を早期に停止させ、大規模または無限のストリームの効率を劇的に向上させます。
+-   **ボイラープレート不要のインデックス作成** – 各要素は本来備わっている、またはカスタマイズされたインデックスを自然に保有し、手動での追跡を不要にします。
+-   **純粋関数型かつ型安全** – 不変な操作と共に、完全で慣用的なTypeScriptの型推論を享受できます。
+-   **メモリリーク防止のイベントストリーム** – `useSubscription`パターンは、リソースセキュリティを第一原則として設計されています。`limit(n)`、`sub(start, end)`、`takeWhile(predicate)`を使用して論理的な境界を定義するだけで、ライブラリが購読の完全なライフサイクルを管理します。これにより、残留リスナーやメモリリークは発生しません。
+-   **組み込み統計スイート** – 外部依存なしで、`number`および`bigint`ストリームに対する平均、中央値、最頻値、分散、歪度、尖度を含む包括的な分析機能にアクセスできます。
+-   **予測可能で調整可能なパフォーマンス** – 正確なパフォーマンスと順序要件に合わせて、順序付きまたは順序なしのコレクターを選択できます。
+-   **本質的にメモリ効率が良い** – ストリームは遅延評価され、メモリ負荷を軽減するため、要素はオンデマンドで処理されます。
+-   **未定義動作なし** – TypeScriptが完全な型安全性とnull安全性を保証します。コールバック関数内で明示的に変更しない限り、ソースデータは不変のままです。
 
-### 3. `Collector<E, A, R>` パターンの力
-Javaに触発され、Collectorパターンは柔軟性のエンジンです。これは、ストリーム要素をどのように累積するかの仕様を、ストリーム自体の実行から分離します。ライブラリは日常業務のための豊富な組み込みコレクタ（toArray、groupBy、summateなど）を提供する一方、独自の複雑で再利用可能なリダクションロジックを実装することを簡単にします。これは、固定された終端メソッドのセットよりもはるかに強力で合成可能です。
+---
 
-### 4. 現代のWebおよび非同期データへの第一級サポート
-Semantic-TypeScriptは、現代の開発のために設計されています。現代のWebソースに対するネイティブのファクトリメソッドを提供します：
-- 静的データのための `useFrom(iterable)`, `useRange()`
-- 時間ベースのストリームのための `useInterval()`, `useAnimationFrame()`
-- チャンク化されたバイナリデータ処理のための `useBlob()`
-- リアルタイムイベントストリームのための `useWebSocket()`, `useDocument()`, `useWindow()`
+### インストール
 
-### 5. 基本的な集計を超えて：組み込み統計分析
-単純な合計や平均を超えてください。このライブラリは専用のNumericStatisticsおよびBigIntStatisticsインターフェースを提供し、分散、標準偏差、中央値、歪度、尖度などの高度な統計尺度にストリームから直接アクセスできるようにします。これにより、複雑なデータ分析がワンライナーに変わります。
+お好みのパッケージマネージャーを使用して、プロジェクトにSemantic‑TypeScriptを統合します：
 
-### 6. 開発者の人間工学のために設計
-- **流暢で連鎖可能なAPI**: 複雑なデータパイプラインを読みやすい連続的なチェーンとして記述できます。
-- **包括的なユーティリティスイート**: 必須のガード（isFunction、isIterable）、ユーティリティ（useCompare、useTraverse）、および関数型インターフェースが含まれています。
-- **Optional<T> 統合**: 値の不在を安全にモデル化し、nullポインタの懸念を排除します。
-- **パフォーマンスガイダンス**: 速度のために順序なしコレクションを使用するタイミングと、シーケンスのために順序ありを使用するタイミングに関する明確なガイダンス。
-
-## インストール
 ```bash
 npm install semantic-typescript
 ```
+または
+```bash
+yarn add semantic-typescript
+```
 
-## 実践におけるコアコンセプト
+---
+
+### 実践的な紹介
+
+以下の例は、基本的な変換から実際のイベント処理までの核心概念を示しています。
 
-### 1. ストリームの作成（Semantic）
-ファクトリ関数を使用してさまざまなソースからストリームを作成できます。
 ```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
+import { useOf, useFrom, useRange, useSubscription, useText, useStringify } from "semantic-typescript";
+
+// ====================================================================
+// 例1: 基本的な操作と数値統計
+// ====================================================================
+// マッピング操作と終端統計操作を示します。変換後、パイプラインを統計コレクターに変換してから、`.summate()`などの終端メソッドを呼び出す必要があります。
+
+const numericSum: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)        // 各要素を2倍: [20, 40, 60, 80]
+  .toNumericStatistics()                    // 統計コレクターに変換
+  .summate();                               // 終端操作: 200
+
+// その他の統計メソッド（`.toNumericStatistics()`後に利用可能）:
+// .average(), .median(), .mode(), .variance(), .skewness(), .kurtosis()
+
+// ====================================================================
+// 例2: BigInt統計
+// ====================================================================
+// 数値統計と同様に動作しますが、BigIntデータ用に最適化されています。
+
+const bigintSum: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2n)       // BigInt演算
+  .toBigIntStatistics()                     // BigInt統計コレクターに変換
+  .summate();                               // 終端操作: 200n
+
+// ====================================================================
+// 例3: ストリーム反転のためのインデックス操作
+// ====================================================================
+// `.redirect()`メソッドを使用して、要素のインデックスを戦略的に再割り当てすることで要素を並べ替える方法を示し、反転などのカスタムパターンを可能にします。
+
+const reversedArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .redirect((_element: number, index: bigint): bigint => -index) // 負のインデックスにマッピング
+  .toOrdered()  // 必須: 新しいインデックスでソートされた要素を収集
+  .toArray();   // 結果: [5, 4, 3, 2, 1]
+
+// 単純な反転には、`.reverse()`も利用可能です。
+
+// ====================================================================
+// 例4: ストリームシャッフル
+// ====================================================================
+// インプレースシャッフルアルゴリズムを使用して、要素のインデックスをランダムに並べ替えます。
+
+const shuffledArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .shuffle()      // インデックスをランダムに再割り当て
+  .toOrdered()    // 新しいランダムなインデックスでソート
+  .toArray();     // 例: [2, 5, 1, 4, 3] (実行ごとに異なる)
+
+// ====================================================================
+// 例5: ストリームの循環ローテーション
+// ====================================================================
+// 要素を循環的にシフトします。正の値は右回転、負の値は左回転です。
+
+// 右へ2ポジション回転
+const rightRotated: number[] = useFrom([1, 2, 3, 4, 5])
+  .translate(2)   // インデックスを右に2つシフト
+  .toOrdered()
+  .toArray();     // 結果: [4, 5, 1, 2, 3]
+
+// ====================================================================
+// 例6: 無限範囲での遅延評価
+// ====================================================================
+// 理論的に無限のストリームを遅延的に処理し、必要な時だけ要素を計算します。
+
+const firstTenMultiples: bigint[] = useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)  // 17の倍数を保持
+  .limit(10n)                   // 重要: 10番目の一致後に停止
+  .toUnordered()                // ソートは不要
+  .toArray();                   // 結果: [0, 17, 34, 51, 68, 85, 102, 119, 136, 153]
+
+// `.limit(10n)`がなければ、パイプラインは100万要素すべてを処理します。
+
+// ====================================================================
+// 例7: 複雑なパイプラインの構築
+// ====================================================================
+// 複数の操作を順次組み合わせる方法を示します。
+
+const complexResult: number[] = useRange(1n, 100n)
+  .map(n => Number(n) * 2)
+  .filter(n => n > 50)
+  .shuffle()
+  .limit(5n)
+  .translate(2)
+  .toOrdered()
+  .toArray();
 
-// 静的配列から
-const staticStream = useFrom([1, 2, 3, 4, 5]);
+// ====================================================================
+// 例8: 管理されたDOMイベント購読
+// ====================================================================
+// 自動的でメモリリーク防止のクリーンアップ機能付きで、ブラウザイベントを監視します。
+// `.limit(n)`の呼び出しは、リスナーの自動削除の境界を定義します。
+
+// Windowターゲット用のサブスクライバーを定義
+const windowSubscriber = {
+    mount: (target: Window): void => { /* セットアップロジック */ },
+    subscribe: (target: Window, event: keyof WindowEventMap, handler: EventListener): void => {
+        target.addEventListener(event, handler);
+    },
+    unsubscribe: (target: Window, event: keyof WindowEventMap, handler: EventListener): void => {
+        target.removeEventListener(event, handler);
+    },
+    unmount: (): void => { /* クリーンアップロジック */ }
+};
+
+useSubscription(window, windowSubscriber, "resize")
+  .limit(5n) // 5イベント後に自動的に購読解除
+  .toUnordered()
+  .forEach((ev: Event, idx) =>
+    console.log(`リサイズ #${idx}: ${(ev.target as Window).innerWidth}x${(ev.target as Window).innerHeight}`)
+  );
 
-// 非同期ジェネレーターから
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
+// ====================================================================
+// 例9: Unicodeコードポイントによる文字列処理
+// ====================================================================
+// マルチバイトUnicode文字を正しく処理しながら、文字列を反復処理します。
 
-// 時間ベースのストリーム
-const tickStream = useInterval(1000); // 毎秒発行
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // 各文字（絵文字を含む）を改行して出力します。
 
-// DOMイベントストリーム（以下の重要な注意点を参照）
-const clickStream = useDocument('click');
-```
+// ====================================================================
+// 例10: 循環参照を含むオブジェクトの安全な文字列化
+// ====================================================================
+// 循環参照を含むオブジェクトを安全にシリアライズします。
 
-### 2. ストリームの変換（中間操作）
-操作は遅延的に連鎖してパイプラインを定義します。
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0) // 偶数だけを保持
-  .map(x => x * 10) // 10倍
-  .flatMap(x => [x, x + 1]) // 各要素を2つに変換
-  .distinct(); // 重複を削除
-// まだ何も実行されていません
-```
+const obj = {
+  a: 1,
+  b: "text"
+};
+(obj as any).c = [obj.a, obj.b, (obj as any).c]; // 循環参照を導入
 
-### 3. ストリームの実行（終端操作）
-結果を得るには、Collectableを取得し、終端操作を呼び出す必要があります。
-```typescript
-// パフォーマンスのために順序なしcollectableを取得
-const resultArray = await processedStream.toUnordered().toArray();
-console.log(resultArray); // 例: [20, 21, 40, 41]
-
-// 組み込みコレクタを使用
-const sum = await processedStream.toUnordered().collect(useSummate());
-console.log(sum);
-
-// または汎用collectメソッドを使用
-const customResult = await processedStream.toOrdered().collect(
-  () => new Map<number, number>(),
-  (map, element, index) => map.set(index, element),
-  map => map
-);
+// const text: string = JSON.stringify(obj); // エラーをスロー
+const text: string = useStringify(obj); // 安全に `{a: 1, b: "text", c: []}` を生成
 ```
 
-### 4. 重要：イベントストリームの操作
-イベントストリーム（useDocument、useWindow、useHTMLElement、useWebSocket）は本質的に無限です。イベントの収集を停止してストリームを完了するタイミングを定義するために、sub、takeWhile、limitなどの操作を使用する必要があります。そうしないと、終端操作は無期限に待機します。
-```typescript
-import { useDocument } from 'semantic-typescript';
+---
 
-// 最初の5回のクリックだけを収集
-const first5Clicks = await useDocument('click')
-  .limit(5) // <- 必須：ストリームを5つのイベントに制限
-  .toUnordered()
-  .toArray();
+### 核心概念
 
-// 10秒間のクリックを収集
-const clicksIn10s = await useDocument('click')
-  .takeWhile((_, index, startTime = Date.now()) => Date.now() - startTime < 10000)
-  .toUnordered()
-  .toArray();
+| 概念 | 目的 | 主な使用例 |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | 非同期ストリーム、イベント、およびプッシュベースの遅延パイプラインのためのコアビルダー。 | リアルタイムイベント、WebSockets、DOMリスナー、または長時間実行/無限ストリーム。 |
+| `SynchronousSemantic` | 同期、メモリ内、またはプルベースの即時評価パイプラインのビルダー。 | 静的データ、有限範囲、または即時の反復処理タスク。 |
+| `toUnordered()` | 最速の終端コレクター。インデックス格納にMapを使用。 | 安定した順序が不要な性能重視のパス（時間・空間計算量 O(n)）。 |
+| `toOrdered()` | ソート済みでインデックスが安定した終端コレクター。 | 要素の順序を保持する必要がある場合、またはインデックスアクセスが必要な場合。 |
+| `toNumericStatistics()` | `number`ストリームでの豊富な統計分析を可能にするコレクター。 | データ分析、メトリクス、統計計算。 |
+| `toBigIntStatistics()` | `bigint`ストリームでの豊富な統計分析を可能にするコレクター。 | 大きな整数データセットの分析と統計。 |
+| `toWindow()` | ストリームに対するスライディングおよびタンブリングウィンドウ操作を提供。 | 時系列分析、バッチ処理、ウィンドウ集計。 |
 
-// インデックス2から5（0ベース）のクリックを収集
-const specificClicks = await useDocument('click')
-  .sub(2n, 6n) // <- インデックス2、3、4、5の要素を取得
-  .toUnordered()
-  .toArray();
-```
+---
 
-**重要な洞察**: イベント（例：MouseEvent）とその連続的な発火インデックス（bigintとして）は、`accept(event, index)`コールバックを介してパイプラインを通して一緒に渡されます。
+**必須の使用ルール**
 
-### 5. 統計の活用
-```typescript
-const numericStream = useFrom([10, 20, 30, 40, 50]).toNumeric();
-const average = await numericStream.average();
-const median = await numericStream.median();
-const standardDeviation = await numericStream.standardDeviation();
-const skewness = await numericStream.skewness();
-console.log(`平均: ${average}, 中央値: ${median}, 標準偏差: ${standardDeviation}`);
-```
+1.  **イベントストリーム**（`useSubscription`などのファクトリー経由で作成）は`AsynchronousSemantic`を返します。
+    → リスナーを終了させるために、`.limit(n)`、`.sub(start, end)`、`.takeWhile(predicate)`などの境界定義メソッドを**必ず**呼び出す必要があります。そうしないと、購読がアクティブなままになります。
 
-## 主な機能
-- **デュアルストリームタイプ**: 同期（Iterable用）と非同期（AsyncIterableとイベント用）の両方のフルサポート
-- **豊富な操作セット**: filter, map, flatMap, concat, distinct, sorted, limit, skip, peek, reverse, shuffle
-- **柔軟な終端操作**: collect（カスタムコレクタ付き）, toArray, toSet, toMap, forEach, reduce, findFirst, anyMatch, allMatch, count
-- **高度なコレクタ**: 連結、グループ化、分割、合計、平均、最大値、最小値のための組み込みコレクタ
-- **統計モジュール**: 数値/ bigintストリームに対する平均、中央値、最頻値、分散、標準偏差、範囲、分位数、歪度、尖度のためのすぐに使えるメソッド
-- **ユーティリティ関数**: 型ガード（isPromise、isAsyncIterable）、コンパレータ（useCompare）、トラバーサル（useTraverse）、変換フック
-- **Optional<T>**: null許容値のためのモナディックコンテナ。検索操作と統合されています。
-
-## API概要
-### コアクラス＆インターフェース
-- `Semantic<E>` / `AsynchronousSemantic<E>`: 抽象ストリーム定義
-- `Collectable<E>` / `AsynchronousCollectable<E>`: 終端操作を持つ実行可能ストリーム
-- `OrderedCollectable<E>` / `UnorderedCollectable<E>`: 順序に敏感または順序に敏感でない操作に最適化された実体化バージョン
-- `Collector<E, A, R>`: 可変リダクション操作の抽象化
-
-### ファクトリ関数（use*）
-- **ソースから**: useFrom, useRange, useFill, useEmpty
-- **時間から**: useInterval, useAnimationFrame
-- **Web APIから**: useBlob, useDocument, useWindow, useHTMLElement, useWebSocket
-- **コレクタ**: useToArray, useGroupBy, useSummate, useJoin など
-
-## パフォーマンスに関する注意点
-- **遅延評価**: パイプラインは、終端操作が呼び出されるまで実行されずに構成されます
-- **短絡評価**: limit、anyMatch、findFirstなどの操作は、結果が決定するとすぐに要素の処理を停止します
-- **順序あり vs 順序なし**:
-    - ソース要素の順序が結果に影響しない終端操作（例：合計、最大値、またはtoSet）の場合、`.toUnordered()`を使用します。これにより、高価なソートステップをスキップする内部最適化が可能になる場合があります
-    - シーケンスが重要な場合（例：順序を保持する必要があるtoArray）には、`.toOrdered()`を使用します
-
-## はじめの一歩の例
-```typescript
-import { useFrom, useSummate, useGroupBy } from 'semantic-typescript';
-
-interface Transaction {
-  id: number;
-  amount: number;
-  category: string;
-}
-
-const transactions: Transaction[] = [
-  { id: 1, amount: 100, category: 'Food' },
-  { id: 2, amount: 200, category: 'Electronics' },
-  { id: 3, amount: 50, category: 'Food' },
-  { id: 4, amount: 300, category: 'Electronics' },
-];
-
-// カテゴリごとの合計金額を計算
-const totalsByCategory = await useFrom(transactions)
-  .toUnordered()
-  .collect(
-    useGroupBy(
-      t => t.category,
-      t => t.amount,
-      useSummate() // 値のためのコレクタ
-    )
-  );
+2.  **終端操作**（`.toArray()`、`.count()`、`.forEach()`、`.findFirst()`など）は、パイプラインをコレクターに変換した**後にのみ**利用可能です：
+    ```typescript
+    .toUnordered()   // 最大速度のため、順序は保証されません。
+    // または
+    .toOrdered()     // 安定した、ソートされた出力のため。
+    // または
+    .toNumericStatistics() // 統計メソッドのため。
+    ```
 
-console.log(totalsByCategory); // Map { 'Food' => 150, 'Electronics' => 500 }
-```
+---
+
+### パフォーマンス特性
+
+| コレクター | 時間計算量 | 空間計算量 | 順序保証？ | 理想的なシナリオ |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | いいえ | 生のスループットが鍵。最終的な順序は重要でない。 |
+| `toOrdered()` | O(n log n) | O(n) | はい（ソート済み） | 安定した順序、インデックスアクセス、または統計用の事前ソートが必要な場合。 |
+| `toNumericStatistics()` | O(n log n) | O(n) | はい（内部ソート） | ソートされたデータを必要とする統計操作の実行。 |
+| `toBigIntStatistics()` | O(n log n) | O(n) | はい（内部ソート） | BigIntデータでの統計操作。 |
+| `toWindow()` | O(n log n) | O(n) | はい（内部ソート） | ソートされたインデックスから恩恵を受けるウィンドウ操作。 |
+
+絶対的な速度が最重要である場合は`toUnordered()`を選択してください。ロジックが要素の順序に依存する場合にのみ、`toOrdered()`または統計コレクターを選択してください。
+
+---
+
+**現代ストリームライブラリとの比較分析**
+
+| 機能 | Semantic‑TypeScript | RxJS | ネイティブ Async Iterators / Generators | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **TypeScript統合** | ファーストクラス、深い型付け、インデックス認識を内包。 | 優れているが、複雑なジェネリックチェーンを伴うことが多い。 | 良いが、手動の型注釈が必要。 | 強い、関数型ファーストの型付けスタイル。 |
+| **組み込み統計分析** | `number`および`bigint`に対する包括的なネイティブサポート。 | ネイティブでは利用不可（カスタムオペレーターまたは他のライブラリが必要）。 | なし。 | なし。 |
+| **インデックス作成と位置認識** | 各要素に対するネイティブで強力なBigIntインデックス作成。 | カスタムオペレーターが必要（例: `scan`、`withLatestFrom`）。 | 手動でのカウンター管理が必要。 | 基本的、組み込みのインデックスプロパティなし。 |
+| **イベントストリーム管理** | 明示的で宣言的なライフサイクル制御を備えた、型安全な専用ファクトリー。 | 強力だが、メモリリークを防ぐためには注意深い手動購読管理が必要。 | イベントリスナーの手動登録とキャンセルトークンの管理。 | 良い`fromEvent`、一般的に軽量。 |
+| **パフォーマンスとメモリ** | 卓越 – 最適化された`toUnordered()`および`toOrdered()`コレクターを提供。 | 非常に良いが、深いオペレーターチェーンはオーバーヘッドをもたらす可能性あり。 | 優れている（ネイティブオーバーヘッド最小限）。 | 優れている。 |
+| **バンドルサイズ** | 非常に軽量。 | 大きい（ツリーシェイキング後でも）。 | ゼロ（言語のネイティブ機能）。 | 小さい。 |
+| **API設計思想** | 明示的なインデックス意味論を持つ関数型コレクターパターン。 | リアクティブObservableパターン。 | 命令型Iterator / 宣言型Generatorパターン。 | 関数型、ポイントフリー構成。 |
+| **フロー制御** | 明示的（`interrupt`、`.limit()`、`.takeWhile()`、`.sub()`）。 | 良い（`take`、`takeUntil`、`first`）。 | 手動（ループ内の`break`）。 | 良い（`take`、`until`）。 |
+| **同期および非同期サポート** | 統一API – 両パラダイムに対するファーストクラスサポート。 | 主に非同期。 | 両方サポートされているが、手動ブリッジが必要。 | 主に非同期。 |
+| **学習曲線** | 関数型およびインデックス付きコレクションパイプラインに慣れた開発者には穏やか。 | 急（オペレーター語彙が広範、Hot/Cold Observable概念）。 | 低から中程度。 | 中程度。 |
+
+**Semantic‑TypeScriptの利点**
+
+*   **独自の能力：** 組み込みの統計およびインデックス作成機能により、手動の`reduce`操作や補助的なデータ分析ライブラリの必要性がなくなります。
+*   **予測可能なリソース管理：** イベントストリームに対する明示的な制御により、RxJSアプリケーションで発生しうる微妙なメモリリークを防止します。
+*   **統一された設計：** 同期および非同期ワークフロー両方の一貫したAPIにより、認知負荷とコード重複が減少します。
+
+この比較は、従来のリアクティブフレームワークの複雑さなしに、高いパフォーマンス、堅牢な型安全性、および豊富なデータ処理機能を要求する現代のTypeScriptアプリケーションに、Semantic‑TypeScriptが特に適している理由を強調しています。
+
+---
+
+### 探求を始めよう
+
+Semantic‑TypeScriptは、複雑なデータフローを読みやすく、構成可能で、高性能なパイプラインに変換します。リアルタイムUIイベントの処理、大規模データセットの処理、分析ダッシュボードの構築のいずれにおいても、データベースレベルのインデックス作成のパワーと関数型プログラミングのエレガンスを提供します。
+
+**次のステップ：**
+
+*   IDE内で直接、完全に型付けされたAPIを探索してください（すべてのエクスポートはメインパッケージエントリーポイントから利用可能です）。
+*   複雑な非同期イテレータやリアクティブチェーンを、明確で意図的なSemanticパイプラインに置き換えた開発者の成長するコミュニティに参加してください。
+
+**Semantic‑TypeScript** – ストリームと構造が出会う場所。
+
+今日から構築を始め、考え抜かれたインデックス作成がもたらす明確な違いを体験してください。
 
-Semantic-TypeScriptは、厳密に設計された、型安全で高性能なストリーム処理ライブラリを求める開発者のために構築されています。これは、エンタープライズレベルのデータ変換パターンの力をTypeScriptエコシステムにもたらし、データ集約型のフロントエンドアプリケーション、Node.jsデータ処理、シーケンスのエレガントで効率的な処理が必要とされるあらゆるシナリオに最適です。
+**明確さをもって構築し、自信をもって前進し、意図をもってデータを変換する。**
 
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript)
+MIT © Eloy Kim