semantic-typescript 0.0.6 → 0.0.8

package/readme.jp.md

@@ -1,335 +1,529 @@
-# 📘 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>` モナド**
-- ✅ **イテレータとジェネレーター**ベースの設計 — 大規模・非同期データにも適応
+| 機能 | 説明 | 利点 |
+|------|------|------|
+| **型安全ジェネリクス** | 完全なTypeScript型サポート | コンパイル時エラー検出、優れた開発体験 |
+| **関数型プログラミング** | 不変データ構造と純粋関数 | 予測可能なコード、テストと保守が容易 |
+| **遅延評価** | オンデマンド計算、パフォーマンス最適化 | 大規模データセット処理時の高いメモリ効率 |
+| **非同期ストリーム処理** | ジェネレータベースの非同期データストリーム | リアルタイムデータとイベント駆動シナリオに適応 |
+| **マルチパラダイムコレクター** | 順序付き、順序なし、統計的収集戦略 | 異なるシナリオに基づく最適な戦略選択 |
+| **統計分析** | 組み込みの完全な統計計算関数 | 統合データ分析とレポート生成 |
 
----
+## パフォーマンスに関する考慮事項
 
-## 📦 インストール
+**重要な注意**: 以下のメソッドは、データを収集してソートするため、パフォーマンスを犠牲にして順序付きデータコレクションを生成します:
+- `toOrdered()`
+- `toWindow()`
+- `toNumericStatistics()`
+- `toBigIntStatistics()`
+- `sorted()`
+- `sorted(comparator)`
 
-```bash
-npm install semantic-typescript
-```
-
----
-
-## 🧠 コア概念
-
-### 1. `Optional<T>` – 安全な null 値処理
-
-`null` または `undefined` になり得る値を格納するモナディックコンテナです。
+特に重要な注意点: `sorted()`および`sorted(comparator)`は、以下のメソッドの結果を上書きします:
+- `redirect(redirector)`
+- `translate(translator)` 
+- `shuffle(mapper)`
 
-#### メソッド：
+## ファクトリメソッド
 
-| メソッド | 説明 | 例 |
-|----------|------|-----|
-| `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()` |
+### ストリーム作成ファクトリ
 
-#### 例：
+| メソッド | シグネチャ | 説明 | 例 |
+|------|------|------|------|
+| `blob` | `(blob: Blob, chunk?: bigint) => Semantic<Uint8Array>` | Blobをバイトストリームに変換 | `blob(fileBlob, 1024n)` |
+| `empty` | `<E>() => Semantic<E>` | 空のストリームを作成 | `empty<number>()` |
+| `fill` | `<E>(element: E, count: bigint) => Semantic<E>` | 指定数の要素で埋め立て | `fill("hello", 5n)` |
+| `from` | `<E>(iterable: Iterable<E>) => Semantic<E>` | 反復可能オブジェクトからストリーム作成 | `from([1, 2, 3])` |
+| `range` | `<N extends number\|bigint>(start: N, end: N, step?: N) => Semantic<N>` | 数値範囲ストリームを作成 | `range(1, 10, 2)` |
+| `iterate` | `<E>(generator: Generator<E>) => Semantic<E>` | ジェネレータ関数からストリーム作成 | `iterate(myGenerator)` |
+| `websocket` | `(websocket: WebSocket) => Semantic<MessageEvent>` | WebSocketからイベントストリーム作成 | `websocket(socket)` |
 
+**コード例補足:**
 ```typescript
-import { Optional } from 'semantic-typescript';
+import { from, range, fill, empty } from 'semantic-typescript';
 
-const value: number | null = Math.random() > 0.5 ? 10 : null;
+// 配列からストリーム作成
+const numberStream = from([1, 2, 3, 4, 5]);
 
-const opt = Optional.ofNullable(value);
+// 数値範囲ストリーム作成
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
 
-const result = opt
-  .filter(v => v > 5)
-  .map(v => v * 2)
-  .getOrDefault(0);
+// 繰り返し要素で埋め立て
+const filledStream = fill("hello", 3n); // "hello", "hello", "hello"
 
-console.log(result); // 20 または 0
+// 空のストリーム作成
+const emptyStream = empty<number>();
 ```
 
