semantic-typescript 0.0.7 → 0.1.4

package/readme.jp.md

@@ -1,335 +1,427 @@
-# 📘 semantic-typescript
+# Semantic-TypeScript ストリーム処理ライブラリ
 
-TypeScript における**意味論的なデータ処理**のための、強力で型安全なユーティリティライブラリです。  
-コレクション、ストリーム、シーケンスを扱うための関数的スタイルの構成要素を提供し、ソート、フィルタリング、グループ化、統計分析などをサポートします。
+## 概要
 
-**順序付きまたは順序なしのデータ**を処理する場合でも、**統計分析**を行う場合でも、単に**演算を流れるようにチェーンしたい**場合でも、本ライブラリが対応します。
+Semantic-TypeScriptは、JavaScript GeneratorFunction、Java Stream、MySQL Indexにインスパイアされたモダンなストリーム処理ライブラリです。このライブラリのコア設計は、データインデックスに基づいた効率的なデータ処理パイプラインの構築にあり、型安全で関数型スタイルのストリーム操作体験をフロントエンド開発者に提供します。
 
----
+従来の同期処理とは異なり、Semanticは非同期処理モードを採用しています。データストリームを作成する際、端末がデータを受信するタイミングは、アップストリームが`accept`および`interrupt`コールバック関数をいつ呼び出すかに完全に依存します。この設計により、ライブラリはリアルタイムデータストリーム、大規模データセット、非同期データソースを優雅に処理できます。
 
-## 🧩 特徴
-
-- ✅ 全面的に**型安全なジェネリクス**
-- ✅ **関数型プログラミング**スタイル（map、filter、reduce など）
-- ✅ **意味論的データストリーム**（`Semantic<E>`）による遅延評価
-- ✅ ストリームを具体的な構造に変換するための**コレクター**
-- ✅ **順序付き＆順序なしコレクション** — `toUnordered()` は**最速**（ソートなし）
-- ✅ `sorted()`、`toOrdered()`、比較器による**ソート機能**
-- ✅ **統計分析**（`Statistics`、`NumericStatistics`、`BigIntStatistics`）
-- ✅ 安全な null 値処理のための **`Optional<T>` モナド**
-- ✅ **イテレータとジェネレーター**ベースの設計 — 大規模・非同期データにも適応
-
----
-
-## 📦 インストール
+## インストール
 
 ```bash
 npm install semantic-typescript
 ```
 
