semantic-typescript 0.3.7 → 0.3.8

package/readme.cn.md

@@ -1,10 +1,60 @@
-# Semantic-TypeScript 流式处理库
+# Semantic-TypeScript 流处理库
 
-## 简介
+## 引言
 
-Semantic-TypeScript 是一个受 JavaScript GeneratorFunction、Java Stream 和 MySQL 索引启发的现代流式处理库。其核心理念是基于数据索引构建高效的数据处理管道，为前端开发提供类型安全、函数式风格的流式操作体验。
+**Semantic-TypeScript: 现代网络流处理技术的范式转变**
 
-与传统同步处理不同，Semantic 采用异步处理模型。在创建数据流时，终端接收到数据的时间完全取决于上游何时调用 `accept` 与 `interrupt` 回调函数。这种设计使该库能够优雅地处理实时数据流、大数据集以及异步数据源。
+Semantic-TypeScript 代表着流处理技术的一次重大进步，它综合了 JavaScript GeneratorFunction、Java Stream 和 MySQL 索引范式中最有效的概念。其基础设计原则围绕通过复杂的数据索引方法构建极其高效的数据处理管道。该库为现代前端开发专门提供了一个严格类型安全、函数式纯正的流操作体验。
+
+与传统同步处理架构相比，Semantic-TypeScript 实现了完全异步的处理模型。在数据流生成过程中，终端接收数据的时间完全由上游对 `accept` 和 `interrupt` 回调机制的调用决定。这种深思熟虑的架构选择使库能够异常优雅地处理：
+
+- 具有确定性延迟特性的**实时数据流**
+- 通过内存高效处理管道处理的**大规模数据集**
+- 具有保证一致性和可靠性的**异步数据源**
+
+该库的创新方法从根本上重新构想了开发者与流数据的交互方式，在一个统一的、内聚的包中提供了前所未有的性能特性和开发者体验。
+
+### 为何选择 Semantic-TypeScript？
+
+在 TypeScript 项目中选择合适的数据流处理库需要在性能、开发者体验和架构契合度之间取得平衡。Semantic-TypeScript 的设计旨在所有这些维度上都表现出色，为现代网络提供了一个范式转变的方法。以下是它脱颖而出的原因。
+
+#### 1. **统一、类型安全的流处理范式**
+Semantic-TypeScript 综合了 **JavaScript GeneratorFunctions**、**Java Streams API** 和**数据库索引策略**中最有效的概念。它为处理任何数据序列（无论是静态数组、实时事件还是异步数据块）提供了一个一致的声明式 API，同时充分利用 TypeScript 的全部功能来确保端到端的类型安全。这消除了整个类别的运行时错误，并将流操作转变为可预测的、编译器验证的活动。
+
+#### 2. **智能惰性求值与不妥协的性能**
+该库的核心建立在**惰性求值**之上。像 `filter`、`map` 和 `flatMap` 这样的操作只是组合一个处理管道；直到调用终端操作（如 `collect` 或 `toArray`）时才会执行任何工作。这与**短路**功能相结合（通过像 `limit`、`anyMatch` 或自定义的 `interruptor` 函数等操作），使得在处理已知结果时可以提前停止，从而显著提高大型或无限流的效率。
+
+#### 3. **架构区分：`Semantic<E>` 与 `Collectable<E>`**
+这个库引入了一个其他库通常缺乏的关键架构分离：
+*   **`Semantic<E>`**： 表示抽象的、惰性的流定义——数据转换的“蓝图”。它是不可变的且可组合的。
+*   **`Collectable<E>`**： 表示流的物化、可执行视图，提供所有终端操作。
+
+这种分离强制执行了一个清晰的思维模型，并允许进行优化（例如，如果不需要顺序，`UnorderedCollectable` 可以跳过昂贵的排序步骤）。
+
+#### 4. **`Collector<E, A, R>` 模式的力量**
+灵感来自 Java 的 `Collector` 模式是灵活性的引擎。它将*如何累积流元素*的*规范*与流本身的*执行*解耦。该库为日常任务提供了一组丰富的内置收集器（`useToArray`、`useGroupBy`、`useSummate` 等），同时该模式使得实现您自己复杂的、可重用的归约逻辑变得简单。这比一组固定的终端方法要强大和可组合得多。
+
+#### 5. **对现代网络和异步数据的原生支持**
+Semantic-TypeScript 为当代前端和 Node.js 开发而设计。它为现代网络源提供了原生工厂方法：
+*   `from(iterable)`、`range()` 用于静态数据。
+*   `interval()`、`animationFrame()` 用于基于时间的流。
+*   `blob()` 用于分块二进制数据处理。
+*   `websocket()` 用于实时消息流。
+它对 `Iterable` 和 `AsyncIterable` 协议的基础支持意味着它能够以同样优雅的 API 处理同步和异步数据流。
+
+#### 6. **超越基本聚合：内置统计分析**
+超越简单的求和与平均值。该库提供了专用的 `NumericStatistics` 和 `BigIntStatistics` 类，允许直接从您的流中立即访问高级统计度量——**方差、标准差、中位数、分位数、偏度和峰度**。这将复杂的数据分析变成一行代码，使您免于手动实现或集成另一个专门的库。
+
+#### 7. **为开发者体验而设计**
+*   **流式的、可链式调用的 API**： 将复杂的数据管道编写为可读的、连续的操作链。
+*   **全面的实用工具集**： 开箱即用地提供了必要的守卫（`isOptional`、`isSemantic`）、类型安全的实用工具（`useCompare`、`useTraverse`）和函数式接口。
+*   **`Optional<T>` 集成**： 安全地对无值状态建模，消除了查找操作中的空指针问题。
+*   **性能指南**： 文档清楚地指导您在何时使用 `toUnordered()`（为了最大速度）与 `toOrdered()`（当顺序很重要时）。
+
+#### 8. **稳健的、面向社区的基础**
+作为一个托管在 **GitHub** 上并通过 **npm** 分发的开源库，它是为实际使用而构建的。广泛的文档，包括时间和空间复杂度注释以及实用示例，降低了学习曲线，并为性能敏感的应用提供了清晰度。
+
+**总而言之，如果您正在寻找一个严格设计、类型安全且高性能的流处理库，它将企业级数据转换模式的力量带到 TypeScript 生态系统中，同时又不损害现代网络开发的习惯和需求，请选择 Semantic-TypeScript。**
 
 ## 安装
 
@@ -12,32 +62,32 @@ Semantic-TypeScript 是一个受 JavaScript GeneratorFunction、Java Stream 和
 npm install 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 标识符 |
+| `OptionalSymbol` | `Optional` 类的符号标识符 |
+| `SemanticSymbol` | `Semantic` 类的符号标识符 |
+| `CollectorsSymbol` | `Collector` 类的符号标识符 |
+| `CollectableSymbol` | `Collectable` 类的符号标识符 |
+| `OrderedCollectableSymbol` | `OrderedCollectable` 类的符号标识符 |
+| `WindowCollectableSymbol` | `WindowCollectable` 类的符号标识符 |
+| `StatisticsSymbol` | `Statistics` 类的符号标识符 |
+| `NumericStatisticsSymbol` | `NumericStatistics` 类的符号标识符 |
+| `BigIntStatisticsSymbol` | `BigIntStatistics` 类的符号标识符 |
+| `UnorderedCollectableSymbol` | `UnorderedCollectable` 类的符号标识符 |
 
 ## 函数式接口
 
 | 接口 | 描述 |
-|------|------|
-| `Runnable` | 无参数且无返回值的函数 |
-| `Supplier<R>` | 无参数并返回 `R` 的函数 |
+|-----------|-------------|
+| `Runnable` | 无参数、无返回值的函数 |
+| `Supplier<R>` | 无参数、返回 `R` 的函数 |
 | `Functional<T, R>` | 单参数转换函数 |
 | `BiFunctional<T, U, R>` | 双参数转换函数 |
 | `TriFunctional<T, U, V, R>` | 三参数转换函数 |
@@ -51,7 +101,7 @@ npm install semantic-typescript
 | `Generator<T>` | 生成器函数（核心与基础） |
 
 ```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;
@@ -61,8 +111,8 @@ let comparator: Comparator<number> = (a: number, b: number): number => 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) |
+| `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) |
@@ -83,41 +133,74 @@ let comparator: Comparator<number> = (a: number, b: number): number => a - b;
 | `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) |
+| `isAsyncFunction(t: unknown): t is AsyncFunction` | 检查是否为 AsyncFunction | O(1) | O(1) |
+| `isGenerator(t: unknown): t is Generator<unknown>` | 检查是否为 Generator | O(1) | O(1) |
+| `isGeneratorFunction(t: unknown): t is GeneratorFunction` | 检查是否为 GeneratorFunction | O(1) | O(1) |
+| `isAsyncGeneratorFunction(t: unknown): t is AsyncGeneratorFunction` | 检查是否为 AsyncGeneratorFunction | O(1) | O(1) |
 
 ```typescript
-// 类型守卫使用示例
+// 类型守卫用法示例
 let value: unknown = "hello";
 
 if (isString(value)) {
-    console.log(value.length); // 类型安全，value 被推断为 string
+    console.log(value.length); // 类型安全，value 推断为 string
 }
 
 if (isOptional(someValue)) {
-    someValue.ifPresent((value): void => console.log(val));
+    someValue.ifPresent((value): void => console.log(value));
 }
 
 if(isIterable(value)){
-    // 类型安全，现在它是可迭代对象
+    // 类型安全，现在它是一个可迭代对象。
     for(let item of value){
         console.log(item);
     }
 }
 ```
 
-## 工具函数
+## 实用函数
 
 | 函数 | 描述 | 时间复杂度 | 空间复杂度 |
 |------|------|------------|------------|
-| `useCompare<T>(t1: T, t2: T): number` | 泛型比较函数 | O(1) | O(1) |
+| `useCompare<T>(t1: T, t2: T): number` | 通用比较函数 | O(1) | O(1) |
 | `useRandom<T = number \| bigint>(index: T): T` | 伪随机数生成器 | O(log n) | O(1) |
+| `useTraverse(t, callback: BiPredicate<keyof T, T[keyof T]>): void` | 深度遍历对象，避免循环引用 | O(n) | O(1) |
+| `useToNumber(t: unknown): number` | 将值转换为数字 | O(1) | O(1) |
+| `useToBigInt(t: unknown): bigint` | 将值转换为 BigInt | O(1) | O(1) |
 
 ```typescript
-// 工具函数使用示例
+// 实用函数用法示例
 let numbers: Array<number> = [3, 1, 4, 1, 5];
 numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-let randomNum = useRandom(42); // 基于种子的随机数