----
+### ユーティリティ関数ファクトリ
 
-### 2. `Semantic<E>` – 遅延データストリーム
+| メソッド | シグネチャ | 説明 | 例 |
+|------|------|------|------|
+| `validate` | `<T>(t: MaybeInvalid<T>) => t is T` | 値が有効か検証 | `validate(null)` → `false` |
+| `invalidate` | `<T>(t: MaybeInvalid<T>) => t is null\|undefined` | 値が無効か検証 | `invalidate(0)` → `false` |
+| `useCompare` | `<T>(t1: T, t2: T) => number` | 汎用比較関数 | `useCompare("a", "b")` → `-1` |
+| `useRandom` | `<T = number\|bigint>(index: T) => T` | 擬似乱数生成器 | `useRandom(5)` → 乱数 |
 
-要素の**遅延評価可能な合成可能シーケンス**です。Java Streams や Kotlin Sequences のような関数的ストリームに似ています。
+**コード例補足:**
+```typescript
+import { validate, invalidate, useCompare, useRandom } from 'semantic-typescript';
 
-`from()`、`range()`、`iterate()`、`fill()` などのヘルパーで `Semantic` を作成できます。
+// データ有効性検証
+const data: string | null = "hello";
+if (validate(data)) {
+    console.log(data.toUpperCase()); // validateがデータがnullでないことを保証するため安全な呼び出し
+}
 
-#### 作成メソッド：
+const nullData: string | null = null;
+if (invalidate(nullData)) {
+    console.log("データが無効です"); // invalidateがnullを検出したため実行される
+}
 
-| 関数 | 説明 | 例 |
-|------|------|-----|
-| `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)` |
+// 値の比較
+const comparison = useCompare("apple", "banana"); // -1
 
-#### 主な演算子：
+// 乱数生成
+const randomNum = useRandom(42); // シード42に基づく乱数
+```
 
-| メソッド | 説明 | 例 |
-|----------|------|-----|
-| `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)` |
+## コアクラス詳細
 
----
+### Optional<T> - 安全なnull値処理
 
-### 3. `toUnordered()` – 🚀 最速、ソートなし
+Optionalクラスは、nullまたはundefinedになる可能性のある値を安全に扱うための関数型アプローチを提供します。
 
-**順序を必要とせず**、**最高のパフォーマンス**を求める場合は、以下を使用してください：
+| メソッド | 戻り値の型 | 説明 | 時間計算量 |
+|------|----------|------|------------|
+| `filter(predicate: Predicate<T>)` | `Optional<T>` | 条件を満たす値をフィルタリング | O(1) |
+| `get()` | `T` | 値を取得、空の場合はエラーをスロー | O(1) |
+| `getOrDefault(defaultValue: T)` | `T` | 値またはデフォルト値を取得 | O(1) |
+| `ifPresent(action: Consumer<T>)` | `void` | 値が存在する場合にアクションを実行 | O(1) |
+| `isEmpty()` | `boolean` | 空かどうかチェック | O(1) |
+| `isPresent()` | `boolean` | 値が存在するかチェック | O(1) |
+| `map<R>(mapper: Functional<T, R>)` | `Optional<R>` | 値のマッピングと変換 | O(1) |
+| `static of<T>(value: MaybeInvalid<T>)` | `Optional<T>` | Optionalインスタンスを作成 | O(1) |
+| `static ofNullable<T>(value?)` | `Optional<T>` | null許容Optionalを作成 | O(1) |
+| `static ofNonNull<T>(value: T)` | `Optional<T>` | non-null Optionalを作成 | O(1) |
 
+**コード例補足:**
 ```typescript
-const fastest = semanticStream.toUnordered();
-```
+import { Optional } from 'semantic-typescript';
 