----
-
-## 🧠 コア概念
-
-### 1. `Optional<T>` – 安全な null 値処理
-
-`null` または `undefined` になり得る値を格納するモナディックコンテナです。
-
-#### メソッド：
-
-| メソッド | 説明 | 例 |
-|----------|------|-----|
-| `of(value)` | 値をラップ（nullish も可） | `Optional.of(null)` |
-| `ofNullable(v)` | ラップ（nullish を許容） | `Optional.ofNullable(someVar)` |
-| `ofNonNull(v)` | ラップ（null/undefined なら例外） | `Optional.ofNonNull(5)` |
-| `get()` | 値を取得（空なら例外） | `opt.get()` |
-| `getOrDefault(d)` | 値を取得、空ならデフォルト値 | `opt.getOrDefault(0)` |
-| `ifPresent(fn)` | 値があれば副作用を実行 | `opt.ifPresent(x => console.log(x))` |
-| `map(fn)` | 値があれば変換 | `opt.map(x => x + 1)` |
-| `filter(fn)` | 述語を満たす場合のみ値を保持 | `opt.filter(x => x > 0)` |
-| `isEmpty()` | 空かどうかを確認 | `opt.isEmpty()` |
-| `isPresent()` | 値を持つかどうかを確認 | `opt.isPresent()` |
-
-#### 例：
+## 基本型
+
+| 型 | 説明 |
+|----|------|
+| `Invalid<T>` | nullまたはundefinedを拡張する型 |
+| `Valid<T>` | nullとundefinedを除外する型 |
+| `MaybeInvalid<T>` | nullまたはundefinedになり得る型 |
+| `Primitive` | プリミティブ型のコレクション |
+| `MaybePrimitive<T>` | プリミティブ型になり得る型 |
+| `OptionalSymbol` | Optionalクラスのシンボル識別子 |
+| `SemanticSymbol` | Semanticクラスのシンボル識別子 |
+| `CollectorsSymbol` | Collectorクラスのシンボル識別子 |
+| `CollectableSymbol` | Collectableクラスのシンボル識別子 |
+| `OrderedCollectableSymbol` | OrderedCollectableクラスのシンボル識別子 |
+| `WindowCollectableSymbol` | WindowCollectableクラスのシンボル識別子 |
+| `StatisticsSymbol` | Statisticsクラスのシンボル識別子 |
+| `NumericStatisticsSymbol` | NumericStatisticsクラスのシンボル識別子 |
+| `BigIntStatisticsSymbol` | BigIntStatisticsクラスのシンボル識別子 |
+| `UnorderedCollectableSymbol` | UnorderedCollectableクラスのシンボル識別子 |
+| `Runnable` | パラメータなし、戻り値なしの関数 |
+| `Supplier<R>` | パラメータなしでRを返す関数 |
+| `Functional<T, R>` | 単一パラメータ変換関数 |
+| `Predicate<T>` | 単一パラメータ述語関数 |
+| `BiFunctional<T, U, R>` | 二重パラメータ変換関数 |
+| `BiPredicate<T, U>` | 二重パラメータ述語関数 |
+| `Comparator<T>` | 比較関数 |
+| `TriFunctional<T, U, V, R>` | 三重パラメータ変換関数 |
+| `Consumer<T>` | 単一パラメータ消費関数 |
+| `BiConsumer<T, U>` | 二重パラメータ消費関数 |
+| `TriConsumer<T, U, V>` | 三重パラメータ消費関数 |
+| `Generator<T>` | ジェネレーター関数 |
 
 ```typescript
-import { Optional } from 'semantic-typescript';
-
-const value: number | null = Math.random() > 0.5 ? 10 : null;
-
-const opt = Optional.ofNullable(value);
-
-const result = opt
-  .filter(v => v > 5)
-  .map(v => v * 2)
-  .getOrDefault(0);
-
-console.log(result); // 20 または 0
+// 型使用例
+const predicate: Predicate<number> = (n) => n > 0;
+const mapper: Functional<string, number> = (str) => str.length;
+const comparator: Comparator<number> = (a, b) => a - b;
 ```
 
----
+## 型ガード
+
+| 関数 | 説明 | 時間計算量 | 空間計算量 |
+|------|------|------------|------------|
+| `validate<T>(t: MaybeInvalid<T>): t is T` | 値がnullまたはundefinedでないことを検証 | O(1) | O(1) |
+| `invalidate<T>(t: MaybeInvalid<T>): t is null \| undefined` | 値がnullまたはundefinedであることを検証 | O(1) | O(1) |
+| `isBoolean(t: unknown): t is boolean` | ブーリアンかどうかチェック | O(1) | O(1) |
+| `isString(t: unknown): t is string` | 文字列かどうかチェック | O(1) | O(1) |
+| `isNumber(t: unknown): t is number` | 数値かどうかチェック | O(1) | O(1) |
+| `isFunction(t: unknown): t is Function` | 関数かどうかチェック | O(1) | O(1) |
+| `isObject(t: unknown): t is object` | オブジェクトかどうかチェック | O(1) | O(1) |
+| `isSymbol(t: unknown): t is symbol` | シンボルかどうかチェック | O(1) | O(1) |
+| `isBigint(t: unknown): t is bigint` | BigIntかどうかチェック | O(1) | O(1) |
+| `isPrimitive(t: unknown): t is Primitive` | プリミティブ型かどうかチェック | O(1) | O(1) |
+| `isIterable(t: unknown): t is Iterable<unknown>` | 反復可能かどうかチェック | O(1) | O(1) |
+| `isOptional(t: unknown): t is Optional<unknown>` | Optionalインスタンスかどうかチェック | O(1) | O(1) |
+| `isSemantic(t: unknown): t is Semantic<unknown>` | Semanticインスタンスかどうかチェック | O(1) | O(1) |
+| `isCollector(t: unknown): t is Collector<unknown, unknown, unknown>` | Collectorインスタンスかどうかチェック | O(1) | O(1) |
+| `isCollectable(t: unknown): t is Collectable<unknown>` | Collectableインスタンスかどうかチェック | O(1) | O(1) |
+| `isOrderedCollectable(t: unknown): t is OrderedCollectable<unknown>` | OrderedCollectableインスタンスかどうかチェック | O(1) | O(1) |
+| `isWindowCollectable(t: unknown): t is WindowCollectable<unknown>` | WindowCollectableインスタンスかどうかチェック | O(1) | O(1) |
+| `isUnorderedCollectable(t: unknown): t is UnorderedCollectable<unknown>` | UnorderedCollectableインスタンスかどうかチェック | O(1) | O(1) |
+| `isStatistics(t: unknown): t is Statistics<unknown, number \| bigint>` | Statisticsインスタンスかどうかチェック | O(1) | O(1) |
+| `isNumericStatistics(t: unknown): t is NumericStatistics<unknown>` | NumericStatisticsインスタンスかどうかチェック | O(1) | O(1) |
+| `isBigIntStatistics(t: unknown): t is BigIntStatistics<unknown>` | BigIntStatisticsインスタンスかどうかチェック | O(1) | O(1) |
 
