semantic-typescript 0.5.3 → 0.6.0

package/readme.tw.md

@@ -1,489 +1,214 @@
-# Semantic-TypeScript 流處理庫
+# Semantic-TypeScript：一款範式轉換的串流處理函式庫
 
 ## 簡介
+Semantic-TypeScript 代表了串流處理技術的一項重大進步，它綜合了 JavaScript GeneratorFunctions、Java Streams 和資料庫索引範式中最有效的概念。其基礎設計原則的核心是透過複雜的惰性求值和智慧索引建構極其高效的資料處理管道。該函式庫提供了一個嚴格型別安全、函數式純正的串流式操作體驗，專門為現代 TypeScript 和 JavaScript 開發而設計。
 
-Semantic-TypeScript 是一個現代化的流處理庫，受到 JavaScript GeneratorFunction、Java Stream 和 MySQL Index 的啟發。它的核心設計哲學是基於數據索引來構建高效的數據處理管道，為前端開發提供類型安全、函數式風格的流式操作體驗。
+與傳統的同步處理架構相比，Semantic-TypeScript 實現了一個統一模型，優雅地處理同步（Iterable）和非同步（AsyncIterable）資料來源。在串流生成過程中，資料的流動和終止由回呼機制精確控制，使函式庫能夠以超凡的優雅處理：
 
-與傳統的同步處理不同，Semantic 使用異步處理模型。在創建數據流時，終端接收數據的時間完全取決於上游何時調用 `accept` 和 `interrupt` 回調函數。這種設計使得庫能夠優雅地處理實時數據流、大數據集和異步數據源。
+- 具有確定性控制的即時資料流（DOM 事件、WebSockets、時間間隔）
+- 透過記憶體高效的惰性管道處理大規模資料集
+- 透過流暢、宣告式的 API 進行複雜的資料轉換
 
-## 安裝
+該函式庫的創新方法從根本上重新構想了開發者與資料序列互動的方式，在一個單一、內聚的套件中同時提供了前所未有的效能特性和開發者體驗。
 
-```bash
-npm install semantic-typescript
-```
+## 核心理念：定義與執行的分離
+Semantic-TypeScript 的一個關鍵架構洞見是清晰地分離串流的定義和執行：
 
-## 基本類型
-
-| 類型 | 描述 |
-|------|------|
-| `Invalid<T>` | 擴展自 `null` 或 `undefined` 的類型 |
-| `Valid<T>` | 排除 `null` 和 `undefined` 的類型 |
-| `MaybeInvalid<T>` | 可能是 `null` 或 `undefined` 的類型 |
-| `Primitive` | 原始類型的集合 |
-| `MaybePrimitive<T>` | 可能是原始類型的類型 |
-| `OptionalSymbol` | `Optional` 類的 Symbol 標識符 |
-| `SemanticSymbol` | `Semantic` 類的 Symbol 標識符 |
-| `CollectorsSymbol` | `Collector` 類的 Symbol 標識符 |
-| `CollectableSymbol` | `Collectable` 類的 Symbol 標識符 |
-| `OrderedCollectableSymbol` | `OrderedCollectable` 類的 Symbol 標識符 |
-| `WindowCollectableSymbol` | `WindowCollectable` 類的 Symbol 標識符 |
-| `StatisticsSymbol` | `Statistics` 類的 Symbol 標識符 |
-| `NumericStatisticsSymbol` | `NumericStatistics` 類的 Symbol 標識符 |
-| `BigIntStatisticsSymbol` | `BigIntStatistics` 類的 Symbol 標識符 |
-| `UnorderedCollectableSymbol` | `UnorderedCollectable` 類的 Symbol 標識符 |
-
-## 函數式接口
-
-| 介面 | 描述 |
-|------|------|
-| `Runnable` | 無參數且無返回值的函數 |
-| `Supplier<R>` | 無參數並返回 `R` 的函數 |
-| `Functional<T, R>` | 單參數轉換函數 |
-| `BiFunctional<T, U, R>` | 雙參數轉換函數 |
-| `TriFunctional<T, U, V, R>` | 三參數轉換函數 |
-| `Predicate<T>` | 單參數斷言函數 |
-| `BiPredicate<T, U>` | 雙參數斷言函數 |
-| `TriPredicate<T, U, V>` | 三參數斷言函數 |
-| `Consumer<T>` | 單參數消費函數 |
-| `BiConsumer<T, U>` | 雙參數消費函數 |
-| `TriConsumer<T, U, V>` | 三參數消費函數 |
-| `Comparator<T>` | 雙參數比較函數 |
-| `Generator<T>` | 生成器函數（核心與基礎） |
+- **Semantic<E>**：一個不可變的、惰性的資料轉換管道藍圖。它定義了將執行哪些操作（過濾、映射等）
+- **Collectable<E>**：一個已實例化的、可執行的串流視圖。它是從 Semantic 獲取的，並提供所有終端操作（收集、遍歷等）來執行管道並產生結果
 