-🔥 **ソートアルゴリズムは適用されません。**  
-順序が関係なく、最大の速度が必要な場合に理想的です。
+// Optionalインスタンス作成
+const optionalValue = Optional.ofNullable<string>(Math.random() > 0.5 ? "hello" : null);
 
----
+// チェーン操作
+const result = optionalValue
+    .filter(val => val.length > 3) // 長さが3より大きい値をフィルタリング
+    .map(val => val.toUpperCase()) // 大文字に変換
+    .getOrDefault("default"); // 値またはデフォルト値を取得
 
-### 4. `toOrdered()` および `sorted()` – ソート済み出力
+console.log(result); // "HELLO" または "default"
 
-**ソート済み出力**が必要な場合は、以下を使用してください：
+// 安全な操作
+optionalValue.ifPresent(val => {
+    console.log(`値が存在します: ${val}`);
+});
 
-```typescript
-const ordered = semanticStream.sorted(); // 自然順
-const customSorted = semanticStream.sorted((a, b) => a - b); // カスタム比較器
-const orderedCollectable = semanticStream.toOrdered(); // こちらもソート
+// ステータスチェック
+if (optionalValue.isPresent()) {
+    console.log("値があります");
+} else if (optionalValue.isEmpty()) {
+    console.log("空です");
+}
 ```
 
-⚠️ これらのメソッドは、自然順または指定された比較器を使用して要素を**ソートします**。
-
----
-
-### 5. `Collector<E, A, R>` – データ集約
+### Semantic<E> - 遅延データストリーム
+
+Semanticは、豊富なストリーム演算子を提供するコアのストリーム処理クラスです。
+
+#### ストリーム変換操作
+
+| メソッド | 戻り値の型 | 説明 | パフォーマンス影響 |
+|------|----------|------|----------|
+| `concat(other: Semantic<E>)` | `Semantic<E>` | 2つのストリームを連結 | O(n+m) |
+| `distinct()` | `Semantic<E>` | 重複を削除（Set使用） | O(n) |
+| `distinct(comparator)` | `Semantic<E>` | カスタム比較子で重複削除 | O(n²) |
+| `dropWhile(predicate)` | `Semantic<E>` | 条件を満たす先頭要素を破棄 | O(n) |
+| `filter(predicate)` | `Semantic<E>` | 要素をフィルタリング | O(n) |
+| `flat(mapper)` | `Semantic<E>` | ネストしたストリームを平坦化 | O(n×m) |
+| `flatMap(mapper)` | `Semantic<R>` | マッピングと平坦化 | O(n×m) |
+| `limit(n)` | `Semantic<E>` | 要素数を制限 | O(n) |
+| `map(mapper)` | `Semantic<R>` | 要素のマッピングと変換 | O(n) |
+| `peek(consumer)` | `Semantic<E>` | 要素を変更せずに閲覧 | O(n) |
+| `redirect(redirector)` | `Semantic<E>` | インデックスのリダイレクト | O(n) |
+| `reverse()` | `Semantic<E>` | ストリーム順序を反転 | O(n) |
+| `shuffle()` | `Semantic<E>` | ランダムにシャッフル | O(n) |
+| `shuffle(mapper)` | `Semantic<E>` | カスタムシャッフルロジック | O(n) |
+| `skip(n)` | `Semantic<E>` | 最初のn要素をスキップ | O(n) |
+| `sub(start, end)` | `Semantic<E>` | サブストリームを取得 | O(n) |
+| `takeWhile(predicate)` | `Semantic<E>` | 条件を満たす先頭要素を取得 | O(n) |
+| `translate(offset)` | `Semantic<E>` | インデックスの平行移動 | O(n) |
+| `translate(translator)` | `Semantic<E>` | カスタムインデックス変換 | O(n) |
+
+**コード例補足:**
+```typescript
+import { from } from 'semantic-typescript';
 
-コレクターにより、ストリームを**単一または複雑な構造に縮約**できます。
+const stream = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
 
-組み込みの静的ファクトリー：
+// ストリーム変換操作の例
+const processedStream = stream
+    .filter(x => x % 2 === 0) // 偶数をフィルタリング
+    .map(x => x * 2) // 各要素を2倍
+    .distinct() // 重複を削除
+    .limit(3) // 最初の3要素に制限
+    .peek((val, index) => console.log(`インデックス${index}の要素${val}`)); // 要素を閲覧
 
-```typescript
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// 注: ストリームはまだ実行されていない、終端操作のためにCollectableへの変換が必要
 ```
 
-通常、`Collectable` クラスの高水準ヘルパーを通じて使用されます。
-
----
+#### ストリーム終端操作
 
-### 6. `Collectable<E>`（抽象クラス）
+| メソッド | 戻り値の型 | 説明 | パフォーマンス特性 |
+|------|----------|------|----------|
+| `toOrdered()` | `OrderedCollectable<E>` | 順序付きコレクションに変換 | ソート操作、パフォーマンス低い |
+| `toUnordered()` | `UnorderedCollectable<E>` | 順序なしコレクションに変換 | 最速、ソートなし |
+| `toWindow()` | `WindowCollectable<E>` | ウィンドウコレクションに変換 | ソート操作、パフォーマンス低い |
+| `toNumericStatistics()` | `Statistics<E, number>` | 数値統計分析 | ソート操作、パフォーマンス低い |
+| `toBigintStatistics()` | `Statistics<E, bigint>` | ビッグ整数統計分析 | ソート操作、パフォーマンス低い |
+| `sorted()` | `OrderedCollectable<E>` | 自然順ソート | リダイレクト結果を上書き |
+| `sorted(comparator)` | `OrderedCollectable<E>` | カスタムソート | リダイレクト結果を上書き |
 
-以下のクラスの基底クラスです：
-
-- `OrderedCollectable<E>` – ソート済み出力
-- `UnorderedCollectable<E>` – ソートなし、最速
-- `WindowCollectable<E>` – スライディングウィンドウ
-- `Statistics<E, D>` – 統計集約
+**コード例補足:**
+```typescript
+import { from } from 'semantic-typescript';
 