-### 2. `Semantic<E>` – 遅延データストリーム
+```typescript
+// 型ガード使用例
+const value: unknown = "hello";
 
-要素の**遅延評価可能な合成可能シーケンス**です。Java Streams や Kotlin Sequences のような関数的ストリームに似ています。
+if (isString(value)) {
+    console.log(value.length); // 型安全、valueはstringと推論
+}
 
-`from()`、`range()`、`iterate()`、`fill()` などのヘルパーで `Semantic` を作成できます。
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
+}
+```
 
-#### 作成メソッド：
+## ユーティリティ関数
 
-| 関数 | 説明 | 例 |
-|------|------|-----|
-| `from(iterable)` | Array/Set/Iterable から作成 | `from([1, 2, 3])` |
-| `range(start, end, step?)` | 数値範囲を生成 | `range(0, 5)` → 0,1,2,3,4 |
-| `fill(element, count)` | 要素を N 回繰り返す | `fill('a', 3n)` |
-| `iterate(gen)` | カスタムジェネレーター関数を使用 | `iterate(genFn)` |
+| 関数 | 説明 | 時間計算量 | 空間計算量 |
+|------|------|------------|------------|
+| `useCompare<T>(t1: T, t2: T): number` | 汎用比較関数 | O(1) | O(1) |
+| `useRandom<T = number \| bigint>(index: T): T` | 擬似乱数生成器 | O(log n) | O(1) |
 
-#### 主な演算子：
+```typescript
+// ユーティリティ関数使用例
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-| メソッド | 説明 | 例 |
-|----------|------|-----|
-| `map(fn)` | 各要素を変換 | `.map(x => x * 2)` |
-| `filter(fn)` | 述語を満たす要素を保持 | `.filter(x => x > 10)` |
-| `limit(n)` | 最初の N 要素に制限 | `.limit(5)` |
-| `skip(n)` | 最初の N 要素をスキップ | `.skip(2)` |
-| `distinct()` | 重複を除去（デフォルトで Set を使用） | `.distinct()` |
-| `sorted()` | 要素をソート（自然順） | `.sorted()` |
-| `sorted(comparator)` | カスタムソート | `.sorted((a, b) => a - b)` |
-| `toOrdered()` | ソートして `OrderedCollectable` を返す | `.toOrdered()` |
-| `toUnordered()` | **ソートなし** – 最速のコレクション | `.toUnordered()` ✅ |
-| `collect(collector)` | コレクターで集約 | `.collect(Collector.full(...))` |
-| `toArray()` | 配列に変換 | `.toArray()` |
-| `toSet()` | Set に変換 | `.toSet()` |
-| `toMap(keyFn, valFn)` | Map に変換 | `.toMap(x => x.id, x => x)` |
+const randomNum = useRandom(42); // シードベースの乱数
+const randomBigInt = useRandom(1000n); // BigInt乱数
+```
 
----
+## ファクトリメソッド
 
-### 3. `toUnordered()` – 🚀 最速、ソートなし
+### Optionalファクトリメソッド
 