-```typescript
-// 類型使用範例
-let predicate: Predicate<number> = (n: number): boolean => n > 0;
-let mapper: Functional<string, number> = (text: string): number => text.length;
-let comparator: Comparator<number> = (a: number, b: number): number => a - b;
-```
+這種分離強化了清晰的心智模型，並釋放了強大的最佳化能力，例如選擇 UnorderedCollectable 來跳過不必要的排序以實現最大速度。
 
-## 類型守衛
-
-| 函數 | 描述 | 時間複雜度 | 空間複雜度 |
-|------|------|------------|------------|
-| `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) |
-| `isPromise(t: unknown): t is Promise<unknown>` | 檢查是否為 Promise 物件 | O(1) | O(1) |
-| `isAsync(t: unknown): t is AsyncFunction` | 檢查是否為 AsyncFunction | O(1) | O(1) |
+## 為什麼選擇 Semantic-TypeScript？
+為資料串流處理選擇合適的函式庫需要在效能、型別安全性和表達能力之間取得平衡。Semantic-TypeScript 的設計旨在所有這些維度上都表現出色。
 
-```typescript
-// 類型守衛使用範例
-let value: unknown = "hello";
+### 1. 適用於所有資料序列的統一、型別安全範式
+它為處理任何資料序列（無論是靜態陣列、即時事件還是非同步區塊）提供了一致的宣告式 API，同時利用 TypeScript 的全部功能確保端到端的型別安全。這消除了一整類執行時錯誤，並將串流操作轉變為可預測的、經過編譯器驗證的活動。
 
-if (isString(value)) {
-    console.log(value.length); // 類型安全，value 被推斷為字串
-}
+### 2. 以智慧惰性求值實現的不妥協效能
+該函式庫的核心建立在惰性求值之上。諸如過濾器、映射和扁平映射等操作僅僅是組合一個處理管道；直到呼叫終端操作時，實際工作才會執行。這結合了短路功能（透過限制、任何匹配或自訂中斷回呼），允許處理提前停止，從而極大地提高了大型或無限串流的處理效率。
 
-if (isOptional(someValue)) {
-    someValue.ifPresent((value): void => console.log(val));
-}
+### 3. `Collector<E, A, R>` 模式的強大之處
+受 Java 啟發，收集器模式是靈活性的引擎。它將如何累積串流元素的規範與串流本身的執行解耦。該函式庫為日常任務提供了一組豐富的內建收集器（toArray、groupBy、summate 等），同時使實現您自己複雜的、可重用的歸約邏輯變得非常簡單。這比固定的一組終端方法要強大和可組合得多。
 