-#### 共通メソッド（継承経由）：
+const semanticStream = from([5, 2, 8, 1, 9, 3, 7, 4, 6]);
 
-| メソッド | 説明 | 例 |
-|----------|------|-----|
-| `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)` |
+// 順序付きコレクションに変換（パフォーマンス低い）
+const ordered = semanticStream.toOrdered();
 
----
+// 順序なしコレクションに変換（最速）
+const unordered = semanticStream.toUnordered();
 
-### 7. `OrderedCollectable<E>` – ソート済みデータ
+// 自然順ソート
+const sortedNatural = semanticStream.sorted();
 
-要素を**自動的にソート**したい場合は、このクラスを使用してください。
+// カスタムソート
+const sortedCustom = semanticStream.sorted((a, b) => b - a); // 降順ソート
 
-**カスタム比較器**を受け入れるか、自然順を使用します。
+// 統計オブジェクトに変換
+const stats = semanticStream.toNumericStatistics();
 
-```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// 注: 上記メソッドはSemanticインスタンスを通じて呼び出し、Collectableを取得してから終端メソッドを使用する必要がある
 ```
 
-🔒 **ソート済み出力が保証されます。**
-
----
+### Collector<E, A, R> - データコレクター
 
-### 8. `UnorderedCollectable<E>` – ソートなし（🚀 最速）
+コレクターは、ストリームデータを特定の構造に集約するために使用されます。
 
-**順序を必要とせず**、**最高のパフォーマンス**を求める場合は、以下を使用してください：
+| メソッド | 説明 | 使用シナリオ |
+|------|------|----------|
+| `collect(generator)` | データ収集を実行 | ストリーム終端操作 |
+| `static full(identity, accumulator, finisher)` | 完全なコレクターを作成 | 完全な処理が必要 |
+| `static shortable(identity, interruptor, accumulator, finisher)` | 中断可能なコレクターを作成 | 早期終了する可能性あり |
 