-**順序を必要とせず**、**最高のパフォーマンス**を求める場合は、以下を使用してください：
+| メソッド | 説明 | 時間計算量 | 空間計算量 |
+|---------|------|------------|------------|
+| `Optional.empty<T>()` | 空のOptionalを作成 | O(1) | O(1) |
+| `Optional.of<T>(value)` | 値を持つOptionalを作成 | O(1) | O(1) |
+| `Optional.ofNullable<T>(value)` | null許容Optionalを作成 | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value)` | 非nullOptionalを作成 | O(1) | O(1) |
 
 ```typescript
-const fastest = semanticStream.toUnordered();
+// Optional使用例
+const emptyOpt = Optional.empty<number>();
+const presentOpt = Optional.of(42);
+const nullableOpt = Optional.ofNullable<string>(null);
+const nonNullOpt = Optional.ofNonNull("hello");
+
+presentOpt.ifPresent(val => console.log(val)); // 42を出力
+console.log(emptyOpt.orElse(100)); // 100を出力
 ```
 
-🔥 **ソートアルゴリズムは適用されません。**  
-順序が関係なく、最大の速度が必要な場合に理想的です。
-
----
+### Collectorファクトリメソッド
 
-### 4. `toOrdered()` および `sorted()` – ソート済み出力
-
-**ソート済み出力**が必要な場合は、以下を使用してください：
+| メソッド | 説明 | 時間計算量 | 空間計算量 |
+|---------|------|------------|------------|
+| `Collector.full(identity, accumulator, finisher)` | 完全なコレクターを作成 | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | 中断可能なコレクターを作成 | O(1) | O(1) |
 
 ```typescript
