semantic-typescript 0.0.7 → 0.0.8

package/readme.tw.md

@@ -1,335 +1,529 @@
-# 📘 semantic-typescript
+# Semantic-TypeScript 串流處理框架
 
-一個強大且**類型安全**的 TypeScript 工具庫，專為**語意化資料處理（Semantic Data Processing）**而設計。  
-提供可組合的函數式結構，用於處理集合（Collections）、資料流（Streams）與序列（Sequences），並支援排序、篩選、分組、統計分析等多種功能。
+## 引言
 
-無論您是處理**已排序或未排序的資料**、進行**統計分析**，還是僅想**流暢地鏈式操作資料**，這個套件都能滿足您的需求。
+Semantic-TypeScript 是一個現代化的串流處理函式庫，靈感來自 JavaScript GeneratorFunction、Java Stream 和 MySQL Index。其核心設計理念基於透過資料索引建構高效的資料處理管道，為前端開發提供型別安全、函數式風格的串流操作體驗。
 
----
+與傳統的同步處理不同，Semantic 採用非同步處理模型。在建立資料流時，終端資料接收的時機完全取決於上游何時呼叫 `accept` 和 `interrupt` 回呼函數。這種設計使得函式庫能夠優雅地處理即時資料流、大型資料集和非同步資料來源。
 
-## 🧩 功能特色
+## 核心特性
 
-- ✅ 全面採用**類型安全的泛型（Generics）**
-- ✅ **函數式編程風格**（例如：map、filter、reduce）
-- ✅ **語意化資料流（Semantic<E>）**，支援延遲求值（Lazy Evaluation）
-- ✅ 可將資料流轉換為實體資料結構的**收集器（Collectors）**
-- ✅ **已排序與未排序的收集器（Collectables）** — 其中 `toUnordered()` 是**最快的（不會排序）**
-- ✅ 支援透過 `sorted()`、`toOrdered()` 與自訂比較器進行**排序**
-- ✅ **統計分析功能**（`Statistics`、`NumericStatistics`、`BigIntStatistics`）
-- ✅ **Optional<T>** — 安全處理可能為 `null` 或 `undefined` 值的 Monad
-- ✅ 採用**迭代器（Iterator）與生成器（Generator）**架構，適用於大型或非同步資料
-
----
-
-## 📦 安裝方式
-
-```bash
-npm install semantic-typescript
-```
-
----
-
-## 🧠 核心概念
-
-### 1. `Optional<T>` — 安全處理可為空（Nullable）的值
-
-用來包裝可能為 `null` 或 `undefined` 的值的 Monad 容器。
-
-#### 提供的方法：
-
-| 方法 | 說明 | 範例 |
+| 特性 | 描述 | 優勢 |
 |------|------|------|
-| `of(value)` | 包裝一個值（可為空） | `Optional.of(null)` |
-| `ofNullable(v)` | 包裝，允許為空值 | `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()` |
-
-#### 範例：
-
+| **型別安全泛型** | 完整的 TypeScript 型別支援 | 編譯時錯誤檢測，更好的開發體驗 |
+| **函數式程式設計** | 不可變資料結構和純函數 | 更可預測的程式碼，易於測試和維護 |
+| **惰性求值** | 按需計算，效能最佳化 | 處理大型資料集時記憶體效率高 |
+| **非同步串流處理** | 基於產生器的非同步資料流 | 適用於即時資料和事件驅動場景 |
+| **多範型收集器** | 有序、無序、統計收集策略 | 根據不同場景選擇最佳策略 |
+| **統計分析** | 內建完整的統計計算函數 | 整合資料分析和報表生成 |
+
+## 效能考量
+
+**重要注意**：以下方法會犧牲效能來收集和排序資料，從而產生有序的資料集合：
+- `toOrdered()`
+- `toWindow()`
+- `toNumericStatistics()`
+- `toBigIntStatistics()`
+- `sorted()`
+- `sorted(comparator)`
+
+特別需要注意的是：`sorted()` 和 `sorted(comparator)` 會覆寫以下方法的結果：
+- `redirect(redirector)`
+- `translate(translator)`
+- `shuffle(mapper)`
+
+## 工廠方法
+
+### 串流建立工廠
+
+| 方法 | 簽章 | 描述 | 範例 |
+|------|------|------|------|
+| `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>` — 延遲資料流（Lazy Data Stream）
-
-一個**可組合、延遲求值的資料序列**，類似於 Java 的 Streams 或 Kotlin 的 Sequences。
+### 實用函數工廠
 