+**コード例補足:**
 ```typescript
-const unordered = new UnorderedCollectable(stream);
-// または
-const fastest = semanticStream.toUnordered();
+import { Collector } from 'semantic-typescript';
+
+// カスタムコレクター作成
+const sumCollector = Collector.full(
+    () => 0, // 初期値
+    (acc, value) => acc + value, // アキュムレータ
+    result => result // フィニッシャー関数
+);
+
+// コレクター使用（SemanticからCollectableへの変換が最初に必要）
+const numbers = from([1, 2, 3, 4, 5]);
+const sum = numbers.toUnordered().collect(sumCollector); // 15
 ```
 
-✅ **ソートアルゴリズムは実行されません**  
-✅ **順序が無関係な場合の最高パフォーマンス**
-
----
+### Collectable<E> - 収集可能データ抽象クラス
 
-### 9. `Statistics<E, D>` – 統計分析
+豊富なデータ集約および変換メソッドを提供します。**注: 最初にSemanticインスタンスを通じてsorted()、toOrdered()などを呼び出してCollectableインスタンスを取得してから、以下のメソッドを使用する必要があります。**
 
-数値データを分析するための抽象基底クラスです。
+#### データクエリ操作
 
-#### サブクラス：
+| メソッド | 戻り値の型 | 説明 | 例 |
+|------|----------|------|------|
+| `anyMatch(predicate)` | `boolean` | いずれかの要素が条件に一致するか | `anyMatch(x => x > 0)` |
+| `allMatch(predicate)` | `boolean` | すべての要素が条件に一致するか | `allMatch(x => x > 0)` |
+| `count()` | `bigint` | 要素数の統計 | `count()` → `5n` |
+| `isEmpty()` | `boolean` | ストリームが空かどうか | `isEmpty()` |
+| `findAny()` | `Optional<E>` | 任意の要素を検索 | `findAny()` |
+| `findFirst()` | `Optional<E>` | 最初の要素を検索 | `findFirst()` |
+| `findLast()` | `Optional<E>` | 最後の要素を検索 | `findLast()` |
 
-- `NumericStatistics<E>` – `number` 型用
-- `BigIntStatistics<E>` – `bigint` 型用
-
-##### 主な統計メソッド：
+**コード例補足:**
+```typescript
+import { from } from 'semantic-typescript';
 
-| メソッド | 説明 | 例 |
-|----------|------|-----|
-| `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()` |
+const numbers = from([1, 2, 3, 4, 5]);
 
----
+// 終端メソッドを使用する前にCollectableに変換する必要がある
+const collectable = numbers.toUnordered();
 
-## 🧪 完全な例
+// データクエリ操作
+const hasEven = collectable.anyMatch(x => x % 2 === 0); // true
+const allPositive = collectable.allMatch(x => x > 0); // true
+const count = collectable.count(); // 5n
+const isEmpty = collectable.isEmpty(); // false
+const firstElement = collectable.findFirst(); // Optional.of(1)
+const anyElement = collectable.findAny(); // 任意の要素
+```
 