-const ordered = semanticStream.sorted(); // 自然順
-const customSorted = semanticStream.sorted((a, b) => a - b); // カスタム比較器
-const orderedCollectable = semanticStream.toOrdered(); // こちらもソート
+// Collector使用例
+const sumCollector = Collector.full(
+    () => 0,
+    (sum, num) => sum + num,
+    result => result
+);
+
+const numbers = from([1, 2, 3, 4, 5]);
+const total = numbers.toUnoredered().collect(sumCollector); // 15
 ```
 
-⚠️ これらのメソッドは、自然順または指定された比較器を使用して要素を**ソートします**。
-
----
+### Semanticファクトリメソッド
 
-### 5. `Collector<E, A, R>` – データ集約
-
-コレクターにより、ストリームを**単一または複雑な構造に縮約**できます。
-
-組み込みの静的ファクトリー：
+| メソッド | 説明 | 時間計算量 | 空間計算量 |
+|---------|------|------------|------------|
+| `blob(blob, chunkSize)` | Blobからストリームを生成 | O(n) | O(chunkSize) |
+| `empty<E>()` | 空のストリームを生成 | O(1) | O(1) |
+| `fill<E>(element, count)` | 埋め尽くされたストリームを生成 | O(n) | O(1) |
+| `from<E>(iterable)` | 反復可能オブジェクトからストリームを生成 | O(1) | O(1) |
+| `interval(period, delay?)` | 定期的なインターバルストリームを生成 | O(1)* | O(1) |
+| `iterate<E>(generator)` | ジェネレータからストリームを生成 | O(1) | O(1) |
+| `range(start, end, step)` | 数値範囲ストリームを生成 | O(n) | O(1) |
+| `websocket(websocket)` | WebSocketからストリームを生成 | O(1) | O(1) |
 
 ```typescript
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// Semanticファクトリメソッドの使用例
+
+// Blobからストリームを作成（チャンク読み込み）
+blob(someBlob, 1024n)
+  .toUnordered()
+  .write(WritableStream)
+  .then(callback) // ストリーム書き込み成功
+  .catch(writeFi); // ストリーム書き込み失敗
+
+// 他のストリームと連結されるまで実行されない空ストリームを作成
+empty<string>()
+  .toUnordered()
+  .join(); //[]
+
+// 埋め尽くされたストリームを作成
+const filledStream = fill("hello", 3); // "hello", "hello", "hello"
+
+// 初期遅延2秒、実行周期5秒の時系列ストリームを作成
+// タイマーメカニズムで実装、システムスケジューリング制限による時間変動の可能性あり
+const intervalStream = interval(5000, 2000);
+
+// 反復可能オブジェクトからストリームを作成
+const numberStream = from([1, 2, 3, 4, 5]);
+const stringStream = from(new Set(["Alex", "Bob"]));
+
+// 範囲ストリームを作成
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
+
+// WebSocketイベントストリーム
+const ws = new WebSocket("ws://localhost:8080");
+websocket(ws)
+  .filter((event)=> event.type === "message") // メッセージイベントのみ監視
+  .toUnordered() // イベントは通常ソート不要
+  .forEach((event)=> receive(event)); // メッセージ受信
 ```
 
-通常、`Collectable` クラスの高水準ヘルパーを通じて使用されます。
-
----
-
-### 6. `Collectable<E>`（抽象クラス）
-
-以下のクラスの基底クラスです：
-
-- `OrderedCollectable<E>` – ソート済み出力
-- `UnorderedCollectable<E>` – ソートなし、最速
-- `WindowCollectable<E>` – スライディングウィンドウ
-- `Statistics<E, D>` – 統計集約
-
-#### 共通メソッド（継承経由）：
-
-| メソッド | 説明 | 例 |
-|----------|------|-----|
-| `count()` | 要素をカウント | `.count()` |
-| `toArray()` | 配列に変換 | `.toArray()` |
-| `toSet()` | Set に変換 | `.toSet()` |
-| `toMap(k, v)` | Map に変換 | `.toMap(x => x.id, x => x)` |
-| `group(k)` | キーでグループ化 | `.group(x => x.category)` |
-| `findAny()` | 任意の一致要素（Optional） | `.findAny()` |
-| `findFirst()` | 最初の要素（Optional） | `.findFirst()` |
-| `reduce(...)` | カスタム縮約 | `.reduce((a,b) => a + b, 0)` |
-
----
-
-### 7. `OrderedCollectable<E>` – ソート済みデータ
-
-要素を**自動的にソート**したい場合は、このクラスを使用してください。
-
-**カスタム比較器**を受け入れるか、自然順を使用します。
+## Semanticクラスメソッド
+
+| メソッド | 説明 | 時間計算量 | 空間計算量 |
+|---------|------|------------|------------|
+| `concat(other)` | 二つのストリームを連結 | O(n) | O(1) |
+| `distinct()` | 重複排除 | O(n) | O(n) |
+| `distinct(comparator)` | コンパレーターを使用した重複排除 | O(n²) | O(n) |
+| `dropWhile(predicate)` | 条件を満たす要素を破棄 | O(n) | O(1) |
+| `filter(predicate)` | 要素のフィルタリング | O(n) | O(1) |
+| `flat(mapper)` | フラットマッピング | O(n × m) | O(1) |
+| `flatMap(mapper)` | 新しい型へのフラットマッピング | O(n × m) | O(1) |
+| `limit(n)` | 要素数の制限 | O(n) | O(1) |
+| `map(mapper)` | マッピング変換 | O(n) | O(1) |
+| `peek(consumer)` | 要素の検査 | O(n) | O(1) |
+| `redirect(redirector)` | インデックスのリダイレクト | O(n) | O(1) |
+| `reverse()` | ストリームの反転 | O(n) | O(1) |
+| `shuffle()` | ランダムシャッフル | O(n) | O(1) |
+| `shuffle(mapper)` | マッパーを使用したシャッフル | O(n) | O(1) |
+| `skip(n)` | 最初のn要素をスキップ | O(n) | O(1) |
+| `sorted()` | ソート | O(n log n) | O(n) |
+| `sorted(comparator)` | コンパレーターを使用したソート | O(n log n) | O(n) |
+| `sub(start, end)` | サブストリームの取得 | O(n) | O(1) |
+| `takeWhile(predicate)` | 条件を満たす要素を取得 | O(n) | O(1) |
+| `translate(offset)` | インデックスの平行移動 | O(n) | O(1) |
+| `translate(translator)` | トランスレーターを使用した平行移動 | O(n) | O(1) |
 
 ```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// Semantic操作例