-您可使用 `from()`、`range()`、`iterate()` 或 `fill()` 等輔助函數建立 `Semantic` 資料流。
+| 方法 | 簽章 | 描述 | 範例 |
+|------|------|------|------|
+| `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)` → 隨機數 |
 
-#### 建立方式：
+**程式碼範例補充：**
+```typescript
+import { validate, invalidate, useCompare, useRandom } from 'semantic-typescript';
 
-| 函數 | 說明 | 範例 |
-|------|------|------|
-| `from(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 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
+}
 
-| 方法 | 說明 | 範例 |
-|------|------|------|
-| `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)` | 使用 Collector 進行聚合 | `.collect(Collector.full(...))` |
-| `toArray()` | 轉為陣列 | `.toArray()` |
-| `toSet()` | 轉為 Set | `.toSet()` |
-| `toMap(keyFn, valFn)` | 轉為 Map | `.toMap(x => x.id, x => x)` |
-
----
-
-### 3. `toUnordered()` — 🚀 最快，不排序
-
-如果您**不需要排序**，且希望獲得**最快的效能**，請使用：
+// 比較值
+const comparison = useCompare("apple", "banana"); // -1
 
-```typescript
-const fastest = semanticStream.toUnordered();
+// 產生隨機數
+const randomNum = useRandom(42); // 基於種子 42 的隨機數
 ```
 
-🔥 **不會套用任何排序演算法。**  
-當資料的順序不重要，而您追求極致效能時，這是最佳選擇。
+## 核心類別詳情
 
----
+### Optional<T> - 安全空值處理
 
-### 4. `toOrdered()` 與 `sorted()` — 排序後的資料
+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>` | 建立可為空的 Optional | O(1) |
+| `static ofNonNull<T>(value: T)` | `Optional<T>` | 建立非空 Optional | O(1) |
 
+**程式碼範例補充：**
 ```typescript
-const ordered = semanticStream.sorted(); // 自然排序
-const customSorted = semanticStream.sorted((a, b) => a - b); // 自訂比較器
-const orderedCollectable = semanticStream.toOrdered(); // 也會排序
-```
+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"); // 獲取值或預設值
 
-### 5. `Collector<E, A, R>` — 資料聚合
+console.log(result); // "HELLO" 或 "default"
 
-Collector 可讓您將資料流**縮減為單一值或複雜的資料結構**。
+// 安全操作
+optionalValue.ifPresent(val => {
+    console.log(`值存在: ${val}`);
+});
 
-內建靜態工廠：
+// 檢查狀態
+if (optionalValue.isPresent()) {
+    console.log("有值");
+} else if (optionalValue.isEmpty()) {
+    console.log("為空");
+}
+```
 
+### Semantic<E> - 惰性資料流
+
+Semantic 是核心的串流處理類別，提供豐富的串流運算子。
+
+#### 串流轉換操作
+
+| 方法 | 回傳型別 | 描述 | 效能影響 |
+|------|----------|------|----------|
+| `concat(other: Semantic<E>)` | `Semantic<E>` | 連接兩個串流 | 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
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
-```
+import { from } from 'semantic-typescript';
 
-但您通常會透過 `Collectable` 類別提供的高階方法來使用它們。
+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(`元素 ${val} 在索引 ${index}`)); // 檢視元素
 
-### 6. `Collectable<E>`（抽象類別）
+// 注意：串流尚未執行，需要轉換為 Collectable 以進行終端操作
+```
 
-以下類別的基礎：
+#### 串流終端操作
 