+#### データ集約操作
+
+| メソッド | 戻り値の型 | 説明 | 計算量 |
+|------|----------|------|--------|
+| `group(classifier)` | `Map<K, E[]>` | 分類子でグループ化 | O(n) |
+| `groupBy(keyExtractor, valueExtractor)` | `Map<K, V[]>` | キー値抽出器でグループ化 | O(n) |
+| `join()` | `string` | 文字列として結合 | O(n) |
+| `join(delimiter)` | `string` | 区切り文字で結合 | O(n) |
+| `partition(count)` | `E[][]` | カウントで分割 | O(n) |
+| `partitionBy(classifier)` | `E[][]` | 分類子で分割 | O(n) |
+| `reduce(accumulator)` | `Optional<E>` | 縮約操作 | O(n) |
+| `reduce(identity, accumulator)` | `E` | 識別子付き縮約 | O(n) |
+| `toArray()` | `E[]` | 配列に変換 | O(n) |
+| `toMap(keyExtractor, valueExtractor)` | `Map<K, V>` | Mapに変換 | O(n) |
+| `toSet()` | `Set<E>` | Setに変換 | O(n) |
+
+**コード例補足:**
 ```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());
+import { from } from 'semantic-typescript';
+
+const people = from([
+    { name: "Alice", age: 25, city: "New York" },
+    { name: "Bob", age: 30, city: "London" },
+    { name: "Charlie", age: 25, city: "New York" }
+]);
+
+// 集約操作を使用する前にCollectableに変換する必要がある
+const collectable = people.toUnordered();
+
+// グループ化操作
+const byCity = collectable.group(person => person.city);
+// Map { "New York" => [{name: "Alice", ...}, {name: "Charlie", ...}], "London" => [{name: "Bob", ...}] }
+
+const byAge = collectable.groupBy(
+    person => person.age,
+    person => person.name
+);
+// Map { 25 => ["Alice", "Charlie"], 30 => ["Bob"] }
+
+// コレクションに変換
+const array = collectable.toArray(); // 元の配列
+const set = collectable.toSet(); // Setコレクション
+const map = collectable.toMap(
+    person => person.name,
+    person => person.age
+); // Map { "Alice" => 25, "Bob" => 30, "Charlie" => 25 }
+
+// 縮約操作
+const totalAge = collectable.reduce(0, (acc, person) => acc + person.age); // 80
+const oldest = collectable.reduce((a, b) => a.age > b.age ? a : b); // Optional.of({name: "Bob", age: 30, ...})
 ```
 
----
+### 特定のコレクター実装
 
-## 🛠️ ユーティリティ関数
+#### UnorderedCollectable<E>
+- **特性**: 最速のコレクター、ソートなし
+- **使用シナリオ**: 順序が重要でない、最大のパフォーマンスが望まれる場合
+- **メソッド**: すべてのCollectableメソッドを継承
 
-本ライブラリは多数の**型ガード**と**比較ユーティリティ**もエクスポートしています：
+#### OrderedCollectable<E> 
+- **特性**: 要素の順序を保証、パフォーマンスは低い
+- **使用シナリオ**: ソートされた結果が必要な場合
+- **特殊メソッド**: すべてのメソッドを継承、内部ソート状態を維持
 
-| 関数 | 用途 |
-|------|------|
-| `isString(x)` | `string` の型ガード |
-| `isNumber(x)` | `number` の型ガード |
-| `isBoolean(x)` | `boolean` の型ガード |
-| `isIterable(x)` | オブジェクトがイテラブルか確認 |
-| `useCompare(a, b)` | 汎用比較関数 |
-| `useRandom(x)` | 疑似乱数ジェネレーター（楽しい） |
+#### WindowCollectable<E>
+- **特性**: スライディングウィンドウ操作をサポート
+- **使用シナリオ**: 時系列データ分析
+- **特殊メソッド**:
+  - `slide(size, step)` - スライディングウィンドウ
+  - `tumble(size)` - タンブリングウィンドウ
 
----
+**コード例補足:**
+```typescript
+import { from } from 'semantic-typescript';
 
-## 🧩 発展：カスタムジェネレーターとウィンドウ
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
 
-無限または制御されたデータストリーム用のカスタム**ジェネレーター**を作成できます：
+// 順序なしコレクター（最速）
+const unordered = data.toUnordered();
+const unorderedArray = unordered.toArray(); // 元の順序を維持する可能性あり [1, 2, 3, ...]
 
-```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 ordered = data.toOrdered();
+const orderedArray = ordered.toArray(); // ソートが保証される [1, 2, 3, ...]
 
-または**スライディングウィンドウ**を使用：
+// ウィンドウコレクター
+const windowed = data.toWindow();
+const slidingWindows = windowed.slide(3n, 2n); // ウィンドウサイズ3、ステップ2
+// ウィンドウ1: [1, 2, 3], ウィンドウ2: [3, 4, 5], ウィンドウ3: [5, 6, 7], ...
 