+const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)        // 偶数のフィルタリング
+    .map(n => n * 2)                 // 2倍に変換
+    .skip(1)                         // 最初の要素をスキップ
+    .limit(3)                        // 3要素に制限
+    .toArray();                      // 配列に変換
+// 結果: [8, 12, 20]
+
+// 複雑な操作例
+const complexResult = range(1, 100, 1)
+    .flatMap(n => from([n, n * 2])) // 各要素を2要素にマッピング
+    .distinct()                      // 重複排除
+    .shuffle()                       // ランダムシャッフル
+    .takeWhile(n => n < 50)         // 50未満の要素を取得
+    .toOrdered()                     // 順序付きコレクターに変換
+    .toArray();                      // 配列に変換
 ```
 
-🔒 **ソート済み出力が保証されます。**
+## コレクター変換メソッド
 
----
-
-### 8. `UnorderedCollectable<E>` – ソートなし（🚀 最速）
-
-**順序を必要とせず**、**最高のパフォーマンス**を求める場合は、以下を使用してください：
+| メソッド | 説明 | 時間計算量 | 空間計算量 |
+|---------|------|------------|------------|
+| `toUnoredered()` | 非順序コレクターに変換（パフォーマンス優先） | O(1) | O(1) |
+| `toOrdered()` | 順序付きコレクターに変換 | O(1) | O(1) |
+| `sorted()` | ソートして順序付きコレクターに変換 | O(n log n) | O(n) |
+| `toWindow()` | ウィンドウコレクターに変換 | O(1) | O(1) |
+| `toNumericStatistics()` | 数値統計に変換 | O(1) | O(1) |
+| `toBigintStatistics()` | BigInt統計に変換 | O(1) | O(1) |
 
 ```typescript
-const unordered = new UnorderedCollectable(stream);
-// または
-const fastest = semanticStream.toUnordered();
+// コレクター変換例
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
+
+// パフォーマンス優先：非順序コレクターを使用
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
+
+// ソート必要：順序付きコレクターを使用  
+const ordered = numbers
+    .sorted()
+    .toOrdered();
+
+// 統計分析：統計コレクターを使用
+const stats = numbers
+    .toNumericStatistics();
+
+console.log(stats.mean());        // 平均値
+console.log(stats.median());      // 中央値
+console.log(stats.standardDeviation()); // 標準偏差
+
+// ウィンドウ操作
+const windowed = numbers
+    .toWindow()
+    .tumble(3n); // 3要素ごとのウィンドウ
+
+windowed.forEach(window => {
+    console.log(window.toArray()); // 各ウィンドウの内容
+});
 ```
 
-✅ **ソートアルゴリズムは実行されません**  
-✅ **順序が無関係な場合の最高パフォーマンス**
-
----
-
-### 9. `Statistics<E, D>` – 統計分析
-
-数値データを分析するための抽象基底クラスです。
-
-#### サブクラス：
-
-- `NumericStatistics<E>` – `number` 型用
-- `BigIntStatistics<E>` – `bigint` 型用
-
-##### 主な統計メソッド：
-
-| メソッド | 説明 | 例 |
-|----------|------|-----|
-| `mean()` | 算術平均 | `.mean()` |
-| `median()` | 中央値 | `.median()` |
-| `mode()` | 最頻値 | `.mode()` |
-| `minimum()` | 最小要素 | `.minimum()` |
-| `maximum()` | 最大要素 | `.maximum()` |
-| `range()` | 最大 − 最小 | `.range()` |
-| `variance()` | 分散 | `.variance()` |
-| `standardDeviation()` | 標準偏差 | `.standardDeviation()` |
-| `summate()` | 要素の合計 | `.summate()` |
-| `quantile(q)` | q パーセンタイル（0–1）の値 | `.quantile(0.5)` → 中央値 |
-| `frequency()` | 頻度マップ | `.frequency()` |
-
----
-
-## 🧪 完全な例
+## Collectable収集メソッド
+
+| メソッド | 説明 | 時間計算量 | 空間計算量 |
+|---------|------|------------|------------|
+| `anyMatch(predicate)` | 一致する要素が存在するかチェック | O(n) | O(1) |
+| `allMatch(predicate)` | すべての要素が一致するかチェック | O(n) | O(1) |
+| `count()` | 要素のカウント | O(n) | O(1) |
+| `isEmpty()` | 空かどうかチェック | O(1) | O(1) |
+| `findAny()` | 任意の要素を検索 | O(n) | O(1) |
+| `findFirst()` | 最初の要素を検索 | O(n) | O(1) |
+| `findLast()` | 最後の要素を検索 | O(n) | O(1) |
+| `forEach(action)` | 全要素の反復処理 | O(n) | O(1) |
+| `group(classifier)` | 分類器によるグループ化 | O(n) | O(n) |
+| `groupBy(keyExtractor, valueExtractor)` | キー値抽出器によるグループ化 | O(n) | O(n) |
+| `join()` | 文字列への結合 | O(n) | O(n) |
+| `join(delimiter)` | 区切り文字を使用した結合 | O(n) | O(n) |
+| `nonMatch(predicate)` | 一致する要素がないかチェック | O(n) | O(1) |
+| `partition(count)` | 数量による分割 | O(n) | O(n) |
+| `partitionBy(classifier)` | 分類器による分割 | O(n) | O(n) |
+| `reduce(accumulator)` | 縮約操作 | O(n) | O(1) |
+| `reduce(identity, accumulator)` | 初期値付き縮約 | O(n) | O(1) |
+| `toArray()` | 配列への変換 | O(n) | O(n) |
+| `toMap(keyExtractor, valueExtractor)` | Mapへの変換 | O(n) | O(n) |
+| `toSet()` | Setへの変換 | O(n) | O(n) |
+| `write(stream)` | ストリームへの書き込み | O(n) | O(1) |
 
 ```typescript