-if(isIterable(value)){
-    // 類型安全，現在它是可迭代物件
-    for(let item of value){
-        console.log(item);
-    }
-}
-```
+### 4. 對現代 Web 和非同步資料的一流支援
+Semantic-TypeScript 專為當代開發而設計。它為現代網路來源提供了原生工廠方法：
 
-## 工具函數
+- `useFrom(iterable)`, `useRange()` 用於靜態資料
+- `useInterval()`, `useAnimationFrame()` 用於基於時間的串流
+- `useBlob()` 用於分塊二進位資料處理
+- `useWebSocket()`, `useDocument()`, `useWindow()` 用於即時事件流
 
-| 函數 | 描述 | 時間複雜度 | 空間複雜度 |
-|------|------|------------|------------|
-| `useCompare<T>(t1: T, t2: T): number` | 泛型比較函數 | O(1) | O(1) |
-| `useRandom<T = number \| bigint>(index: T): T` | 偽隨機數產生器 | O(log n) | O(1) |
+### 5. 超越基本聚合：內建統計分析
+超越簡單的求和與平均。該函式庫提供了專用的 NumericStatistics 和 BigIntStatistics 介面，可以直接從您的串流中即時存取進階統計指標——變異數、標準差、中位數、偏度和峰度。這將複雜的資料分析變成了一行程式碼。
 
-```typescript
-// 工具函數使用範例
-let numbers: Array<number> = [3, 1, 4, 1, 5];
-numbers.sort(useCompare); // [1, 1, 3, 4, 5]
+### 6. 為開發者體驗而設計
+- **流暢、可鏈式呼叫的 API**：將複雜的資料管道編寫為可讀的、順序鏈
+- **全面的工具套件**：包含必要的守衛（isFunction, isIterable）、實用程式（useCompare, useTraverse）和函數式介面
+- **Optional<T> 整合**：安全地建模值的缺失，消除了空指標的擔憂
+- **效能指南**：清楚地指導何時使用無序集合以獲得速度，何時使用有序集合以保持序列
 
-let randomNum = useRandom(42); // 基於種子的隨機數
+## 安裝
+```bash
+npm install semantic-typescript
 ```
 
-## 工廠方法
+## 核心概念實踐
 
-### 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) |
+### 1. 建立串流 (Semantic)
+可以使用工廠函數從各種來源建立串流。
 
 ```typescript
-// Optional 使用範例
-let empty: Optional<number> = Optional.empty();
-let present: Optional<number> = Optional.of(42);
-let nullable: Optional<string> = Optional.ofNullable<string>(null);
-let nonNull: Optional<string> = Optional.ofNonNull("hello");
-
-presentO.ifPresent((value: number): void => console.log(value)); // 輸出 42
-console.log(empty.get(100)); // 輸出 100
-```
-
-### Collector 工廠方法
-
-| 方法 | 描述 | 時間複雜度 | 空間複雜度 |
-|------|------|------------|------------|
-| `Collector.full(identity, accumulator, finisher)` | 建立一個完整的收集器 | O(1) | O(1) |
-| `Collector.shortable(identity, interruptor, accumulator, finisher)` | 建立一個可中斷的收集器 | O(1) | O(1) |
+import { useFrom, useInterval, useDocument } from 'semantic-typescript';
 
-```typescript
-// Collector 轉換範例
-let numbers: Semantic<number> = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
-
-// 效能優先：使用無序收集器
-let unordered: UnorderedCollectable<number> = from([3, 1, 4, 1, 5, 9, 2, 6, 5])
-    .filter((n: number): boolean => n > 3)
-    .toUnordered();
-
-// 需要排序：使用有序收集器  
-let ordered: OrderedCollectable<number> = from([3, 1, 4, 1, 5, 9, 2, 6, 5])
-    .sorted();
-
-// 統計元素數量
-let count: Collector<number, number, number> = Collector.full(
-    (): number => 0, // 初始值
-    (accumulator: number, element: number): number => accumulator + element, // 累積
-    (accumulator: number): number => accumulator // 完成
-);
-count.collect(from([1,2,3,4,5])); // 從流中統計
-count.collect([1,2,3,4,5]); // 從可迭代物件統計
-
-let find: Optional<number> = Collector.shortable(
-    (): Optional<number> => Optional.empty(), // 初始值
-    (element: number, index: bigint, accumulator: Optional<number>): Optional<number> => accumulator.isPresent(), // 中斷
-    (accumulator: Optional<number>, element: number, index: bigint): Optional<number> => Optional.of(element), // 累積
-    (accumulator: Optional<number>): Optional<number> => accumulator // 完成
-);
-find.collect(from([1,2,3,4,5])); // 查找第一個元素
-find.collect([1,2,3,4,5]); // 查找第一個元素
-```
+// 從靜態陣列建立
+const staticStream = useFrom([1, 2, 3, 4, 5]);
 