-- `OrderedCollectable<E>` — 排序後的資料
-- `UnorderedCollectable<E>` — 不排序，速度最快
-- `WindowCollectable<E>` — 滑動視窗資料
-- `Statistics<E, D>` — 統計資料聚合
+| 方法 | 回傳型別 | 描述 | 效能特性 |
+|------|----------|------|----------|
+| `toOrdered()` | `OrderedCollectable<E>` | 轉換為有序集合 | 排序操作，效能較低 |
+| `toUnordered()` | `UnorderedCollectable<E>` | 轉換為無序集合 | 最快，無排序 |
+| `toWindow()` | `WindowCollectable<E>` | 轉換為視窗集合 | 排序操作，效能較低 |
+| `toNumericStatistics()` | `Statistics<E, number>` | 數值統計分析 | 排序操作，效能較低 |
+| `toBigintStatistics()` | `Statistics<E, bigint>` | 大整數統計分析 | 排序操作，效能較低 |
+| `sorted()` | `OrderedCollectable<E>` | 自然排序 | 覆寫重新導向結果 |
+| `sorted(comparator)` | `OrderedCollectable<E>` | 自訂排序 | 覆寫重新導向結果 |
 
-#### 常見方法（繼承而來）：
+**程式碼範例補充：**
+```typescript
+import { from } from 'semantic-typescript';
 
-| 方法 | 說明 | 範例 |
-|------|------|------|
-| `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 semanticStream = from([5, 2, 8, 1, 9, 3, 7, 4, 6]);
 
----
+// 轉換為有序集合（效能較低）
+const ordered = semanticStream.toOrdered();
 
-### 7. `OrderedCollectable<E>` — 排序資料
+// 轉換為無序集合（最快）
+const unordered = semanticStream.toUnordered();
 
-如果您希望資料**自動排序**，可使用此類別。
+// 自然排序
+const sortedNatural = semanticStream.sorted();
 
-可接受**自訂比較器**，或使用自然排序。
+// 自訂排序
+const sortedCustom = semanticStream.sorted((a, b) => b - a); // 降序排序
 
-```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
-```
+// 轉換為統計物件
+const stats = semanticStream.toNumericStatistics();
 
-🔒 **保證輸出為排序後的資料。**
+// 注意：必須透過 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> - 可收集資料抽象類別
 
----
+提供豐富的資料聚合和轉換方法。**注意：必須先透過 Semantic 實例呼叫 sorted()、toOrdered() 等方法獲取 Collectable 實例，然後才能使用以下方法。**
 
-### 9. `Statistics<E, D>` — 統計分析
+#### 資料查詢操作
 
-用於分析數值資料的抽象基礎類別。
+| 方法 | 回傳型別 | 描述 | 範例 |
+|------|----------|------|------|
+| `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()` |
 
-#### 子類別：
+**程式碼範例補充：**
+```typescript
+import { from } from 'semantic-typescript';
 
-- `NumericStatistics<E>` — 適用於 `number` 類型
-- `BigIntStatistics<E>` — 適用於 `bigint` 類型
+const numbers = from([1, 2, 3, 4, 5]);
 
-##### 常見統計方法：
+// 必須先轉換為 Collectable 才能使用終端方法
+const collectable = numbers.toUnordered();
 
-| 方法 | 說明 | 範例 |
-|------|------|------|
-| `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()` | 頻率統計（Map） | `.frequency()` |
-
----
-
-## 🧪 完整範例
+// 資料查詢操作
+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 方法
 
-本套件也提供多種**型別守衛（Type Guards）**與**比較工具**：
+#### 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, ...]
 
-或者使用**滑動視窗（Sliding Window）**：
+// 視窗收集器
+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(); // 任意值（因為每個都出現一次）
+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 型別
 
-歡迎提交 Pull Request、提出問題（Issues）或分享想法！
+**BigIntStatistics<E>**
+- 處理 bigint 型別的統計分析
+- 所有統計計算回傳 bigint 型別
 
----
+**程式碼範例補充：**
+```typescript
+import { from } from 'semantic-typescript';
 
-## 🚀 快速入門總覽
+// 數值統計
+const numberData = from([10, 20, 30, 40, 50]);
+const numericStats = numberData.toNumericStatistics();
 
-| 任務 | 方法 |
-|------|------|
-| 安全處理 null/undefined | `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()` 檢查無效資料
+
+這種設計確保了型別安全性和效能最佳化，同時提供豐富的串流處理功能。