-import { from, toUnordered, toOrdered, sorted, NumericStatistics } from 'semantic-typescript';
-
-// サンプルデータ
-const numbers = from([10, 2, 8, 4, 5, 6]);
-
-// 🚀 最速：ソートなし
-const fastest = numbers.toUnordered();
-console.log(fastest.toArray()); // 例: [10, 2, 8, 4, 5, 6]（元の順序）
-
-// 🔢 自然順でソート
-const ordered = numbers.sorted();
-console.log(ordered.toArray()); // [2, 4, 5, 6, 8, 10]
-
-// 📊 統計分析を実行
-const stats = new NumericStatistics(numbers);
-console.log('平均:', stats.mean());
-console.log('中央値:', stats.median());
-console.log('最頻値:', stats.mode());
-console.log('範囲:', stats.range());
-console.log('標準偏差:', stats.standardDeviation());
+// Collectable操作例
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)
+    .toOrdered();
+
+// 一致チェック
+console.log(data.anyMatch(n => n > 5)); // true
+console.log(data.allMatch(n => n < 20)); // true
+
+// 検索操作
+data.findFirst().ifPresent(n => console.log(n)); // 2
+data.findAny().ifPresent(n => console.log(n)); // 任意の要素
+
+// グループ化操作
+const grouped = data.groupBy(
+    n => n > 5 ? "large" : "small",
+    n => n * 2
+);
+// {small: [4, 8], large: [12, 16, 20]}
+
+// 縮約操作
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
+
+// 出力操作
+data.join(", "); // "2, 4, 6, 8, 10"
 ```
 
----
-
-## 🛠️ ユーティリティ関数
-
-本ライブラリは多数の**型ガード**と**比較ユーティリティ**もエクスポートしています：
-
-| 関数 | 用途 |
-|------|------|
-| `isString(x)` | `string` の型ガード |
-| `isNumber(x)` | `number` の型ガード |
-| `isBoolean(x)` | `boolean` の型ガード |
-| `isIterable(x)` | オブジェクトがイテラブルか確認 |
-| `useCompare(a, b)` | 汎用比較関数 |
-| `useRandom(x)` | 疑似乱数ジェネレーター（楽しい） |
-
----
-
-## 🧩 発展：カスタムジェネレーターとウィンドウ
-
-無限または制御されたデータストリーム用のカスタム**ジェネレーター**を作成できます：
+## 統計分析メソッド
+
+### NumericStatisticsメソッド
+
+| メソッド | 説明 | 時間計算量 | 空間計算量 |
+|---------|------|------------|------------|
+| `range()` | 範囲 | O(n) | O(1) |
+| `variance()` | 分散 | O(n) | O(1) |
+| `standardDeviation()` | 標準偏差 | O(n) | O(1) |
+| `mean()` | 平均値 | O(n) | O(1) |
+| `median()` | 中央値 | O(n log n) | O(n) |
+| `mode()` | 最頻値 | O(n) | O(n) |
+| `frequency()` | 度数分布 | O(n) | O(n) |
+| `summate()` | 合計 | O(n) | O(1) |
+| `quantile(quantile)` | 分位数 | O(n log n) | O(n) |
+| `interquartileRange()` | 四分位範囲 | O(n log n) | O(n) |
+| `skewness()` | 歪度 | O(n) | O(1) |
+| `kurtosis()` | 尖度 | O(n) | O(1) |
 
 ```typescript