-### Semantic 工廠方法
+// 從非同步產生器建立
+const asyncStream = useFrom(async function*() {
+  yield 1;
+  yield 2;
+});
 
-| 方法 | 描述 | 時間複雜度 | 空間複雜度 |
-|------|------|------------|------------|
-| `animationFrame(period: number, delay: number = 0)` | 建立定時動畫幀流 | O(1)* | O(1) |
-| `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) |
+// 一個基於時間的串流
+const tickStream = useInterval(1000); // 每秒發射一次
 
-```typescript
-// Semantic 工廠方法使用範例
-
-// 從定時動畫幀建立流
-animationFrame(1000)
-    .toUnordered()
-    .forEach(frame => console.log(frame));
-
-// 從 Blob 建立流（分塊讀取）
-blob(someBlob, 1024n)
-    .toUnordered()
-    .write(WritableStream)
-    .then(callback) // 寫入流成功
-    .catch(callback); // 寫入流失敗
-
-// 建立空流，需與其他流連接後才會執行
-empty<string>()
-    .toUnordered()
-    .join(); //[]
-
-// 建立填充流
-let filledStream = fill("hello", 3); // "hello", "hello", "hello"
-
-// 建立初始延遲 2 秒、執行週期 5 秒的定時流，基於定時器機制實現；可能因系統排程精確度限制產生時間漂移。
-let intervalStream = interval(5000, 2000);
-
-// 從可迭代物件建立流
-let numberStream = from([1, 2, 3, 4, 5]);
-let stringStream = from(new Set(["Alex", "Bob"]));
-
-// 從已解析的 Promise 建立流
-let promisedStream: Semantic<Array<number>> = Promise.resolve([1, 2, 3, 4, 5]);
-
-// 建立範圍流
-let rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
-
-// WebSocket 事件流
-let ws = new WebSocket("ws://localhost:8080");
-websocket(ws)
-  .filter((event): boolean => event.type === "message"); // 僅監聽訊息事件
-  .toUnordered() // 事件通常無序
-  .forEach((event): void => receive(event)); // 接收訊息
+// 一個 DOM 事件流（參見下面的重要說明）
+const clickStream = useDocument('click');
 ```
 
-## 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) |
+### 2. 轉換串流（中間操作）
+透過鏈式惰性呼叫來定義管道。
 
 ```typescript
