semantic-typescript 0.0.7 → 0.1.4

package/readme.tw.md

@@ -1,335 +1,426 @@
-# 📘 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()` |
+## 基礎類型
 
-#### 範例：
+| 類型 | 描述 |
+|------|------|
+| `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` | 檢查是否為 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>` — 延遲資料流（Lazy Data Stream）
+```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)` | 從陣列、集合或可迭代物件建立 | `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)` | 使用 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)` | 創建可能為空的 Optional | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value)` | 創建非空的 Optional | 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) |
 
-Collector 可讓您將資料流**縮減為單一值或複雜的資料結構**。
+```typescript
+// 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)); // 接收訊息
+```
 
-內建靜態工廠：
+## 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
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// 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])) // 每個元素映射為兩個
+    .distinct()                      // 去重
+    .shuffle()                       // 打亂順序
+    .takeWhile(n => n < 50)         // 取小於50的元素
+    .toOrdered()                     // 轉換為有序收集器
+    .toArray();                      // 轉換為陣列
 ```
 
-但您通常會透過 `Collectable` 類別提供的高階方法來使用它們。
+## 收集器轉換方法
 
----
+| 方法 | 描述 | 時間複雜度 | 空間複雜度 |
+|------|------|------------|------------|
+| `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()` | 轉換為大數統計 | O(1) | O(1) |
 
-### 6. `Collectable<E>`（抽象類別）
-
-以下類別的基礎：
+```typescript
+// 收集器轉換示例
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
 
-- `OrderedCollectable<E>` — 排序後的資料
-- `UnorderedCollectable<E>` — 不排序，速度最快
-- `WindowCollectable<E>` — 滑動視窗資料
-- `Statistics<E, D>` — 統計資料聚合
+// 效能優先：使用無序收集器
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
 
-#### 常見方法（繼承而來）：
+// 需要排序：使用有序收集器  
+const ordered = numbers.sorted();
 
-| 方法 | 說明 | 範例 |
-|------|------|------|
-| `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 stats = numbers
+    .toNumericStatistics();
 
----
+console.log(stats.mean());        // 平均值
+console.log(stats.median());      // 中位數
+console.log(stats.standardDeviation()); // 標準差
 
-### 7. `OrderedCollectable<E>` — 排序資料
+// 視窗操作
+const windowed = numbers
+    .toWindow()
+    .tumble(3n); // 每3個元素一個視窗
 
-如果您希望資料**自動排序**，可使用此類別。
+windowed.forEach(window => {
+    console.log(window.toArray()); // 每個視窗的內容
+});
+```
 
-可接受**自訂比較器**，或使用自然排序。
+## 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
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// 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"
 ```
 
-🔒 **保證輸出為排序後的資料。**
-
----
-
-### 8. `UnorderedCollectable<E>` — 不排序（🚀 最快）
-
-如果您**不在意資料順序**，且希望獲得**最佳效能**，可使用：
+## 統計分析方法
+
+### 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 unordered = new UnorderedCollectable(stream);
-// 或
-const fastest = semanticStream.toUnordered();
+// 統計分析示例
+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
 ```
 
-✅ **不執行任何排序演算法**  
-✅ **當資料順序不重要時，提供最快速的處理方式**
-
----
-
-### 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()` | 頻率統計（Map） | `.frequency()` |
-
----
-
-## 🧪 完整範例
+## 效能選擇指南
 
+### 選擇無序收集器（效能優先）
 ```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());
+// 當不需要順序保證時，使用無序收集器獲得最佳效能
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // 最佳效能
 ```
 
----
-
-## 🛠️ 工具函數
-
-本套件也提供多種**型別守衛（Type Guards）**與**比較工具**：
-
-| 函數 | 用途 |
-|------|------|
-| `isString(x)` | 判斷是否為 `string` |
-| `isNumber(x)` | 判斷是否為 `number` |
-| `isBoolean(x)` | 判斷是否為 `boolean` |
-| `isIterable(x)` | 判斷是否為可迭代物件 |
-| `useCompare(a, b)` | 通用比較函數 |
-| `useRandom(x)` | 偽隨機數生成器（趣味用途） |
-
----
-
-## 🧩 進階：自訂生成器與滑動視窗
-
-您可以建立**自訂的資料生成器**，用於控制或無限的資料流：
-
+### 選擇有序收集器（需要順序）
 ```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
+    .sorted(comparator) // 排序操作會覆蓋重定向效果
 ```
 
-或者使用**滑動視窗（Sliding Window）**：
-
+### 選擇視窗收集器（視窗操作）
 ```typescript
-const windowed = ordered.slide(3n, 2n); // 視窗大小為 3，每次移動 2
+// 需要進行視窗操作時
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // 滑動視窗
 ```
 
----
-
-## 📄 授權
-
-本專案採用 **MIT 授權**，可免費用於商業或個人用途。
-
----
-
-## 🙌 貢獻
-
-歡迎提交 Pull Request、提出問題（Issues）或分享想法！
-
----
-
-## 🚀 快速入門總覽
-
-| 任務 | 方法 |
-|------|------|
-| 安全處理 null/undefined | `Optional<T>` |
-| 建立資料流 | `from([...])`、`range()`、`fill()` |
-| 資料轉換 | `map()`、`filter()` |
-| 資料排序 | `sorted()`、`toOrdered()` |
-| 不排序（最快） | `toUnordered()` ✅ |
-| 分組 / 聚合 | `toMap()`、`group()`、`Collector` |
-| 統計分析 | `NumericStatistics`、`mean()`、`median()` 等 |
-
----
-
-## 🔗 相關連結
+### 選擇統計分析（數值計算）
+```typescript
+// 需要進行統計分析時
+const stats = data
+    .toNumericStatistics(); // 數值統計
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 文件：請參考原始碼 / 類型定義
+const bigIntStats = data
+    .toBigintStatistics(); // 大數統計
+```
 
----
+[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 開發者提供了強大而靈活的流式處理能力，結合了函數式編程的優點和類型安全的保障。