+let randomNum: number = useRandom(42); // 基于种子的随机数
+
+let o = {
+    a: 1,
+    b: {
+        c: 2,
+        d: o
+    },
+    c: [1, 3, 5, o],
+    e: undefined,
+    f: null
+};
+useTraverse(o, (value, key): boolean => {
+    console.log(key, value);
+    /*
+    a 1
+    c 2
+    1 3 5
+    不遍历循环引用、undefined 和 null 值。
+    */
+    return true; // 返回 true 以继续遍历。
+});
+
+let toBeResolved: object = {
+    [Symbol.toPrimitive]: () => 5
+};
+let resolvedNumber: number = useToNumber(toBeResolved); // 5
+let resolvedBigInt: bigint = useToBigInt(toBeResolved); // 5n
 ```
 
 ## 工厂方法
@@ -126,13 +209,13 @@ let randomNum = useRandom(42); // 基于种子的随机数
 
 | 方法 | 描述 | 时间复杂度 | 空间复杂度 |
 |------|------|------------|------------|
-| `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) |
+| `Optional.empty<T>(): Optional<T>` | 创建一个空的 Optional | O(1) | O(1) |
+| `Optional.of<T>(value): Optional<T>` | 创建一个包含值的 Optional | O(1) | O(1) |
+| `Optional.ofNullable<T>(value): Optional<T>` | 创建一个可能为空的 Optional | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value): Optional<T>` | 创建一个非 null 的 Optional | O(1) | O(1) |
 
 ```typescript
-// Optional 使用示例
+// Optional 用法示例
 let empty: Optional<number> = Optional.empty();
 let present: Optional<number> = Optional.of(42);
 let nullable: Optional<string> = Optional.ofNullable<string>(null);
@@ -146,62 +229,174 @@ console.log(empty.get(100)); // 输出 100
 
 | 方法 | 描述 | 时间复杂度 | 空间复杂度 |
 |------|------|------------|------------|