-// Semantic 操作範例
-let result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .filter((n: number): boolean => n % 2 === 0)        // 過濾偶數
-    .map((n: number): number => n * 2)                 // 乘以 2
-    .skip(1)                         // 跳過第一個
-    .limit(3)                        // 限制為 3 個元素
-    .toUnordered()                   // 轉換為無序收集器
-    .toArray();                      // 轉換為陣列
-// 結果: [8, 12, 20]
-
-// 複雜操作範例
-let complexResult = range(1, 100, 1)
-    .flatMap((n: number): Semantics<number> => from([n, n * 2])) // 將每個元素映射為兩個
-    .distinct()                      // 移除重複項
-    .shuffle()                       // 隨機洗牌
-    .takeWhile((n: number): boolean => n < 50)         // 取小於 50 的元素
-    .toOrdered()                     // 轉換為有序收集器
-    .toArray();                      // 轉換為陣列
-```
-
-## Semantic 轉換方法
-
-| 方法 | 描述 | 時間複雜度 | 空間複雜度 |
-|------------|------------|------------|------------|
-| `sorted()` | 轉換為有序收集器 | O(n log n) | O(n) |
-| `toUnordered()` | 轉換為無序收集器 | O(1) | O(1) |
-| `toOrdered()` | 轉換為有序收集器 | O(1) | O(1) |
-| `toNumericStatistics()` | 轉換為數值統計 | O(n) | O(1) |
-| `toBigintStatistics()` | 轉換為 BigInt 統計 | O(n) | O(1) |
-| `toWindow()` | 轉換為視窗收集器 | O(1) | O(1) |
-| `toCollectable()` | 轉換為 `UnorderdCollectable` | O(n) | O(1) |
-| `toCollectable(mapper)` | 轉換為自訂收集器 | O(n) | O(1) |
+const processedStream = staticStream
+  .filter(x => x % 2 === 0)  // 僅保留偶數
+  .map(x => x * 10)          // 乘以 10
+  .flatMap(x => [x, x + 1])  // 將每個元素轉換為兩個
+  .distinct();               // 移除重複項
 
-```typescript
-// 轉換為升序陣列
-from([6,4,3,5,2]) // 建立流
-    .sorted() // 按升序排序
-    .toArray(); // [2, 3, 4, 5, 6]
-
-// 轉換為降序陣列
-from([6,4,3,5,2]) // 建立流
-    .soted((a: number, b: number): number => b - a) // 按降序排序
-    .toArray(); // [6, 5, 4, 3, 2]
-
-// 重定向為倒序陣列
-from([6,4,3,5,2])
-    .redirect((element, index): bigint => -index) // 重定向為倒序
-    .toOrderd() // 保持重定向順序
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// 忽略重定向以倒序陣列
-from([6,4,3,5,2])
-    .redirect((element: number, index: bigint) => -index) // 重定向為倒序
-    .toUnorderd() // 丟棄重定向順序。此操作將忽略 `redirect`、`reverse`、`shuffle` 和 `translate` 操作
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// 反轉流為陣列
-from([6, 4, 3, 5, 2])
-    .reverse() // 反轉流
-    .toOrdered() // 保證反轉順序
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// 覆蓋洗牌的流為陣列
-from([6, 4, 3, 5, 2])
-    .shuffle() // 洗牌流
-    .sorted() // 覆蓋洗牌順序。此操作將覆蓋 `redirect`、`reverse`、`shuffle` 和 `translate` 操作
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// 轉換為視窗收集器
-from([6, 4, 3, 5, 2]).toWindow();
-
-// 轉換為數值統計
-from([6, 4, 3, 5, 2]).toNumericStatistics();
-
-// 轉換為 BigInt 統計
-from([6n, 4n, 3n, 5n, 2n]).toBigintStatistics();
-
-// 定義自訂收集器來收集資料
-let customizedCollector = from([1, 2, 3, 4, 5]).toCollectable((generator: Generator<E>) => new CustomizedCollector(generator));
+// 此時尚未執行任何操作
 ```
 
-## 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) |
+### 3. 執行串流（終端操作）
+要獲得結果，必須取得一個 Collectable 並呼叫終端操作。
 
 ```typescript