-```typescript
-const windowed = ordered.slide(3n, 2n); // サイズ 3、ステップ 2 のウィンドウ
+const tumblingWindows = windowed.tumble(4n); // タンブリングウィンドウサイズ4
+// ウィンドウ1: [1, 2, 3, 4], ウィンドウ2: [5, 6, 7, 8], ...
 ```
 
----
-
-## 📄 ライセンス
-
-本プロジェクトは **MIT ライセンス**の下で公開されており、商用および個人的利用が自由です。
+### Statistics<E, D> - 統計分析
+
+統計分析の基底クラスで、豊富な統計計算メソッドを提供します。**注: 最初にSemanticインスタンスを通じてtoNumericStatistics()またはtoBigIntStatistics()を呼び出してStatisticsインスタンスを取得してから、以下のメソッドを使用する必要があります。**
+
+#### 統計計算操作
+
+| メソッド | 戻り値の型 | 説明 | アルゴリズム計算量 |
+|------|----------|------|------------|
+| `maximum()` | `Optional<E>` | 最大値 | O(n) |
+| `minimum()` | `Optional<E>` | 最小値 | O(n) |
+| `range()` | `D` | 範囲（最大-最小） | O(n) |
+| `variance()` | `D` | 分散 | O(n) |
+| `standardDeviation()` | `D` | 標準偏差 | O(n) |
+| `mean()` | `D` | 平均値 | O(n) |
+| `median()` | `D` | 中央値 | O(n log n) |
+| `mode()` | `D` | 最頻値 | O(n) |
+| `frequency()` | `Map<D, bigint>` | 度数分布 | O(n) |
+| `summate()` | `D` | 合計 | O(n) |
+| `quantile(quantile)` | `D` | 分位数 | O(n log n) |
+| `interquartileRange()` | `D` | 四分位範囲 | O(n log n) |
+| `skewness()` | `D` | 歪度 | O(n) |
+| `kurtosis()` | `D` | 尖度 | O(n) |
+
+**コード例補足:**
+```typescript
+import { from } from 'semantic-typescript';
+
+const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+// 統計メソッドを使用する前に統計オブジェクトに変換する必要がある
+const stats = numbers.toNumericStatistics();
+
+// 基本統計
+const count = stats.count(); // 10n
+const max = stats.maximum(); // Optional.of(10)
+const min = stats.minimum(); // Optional.of(1)
+const range = stats.range(); // 9
+const mean = stats.mean(); // 5.5
+const median = stats.median(); // 5.5
+const sum = stats.summate(); // 55
+
+// 高度な統計
+const variance = stats.variance(); // 8.25
+const stdDev = stats.standardDeviation(); // 2.872
+const mode = stats.mode(); // 任意の値（すべて1回ずつ出現するため）
+const q1 = stats.quantile(0.25); // 3.25
+const q3 = stats.quantile(0.75); // 7.75
+const iqr = stats.interquartileRange(); // 4.5
+
+// 度数分布
+const freq = stats.frequency(); // Map {1 => 1n, 2 => 1n, ...}
+```
 
----
+#### 特定の統計実装クラス
 
-## 🙌 貢献
+**NumericStatistics<E>**
+- number型の統計分析を処理
+- すべての統計計算はnumber型を返す
 
-プルリクエスト、イシュー、提案を歓迎します！
+**BigIntStatistics<E>**  
+- bigint型の統計分析を処理
+- すべての統計計算はbigint型を返す
 