-| `Collector.full(identity, accumulator, finisher)` | 创建完整收集器 | O(1) | O(1) |
-| `Collector.shortable(identity, interruptor, accumulator, finisher)` | 创建可中断收集器 | O(1) | O(1) |
+| `Collector.full(identity: Supplier<A>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个完整的收集器 | O(1) | O(1) |
+| `Collector.full(identity: Supplier<A>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个完整的收集器 | O(1) | O(1) |
+| `Collector.shortable(identity: Supplier<A>, interruptor: Predicate<E>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | O(1) | O(1) |
+| `Collector.shortable(identity: Supplier<A>, interruptor: Predicate<E>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | O(1) | O(1) |
+| `Collector.shortable(identity: Supplier<A>, interruptor: BiPredicate<E, bigint>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | O(1) | O(1) |
+| `Collector.shortable(identity: Supplier<A>, interruptor: BiPredicate<E, bigint>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | O(1) | O(1) |
+| `Collector.shortable(identity: Supplier<A>, interruptor: TriPredicate<E, bigint, A>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | O(1) | O(1) |
+| `Collector.shortable(identity: Supplier<A>, interruptor: TriPredicate<E, bigint, A>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | O(1) | O(1) |
+| `useAnyMatch<E>(predicate: Predicate<E>): Collector<E, boolean, boolean>` | 创建一个检查是否有任何元素匹配断言的收集器 | `predicate: Predicate<E>` | `Collector<E, boolean, boolean>` |
+| `useAllMatch<E>(predicate: Predicate<E>): Collector<E, boolean, boolean>` | 创建一个检查是否所有元素都匹配断言的收集器 | `predicate: Predicate<E>` | `Collector<E, boolean, boolean>` |
+| `useCollect<E, A, R>(identity: Supplier<A>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个完整的收集器 | `identity: Supplier<A>`, `accumulator: BiFunctional<A, E, A>`, `finisher: Functional<A, R>` | `Collector<E, A, R>` |
+| `useCollect<E, A, R>(identity: Supplier<A>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个完整的收集器 | `identity: Supplier<A>`, `accumulator: TriFunctional<A, E, bigint, A>`, `finisher: Functional<A, R>` | `Collector<E, A, R>` |
+| `useCollect<E, A, R>(identity: Supplier<A>, interruptor: Predicate<E>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | `identity: Supplier<A>`, `interruptor: Predicate<E>`, `accumulator: BiFunctional<A, E, A>`, `finisher: Functional<A, R>` | `Collector<E, A, R>` |
+| `useCollect<E, A, R>(identity: Supplier<A>, interruptor: Predicate<E>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | `identity: Supplier<A>`, `interruptor: Predicate<E>`, `accumulator: TriFunctional<A, E, bigint, A>`, `finisher: Functional<A, R>` | `Collector<E, A, R>` |
+| `useCollect<E, A, R>(identity: Supplier<A>, interruptor: BiPredicate<E, bigint>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | `identity: Supplier<A>`, `interruptor: BiPredicate<E, bigint>`, `accumulator: BiFunctional<A, E, A>`, `finisher: Functional<A, R>` | `Collector<E, A, R>` |
+| `useCollect<E, A, R>(identity: Supplier<A>, interruptor: BiPredicate<E, bigint>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | `identity: Supplier<A>`, `interruptor: BiPredicate<E, bigint>`, `accumulator: TriFunctional<A, E, bigint, A>`, `finisher: Functional<A, R>` | `Collector<E, A, R>` |
+| `useCollect<E, A, R>(identity: Supplier<A>, interruptor: TriPredicate<E, bigint, A>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | `identity: Supplier<A>`, `interruptor: TriPredicate<E, bigint, A>`, `accumulator: BiFunctional<A, E, A>`, `finisher: Functional<A, R>` | `Collector<E, A, R>` |
+| `useCollect<E, A, R>(identity: Supplier<A>, interruptor: TriPredicate<E, bigint, A>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): Collector<E, A, R>` | 创建一个可中断的收集器 | `identity: Supplier<A>`, `interruptor: TriPredicate<E, bigint, A>`, `accumulator: TriFunctional<A, E, bigint, A>`, `finisher: Functional<A, R>` | `Collector<E, A, R>` |
+| `useCount<E = unknown>(): Collector<E, bigint, bigint>` | 创建一个计算元素数量的收集器 | 无 | `Collector<E, bigint, bigint>` |
+| `useError<E = unknown>(): Collector<E, string, string>` | 创建一个将错误累积到 console.error 的收集器 | 无 | `Collector<E, string, string>` |
+| `useError<E = unknown>(accumulator: BiFunctional<string, E, string>): Collector<E, string, string>` | 创建一个使用自定义累加器累积错误的收集器 | `accumulator: BiFunctional<string, E, string>` | `Collector<E, string, string>` |
+| `useError<E = unknown>(accumulator: TriFunctional<string, E, bigint, string>): Collector<E, string, string>` | 创建一个使用自定义累加器累积错误的收集器 | `accumulator: TriFunctional<string, E, bigint, string>` | `Collector<E, string, string>` |
+| `useError<E = unknown>(prefix: string, accumulator: BiFunctional<string, E, string>, suffix: string): Collector<E, string, string>` | 创建一个带前缀和后缀的累积错误收集器 | `prefix: string`, `accumulator: BiFunctional<string, E, string>`, `suffix: string` | `Collector<E, string, string>` |
+| `useError<E = unknown>(prefix: string, accumulator: TriFunctional<string, E, bigint, string>, suffix: string): Collector<E, string, string>` | 创建一个带前缀和后缀的累积错误收集器 | `prefix: string`, `accumulator: TriFunctional<string, E, bigint, string>`, `suffix: string` | `Collector<E, string, string>` |
+| `useFindFirst<E>(): Collector<E, Optional<E>, Optional<E>>` | 创建一个查找第一个元素的收集器 | 无 | `Collector<E, Optional<E>, Optional<E>>` |
+| `useFindAny<E>(): Collector<E, Optional<E>, Optional<E>>` | 创建一个随机查找任意元素的收集器 | 无 | `Collector<E, Optional<E>, Optional<E>>` |
+| `useFindLast<E>(): Collector<E, Optional<E>, Optional<E>>` | 创建一个查找最后一个元素的收集器 | 无 | `Collector<E, Optional<E>, Optional<E>>` |
+| `useFindMaximum<E>(): Collector<E, Optional<E>, Optional<E>>` | 创建一个查找最大元素的收集器 | 无 | `Collector<E, Optional<E>, Optional<E>>` |
+| `useFindMaximum<E>(comparator: Comparator<E>): Collector<E, Optional<E>, Optional<E>>` | 创建一个使用自定义比较器查找最大元素的收集器 | `comparator: Comparator<E>` | `Collector<E, Optional<E>, Optional<E>>` |
+| `useFindMinimum<E>(): Collector<E, Optional<E>, Optional<E>>` | 创建一个查找最小元素的收集器 | 无 | `Collector<E, Optional<E>, Optional<E>>` |
+| `useFindMinimum<E>(comparator: Comparator<E>): Collector<E, Optional<E>, Optional<E>>` | 创建一个使用自定义比较器查找最小元素的收集器 | `comparator: Comparator<E>` | `Collector<E, Optional<E>, Optional<E>>` |
+| `useForEach<E>(action: Consumer<E>): Collector<E, bigint, bigint>` | 创建一个对每个元素执行操作的收集器 | `action: Consumer<E>` | `Collector<E, bigint, bigint>` |
+| `useForEach<E>(action: BiConsumer<E, bigint>): Collector<E, bigint, bigint>` | 创建一个对每个元素（带索引）执行操作的收集器 | `action: BiConsumer<E, bigint>` | `Collector<E, bigint, bigint>` |
+| `useNoneMatch<E>(predicate: Predicate<E>): Collector<E, boolean, boolean>` | 创建一个检查是否有元素不匹配断言的收集器 | `predicate: Predicate<E>` | `Collector<E, boolean, boolean>` |
+| `useGroup<E, K>(classifier: Functional<E, K>): Collector<E, Map<K, E[]>, Map<K, E[]>>` | 创建一个按分类器分组元素的收集器 | `classifier: Functional<E, K>` | `Collector<E, Map<K, E[]>, Map<K, E[]>>` |
+| `useGroupBy<E, K, V>(keyExtractor: Functional<E, K>, valueExtractor: Functional<E, V>): Collector<E, Map<K, V[]>, Map<K, V[]>>` | 创建一个按键分组并提取值的收集器 | `keyExtractor: Functional<E, K>`, `valueExtractor: Functional<E, V>` | `Collector<E, Map<K, V[]>, Map<K, V[]>>` |
+| `useJoin<E = unknown>(): Collector<E, string, string>` | 创建一个将元素连接成字符串的收集器 | 无 | `Collector<E, string, string>` |
+| `useJoin<E = unknown>(delimiter: string): Collector<E, string, string>` | 创建一个使用分隔符连接元素的收集器 | `delimiter: string` | `Collector<E, string, string>` |
+| `useJoin<E = unknown>(prefix: string, delimiter: string, suffix: string): Collector<E, string, string>` | 创建一个使用前缀、分隔符和后缀连接元素的收集器 | `prefix: string`, `delimiter: string`, `suffix: string` | `Collector<E, string, string>` |
+| `useJoin<E = unknown>(prefix: string, accumulator: BiFunctional<string, E, string>, suffix: string): Collector<E, string, string>` | 创建一个使用自定义累加器连接元素的收集器 | `prefix: string`, `accumulator: BiFunctional<string, E, string>`, `suffix: string` | `Collector<E, string, string>` |
+| `useJoin<E = unknown>(prefix: string, accumulator: TriFunctional<string, E, bigint, string>, suffix: string): Collector<E, string, string>` | 创建一个使用自定义累加器连接元素的收集器 | `prefix: string`, `accumulator: TriFunctional<string, E, bigint, string>`, `suffix: string` | `Collector<E, string, string>` |
+| `useLog<E = unknown>(): Collector<E, string, string>` | 创建一个将日志累积到 console.log 的收集器 | 无 | `Collector<E, string, string>` |
+| `useLog<E = unknown>(accumulator: BiFunctional<string, E, string>): Collector<E, string, string>` | 创建一个使用自定义累加器累积日志的收集器 | `accumulator: BiFunctional<string, E, string>` | `Collector<E, string, string>` |
+| `useLog<E = unknown>(accumulator: TriFunctional<string, E, bigint, string>): Collector<E, string, string>` | 创建一个使用自定义累加器累积日志的收集器 | `accumulator: TriFunctional<string, E, bigint, string>` | `Collector<E, string, string>` |
+| `useLog<E = unknown>(prefix: string, accumulator: BiFunctional<string, E, string>, suffix: string): Collector<E, string, string>` | 创建一个带前缀和后缀的累积日志收集器 | `prefix: string`, `accumulator: BiFunctional<string, E, string>`, `suffix: string` | `Collector<E, string, string>` |
+| `useLog<E = unknown>(prefix: string, accumulator: TriFunctional<string, E, bigint, string>, suffix: string): Collector<E, string, string>` | 创建一个带前缀和后缀的累积日志收集器 | `prefix: string`, `accumulator: TriFunctional<string, E, bigint, string>`, `suffix: string` | `Collector<E, string, string>` |
+| `usePartition<E>(count: bigint): Collector<E, Array<Array<E>>, Array<Array<E>>>` | 创建一个将元素分组的收集器 | `count: bigint` | `Collector<E, Array<Array<E>>, Array<Array<E>>>` |
+| `usePartitionBy<E>(classifier: Functional<E, bigint>): Collector<E, Array<E[]>, Array<E[]>>` | 创建一个按分类器对元素分区的收集器 | `classifier: Functional<E, bigint>` | `Collector<E, Array<E[]>, Array<E[]>>` |
+| `useReduce<E>(accumulator: BiFunctional<E, E, E>): Collector<E, Optional<E>, Optional<E>>` | 创建一个归约元素的收集器 | `accumulator: BiFunctional<E, E, E>` | `Collector<E, Optional<E>, Optional<E>>` |
+| `useReduce<E>(accumulator: TriFunctional<E, E, bigint, E>): Collector<E, Optional<E>, Optional<E>>` | 创建一个归约元素的收集器 | `accumulator: TriFunctional<E, E, bigint, E>` | `Collector<E, Optional<E>, Optional<E>>` |
+| `useReduce<E>(identity: E, accumulator: BiFunctional<E, E, E>): Collector<E, E, E>` | 创建一个带恒等值的归约元素收集器 | `identity: E`, `accumulator: BiFunctional<E, E, E>` | `Collector<E, E, E>` |
+| `useReduce<E>(identity: E, accumulator: TriFunctional<E, E, bigint, E>): Collector<E, E, E>` | 创建一个带恒等值的归约元素收集器 | `identity: E`, `accumulator: TriFunctional<E, E, bigint, E>` | `Collector<E, E, E>` |
+| `useReduce<E, R>(identity: R, accumulator: BiFunctional<R, E, R>, finisher: Functional<R, R>): Collector<E, R, R>` | 创建一个带恒等值和最终器的归约元素收集器 | `identity: R`, `accumulator: BiFunctional<R, E, R>`, `finisher: Functional<R, R>` | `Collector<E, R, R>` |
+| `useReduce<E, R>(identity: R, accumulator: TriFunctional<R, E, bigint, R>, finisher: Functional<R, R>): Collector<E, R, R>` | 创建一个带恒等值和最终器的归约元素收集器 | `identity: R`, `accumulator: TriFunctional<R, E, bigint, R>`, `finisher: Functional<R, R>` | `Collector<E, R, R>` |
+| `useToArray<E>(): Collector<E, E[], E[]>` | 创建一个将元素累积到数组中的收集器 | 无 | `Collector<E, E[], E[]>` |
+| `useToMap<E, K, V>(keyExtractor: Functional<E, K>, valueExtractor: Functional<E, V>): Collector<E, Map<K, V>, Map<K, V>>` | 创建一个将元素累积到映射中的收集器 | `keyExtractor: Functional<E, K>`, `valueExtractor: Functional<E, V>` | `Collector<E, Map<K, V>, Map<K, V>>` |
+| `useToSet<E>(): Collector<E, Set<E>, Set<E>>` | 创建一个将元素累积到集合中的收集器 | 无 | `Collector<E, Set<E>, Set<E>>` |
+| `useWrite<E, S = string>(stream: WritableStream<S>): Collector<E, Promise<WritableStream<S>>, Promise<WritableStream<S>>>` | 创建一个将元素写入流的收集器 | `stream: WritableStream<S>` | `Collector<E, Promise<WritableStream<S>>, Promise<WritableStream<S>>>` |
+| `useWrite<E, S = string>(stream: WritableStream<S>, accumulator: BiFunctional<WritableStream<S>, E, WritableStream<S>>): Collector<E, Promise<WritableStream<S>>, Promise<WritableStream<S>>>` | 创建一个使用自定义累加器将元素写入流的收集器 | `stream: WritableStream<S>`, `accumulator: BiFunctional<WritableStream<S>, E, WritableStream<S>>` | `Collector<E, Promise<WritableStream<S>>, Promise<WritableStream<S>>>` |
+| `useWrite<E, S = string>(stream: WritableStream<S>, accumulator: TriFunctional<WritableStream<S>, E, bigint, WritableStream<S>>): Collector<E, Promise<WritableStream<S>>, Promise<WritableStream<S>>>` | 创建一个使用自定义累加器将元素写入流的收集器 | `stream: WritableStream<S>`, `accumulator: TriFunctional<WritableStream<S>, E, bigint, WritableStream<S>>` | `Collector<E, Promise<WritableStream<S>>, Promise<WritableStream<S>>>` |
+| `useNumericSummate<E>(): Collector<E, number, number>` | 创建一个对数字值求和的收集器 | 无 | `Collector<number, number, number>` 或 `Collector<E, number, number>` |
+| `useNumericSummate<E>(mapper: Functional<E, number>): Collector<E, number, number>` | 创建一个对映射的数字值求和的收集器 | `mapper: Functional<E, number>` | `Collector<E, number, number>` |
+| `useBigIntSummate<E>(): Collector<E, bigint, bigint>` | 创建一个对 bigint 值求和的收集器 | 无 | `Collector<bigint, bigint, bigint>` 或 `Collector<E, bigint, bigint>` |
+| `useBigIntSummate<E>(mapper: Functional<E, bigint>): Collector<E, bigint, bigint>` | 创建一个对映射的 bigint 值求和的收集器 | `mapper: Functional<E, bigint>` | `Collector<E, bigint, bigint>` |
+| `useNumericAverage<E>(): Collector<E, NumericAverageAccumulator, number>` | 创建一个计算数字平均值的收集器 | 无 | `Collector<number, NumericAverageAccumulator, number>` 或 `Collector<E, NumericAverageAccumulator, number>` |
+| `useNumericAverage<E>(mapper: Functional<E, number>): Collector<E, NumericAverageAccumulator, number>` | 创建一个计算映射值数字平均值的收集器 | `mapper: Functional<E, number>` | `Collector<E, NumericAverageAccumulator, number>` |
+| `useBigIntAverage<E>(): Collector<E, BigIntAverageAccumulator, bigint>` | 创建一个计算 bigint 平均值的收集器 | 无 | `Collector<bigint, BigIntAverageAccumulator, bigint>` 或 `Collector<E, BigIntAverageAccumulator, bigint>` |
+| `useBigIntAverage<E>(mapper: Functional<E, bigint>): Collector<E, BigIntAverageAccumulator, bigint>` | 创建一个计算映射值 bigint 平均值的收集器 | `mapper: Functional<E, bigint>` | `Collector<E, BigIntAverageAccumulator, bigint>` |
+| `useFrequency<E>(): Collector<E, Map<E, bigint>, Map<E, bigint>>` | 创建一个计算元素频率的收集器 | 无 | `Collector<E, Map<E, bigint>, Map<E, bigint>>` |
+| `useNumericMode<E>(): Collector<E, Map<number, bigint>, number>` | 创建一个查找数字众数的收集器 | 无 | `Collector<number, Map<number, bigint>, number>` 或 `Collector<E, Map<number, bigint>, number>` |
+| `useNumericMode<E>(mapper: Functional<E, number>): Collector<E, Map<number, bigint>, number>` | 创建一个查找映射值数字众数的收集器 | `mapper: Functional<E, number>` | `Collector<E, Map<number, bigint>, number>` |
+| `useBigIntMode<E>(): Collector<E, Map<bigint, bigint>, bigint>` | 创建一个查找 bigint 众数的收集器 | 无 | `Collector<bigint, Map<bigint, bigint>, bigint>` 或 `Collector<E, Map<bigint, bigint>, bigint>` |
+| `useBigIntMode<E>(mapper: Functional<E, bigint>): Collector<E, Map<bigint, bigint>, bigint>` | 创建一个查找映射值 bigint 众数的收集器 | `mapper: Functional<E, bigint>` | `Collector<E, Map<bigint, bigint>, bigint>` |
+| `useNumericVariance<E>(): Collector<E, VarianceAccumulator, number>` | 创建一个计算数字方差的收集器 | 无 | `Collector<number, VarianceAccumulator, number>` 或 `Collector<E, VarianceAccumulator, number>` |
+| `useNumericVariance<E>(mapper: Functional<E, number>): Collector<E, VarianceAccumulator, number>` | 创建一个计算映射值数字方差的收集器 | `mapper: Functional<E, number>` | `Collector<E, VarianceAccumulator, number>` |
+| `useBigIntVariance<E>(): Collector<E, BigIntVarianceAccumulator, bigint>` | 创建一个计算 bigint 方差的收集器 | 无 | `Collector<bigint, BigIntVarianceAccumulator, bigint>` 或 `Collector<E, BigIntVarianceAccumulator, bigint>` |
+| `useBigIntVariance<E>(mapper: Functional<E, bigint>): Collector<E, BigIntVarianceAccumulator, bigint>` | 创建一个计算映射值 bigint 方差的收集器 | `mapper: Functional<E, bigint>` | `Collector<E, BigIntVarianceAccumulator, bigint>` |
+| `useNumericStandardDeviation<E>(): Collector<E, StandardDeviationAccumulator, number>` | 创建一个计算数字标准差的收集器 | 无 | `Collector<number, StandardDeviationAccumulator, number>` 或 `Collector<E, StandardDeviationAccumulator, number>` |
+| `useNumericStandardDeviation<E>(mapper: Functional<E, number>): Collector<E, StandardDeviationAccumulator, number>` | 创建一个计算映射值数字标准差的收集器 | `mapper: Functional<E, number>` | `Collector<E, StandardDeviationAccumulator, number>` |
+| `useBigIntStandardDeviation<E>(): Collector<E, BigIntStandardDeviationAccumulator, bigint>` | 创建一个计算 bigint 标准差的收集器 | 无 | `Collector<bigint, BigIntStandardDeviationAccumulator, bigint>` 或 `Collector<E, BigIntStandardDeviationAccumulator, bigint>` |
+| `useBigIntStandardDeviation<E>(mapper: Functional<E, bigint>): Collector<E, BigIntStandardDeviationAccumulator, bigint>` | 创建一个计算映射值 bigint 标准差的收集器 | `mapper: Functional<E, bigint>` | `Collector<E, BigIntStandardDeviationAccumulator, bigint>` |
+| `useNumericMedian<E>(): Collector<E, number[], number>` | 创建一个计算数字中位数的收集器 | 无 | `Collector<number, number[], number>` 或 `Collector<E, number[], number>` |
+| `useNumericMedian<E>(mapper: Functional<E, number>): Collector<E, number[], number>` | 创建一个计算映射值数字中位数的收集器 | `mapper: Functional<E, number>` | `Collector<E, number[], number>` |
+| `useBigIntMedian<E>(): Collector<E, bigint[], bigint>` | 创建一个计算 bigint 中位数的收集器 | 无 | `Collector<bigint, bigint[], bigint>` 或 `Collector<E, bigint[], bigint>` |
+| `useBigIntMedian<E>(mapper: Functional<E, bigint>): Collector<E, bigint[], bigint>` | 创建一个计算映射值 bigint 中位数的收集器 | `mapper: Functional<E, bigint>` | `Collector<E, bigint[], bigint>` |
+| `useToGeneratorFunction<E>(): Collector<E, Array<E>, globalThis.Generator<E, void, undefined>>` | 创建一个将元素转换为生成器函数的收集器 | 无 | `Collector<E, Array<E>, globalThis.Generator<E, void, undefined>>` |
+| `useToAsyncGeneratorFunction<E>(): Collector<E, Array<E>, globalThis.AsyncGenerator<E, void, undefined>>` | 创建一个将元素转换为异步生成器函数的收集器 | 无 | `Collector<E, Array<E>, globalThis.AsyncGenerator<E, void, undefined>>` |
 
 ```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)
-    .toUnoredered();
+    .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 // 完成
-);
+// 计算元素数量
+let count: Collector<number, number, number> = useCount();
 count.collect(from([1,2,3,4,5])); // 从流中计数
-count.collect([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 // 完成
-);
+// 查找第一个元素
+let findFirst: Collector<number, number, number> = useFindFirst();
 find.collect(from([1,2,3,4,5])); // 查找第一个元素
 find.collect([1,2,3,4,5]); // 查找第一个元素
+
+// 计算元素总和
+let summate: Collector<number, number, number> = useSummate();
+summate.collect(from([1,2,3,4,5])); // 从流中求和
+summate.collect([1,2,3,4,5]); // 从可迭代对象中求和
+
+// 计算元素平均值
+let average: Collector<number, number, number> = useNumericAverage();
+average.collect(from([1,2,3,4,5])); // 从流中计算平均值
+average.collect([1,2,3,4,5]); // 从可迭代对象中计算平均值
 ```
 
-### Semantic 工厂方法
+## Collector 类方法
 
 | 方法 | 描述 | 时间复杂度 | 空间复杂度 |
-|------|------|------------|------------|
-| `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) |
+|--------|-------------|-----------------|------------------|
+| `collect(generator: Generator<E>): R` | 从生成器函数收集元素 | O(n) | O(1) |
+| `collect(iterable: Iterable<E>): R` | 从可迭代对象收集元素 | O(n) | O(1) |
+| `collect(semantic: Semantic<E>): R` | 从语义流收集元素 | O(n) | O(1) |
+| `collect(collectable: Collectable<E>): R` | 从可收集流收集元素 | O(n) | O(1) |
+| `collect(start: number, end: number): R` | 从数字范围收集元素 | O(n) | O(1) |
+| `collect(start: bigint, end: bigint): R` | 从 bigint 范围收集元素 | O(n) | O(1) |
+
+### Semantic 工厂方法
+
+基于提供的代码，以下是所有 Semantic 工厂函数的描述表：
+
+| 函数 | 描述 | 参数 | 返回类型 |
+|----------|-------------|------------|-------------|
+| `animationFrame(period: number): Semantic<number>` | 创建一个发出动画帧时间戳的语义流 | `period: number` | `Semantic<number>` |
+| `animationFrame(period: number, delay: number): Semantic<number>` | 创建一个带延迟的发出动画帧时间戳的语义流 | `period: number`, `delay: number` | `Semantic<number>` |
+| `attribute<T extends object>(target: T): Semantic<Attribute<T>>` | 创建一个发出对象属性的语义流 | `target: T` | `Semantic<Attribute<T>>` |
+| `blob(blob: Blob): Semantic<Uint8Array>` | 创建一个以块的形式发出 Blob 数据的语义流 | `blob: Blob` | `Semantic<Uint8Array>` |
+| `blob(blob: Blob, chunk: bigint): Semantic<Uint8Array>` | 创建一个使用自定义块大小发出 Blob 数据的语义流 | `blob: Blob`, `chunk: bigint` | `Semantic<Uint8Array>` |
+| `empty<E>(): Semantic<E>` | 创建一个不发出任何元素的空语义流 | 无 | `Semantic<E>` |
+| `fill<E>(element: E, count: bigint): Semantic<E>` | 创建一个重复发出一个元素的语义流 | `element: E`, `count: bigint` | `Semantic<E>` |
+| `fill<E>(supplier: Supplier<E>, count: bigint): Semantic<E>` | 创建一个从提供者发出值的语义流 | `supplier: Supplier<E>`, `count: bigint` | `Semantic<E>` |
+| `from<E>(iterable: Iterable<E>): Semantic<E>` | 从可迭代对象创建语义流 | `iterable: Iterable<E>` | `Semantic<E>` |
+| `from<E>(iterable: AsyncIterable<E>): Semantic<E>` | 从异步可迭代对象创建语义流 | `iterable: AsyncIterable<E>` | `Semantic<E>` |
+| `generate<E>(supplier: Supplier<E>, count: bigint): Semantic<E>` | 创建一个生成固定数量值的语义流 | `supplier: Supplier<E>`, `count: bigint` | `Semantic<E>` |
+| `generate<E>(element: E, count: bigint): Semantic<E>` | 创建一个重复一个元素的语义流 | `element: E`, `count: bigint` | `Semantic<E>` |
+| `generate<E>(supplier: Supplier<E>, interrupt: Predicate<E>): Semantic<E>` | 创建一个生成直到满足条件的语义流 | `supplier: Supplier<E>`, `interrupt: Predicate<E>` | `Semantic<E>` |
+| `generate<E>(supplier: Supplier<E>, interrupt: BiPredicate<E, bigint>): Semantic<E>` | 创建一个生成直到满足条件的语义流 | `supplier: Supplier<E>`, `interrupt: BiPredicate<E, bigint>` | `Semantic<E>` |
+| `interval(period: number): Semantic<number>` | 创建一个以固定间隔发出的语义流 | `period: number` | `Semantic<number>` |
+| `interval(period: number, delay: number): Semantic<number>` | 创建一个具有初始延迟的以固定间隔发出的语义流 | `period: number`, `delay: number` | `Semantic<number>` |
+| `iterate<E>(generator: Generator<E>): Semantic<E>` | 从生成器函数创建语义流 | `generator: Generator<E>` | `Semantic<E>` |
+| `promise<T>(promise: Promise<T>): Semantic<T>` | 创建一个发出 Promise 结果的语义流 | `promise: Promise<T>` | `Semantic<T>` |
+| `range(start: number, end: number): Semantic<number>` | 创建一个发出数字范围的语义流 | `start: number`, `end: number` | `Semantic<number>` |
+| `range(start: number, end: number, step: number): Semantic<number>` | 创建一个使用自定义步长发出范围的语义流 | `start: number`, `end: number`, `step: number` | `Semantic<number>` |
+| `websocket(websocket: WebSocket): Semantic<MessageEvent \| CloseEvent \| Event>` | 创建一个发出 WebSocket 事件的语义流 | `websocket: WebSocket` | `Semantic<MessageEvent \| CloseEvent \| Event>` |
 
 ```typescript
-// Semantic 工厂方法使用示例
+// Semantic 工厂方法用法示例
 
 // 从定时动画帧创建流
 animationFrame(1000)
     .toUnordered()
-    .forEach(frame => console.log(frame));
+    .forEach((frame): void => console.log(frame));
 
 // 从 Blob 创建流（分块读取）
 blob(someBlob, 1024n)
@@ -210,15 +405,15 @@ blob(someBlob, 1024n)
     .then(callback) // 写入流成功
     .catch(callback); // 写入流失败
 
-// 创建空流，需与其他流连接后才会执行
+// 创建一个空流，直到与其他流连接才会执行
 empty<string>()
     .toUnordered()
     .join(); //[]
 
-// 创建填充流
+// 创建一个填充的流
 let filledStream = fill("hello", 3); // "hello", "hello", "hello"
 
-// 创建初始延迟 2 秒、执行周期 5 秒的定时流，基于定时器机制实现；可能因系统调度精度限制产生时间漂移。
+// 创建一个具有初始 2 秒延迟和 5 秒执行周期的定时流，基于计时器机制实现；由于系统调度精度限制，可能会经历时间漂移。
 let intervalStream = interval(5000, 2000);
 
 // 从可迭代对象创建流
@@ -226,47 +421,61 @@ 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 promisedStream: Semantic<Array<number>> = promise(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() // 事件通常无序
+  .filter((event): boolean => event.type === "message"); // 只监听消息事件
+  .toUnordered() // 通常事件不需要有序
   .forEach((event): void => 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) |
+|--------|-------------|-----------------|------------------|
+| `concat(other: Semantic<E>): Semantic<E>` | 连接两个语义流 | O(m+n) | O(1) |
+| `concat(other: Iterable<E>): Semantic<E>` | 将语义流与可迭代对象连接 | O(m+n) | O(1) |
+| `distinct(): Semantic<E>` | 返回不同的元素 | O(n) | O(n) |
+| `distinct<K>(keyExtractor: Functional<E, K>): Semantic<E>` | 按键返回不同的元素 | O(n) | O(n) |
+| `distinct<K>(keyExtractor: BiFunctional<E, bigint, K>): Semantic<E>` | 按键（带索引）返回不同的元素 | O(n) | O(n) |
+| `dropWhile(predicate: Predicate<E>): Semantic<E>` | 在断言为真时丢弃元素 | O(n) | O(1) |
+| `dropWhile(predicate: BiPredicate<E, bigint>): Semantic<E>` | 在断言为真时丢弃元素（带索引） | O(n) | O(1) |
+| `filter(predicate: Predicate<E>): Semantic<E>` | 按断言过滤元素 | O(n) | O(1) |
+| `filter(predicate: BiPredicate<E, bigint>): Semantic<E>` | 按断言过滤元素（带索引） | O(n) | O(1) |
+| `flat(mapper: Functional<E, Iterable<E>>): Semantic<E>` | 展平可迭代结果 | O(n) | O(1) |
+| `flat(mapper: BiFunctional<E, bigint, Iterable<E>>): Semantic<E>` | 展平可迭代结果（带索引） | O(n) | O(1) |
+| `flat(mapper: Functional<E, Semantic<E>>): Semantic<E>` | 展平语义结果 | O(n) | O(1) |
+| `flat(mapper: BiFunctional<E, bigint, Semantic<E>>): Semantic<E>` | 展平语义结果（带索引） | O(n) | O(1) |
+| `flatMap<R>(mapper: Functional<E, Iterable<R>>): Semantic<R>` | 映射并展平为不同类型 | O(n) | O(1) |
+| `flatMap<R>(mapper: BiFunctional<E, bigint, Iterable<R>>): Semantic<R>` | 映射并展平（带索引） | O(n) | O(1) |
+| `flatMap<R>(mapper: Functional<E, Semantic<R>>): Semantic<R>` | 映射并展平语义 | O(n) | O(1) |
+| `flatMap<R>(mapper: BiFunctional<E, bigint, Semantic<R>>): Semantic<R>` | 映射并展平语义（带索引） | O(n) | O(1) |
+| `limit(n: number): Semantic<E>` | 限制元素数量 | O(n) | O(1) |
+| `limit(n: bigint): Semantic<E>` | 限制元素数量 (bigint) | O(n) | O(1) |
+| `map<R>(mapper: Functional<E, R>): Semantic<R>` | 将元素映射到不同类型 | O(n) | O(1) |
+| `map<R>(mapper: BiFunctional<E, bigint, R>): Semantic<R>` | 将元素映射（带索引） | O(n) | O(1) |
+| `peek(consumer: Consumer<E>): Semantic<E>` | 对元素执行操作 | O(n) | O(1) |
+| `peek(consumer: BiConsumer<E, bigint>): Semantic<E>` | 对元素执行操作（带索引） | O(n) | O(1) |
+| `redirect(redirector: BiFunctional<E, bigint, bigint>): Semantic<E>` | 重定向元素索引 | O(n) | O(1) |
+| `reverse(): Semantic<E>` | 反转元素索引 | O(n) | O(1) |
+| `shuffle(): Semantic<E>` | 随机打乱元素索引 | O(n) | O(1) |
+| `shuffle(mapper: BiFunctional<E, bigint, bigint>): Semantic<E>` | 使用映射器打乱元素索引 | O(n) | O(1) |
+| `skip(n: number): Semantic<E>` | 跳过前 n 个元素 | O(n) | O(1) |
+| `skip(n: bigint): Semantic<E>` | 跳过前 n 个元素 (bigint) | O(n) | O(1) |
+| `sub(start: bigint, end: bigint): Semantic<E>` | 返回语义流子范围 | O(n) | O(1) |
+| `takeWhile(predicate: Predicate<E>): Semantic<E>` | 在断言为真时获取元素 | O(n) | O(1) |
+| `takeWhile(predicate: BiPredicate<E, bigint>): Semantic<E>` | 在断言为真时获取元素（带索引） | O(n) | O(1) |
+| `translate(offset: number): Semantic<E>` | 将元素索引平移偏移量 | O(n) | O(1) |
+| `translate(offset: bigint): Semantic<E>` | 将元素索引平移偏移量 (bigint) | O(n) | O(1) |
+| `translate(translator: BiFunctional<E, bigint, bigint>): Semantic<E>` | 使用转换器平移元素索引 | O(n) | O(1) |
 
 ```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
@@ -278,10 +487,10 @@ let result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
 
 // 复杂操作示例
 let complexResult = range(1, 100, 1)
-    .flatMap((n: number): Semantics<number> => from([n, n * 2])) // 每个元素映射为两个
+    .flatMap((n: number): Semantics<number> => from([n, n * 2])) // 将每个元素映射为两个
     .distinct()                      // 去重
     .shuffle()                       // 打乱顺序
-    .takeWhile((n: number): boolean => n < 50)         // 取小于 50 的元素
+    .takeWhile((n: number): boolean => n < 50)         // 获取小于 50 的元素
     .toOrdered()                     // 转换为有序收集器
     .toArray();                      // 转换为数组
 ```
@@ -290,94 +499,132 @@ let complexResult = range(1, 100, 1)
 
 | 方法 | 描述 | 时间复杂度 | 空间复杂度 |
 |------------|------------|------------|------------|
-| `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) |
+| `sorted(): OrderedCollectable<E>` | 返回排序后的可收集流 | O(n log n) | O(n) |
+| `sorted(comparator: Comparator<E>): OrderedCollectable<E>` | 使用比较器返回排序后的可收集流 | O(n log n) | O(n) |
+| `toCollectable(): Collectable<E>` | 转换为可收集流 | O(1) | O(1) |
+| `toCollectable<C extends Collectable<E>>(mapper: Functional<Generator<E>, C>): C` | 使用映射器转换为可收集流 | O(1) | O(1) |
+| `toBigintStatistics(): BigIntStatistics<E>` | 转换为 bigint 统计信息 | O(1) | O(1) |
+| `toNumericStatistics(): NumericStatistics<E>` | 转换为数字统计信息 | O(1) | O(1) |
+| `toOrdered(): OrderedCollectable<E>` | 转换为有序可收集流 | O(1) | O(1) |
+| `toUnordered(): UnorderedCollectable<E>` | 转换为无序可收集流 | O(1) | O(1) |
+| `toWindow(): WindowCollectable<E>` | 转换为窗口可收集流 | O(1) | O(1) |
 
 ```typescript
-// 转换为升序数组
-from([6,4,3,5,2]) // 创建流
-    .sorted() // 按升序排序
+// 转换为升序排序的数组
+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) // 按降序排序
+// 转换为降序排序的数组
+from([6,4,3,5,2]) // 创建一个流
+    .sorted((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() // 保持重定向顺序
+    .redirect((element, index): bigint => -index) // 重定向为反转顺序
+    .toOrdered() // 保持重定向的顺序
     .toArray(); // [2, 5, 3, 4, 6]
 
-// 忽略重定向以倒序数组
+// 忽略重定向，反转数组
 from([6,4,3,5,2])
-    .redirect((element: number, index: bigint) => -index) // 重定向为倒序
-    .toUnorderd() // 丢弃重定向顺序。此操作将忽略 `redirect`、`reverse`、`shuffle` 和 `translate` 操作
+    .redirect((element: number, index: bigint) => -index) // 重定向为反转顺序
+    .toUnordered() // 丢弃重定向的顺序。此操作将忽略 `redirect`、`reverse`、`shuffle` 和 `translate` 操作
     .toArray(); // [2, 5, 3, 4, 6]
 
-// 反转流为数组
+// 将流反转为数组
 from([6, 4, 3, 5, 2])
     .reverse() // 反转流
-    .toOrdered() // 保证反转顺序
+    .toOrdered() // 保证反转的顺序
     .toArray(); // [2, 5, 3, 4, 6]
 
-// 覆盖打乱的流为数组
+// 覆盖已打乱的流为数组
 from([6, 4, 3, 5, 2])
     .shuffle() // 打乱流
-    .sorted() // 覆盖打乱顺序。此操作将覆盖 `redirect`、`reverse`、`shuffle` 和 `translate` 操作
+    .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 统计
+// 转换为 bigint 统计信息
 from([6n, 4n, 3n, 5n, 2n]).toBigintStatistics();
 
-// 定义自定义收集器来收集数据
+// 定义自定义收集器以收集数据
 let customizedCollector = from([1, 2, 3, 4, 5]).toCollectable((generator: Generator<E>) => new CustomizedCollector(generator));
 ```
 
-## Collectable 集合方法
+## 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) |
+|--------|-------------|-----------------|------------------|
+| `anyMatch(predicate: Predicate<E>): boolean` | 如果有任何元素匹配断言则返回 true | O(n) | O(1) |
+| `allMatch(predicate: Predicate<E>): boolean` | 如果所有元素都匹配断言则返回 true | O(n) | O(1) |
+| `collect<A, R>(collector: Collector<E, A, R>): R` | 使用收集器收集元素 | O(n) | O(1) |
+| `collect<A, R>(identity: Supplier<A>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): R` | 使用累加器和最终器收集元素 | O(n) | O(1) |
+| `collect<A, R>(identity: Supplier<A>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): R` | 使用支持索引感知的累加器收集元素 | O(n) | O(1) |
+| `collect<A, R>(identity: Supplier<A>, interruptor: Predicate<E>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): R` | 使用中断器和累加器收集 | O(n) | O(1) |
+| `collect<A, R>(identity: Supplier<A>, interruptor: BiPredicate<E, bigint>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): R` | 使用支持索引感知的中断器收集 | O(n) | O(1) |
+| `collect<A, R>(identity: Supplier<A>, interruptor: TriPredicate<E, bigint, A>, accumulator: BiFunctional<A, E, A>, finisher: Functional<A, R>): R` | 使用支持状态感知的中断器收集 | O(n) | O(1) |
+| `collect<A, R>(identity: Supplier<A>, interruptor: Predicate<E>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): R` | 使用支持索引感知的累加器收集 | O(n) | O(1) |
+| `collect<A, R>(identity: Supplier<A>, interruptor: BiPredicate<E, bigint>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): R` | 使用两者都支持索引感知的收集 | O(n) | O(1) |
+| `collect<A, R>(identity: Supplier<A>, interruptor: TriPredicate<E, bigint, A>, accumulator: TriFunctional<A, E, bigint, A>, finisher: Functional<A, R>): R` | 使用支持状态和索引感知的收集 | O(n) | O(1) |
+| `count(): bigint` | 计算元素数量 | O(n) | O(1) |
+| `error(): void` | 将元素记录到 console.error | O(n) | O(1) |
+| `error(accumulator: BiFunctional<string, E, string>): void` | 使用自定义累加器记录 | O(n) | O(1) |
+| `error(accumulator: TriFunctional<string, E, bigint, string>): void` | 使用支持索引感知的累加器记录 | O(n) | O(1) |
+| `error(prefix: string, accumulator: BiFunctional<string, E, string>, suffix: string): void` | 使用前缀和后缀记录 | O(n) | O(1) |
+| `error(prefix: string, accumulator: TriFunctional<string, E, bigint, string>, suffix: string): void` | 使用支持索引感知的累加器记录 | O(n) | O(1) |
+| `isEmpty(): boolean` | 如果没有元素则返回 true | O(1) | O(1) |
+| `findAny(): Optional<E>` | 随机返回任意元素 | O(1) | O(1) |
+| `findFirst(): Optional<E>` | 返回第一个元素 | O(1) | O(1) |
+| `findLast(): Optional<E>` | 返回最后一个元素 | O(n) | O(1) |
+| `findMaximum(): Optional<E>` | 返回最大元素 | O(n) | O(1) |
+| `findMaximum(comparator: Comparator<E>): Optional<E>` | 使用比较器返回最大值 | O(n) | O(1) |
+| `findMinimum(): Optional<E>` | 返回最小元素 | O(n) | O(1) |
+| `findMinimum(comparator: Comparator<E>): Optional<E>` | 使用比较器返回最小值 | O(n) | O(1) |
+| `forEach(action: Consumer<E>): void` | 对每个元素执行操作 | O(n) | O(1) |
+| `forEach(action: BiConsumer<E, bigint>): void` | 对每个元素执行操作（带索引） | O(n) | O(1) |
+| `group<K>(classifier: Functional<E, K>): Map<K, Array<E>>` | 按分类器对元素分组 | O(n) | O(n) |
+| `groupBy<K, V>(keyExtractor: Functional<E, K>, valueExtractor: Functional<E, V>): Map<K, Array<V>>` | 使用键值映射对元素分组 | O(n) | O(n) |
+| `join(): string` | 将元素连接成字符串 | O(n) | O(1) |
+| `join(delimiter: string): string` | 使用分隔符连接 | O(n) | O(1) |
+| `join(prefix: string, delimiter: string, suffix: string): string` | 使用前缀和后缀连接 | O(n) | O(1) |
+| `join(prefix: string, accumulator: BiFunctional<string, E, string>, suffix: string): string` | 使用自定义累加器连接 | O(n) | O(1) |
+| `join(prefix: string, accumulator: TriFunctional<string, E, bigint, string>, suffix: string): string` | 使用支持索引感知的累加器连接 | O(n) | O(1) |
+| `log(): void` | 将元素记录到 console.log | O(n) | O(1) |
+| `log(accumulator: BiFunctional<string, E, string>): void` | 使用自定义累加器记录 | O(n) | O(1) |
+| `log(accumulator: TriFunctional<string, E, bigint, string>): void` | 使用支持索引感知的累加器记录 | O(n) | O(1) |
+| `log(prefix: string, accumulator: BiFunctional<string, E, string>, suffix: string): void` | 使用前缀和后缀记录 | O(n) | O(1) |
+| `log(prefix: string, accumulator: TriFunctional<string, E, bigint, string>, suffix: string): void` | 使用支持索引感知的累加器记录 | O(n) | O(1) |
+| `nonMatch(predicate: Predicate<E>): boolean` | 如果没有元素匹配则返回 true | O(n) | O(1) |
+| `partition(count: bigint): Array<Array<E>>` | 将元素按大小分组 | O(n) | O(n) |
+| `partitionBy(classifier: Functional<E, bigint>): Array<Array<E>>` | 按分类器对元素分区 | O(n) | O(n) |
+| `reduce(accumulator: BiFunctional<E, E, E>): Optional<E>` | 归约元素 | O(n) | O(1) |
+| `reduce(accumulator: TriFunctional<E, E, bigint, E>): Optional<E>` | 归约元素（带索引） | O(n) | O(1) |
+| `reduce(identity: E, accumulator: BiFunctional<E, E, E>): E` | 带恒等值的归约 | O(n) | O(1) |
+| `reduce(identity: E, accumulator: TriFunctional<E, E, bigint, E>): E` | 带恒等值和索引的归约 | O(n) | O(1) |
+| `reduce<R>(identity: R, accumulator: BiFunctional<R, E, R>, finisher: Functional<R, R>): R` | 带最终器的归约 | O(n) | O(1) |
+| `reduce<R>(identity: R, accumulator: TriFunctional<R, E, bigint, R>, finisher: Functional<R, R>): R` | 带索引和最终器的归约 | O(n) | O(1) |
+| `semantic(): Semantic<E>` | 转换为语义流 | O(1) | O(1) |
+| `source(): Generator<E>` | 返回生成器源 | O(1) | O(1) |
+| `toArray(): Array<E>` | 转换为数组 | O(n) | O(n) |
+| `toMap<K, V>(keyExtractor: Functional<E, K>, valueExtractor: Functional<E, V>): Map<K, V>` | 转换为映射 | O(n) | O(n) |
+| `toSet(): Set<E>` | 转换为集合 | O(n) | O(n) |
+| `write<S = string>(stream: WritableStream<S>): Promise<WritableStream<S>>` | 将元素写入可写流 | O(n) | O(1) |
+| `write<S = string>(stream: WritableStream<S>, accumulator: BiFunctional<WritableStream<S>, E, WritableStream<S>>): Promise<WritableStream<S>>` | 使用自定义累加器写入流 | O(n) | O(1) |
+| `write<S = string>(stream: WritableStream<S>, accumulator: TriFunctional<WritableStream<S>, E, bigint, WritableStream<S>>): Promise<WritableStream<S>>` | 使用支持索引感知的累加器写入流 | O(n) | O(1) |
 
 ```typescript
 // Collectable 操作示例
-const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+let data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
     .filter((n: number): boolean => n % 2 === 0)
-    .toOrdered(); // 匹配检查
+    .toOrdered();
+
+// 匹配检查
 console.log(data.anyMatch((n: number): boolean => n > 5)); // true
 console.log(data.allMatch((n: number): boolean => n < 20)); // true
 
@@ -386,101 +633,376 @@ data.findFirst().ifPresent((n: number): void => console.log(n)); // 2
 data.findAny().ifPresent((n: number): void => console.log(n)); // 任意元素
 
 // 分组操作
-const grouped = data.groupBy(
-    (n: number): string => (n > 5 ? "large" : "small"),
+let grouped = data.groupBy(
+    (n: number): string => n > 5 ? "large" : "small",
     (n: number): number => n * 2
-); // {small: [4, 8], large: [12, 16, 20]}
+);
+// Map { "small" => [4, 8], "large" => [12, 16, 20] }
 
 // 归约操作
-const sum = data.reduce(0, (accumulator: number, n: number): number => accumulator + n); // 30
+let sum = data.reduce(0, (accumulator: number, n: number): number => accumulator + n); // 30
 
 // 输出操作
-data.join(", "); // "[2, 4, 6, 8, 10]"
+data.join(", "); // "2, 4, 6, 8, 10"
+
+// 写入流操作
+let writableStream = new WritableStream<string>({
+    write(chunk) {
+        console.log('写入:', chunk);
+    }
+});
+data.write(writableStream)
+    .then(() => console.log('写入完成'))
+    .catch((err) => console.error('写入失败:', err));
 ```
 
-## 统计分析方法
+## UnorderedCollectable 类方法
 
-### NumericStatistics 方法
+`UnorderedCollectable<E>` 是 `Collectable<E>` 的一种实现，它在处理流时**不保证**元素的顺序，从而在不需要顺序的场景下（例如，仅计算元素数量、总和、是否存在等）可以提供最佳性能。它会自动忽略 `redirect`、`reverse`、`shuffle` 和 `translate` 等会影响顺序的操作。
 
 | 方法 | 描述 | 时间复杂度 | 空间复杂度 |
-|------|------|------------|------------|
-| `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) |
+|--------|-------------|-----------------|------------------|
+| `constructor(generator: Generator<E>)` | 创建无序可收集流实例 | O(1) | O(1) |
+| `source(): Generator<E>` | 返回生成器源 | O(1) | O(1) |
+| `: Generator<E, void, undefined>` | 返回迭代器 | O(n) | O(1) |
+| `: AsyncGenerator<E, void, undefined>` | 返回异步迭代器 | O(n) | O(1) |
+
+```typescript
+// 创建并操作 UnorderedCollectable
+let unorderedData: UnorderedCollectable<number> = from([5, 3, 8, 1, 4])
+    .filter(n => n > 2)
+    .toUnordered(); // 转换为无序收集器以获得最佳性能
+
+console.log(unorderedData.anyMatch(n => n > 6)); // true
+console.log(unorderedData.count()); // 4n
+console.log(unorderedData.toArray()); // 元素顺序不一定为 [5, 3, 8, 4]
+```
+
+## OrderedCollectable 类方法
+
+`OrderedCollectable<E>` 是 `Collectable<E>` 的一种实现，它**严格保证**元素的顺序。当您调用 `.sorted()` 方法时，会自动创建一个 `OrderedCollectable` 实例。它会尊重并维护 `redirect`、`reverse`、`shuffle` 和 `translate` 等操作产生的顺序，但 `sorted()` 操作会覆盖之前所有的顺序定义。
+
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|--------|-------------|-----------------|------------------|
+| `constructor(generator: Generator<E>)` | 创建有序可收集流实例 | O(n log n) | O(n) |
+| `constructor(generator: Generator<E>, comparator: Comparator<E>)` | 使用比较器创建有序可收集流实例 | O(n log n) | O(n) |
+| `: Generator<E, void, undefined>` | 返回迭代器 | O(n) | O(1) |
+| `: AsyncGenerator<E, void, undefined>` | 返回异步迭代器 | O(n) | O(1) |
+| `source(): Generator<E>` | 返回索引化后的生成器源 | O(1) | O(1) |
+| `isEmpty(): boolean` | 如果缓冲区为空则返回 true | O(1) | O(1) |
+
+```typescript
+// 创建并操作 OrderedCollectable
+let orderedData: OrderedCollectable<number> = from([5, 3, 8, 1, 4])
+    .sorted(); // 自动创建 OrderedCollectable 并进行升序排序
+
+console.log(orderedData.toArray()); // [1, 3, 4, 5, 8]
+
+// 使用自定义比较器进行降序排序
+let descendingData: OrderedCollectable<number> = from([5, 3, 8, 1, 4])
+    .sorted((a, b) => b - a);
+
+console.log(descendingData.toArray()); // [8, 5, 4, 3, 1]
+```
+
+## 统计分析类方法
+
+### Statistics 类方法
+
+`Statistics<E, D extends number | bigint>` 是一个泛型基类，用于对元素流进行统计分析。`NumericStatistics` 和 `BigIntStatistics` 都继承自此基类。
+
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|--------|-------------|-----------------|------------------|
+| `constructor(generator: Generator<E>)` | 创建一个统计实例 | O(n log n) | O(n) |
+| `constructor(generator: Generator<E>, comparator: Comparator<E>)` | 使用比较器创建一个统计实例 | O(n log n) | O(n) |
+| `: Generator<E, void, undefined>` | 返回迭代器 | O(n) | O(1) |
+| `: AsyncGenerator<E, void, undefined>` | 返回异步迭代器 | O(n) | O(1) |
+| `count(): bigint` | 返回元素数量 | O(1) | O(1) |
+| `average(): D` | 返回平均值（算术平均） | O(n) | O(1) |
+| `average(mapper: Functional<E, D>): D` | 返回映射值的平均值 | O(n) | O(1) |
+| `range(): D` | 返回极差（最大值-最小值） | O(1) | O(1) |
+| `range(mapper: Functional<E, D>): D` | 返回映射值的极差 | O(1) | O(1) |
+| `variance(): D` | 返回方差 | O(n) | O(1) |
+| `variance(mapper: Functional<E, D>): D` | 返回映射值的方差 | O(n) | O(1) |
+| `standardDeviation(): D` | 返回标准差 | O(n) | O(1) |
+| `standardDeviation(mapper: Functional<E, D>): D` | 返回映射值的标准差 | O(n) | O(1) |
+| `mean(): D` | 返回均值（同 average） | O(n) | O(1) |
+| `mean(mapper: Functional<E, D>): D` | 返回映射值的均值 | O(n) | O(1) |
+| `median(): D` | 返回中位数 | O(n) | O(n) |
+| `median(mapper: Functional<E, D>): D` | 返回映射值的中位数 | O(n) | O(n) |
+| `mode(): D` | 返回众数 | O(n) | O(n) |
+| `mode(mapper: Functional<E, D>): D` | 返回映射值的众数 | O(n) | O(n) |
+| `frequency(): Map<E, bigint>` | 返回频率分布 | O(n) | O(n) |
+| `summate(): D` | 返回元素总和 | O(n) | O(1) |
+| `summate(mapper: Functional<E, D>): D` | 返回映射值的总和 | O(n) | O(1) |
+| `quantile(quantile: number): D` | 返回指定分位数 | O(1) | O(1) |
+| `quantile(quantile: number, mapper: Functional<E, D>): D` | 返回映射值的指定分位数 | O(1) | O(1) |
+| `interquartileRange(): D` | 返回四分位距 (IQR) | O(1) | O(1) |
+| `interquartileRange(mapper: Functional<E, D>): D` | 返回映射值的四分位距 | O(1) | O(1) |
+| `skewness(): D` | 返回偏度 | O(n) | O(1) |
+| `skewness(mapper: Functional<E, D>): D` | 返回映射值的偏度 | O(n) | O(1) |
+| `kurtosis(): D` | 返回峰度 | O(n) | O(1) |
+| `kurtosis(mapper: Functional<E, D>): D` | 返回映射值的峰度 | O(n) | O(1) |
+
+### NumericStatistics 类方法
+
+`NumericStatistics<E>` 继承自 `Statistics<E, number>`，专门用于处理数值类型 (`number`) 的统计分析。
+
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|--------|-------------|-----------------|------------------|
+| `constructor(generator: Generator<E>)` | 创建一个数字统计实例 | O(n log n) | O(n) |
+| `constructor(generator: Generator<E>, comparator: Comparator<E>)` | 使用比较器创建一个数字统计实例 | O(n log n) | O(n) |
+| `: Generator<E, void, undefined>` | 返回迭代器 | O(n) | O(1) |
+| `: AsyncGenerator<E, void, undefined>` | 返回异步迭代器 | O(n) | O(1) |
+| `count(): bigint` | 返回元素数量 | O(1) | O(1) |
+| `average(): number` | 返回数字平均值 | O(n) | O(1) |
+| `average(mapper: Functional<E, number>): number` | 返回映射数字值的平均值 | O(n) | O(1) |
+| `range(): number` | 返回数字极差 | O(1) | O(1) |
+| `range(mapper: Functional<E, number>): number` | 返回映射数字值的极差 | O(1) | O(1) |
+| `variance(): number` | 返回数字方差 | O(n) | O(1) |
+| `variance(mapper: Functional<E, number>): number` | 返回映射数字值的方差 | O(n) | O(1) |
+| `standardDeviation(): number` | 返回数字标准差 | O(n) | O(1) |
+| `standardDeviation(mapper: Functional<E, number>): number` | 返回映射数字值的标准差 | O(n) | O(1) |
+| `mean(): number` | 返回数字均值（同 average） | O(n) | O(1) |
+| `mean(mapper: Functional<E, number>): number` | 返回映射数字值的均值 | O(n) | O(1) |
+| `median(): number` | 返回数字中位数 | O(n) | O(n) |
+| `median(mapper: Functional<E, number>): number` | 返回映射数字值的中位数 | O(n) | O(n) |
+| `mode(): number` | 返回数字众数 | O(n) | O(n) |
+| `mode(mapper: Functional<E, number>): number` | 返回映射数字值的众数 | O(n) | O(n) |
+| `frequency(): Map<E, bigint>` | 返回频率分布 | O(n) | O(n) |
+| `summate(): number` | 返回数字总和 | O(n) | O(1) |
+| `summate(mapper: Functional<E, number>): number` | 返回映射数字值的总和 | O(n) | O(1) |
+| `quantile(quantile: number): number` | 返回指定数字分位数 | O(1) | O(1) |
+| `quantile(quantile: number, mapper: Functional<E, number>): number` | 返回映射数字值的指定分位数 | O(1) | O(1) |
+| `interquartileRange(): number` | 返回数字四分位距 | O(1) | O(1) |
+| `interquartileRange(mapper: Functional<E, number>): number` | 返回映射数字值的四分位距 | O(1) | O(1) |
+| `skewness(): number` | 返回数字偏度 | O(n) | O(1) |
+| `skewness(mapper: Functional<E, number>): number` | 返回映射数字值的偏度 | O(n) | O(1) |
+| `kurtosis(): number` | 返回数字峰度 | O(n) | O(1) |
+| `kurtosis(mapper: Functional<E, number>): number` | 返回映射数字值的峰度 | O(n) | O(1) |
 
 ```typescript
-// 统计分析示例
-const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+// 数字统计分析示例
+let numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
     .toNumericStatistics();
-console.log("平均值:", numbers.mean()); // 5.5
+
+console.log("均值:", numbers.mean()); // 5.5
 console.log("中位数:", numbers.median()); // 5.5
-console.log("标准差:", numbers.standardDeviation()); // ~2.87
+console.log("标准差:", numbers.standardDeviation().toFixed(2)); // ~2.87
 console.log("总和:", numbers.summate()); // 55
-
-// 使用映射器的统计分析
-const objects = from([
-    { value: 10 },
-    { value: 20 },
-    { value: 30 }
+console.log("极差:", numbers.range()); // 9
+console.log("四分位距 (IQR):", numbers.interquartileRange()); // 5
+console.log("下四分位数:", numbers.quantile(0.25)); // 3.25
+console.log("偏度:", numbers.skewness().toFixed(2)); // 0
+console.log("峰度:", numbers.kurtosis().toFixed(2)); // ~-1.2
+
+// 对对象数组进行统计
+let objects = from([
+    { value: 10, weight: 2 },
+    { value: 20, weight: 3 },
+    { value: 30, weight: 5 }
 ]).toNumericStatistics();
-console.log("映射后的平均值:", objects.mean(obj => obj.value)); // 20
+
+console.log("对象值的平均值:", objects.average(obj => obj.value)); // 20
+console.log("对象值的总和:", objects.summate(obj => obj.value)); // 60
+console.log("对象值的中位数:", objects.median(obj => obj.value)); // 20
+console.log("加权平均值:", objects.summate(obj => obj.value * obj.weight) / objects.summate(obj => obj.weight)); // 24.0
+```
+
+### BigIntStatistics 类方法
+
+`BigIntStatistics<E>` 继承自 `Statistics<E, bigint>`，专门用于处理大整数类型 (`bigint`) 的统计分析，避免在计算过程中因数值过大而溢出。
+
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|--------|-------------|-----------------|------------------|
+| `constructor(generator: Generator<E>)` | 创建一个 bigint 统计实例 | O(n log n) | O(n) |
+| `constructor(generator: Generator<E>, comparator: Comparator<E>)` | 使用比较器创建一个 bigint 统计实例 | O(n log n) | O(n) |
+| `: Generator<E, void, undefined>` | 返回迭代器 | O(n) | O(1) |
+| `: AsyncGenerator<E, void, undefined>` | 返回异步迭代器 | O(n) | O(1) |
+| `count(): bigint` | 返回元素数量 | O(1) | O(1) |
+| `average(): bigint` | 返回 bigint 平均值 | O(n) | O(1) |
+| `average(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的平均值 | O(n) | O(1) |
+| `range(): bigint` | 返回 bigint 极差 | O(1) | O(1) |
+| `range(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的极差 | O(1) | O(1) |
+| `variance(): bigint` | 返回 bigint 方差 | O(n) | O(1) |
+| `variance(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的方差 | O(n) | O(1) |
+| `standardDeviation(): bigint` | 返回 bigint 标准差 | O(n) | O(1) |
+| `standardDeviation(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的标准差 | O(n) | O(1) |
+| `mean(): bigint` | 返回 bigint 均值（同 average） | O(n) | O(1) |
+| `mean(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的均值 | O(n) | O(1) |
+| `median(): bigint` | 返回 bigint 中位数 | O(n) | O(n) |
+| `median(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的中位数 | O(n) | O(n) |
+| `mode(): bigint` | 返回 bigint 众数 | O(n) | O(n) |
+| `mode(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的众数 | O(n) | O(n) |
+| `frequency(): Map<E, bigint>` | 返回频率分布 | O(n) | O(n) |
+| `summate(): bigint` | 返回 bigint 总和 | O(n) | O(1) |
+| `summate(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的总和 | O(n) | O(1) |
+| `quantile(quantile: number): bigint` | 返回指定 bigint 分位数 | O(1) | O(1) |
+| `quantile(quantile: number, mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的指定分位数 | O(1) | O(1) |
+| `interquartileRange(): bigint` | 返回 bigint 四分位距 | O(1) | O(1) |
+| `interquartileRange(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的四分位距 | O(1) | O(1) |
+| `skewness(): bigint` | 返回 bigint 偏度 | O(n) | O(1) |
+| `skewness(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的偏度 | O(n) | O(1) |
+| `kurtosis(): bigint` | 返回 bigint 峰度 | O(n) | O(1) |
+| `kurtosis(mapper: Functional<E, bigint>): bigint` | 返回映射 bigint 值的峰度 | O(n) | O(1) |
+
+```typescript
+// 大整数统计分析示例
+let bigInts = from([1000n, 2000n, 3000n, 4000n, 5000n, 6000n, 7000n, 8000n, 9000n, 10000n])
+    .toBigIntStatistics();
+
+console.log("bigint 均值:", bigInts.mean()); // 5500n
+console.log("bigint 总和:", bigInts.summate()); // 55000n
+console.log("bigint 标准差:", bigInts.standardDeviation()); // 3027.65... 注意：计算为 bigint，结果为近似值
+console.log("bigint 中位数:", bigInts.median()); // 5500n
+```
+
+## WindowCollectable 类方法
+
+`WindowCollectable<E>` 是 `Collectable<E>` 的一种实现，专为**窗口操作**设计。它允许您将元素流划分为重叠或非重叠的窗口（片段），非常适合处理时间序列数据、批处理或滑动平均等场景。
+
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|--------|-------------|-----------------|------------------|
+| `constructor(generator: Generator<E>)` | 创建一个窗口可收集流实例 | O(n log n) | O(n) |
+| `constructor(generator: Generator<E>, comparator: Comparator<E>)` | 使用比较器创建一个窗口可收集流实例 | O(n log n) | O(n) |
+| `: Generator<E, void, undefined>` | 返回迭代器 | O(n) | O(1) |
+| `: AsyncGenerator<E, void, undefined>` | 返回异步迭代器 | O(n) | O(1) |
+| `slide(size: bigint): Semantic<Semantic<E>>` | 创建滑动窗口（步长为 1） | O(m × n) | O(m × n) |
+| `slide(size: bigint, step: bigint): Semantic<Semantic<E>>` | 创建滑动窗口 | O(m × n) | O(m × n) |
+| `tumble(size: bigint): Semantic<Semantic<E>>` | 创建滚动窗口 | O(k × n) | O(k × n) |
+
+**参数说明**：
+- `size`: 窗口大小（包含的元素数量）。
+- `step`: 滑动步长（`slide` 方法专用）。
+- 返回值：一个 `Semantic<Semantic<E>>`，其中每个内部 `Semantic<E>` 代表一个窗口。
+
+**窗口类型**：
+1.  **滑动窗口 (Sliding Window)**: 通过 `slide(size, step)` 创建。窗口按指定步长滑动，相邻窗口之间可以有重叠。
+2.  **滚动窗口 (Tumbling Window)**: 通过 `tumble(size)` 创建。窗口是连续且不重叠的，等同于 `slide(size, size)`。
+
+```typescript
+// WindowCollectable 操作示例
+let dataStream = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+// 转换为 WindowCollectable
+let windowedData: WindowCollectable<number> = dataStream.toWindow();
+
+// 示例 1: 大小为 3 的滑动窗口，步长为 1
+let slidingWindows: Semantic<Semantic<number>> = windowedData.slide(3n, 1n);
+console.log("滑动窗口 (size=3, step=1):");
+slidingWindows.toUnordered()
+    .forEach((window, idx) => {
+        console.log(`  窗口 ${idx}:`, window.toArray());
+    });
+// 输出:
+//   窗口 0: [1, 2, 3]
+//   窗口 1: [2, 3, 4]
+//   窗口 2: [3, 4, 5]
+//   ... 以此类推
+
+// 示例 2: 大小为 3 的滚动窗口
+let tumblingWindows: Semantic<Semantic<number>> = windowedData.tumble(3n);
+console.log("滚动窗口 (size=3):");
+tumblingWindows.toUnordered()
+    .forEach((window, idx) => {
+        console.log(`  窗口 ${idx}:`, window.toArray());
+    });
+// 输出:
+//   窗口 0: [1, 2, 3]
+//   窗口 1: [4, 5, 6]
+//   窗口 2: [7, 8, 9]
+//   最后一个不完整的窗口 [10] 通常会被丢弃（取决于实现）
+
+// 示例 3: 计算每个窗口的平均值
+let slidingWindowAverages = windowedData.slide(5n, 2n) // 大小为5，步长为2的滑动窗口
+    .map((windowSemantic) => {
+        return windowSemantic
+            .toNumericStatistics()
+            .average();
+    })
+    .toUnordered()
+    .toArray();
+console.log("滑动窗口平均值 (size=5, step=2):", slidingWindowAverages);
+// 输出: [3, 5, 7] （即 [1,2,3,4,5] 的平均值 3, [3,4,5,6,7] 的平均值 5, [5,6,7,8,9] 的平均值 7）
 ```
 
 ## 性能选择指南
 
-### 选择无序收集器（性能优先）
+选择合适的收集器类型对于优化应用性能至关重要。以下是基于不同使用场景的推荐选择：
+
+### 场景 1：选择 UnorderedCollectable (性能优先)
+当您的操作**不依赖**元素的顺序时，应始终优先使用 `toUnordered()`。这可以避免不必要的排序和索引维护开销，提供最佳性能。`UnorderedCollectable` 会自动忽略 `redirect`、`reverse`、`shuffle` 和 `translate` 等顺序操作。
 
 ```typescript
-// 当不需要顺序保证时，使用无序收集器以获得最佳性能
+// 典型场景：计数、求和、检查存在性、去重、分组、写入流、日志记录等。
 let highPerformance = data
-    .filter(predicate)
-    .map(mapper)
-    .toUnordered(); // 最佳性能
+    .filter((n) => n > 0) // 过滤
+    .map((n) => n * 2)    // 映射
+    .toUnordered();       // 转换为无序收集器以获得最佳性能
+
+let count = highPerformance.count(); // 快速计数
+let exists = highPerformance.anyMatch((n) => n > 100); // 快速检查
+highPerformance.forEach((n) => console.log(n)); // 快速遍历
 ```
 
-### 选择有序收集器（需要顺序）
+### 场景 2：选择 OrderedCollectable (顺序必需)
+当您的操作**依赖**元素的顺序时，必须使用 `OrderedCollectable`。调用 `.sorted()` 方法会自动创建它。它保证了结果的确定性顺序，但会带来 O(n log n) 的排序开销。
 
 ```typescript
-// 当需要保持元素顺序时，使用有序收集器
-let ordered = data.sorted(comparator);
+// 典型场景：排序、查找第一个/最后一个、需要确定顺序的归约、需要顺序的窗口操作等。
+let ordered = data
+    .sorted((a, b) => b - a) // 降序排序，自动创建 OrderedCollectable
+    .limit(5); // 取最大的5个
+
+let first = ordered.findFirst(); // 获取最大值
+let last = ordered.findLast();   // 获取排序后的最后一个值（即第5大的值）
 ```
 
-### 选择窗口收集器（窗口操作）
+### 场景 3：选择 WindowCollectable (窗口操作)
+当您需要对数据流进行**分块**或**滑动**分析时，请使用 `WindowCollectable`。它专门为处理时间窗口、数据批次或滑动聚合而设计。
 
 ```typescript
-// 当需要窗口操作时
-let window: WindowCollectable<number> = data
-    .toWindow()
-    .slide(5n, 2n); // 滑动窗口
+// 典型场景：计算滑动平均、实时统计、批次处理、时间序列分析。
+let windowedData: WindowCollectable<number> = data
+    .toWindow();
+
+// 计算每5个元素的滚动平均值
+let movingAverages = windowedData
+    .slide(5n, 1n) // 滑动窗口
+    .map(window => window.toNumericStatistics().average())
+    .toUnordered()
+    .toArray();
 ```
 
-### 选择统计分析（数值计算）
+### 场景 4：选择 StatisticalAnalysis (数值计算)
+当您需要对数值流（`number` 或 `bigint`）进行**统计分析**（如均值、方差、标准差、中位数、分位数等）时，应使用对应的统计类。它们内部已针对这些计算进行了优化。
 
 ```typescript
-// 当需要统计分析时
-let statistics: NumericStatistics<number> = data
-    .toNumericStatistics(); // 数值统计
-let bigIntStatistics: BigintStatistics<bigint> = data
-    .toBigintStatistics(); // 大整数统计
-```
+// 典型场景：数据科学、财务分析、性能监控、质量评估。
+let stats: NumericStatistics<number> = data
+    .toNumericStatistics(); // 转换为数字统计
 
-[GitHub](https://github.com/eloyhere/semantic-typescript)
-[NPMJS](https://www.npmjs.com/package/semantic-typescript)
+console.log("均值:", stats.mean());
+console.log("标准差:", stats.standardDeviation());
+console.log("90% 分位数:", stats.quantile(0.9));
+
+// 对于大整数数据
+let bigIntStats: BigIntStatistics<bigint> = largeIntegerData
+    .toBigIntStatistics();
+```
 
 ## 重要注意事项
 
-1. **排序操作的影响**：在有序收集器中，`sorted()` 操作会覆盖 `redirect`、`translate`、`shuffle`、`reverse` 的效果。
-2. **性能考虑**：如果不需要顺序保证，优先使用 `toUnordered()` 以获得更好的性能。
-3. **内存使用**：排序操作需要额外的 O(n) 空间。
-4. **实时数据处理**：Semantic 流适用于处理实时数据，并支持异步数据源。
+1.  **排序操作的影响**：在 `OrderedCollectable` 中，`sorted()` 操作会覆盖 `redirect`、`translate`、`shuffle`、`reverse` 等先前定义的所有顺序。最终顺序由 `sorted()` 决定。
+2.  **性能考量**：如果不需要顺序保证，请优先使用 `toUnordered()` 以获得最佳性能。排序操作（`sorted()`）需要 O(n) 的额外空间和 O(n log n) 的时间。
+3.  **内存使用**：`WindowCollectable` 和 `Statistics` 类在处理过程中可能需要缓存数据以进行计算，尤其是在进行窗口操作或排序时，请注意大数据集可能带来的内存压力。
+4.  **实时数据处理**：`Semantic` 流非常适合处理实时数据源（如 `interval`、`websocket`、`blob`），并支持异步数据源。结合 `WindowCollectable` 可以进行高效的流式分析。
+5.  **短路操作**：利用 `anyMatch`、`allMatch`、`noneMatch`、`findFirst` 等短路操作，可以在满足条件时立即终止流的处理，从而提升效率。
+6.  **类型安全**：该库充分利用 TypeScript 的类型系统，在编译时捕获许多潜在错误。请确保为您的映射器、断言和比较器函数提供正确的类型签名。
+
+该库为 TypeScript 开发者提供了强大而灵活的流处理能力，将函数式编程的优势与类型安全保证完美结合。通过理解 `Semantic`、`Collectable` 及其各种子类（`UnorderedCollectable`、`OrderedCollectable`、`WindowCollectable`、`NumericStatistics`、`BigIntStatistics`）的职责，您可以构建出既高效又易于维护的数据处理管道。
+
+---
 
-这个库为 TypeScript 开发者提供了强大而灵活的流处理能力，结合了函数式编程的优势和类型安全的保障。
+https://github.com/eloyhere/semantic-typescript
+https://www.npmjs.com/package/semantic-typescript