-// Collectable 操作範例
-let data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .filter((n: number): boolean => n % 2 === 0)
-    .toOrdered();
-
-// 符合檢查
-console.log(data.anyMatch((n: number): boolean => n > 5)); // true
-console.log(data.allMatch((n: number): boolean => n < 20)); // true
-
-// 查找操作
-data.findFirst().ifPresent((n: number): void => console.log(n)); // 2
-data.findAny().ifPresent((n: number): void => console.log(n)); // 任何元素
-
-// 分組操作
-let grouped = data.groupBy(
-    (n: number): string => (n > 5 ? "large" : "small"),
-    (n: number): number => n * 2
-); // {small: [4, 8], large: [12, 16, 20]}
-
-// 歸約操作
-let sum = data.reduce(0, (accumulator: number, n: number): number => accumulator + n); // 30
-
-// 輸出操作
-data.join(", "); // "[2, 4, 6, 8, 10]"
+// 取得一個無序收集器以提高效能
+const resultArray = await processedStream.toUnordered().toArray();
+console.log(resultArray); // 例如：[20, 21, 40, 41]
+
+// 使用內建收集器
+const sum = await processedStream.toUnordered().collect(useSummate());
+console.log(sum);
+
+// 或使用通用的 collect 方法
+const customResult = await processedStream.toOrdered().collect(
+  () => new Map<number, number>(),
+  (map, element, index) => map.set(index, element),
+  map => map
+);
 ```
 
-## 統計分析方法
-
-### 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) |
+### 4. 關鍵：處理事件流
+事件流（useDocument, useWindow, useHTMLElement, useWebSocket）本質上是無限的。您必須使用諸如 sub、takeWhile 或 limit 等操作來定義何時停止收集事件並完成串流。否則，終端操作將無限期等待。
 
 ```typescript
-// 統計分析範例
-let 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
-
-// 使用映射器的統計分析
-let objects = from([
-    { value: 10 },
-    { value: 20 }, 
-    { value: 30 }
-]).toNumericStatistics();
-console.log("映射後的平均:", objects.mean(obj => obj.value)); // 20
+import { useDocument } from 'semantic-typescript';
+
+// 僅收集前 5 次點擊
+const first5Clicks = await useDocument('click')
+  .limit(5) // <- 關鍵：將串流限制為 5 個事件
+  .toUnordered()
+  .toArray();
+
+// 收集 10 秒視窗內的點擊
+const clicksIn10s = await useDocument('click')
+  .takeWhile((_, index, startTime = Date.now()) => Date.now() - startTime < 10000)
+  .toUnordered()
+  .toArray();
+
+// 收集索引 2 到 5 的點擊（基於 0）
+const specificClicks = await useDocument('click')
+  .sub(2n, 6n) // <- 獲取索引為 2, 3, 4, 5 的元素
+  .toUnordered()
+  .toArray();
 ```
 
-## 效能選擇指南
-
-### 選擇無序收集器（效能優先）
+**關鍵見解**：事件（例如 MouseEvent）及其順序觸發索引（作為大整數）透過 `accept(event, index)` 回呼一起在管道中傳遞。
 
+### 5. 利用統計功能
 ```typescript
-// 當不需要順序保證時，使用無序收集器以獲得最佳效能
-let highPerformance = data
-    .filter(predicate)
-    .map(mapper)
-    .toUnordered(); // 最佳效能
-```
+const numericStream = useFrom([10, 20, 30, 40, 50]).toNumeric();
 
-### 選擇有序收集器（需要順序）
+const average = await numericStream.average();
+const median = await numericStream.median();
+const standardDeviation = await numericStream.standardDeviation();
+const skewness = await numericStream.skewness();
 
-```typescript
-// 當需要維持元素順序時，使用有序收集器
-let ordered = data.sorted(comparator);
+console.log(`Average: ${average}, Median: ${median}, StdDev: ${standardDeviation}`);
 ```
 
-### 選擇視窗收集器（視窗操作）
-
+## 主要特性
+- **雙流類型**：完全支援同步語意（用於 Iterable）和非同步語意（用於 AsyncIterable 和事件）
+- **豐富的操作集**：過濾器、映射、扁平映射、連接、去重、排序、限制、跳過、檢視、反轉、打亂
+- **靈活的終端操作**：收集（使用自訂收集器）、toArray、toSet、toMap、forEach、reduce、findFirst、anyMatch、allMatch、count
+- **進階收集器**：用於連接、分組、分割區、求和、平均、最大值、最小值的內建收集器
+- **統計模組**：在數值/大整數流上用於均值、中位數、眾數、變異數、標準差、範圍、分位數、偏度、峰度的即用型方法
+- **實用函數**：型別守衛（isPromise, isAsyncIterable）、比較器（useCompare）、遍歷（useTraverse）和轉換勾點
+- **Optional<T>**：一個用於可空值的單子容器，與查詢操作整合
+
+## API 概述
+### 核心類別和介面
+- `Semantic<E>` / `AsynchronousSemantic<E>`：抽象的串流定義
+- `Collectable<E>` / `AsynchronousCollectable<E>`：具有終端操作的可執行串流
+- `OrderedCollectable<E>` / `UnorderedCollectable<E>`：為順序敏感或順序不敏感操作最佳化的實例化版本
+- `Collector<E, A, R>`：可變歸約操作的抽象
+
+### 工廠函數 (use*)
+- **從來源建立**：useFrom, useRange, useFill, useEmpty
+- **從時間建立**：useInterval, useAnimationFrame
+- **從 Web API 建立**：useBlob, useDocument, useWindow, useHTMLElement, useWebSocket
+- **收集器**：useToArray, useGroupBy, useSummate, useJoin 等
+
+## 效能說明
+- **惰性求值**：在呼叫終端操作之前，管道僅組合而不執行
+- **短路求值**：諸如限制、任何匹配和查詢首個等操作將在結果確定後立即停止處理元素
+- **有序與無序**：
+  - 當來源元素的順序對您的結果不重要時（例如，求和、最大值或 toSet），對終端操作使用 `.toUnordered()`。這允許內部最佳化跳過昂貴的排序步驟
+  - 當順序很重要時（例如，toArray 必須保留順序），使用 `.toOrdered()`
+
+## 入門範例
 ```typescript