----
+**コード例補足:**
+```typescript
+import { from } from 'semantic-typescript';
 
-## 🚀 クイックスタート概要
+// 数値統計
+const numberData = from([10, 20, 30, 40, 50]);
+const numericStats = numberData.toNumericStatistics();
 
-| タスク | メソッド |
-|-------|----------|
-| null を安全に処理 | `Optional<T>` |
-| ストリームを作成 | `from([...])`、`range()`、`fill()` |
-| データを変換 | `map()`、`filter()` |
-| データをソート | `sorted()`、`toOrdered()` |
-| ソートなし（最速） | `toUnordered()` ✅ |
-| グループ化／集約 | `toMap()`、`group()`、`Collector` |
-| 統計 | `NumericStatistics`、`mean()`、`median()` など |
+console.log(numericStats.mean()); // 30
+console.log(numericStats.summate()); // 150
 
----
+// ビッグ整数統計
+const bigintData = from([100n, 200n, 300n, 400n, 500n]);
+const bigintStats = bigintData.toBigIntStatistics();
 
-## 🔗 リンク
+console.log(bigintStats.mean()); // 300n
+console.log(bigintStats.summate()); // 1500n
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 ドキュメント: ソースコード／型定義を参照
+// マッパー関数を使用した統計
+const objectData = from([
+    { value: 15 },
+    { value: 25 }, 
+    { value: 35 },
+    { value: 45 }
+]);
 
----
+const objectStats = objectData.toNumericStatistics();
+const meanWithMapper = objectStats.mean(obj => obj.value); // 30
+const sumWithMapper = objectStats.summate(obj => obj.value); // 120
+```
 
-**TypeScript での合成可能で型安全、関数的なデータ処理をお楽しみください。** 🚀
+## 完全な使用例
 
---- 
+```typescript
+import { from, validate, invalidate } from 'semantic-typescript';
+
+// 1. データストリーム作成
+const rawData = [5, 2, 8, 1, null, 9, 3, undefined, 7, 4, 6];
+const semanticStream = from(rawData);
+
+// 2. ストリーム処理パイプライン
+const processedStream = semanticStream
+    .filter(val => validate(val)) // nullとundefinedをフィルタリング
+    .map(val => val! * 2) // 各値を2倍（!を使用、validateが空でないことを保証するため）
+    .distinct(); // 重複を削除
+
+// 3. Collectableに変換して終端操作を使用
+const collectable = processedStream.toUnordered();
+
+// 4. データ検証と使用
+if (!collectable.isEmpty()) {
+    const results = collectable
+        .filter(x => x > 5) // 再度フィルタリング
+        .toArray(); // 配列に変換
+    
+    console.log("処理結果:", results); // [16, 18, 14, 8, 12]
+    
+    // 統計情報
+    const stats = processedStream.toNumericStatistics();
+    console.log("平均値:", stats.mean()); // 11.2
+    console.log("合計:", stats.summate()); // 56
+}
+
+// 5. 潜在的に無効なデータの処理
+const potentiallyInvalidData: Array<number | null> = [1, null, 3, 4, null];
+const validData = potentiallyInvalidData.filter(validate);
+const invalidData = potentiallyInvalidData.filter(invalidate);
+
+console.log("有効なデータ:", validData); // [1, 3, 4]
+console.log("無効なデータ:", invalidData); // [null, null]
+```
 
-✅ **覚えておいてください：**  
-- `toUnordered()` → **ソートなし、最速**  
-- その他すべて（例: `sorted()`、`toOrdered()`）→ **データをソート**
+## 重要な使用ルールのまとめ
+
+1. **ストリーム作成**: `from()`、`range()`、`fill()`などのファクトリメソッドを使用してSemanticインスタンスを作成
+2. **ストリーム変換**: Semanticインスタンスで`map()`、`filter()`、`distinct()`などのメソッドを呼び出し
+3. **Collectableへの変換**: Semanticインスタンスを通じて以下のいずれかのメソッドを呼び出す必要があります:
+   - `toOrdered()` - 順序付きコレクター
+   - `toUnordered()` - 順序なしコレクター（最速）
+   - `toWindow()` - ウィンドウコレクター  
+   - `toNumericStatistics()` - 数値統計
+   - `toBigIntStatistics()` - ビッグ整数統計
+   - `sorted()` - 自然順ソート
+   - `sorted(comparator)` - カスタムソート
+4. **終端操作**: Collectableインスタンスで`toArray()`、`count()`、`summate()`などの終端メソッドを呼び出し
+5. **データ検証**: `validate()`を使用してデータがnull/undefinedでないことを保証、`invalidate()`を使用して無効なデータをチェック
+
+この設計は、型安全性とパフォーマンス最適化を確保しながら、豊富なストリーム処理機能を提供します。