-const gen = (accept: BiConsumer<number, bigint>, interrupt: Predicate<number>) => {
-  for (let i = 0; i < 10; i++) {
-    accept(i, BigInt(i));
-    if (i === 5) interrupt(i);
-  }
-};
-
-const s = new Semantic(gen);
+// 統計分析例
+const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .toNumericStatistics();
+
+console.log("平均値:", numbers.mean()); // 5.5
+console.log("中央値:", numbers.median()); // 5.5
+console.log("標準偏差:", numbers.standardDeviation()); // ~2.87
+console.log("合計:", numbers.summate()); // 55
+
+// マッパーを使用した統計分析
+const objects = from([
+    { value: 10 },
+    { value: 20 }, 
+    { value: 30 }
+]).toNumericStatistics();
+
+console.log("マップされた平均値:", objects.mean(obj => obj.value)); // 20
 ```
 
-または**スライディングウィンドウ**を使用：
+## パフォーマンス選択ガイド
 
+### 非順序コレクターを選択（パフォーマンス優先）
 ```typescript
-const windowed = ordered.slide(3n, 2n); // サイズ 3、ステップ 2 のウィンドウ
+// 順序保証が不要な場合
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // 最高のパフォーマンス
 ```
 
----
-
-## 📄 ライセンス
-
-本プロジェクトは **MIT ライセンス**の下で公開されており、商用および個人的利用が自由です。
-
----
-
-## 🙌 貢献
-
-プルリクエスト、イシュー、提案を歓迎します！
-
----
-
-## 🚀 クイックスタート概要
-
-| タスク | メソッド |
-|-------|----------|
-| null を安全に処理 | `Optional<T>` |
-| ストリームを作成 | `from([...])`、`range()`、`fill()` |
-| データを変換 | `map()`、`filter()` |
-| データをソート | `sorted()`、`toOrdered()` |
-| ソートなし（最速） | `toUnordered()` ✅ |
-| グループ化／集約 | `toMap()`、`group()`、`Collector` |
-| 統計 | `NumericStatistics`、`mean()`、`median()` など |
+### 順序付きコレクターを選択（順序が必要）
+```typescript
+// 要素の順序を維持する必要がある場合
+const ordered = data.sorted(comparator);
+```
 
----
+### ウィンドウコレクターを選択（ウィンドウ操作）
+```typescript
+// ウィンドウ操作が必要な場合
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // スライディングウィンドウ
+```
 
-## 🔗 リンク
+### 統計分析を選択（数値計算）
+```typescript
+// 統計分析が必要な場合
+const stats = data
+    .toNumericStatistics(); // 数値統計
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 ドキュメント: ソースコード／型定義を参照
+const bigIntStats = data
+    .toBigintStatistics(); // BigInt統計
+```
 
----
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-**TypeScript での合成可能で型安全、関数的なデータ処理をお楽しみください。** 🚀
+## 重要な注意点
 
---- 
+1. **ソート操作の影響**: 順序付きコレクターでは、`sorted()`操作が`redirect`, `translate`, `shuffle`, `reverse`の効果を上書きします
+2. **パフォーマンス考慮**: 順序保証が不要な場合は、`toUnoredered()`を優先してより良いパフォーマンスを得てください
+3. **メモリ使用量**: ソート操作にはO(n)の追加スペースが必要です
+4. **リアルタイムデータ**: Semanticストリームはリアルタイムデータに適しており、非同期データソースをサポートします
 
-✅ **覚えておいてください：**  
-- `toUnordered()` → **ソートなし、最速**  
-- その他すべて（例: `sorted()`、`toOrdered()`）→ **データをソート**
+このライブラリは、TypeScript開発者に強力で柔軟なストリーム処理能力を提供し、関数型プログラミングの利点と型安全性を組み合わせています。