-// 當需要視窗操作時
-let window: WindowCollectable<number> = data
-    .toWindow()
-    .slide(5n, 2n); // 滑動視窗
-```
+import { useFrom, useSummate, useGroupBy } from 'semantic-typescript';
 
-### 選擇統計分析（數值計算）
+interface Transaction {
+  id: number;
+  amount: number;
+  category: string;
+}
 
-```typescript
-// 當需要統計分析時
-let statistics: NumericStatistics<number> = data
-    .toNumericStatistics(); // 數值統計
-let bigIntStatistics: BigintStatistics<bigint> = data
-    .toBigintStatistics(); // 大整數統計
+const transactions: Transaction[] = [
+  { id: 1, amount: 100, category: 'Food' },
+  { id: 2, amount: 200, category: 'Electronics' },
+  { id: 3, amount: 50, category: 'Food' },
+  { id: 4, amount: 300, category: 'Electronics' },
+];
+
+// 計算每個類別的總金額
+const totalsByCategory = await useFrom(transactions)
+  .toUnordered()
+  .collect(
+    useGroupBy(
+      t => t.category,
+      t => t.amount,
+      useSummate() // 值的收集器
+    )
+  );
+
+console.log(totalsByCategory); // Map { 'Food' => 150, 'Electronics' => 500 }
 ```
 
-[GitHub](https://github.com/eloyhere/semantic-typescript)
-[NPMJS](https://www.npmjs.com/package/semantic-typescript)
-
-## 重要注意事項
-
-1. **排序操作的影響**：在有序收集器中，`sorted()` 操作會覆蓋 `redirect`、`translate`、`shuffle`、`reverse` 的效果。
-2. **效能考量**：如果不需要順序保證，優先使用 `toUnordered()` 以獲得更好的效能。
-3. **記憶體使用**：排序操作需要額外的 O(n) 空間。
-4. **即時資料**：Semantic 流適用於處理即時資料，並支援異步資料來源。
+Semantic-TypeScript 是為那些尋求嚴格設計、型別安全和高效能串流處理函式庫的開發者而建構的。它將企業級資料轉換模式的力量帶入了 TypeScript 生態系統，非常適合資料密集型前端應用程式、Node.js 資料處理，以及任何需要優雅、高效處理序列的場景。
 
-這個庫為 TypeScript 開發者提供了強大而靈活的流處理能力，結合了函數式程式設計的好處和類型安全的保證。
+[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript)