semantic-typescript 0.0.7 → 0.1.4

package/readme.cn.md

@@ -1,335 +1,426 @@
-# 📘 semantic-typescript
+# Semantic-TypeScript 流处理库
 
-一个强大、类型安全的 TypeScript 工具库，用于**语义化数据处理**。  
-提供可组合的函数式风格构造，用于处理集合、流和序列 —— 支持排序、过滤、分组、统计分析等功能。
+## 简介
 
-无论您是在处理**有序或无序数据**、进行**统计分析**，还是仅仅想要**流畅地链式操作**，本库都能满足您的需求。
+Semantic-TypeScript 是一个受到 JavaScript GeneratorFunction、Java Stream 和 MySQL Index 启发而设计的现代化流处理库。该库的核心设计理念是基于数据索引构建高效的数据处理管道，为前端开发提供类型安全、函数式风格的流式操作体验。
 
----
+与传统的同步处理不同，Semantic 采用异步处理模式。在创建数据流时，终端接收数据的时间完全取决于上游何时调用 `accept` 和 `interrupt` 回调函数，这种设计使得库能够优雅地处理实时数据流、大型数据集和异步数据源。
 
-## 🧩 特性
-
-- ✅ 全程**类型安全泛型**
-- ✅ **函数式编程**风格（map、filter、reduce 等）
-- ✅ **语义数据流**（`Semantic<E>`）支持惰性求值
-- ✅ **收集器**用于将流转换为具体结构
-- ✅ **有序与无序收集器** —— `toUnordered()` **不排序，最快**！其他收集器会排序
-- ✅ **排序支持**通过 `sorted()`、`toOrdered()`、比较器
-- ✅ **统计分析**（`Statistics`、`NumericStatistics`、`BigIntStatistics`）
-- ✅ **Optional<T>** 单体模式，安全处理可空值
-- ✅ 基于**迭代器与生成器**的设计 —— 适用于大型/异步数据
-
----
-
-## 📦 安装
+## 安装
 
 ```bash
 npm install semantic-typescript
 ```
 
----
-
-## 🧠 核心概念
-
-### 1. `Optional<T>` – 安全的可空值处理
-
-用于包装可能为 `null` 或 `undefined` 的值的单体制容器。
-
-#### 方法：
-
-| 方法 | 说明 | 示例 |
-|------|------|------|
-| `of(value)` | 包装值（可为空） | `Optional.of(null)` |
-| `ofNullable(v)` | 包装，允许空值 | `Optional.ofNullable(someVar)` |
-| `ofNonNull(v)` | 包装，若为 null/undefined 则抛出 | `Optional.ofNonNull(5)` |
-| `get()` | 获取值，空则抛出 | `opt.get()` |
-| `getOrDefault(d)` | 获取值或默认值 | `opt.getOrDefault(0)` |
-| `ifPresent(fn)` | 若存在则执行副作用 | `opt.ifPresent(x => console.log(x))` |
-| `map(fn)` | 若存在则转换值 | `opt.map(x => x + 1)` |
-| `filter(fn)` | 仅保留满足谓词的值 | `opt.filter(x => x > 0)` |
-| `isEmpty()` | 检查是否为空 | `opt.isEmpty()` |
-| `isPresent()` | 检查是否有值 | `opt.isPresent()` |
+## 基础类型
 
-#### 示例：
+| 类型 | 描述 |
+|------|------|
+| `Invalid<T>` | 扩展 null 或 undefined 的类型 |
+| `Valid<T>` | 排除 null 和 undefined 的类型 |
+| `MaybeInvalid<T>` | 可能为 null 或 undefined 的类型 |
+| `Primitive` | 原始类型集合 |
+| `MaybePrimitive<T>` | 可能为原始类型的类型 |
+| `OptionalSymbol` | Optional 类的符号标识 |
+| `SemanticSymbol` | Semantic 类的符号标识 |
+| `CollectorsSymbol` | Collector 类的符号标识 |
+| `CollectableSymbol` | Collectable 类的符号标识 |
+| `OrderedCollectableSymbol` | OrderedCollectable 类的符号标识 |
+| `WindowCollectableSymbol` | WindowCollectable 类的符号标识 |
+| `StatisticsSymbol` | Statistics 类的符号标识 |
+| `NumericStatisticsSymbol` | NumericStatistics 类的符号标识 |
+| `BigIntStatisticsSymbol` | BigIntStatistics 类的符号标识 |
+| `UnorderedCollectableSymbol` | UnorderedCollectable 类的符号标识 |
+| `Runnable` | 无参数无返回值的函数 |
+| `Supplier<R>` | 无参数返回 R 的函数 |
+| `Functional<T, R>` | 单参数转换函数 |
+| `Predicate<T>` | 单参数判断函数 |
+| `BiFunctional<T, U, R>` | 双参数转换函数 |
+| `BiPredicate<T, U>` | 双参数判断函数 |
+| `Comparator<T>` | 比较函数 |
+| `TriFunctional<T, U, V, R>` | 三参数转换函数 |
+| `Consumer<T>` | 单参数消费函数 |
+| `BiConsumer<T, U>` | 双参数消费函数 |
+| `TriConsumer<T, U, V>` | 三参数消费函数 |
+| `Generator<T>` | 生成器函数 |
 
 ```typescript
-import { Optional } from 'semantic-typescript';
-
-const value: number | null = Math.random() > 0.5 ? 10 : null;
-
-const opt = Optional.ofNullable(value);
-
-const result = opt
-  .filter(v => v > 5)
-  .map(v => v * 2)
-  .getOrDefault(0);
-
-console.log(result); // 20 或 0
+// 类型使用示例
+const predicate: Predicate<number> = (n) => n > 0;
+const mapper: Functional<string, number> = (str) => str.length;
+const comparator: Comparator<number> = (a, b) => a - b;
 ```
 
----
+## 类型守卫
+
+| 函数 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `validate<T>(t: MaybeInvalid<T>): t is T` | 验证值不为 null 或 undefined | O(1) | O(1) |
+| `invalidate<T>(t: MaybeInvalid<T>): t is null \| undefined` | 验证值为 null 或 undefined | O(1) | O(1) |
+| `isBoolean(t: unknown): t is boolean` | 检查是否为布尔值 | O(1) | O(1) |
+| `isString(t: unknown): t is string` | 检查是否为字符串 | O(1) | O(1) |
+| `isNumber(t: unknown): t is number` | 检查是否为数字 | O(1) | O(1) |
+| `isFunction(t: unknown): t is Function` | 检查是否为函数 | O(1) | O(1) |
+| `isObject(t: unknown): t is object` | 检查是否为对象 | O(1) | O(1) |
+| `isSymbol(t: unknown): t is symbol` | 检查是否为 Symbol | O(1) | O(1) |
+| `isBigint(t: unknown): t is bigint` | 检查是否为 BigInt | O(1) | O(1) |
+| `isPrimitive(t: unknown): t is Primitive` | 检查是否为原始类型 | O(1) | O(1) |
+| `isIterable(t: unknown): t is Iterable<unknown>` | 检查是否为可迭代对象 | O(1) | O(1) |
+| `isOptional(t: unknown): t is Optional<unknown>` | 检查是否为 Optional 实例 | O(1) | O(1) |
+| `isSemantic(t: unknown): t is Semantic<unknown>` | 检查是否为 Semantic 实例 | O(1) | O(1) |
+| `isCollector(t: unknown): t is Collector<unknown, unknown, unknown>` | 检查是否为 Collector 实例 | O(1) | O(1) |
+| `isCollectable(t: unknown): t is Collectable<unknown>` | 检查是否为 Collectable 实例 | O(1) | O(1) |
+| `isOrderedCollectable(t: unknown): t is OrderedCollectable<unknown>` | 检查是否为 OrderedCollectable 实例 | O(1) | O(1) |
+| `isWindowCollectable(t: unknown): t is WindowCollectable<unknown>` | 检查是否为 WindowCollectable 实例 | O(1) | O(1) |
+| `isUnorderedCollectable(t: unknown): t is UnorderedCollectable<unknown>` | 检查是否为 UnorderedCollectable 实例 | O(1) | O(1) |
+| `isStatistics(t: unknown): t is Statistics<unknown, number \| bigint>` | 检查是否为 Statistics 实例 | O(1) | O(1) |
+| `isNumericStatistics(t: unknown): t is NumericStatistics<unknown>` | 检查是否为 NumericStatistics 实例 | O(1) | O(1) |
+| `isBigIntStatistics(t: unknown): t is BigIntStatistics<unknown>` | 检查是否为 BigIntStatistics 实例 | O(1) | O(1) |
 
-### 2. `Semantic<E>` – 惰性数据流
+```typescript
+// 类型守卫使用示例
+const value: unknown = "hello";
 
-一个**惰性、可组合的序列**元素。类似于 Java Streams 或 Kotlin Sequences 的函数式流。
+if (isString(value)) {
+    console.log(value.length); // 类型安全，value 被推断为 string
+}
 
-您可以使用 `from()`、`range()`、`iterate()` 或 `fill()` 等辅助函数创建 `Semantic`。
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
+}
+```
 
-#### 创建方法：
+## 工具函数
 
-| 函数 | 说明 | 示例 |
-|------|------|------|
-| `from(iterable)` | 从 Array/Set/Iterable 创建 | `from([1, 2, 3])` |
-| `range(start, end, step?)` | 生成数字范围 | `range(0, 5)` → 0,1,2,3,4 |
-| `fill(element, count)` | 重复元素 N 次 | `fill('a', 3n)` |
-| `iterate(gen)` | 使用自定义生成器函数 | `iterate(genFn)` |
+| 函数 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `useCompare<T>(t1: T, t2: T): number` | 通用比较函数 | O(1) | O(1) |
+| `useRandom<T = number \| bigint>(index: T): T` | 伪随机数生成器 | O(log n) | O(1) |
 
-#### 常用操作符：
+```typescript
+// 工具函数使用示例
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-| 方法 | 说明 | 示例 |
-|------|------|------|
-| `map(fn)` | 转换每个元素 | `.map(x => x * 2)` |
-| `filter(fn)` | 保留满足谓词的元素 | `.filter(x => x > 10)` |
-| `limit(n)` | 限制前 N 个元素 | `.limit(5)` |
-| `skip(n)` | 跳过前 N 个元素 | `.skip(2)` |
-| `distinct()` | 去重（默认使用 Set） | `.distinct()` |
-| `sorted()` | 排序元素（需自然排序） | `.sorted()` |
-| `sorted(comparator)` | 自定义排序 | `.sorted((a,b) => a - b)` |
-| `toOrdered()` | 排序并返回 OrderedCollectable | `.toOrdered()` |
-| `toUnordered()` | **不排序** – 最快的收集器 | `.toUnordered()` ✅ |
-| `collect(collector)` | 使用收集器聚合 | `.collect(Collector.full(...))` |
-| `toArray()` | 转换为数组 | `.toArray()` |
-| `toSet()` | 转换为 Set | `.toSet()` |
-| `toMap(keyFn, valFn)` | 转换为 Map | `.toMap(x => x.id, x => x)` |
+const randomNum = useRandom(42); // 基于种子的随机数
+const randomBigInt = useRandom(1000n); // BigInt 随机数
+```
 
----
+## 工厂方法
 
-### 3. `toUnordered()` – 🚀 最快，不排序
+### Optional 工厂方法
 
-如果您**不关心顺序**且希望获得**最佳性能**，请使用：
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `Optional.empty<T>()` | 创建空的 Optional | O(1) | O(1) |
+| `Optional.of<T>(value)` | 创建包含值的 Optional | O(1) | O(1) |
+| `Optional.ofNullable<T>(value)` | 创建可能为空的 Optional | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value)` | 创建非空的 Optional | O(1) | O(1) |
 
 ```typescript
-const fastest = semanticStream.toUnordered();
+// Optional 使用示例
+const emptyOpt = Optional.empty<number>();
+const presentOpt = Optional.of(42);
+const nullableOpt = Optional.ofNullable<string>(null);
+const nonNullOpt = Optional.ofNonNull("hello");
+
+presentOpt.ifPresent(val => console.log(val)); // 输出 42
+console.log(emptyOpt.orElse(100)); // 输出 100
 ```
 
-🔥 **不应用任何排序算法。**  
-当顺序无关紧要且您需要最大速度时，请使用此方法。
-
----
+### Collector 工厂方法
 
-### 4. `toOrdered()` 和 `sorted()` – 排序输出
-
-如果您需要**排序输出**，请使用：
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `Collector.full(identity, accumulator, finisher)` | 创建完整收集器 | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | 创建可中断收集器 | O(1) | O(1) |
 
 ```typescript
-const ordered = semanticStream.sorted(); // 自然排序
-const customSorted = semanticStream.sorted((a, b) => a - b); // 自定义比较器
-const orderedCollectable = semanticStream.toOrdered(); // 同样排序
+// Collector 使用示例
+const sumCollector = Collector.full(
+    () => 0,
+    (sum, num) => sum + num,
+    result => result
+);
+
+const numbers = from([1, 2, 3, 4, 5]);
+const total = numbers.toUnoredered().collect(sumCollector); // 15
 ```
 
-⚠️ 这些方法**会对元素进行排序**，使用自然排序或提供的比较器。
-
----
+### Semantic 工厂方法
 
-### 5. `Collector<E, A, R>` – 数据聚合
-
-收集器让您能够将流**缩减为单个或复杂结构**。
-
-内置静态工厂：
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `blob(blob, chunkSize)` | 从 Blob 创建流 | O(n) | O(chunkSize) |
+| `empty<E>()` | 创建空流 | O(1) | O(1) |
+| `fill<E>(element, count)` | 创建填充流 | O(n) | O(1) |
+| `from<E>(iterable)` | 从可迭代对象创建流 | O(1) | O(1) |
+| `interval(period, delay?)` | 创建定时间隔流 | O(1)* | O(1) |
+| `iterate<E>(generator)` | 从生成器创建流 | O(1) | O(1) |
+| `range(start, end, step)` | 创建数值范围流 | O(n) | O(1) |
+| `websocket(websocket)` | 从 WebSocket 创建流 | O(1) | O(1) |
 
 ```typescript
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// Semantic 工厂方法使用示例
+
+// 从 Blob 创建流（分块读取）
+blob(someBlob, 1024n)
+  .toUnordered()
+  .write(WritableStream)
+  .then(callback) // 写入流成功
+  .catch(writeFi); // 写入流失败
+
+// 创建空流，在拼接其它流之前不会执行
+empty<string>()
+  .toUnordered()
+  .join(); //[]
+
+// 创建填充流
+const filledStream = fill("hello", 3); // "hello", "hello", "hello"
+
+// 创建初始延迟2秒、执行周期5秒的时序流，基于计时器机制实现，因系统调度精度限制可能存在时间漂移。
+const intervalStream = interval(5000, 2000);
+
+// 从可迭代对象创建流
+const numberStream = from([1, 2, 3, 4, 5]);
+const stringStream = from(new Set(["Alex", "Bob"]));
+
+// 创建范围流
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
+
+// WebSocket 事件流
+const ws = new WebSocket("ws://localhost:8080");
+websocket(ws)
+  .filter((event)=> event.type === "message"); //只监听消息事件
+  .toUnordered() // 对于事件一般不排序
+  .forEach((event)=> receive(event)); //接收消息
 ```
 
-但您通常会通过 `Collectable` 类的高层辅助方法使用它们。
-
----
-
-### 6. `Collectable<E>`（抽象类）
-
-以下类的基类：
-
-- `OrderedCollectable<E>` – 排序输出
-- `UnorderedCollectable<E>` – 不排序，最快
-- `WindowCollectable<E>` – 滑动窗口
-- `Statistics<E, D>` – 统计聚合
-
-#### 常用方法（通过继承）：
-
-| 方法 | 说明 | 示例 |
-|------|------|------|
-| `count()` | 计数元素 | `.count()` |
-| `toArray()` | 转为数组 | `.toArray()` |
-| `toSet()` | 转为 Set | `.toSet()` |
-| `toMap(k, v)` | 转为 Map | `.toMap(x => x.id, x => x)` |
-| `group(k)` | 按键分组 | `.group(x => x.category)` |
-| `findAny()` | 任意匹配元素（Optional） | `.findAny()` |
-| `findFirst()` | 第一个元素（Optional） | `.findFirst()` |
-| `reduce(...)` | 自定义缩减 | `.reduce((a,b) => a + b, 0)` |
-
----
-
-### 7. `OrderedCollectable<E>` – 排序数据
-
-如果您希望元素**自动排序**，请使用此类。
-
-可接受**自定义比较器**或使用自然排序。
+## Semantic 类方法
+
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `concat(other)` | 连接两个流 | O(n) | O(1) |
+| `distinct()` | 去重 | O(n) | O(n) |
+| `distinct(comparator)` | 使用比较器去重 | O(n²) | O(n) |
+| `dropWhile(predicate)` | 丢弃满足条件的元素 | O(n) | O(1) |
+| `filter(predicate)` | 过滤元素 | O(n) | O(1) |
+| `flat(mapper)` | 扁平化映射 | O(n × m) | O(1) |
+| `flatMap(mapper)` | 扁平化映射到新类型 | O(n × m) | O(1) |
+| `limit(n)` | 限制元素数量 | O(n) | O(1) |
+| `map(mapper)` | 映射转换 | O(n) | O(1) |
+| `peek(consumer)` | 查看元素 | O(n) | O(1) |
+| `redirect(redirector)` | 重定向索引 | O(n) | O(1) |
+| `reverse()` | 反转流 | O(n) | O(1) |
+| `shuffle()` | 随机打乱 | O(n) | O(1) |
+| `shuffle(mapper)` | 使用映射器打乱 | O(n) | O(1) |
+| `skip(n)` | 跳过前n个元素 | O(n) | O(1) |
+| `sorted()` | 排序 | O(n log n) | O(n) |
+| `sorted(comparator)` | 使用比较器排序 | O(n log n) | O(n) |
+| `sub(start, end)` | 获取子流 | O(n) | O(1) |
+| `takeWhile(predicate)` | 获取满足条件的元素 | O(n) | O(1) |
+| `translate(offset)` | 平移索引 | O(n) | O(1) |
+| `translate(translator)` | 使用转换器平移索引 | O(n) | O(1) |
 
 ```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// Semantic 操作示例
+const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)        // 过滤偶数
+    .map(n => n * 2)                 // 乘以2
+    .skip(1)                         // 跳过第一个
+    .limit(3)                        // 限制3个元素
+    .toArray();                      // 转换为数组
+// 结果: [8, 12, 20]
+
+// 复杂操作示例
+const complexResult = range(1, 100, 1)
+    .flatMap(n => from([n, n * 2])) // 每个元素映射为两个
+    .distinct()                      // 去重
+    .shuffle()                       // 打乱顺序
+    .takeWhile(n => n < 50)         // 取小于50的元素
+    .toOrdered()                     // 转换为有序收集器
+    .toArray();                      // 转换为数组
 ```
 
-🔒 **保证排序输出。**
+## 收集器转换方法
 
----
-
-### 8. `UnorderedCollectable<E>` – 不排序（🚀 最快）
-
-如果您**不关心顺序**且希望获得**最佳性能**，请使用：
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `toUnoredered()` | 转换为无序收集器（性能优先） | O(1) | O(1) |
+| `toOrdered()` | 转换为有序收集器 | O(1) | O(1) |
+| `sorted()` | 排序并转换为有序收集器 | O(n log n) | O(n) |
+| `toWindow()` | 转换为窗口收集器 | O(1) | O(1) |
+| `toNumericStatistics()` | 转换为数值统计 | O(1) | O(1) |
+| `toBigintStatistics()` | 转换为大数统计 | O(1) | O(1) |
 
 ```typescript
-const unordered = new UnorderedCollectable(stream);
-// 或
-const fastest = semanticStream.toUnordered();
+// 收集器转换示例
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
+
+// 性能优先：使用无序收集器
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
+
+// 需要排序：使用有序收集器  
+const ordered = numbers
+    .sorted()
+    .toOrdered();
+
+// 统计分析：使用统计收集器
+const stats = numbers
+    .toNumericStatistics();
+
+console.log(stats.mean());        // 平均值
+console.log(stats.median());      // 中位数
+console.log(stats.standardDeviation()); // 标准差
+
+// 窗口操作
+const windowed = numbers
+    .toWindow()
+    .tumble(3n); // 每3个元素一个窗口
+
+windowed.forEach(window => {
+    console.log(window.toArray()); // 每个窗口的内容
+});
 ```
 
-✅ **不执行任何排序算法**  
-✅ **顺序无关紧要时的最佳性能**
-
----
-
-### 9. `Statistics<E, D>` – 统计分析
-
-用于分析数值数据的抽象基类。
-
-#### 子类：
-
-- `NumericStatistics<E>` – 适用于 `number` 值
-- `BigIntStatistics<E>` – 适用于 `bigint` 值
-
-##### 常用统计方法：
-
-| 方法 | 说明 | 示例 |
-|------|------|------|
-| `mean()` | 平均值 | `.mean()` |
-| `median()` | 中位数 | `.median()` |
-| `mode()` | 众数 | `.mode()` |
-| `minimum()` | 最小元素 | `.minimum()` |
-| `maximum()` | 最大元素 | `.maximum()` |
-| `range()` | 最大值 - 最小值 | `.range()` |
-| `variance()` | 方差 | `.variance()` |
-| `standardDeviation()` | 标准差 | `.standardDeviation()` |
-| `summate()` | 元素总和 | `.summate()` |
-| `quantile(q)` | 第 q 分位数（0–1） | `.quantile(0.5)` → 中位数 |
-| `frequency()` | 频率映射表 | `.frequency()` |
-
----
-
-## 🧪 完整示例
+## Collectable 收集方法
+
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `anyMatch(predicate)` | 是否存在匹配元素 | O(n) | O(1) |
+| `allMatch(predicate)` | 是否所有元素匹配 | O(n) | O(1) |
+| `count()` | 元素计数 | O(n) | O(1) |
+| `isEmpty()` | 是否为空 | O(1) | O(1) |
+| `findAny()` | 查找任意元素 | O(n) | O(1) |
+| `findFirst()` | 查找第一个元素 | O(n) | O(1) |
+| `findLast()` | 查找最后一个元素 | O(n) | O(1) |
+| `forEach(action)` | 遍历所有元素 | O(n) | O(1) |
+| `group(classifier)` | 按分类器分组 | O(n) | O(n) |
+| `groupBy(keyExtractor, valueExtractor)` | 按键值提取器分组 | O(n) | O(n) |
+| `join()` | 连接为字符串 | O(n) | O(n) |
+| `join(delimiter)` | 使用分隔符连接 | O(n) | O(n) |
+| `nonMatch(predicate)` | 是否没有元素匹配 | O(n) | O(1) |
+| `partition(count)` | 按数量分区 | O(n) | O(n) |
+| `partitionBy(classifier)` | 按分类器分区 | O(n) | O(n) |
+| `reduce(accumulator)` | 归约操作 | O(n) | O(1) |
+| `reduce(identity, accumulator)` | 带初始值的归约 | O(n) | O(1) |
+| `toArray()` | 转换为数组 | O(n) | O(n) |
+| `toMap(keyExtractor, valueExtractor)` | 转换为Map | O(n) | O(n) |
+| `toSet()` | 转换为Set | O(n) | O(n) |
+| `write(stream)` | 写入流 | O(n) | O(1) |
 
 ```typescript
-import { from, toUnordered, toOrdered, sorted, NumericStatistics } from 'semantic-typescript';
-
-// 示例数据
-const numbers = from([10, 2, 8, 4, 5, 6]);
-
-// 🚀 最快：不排序
-const fastest = numbers.toUnordered();
-console.log(fastest.toArray()); // 例如 [10, 2, 8, 4, 5, 6]（保持原顺序）
-
-// 🔢 自然排序
-const ordered = numbers.sorted();
-console.log(ordered.toArray()); // [2, 4, 5, 6, 8, 10]
-
-// 📊 获取统计数据
-const stats = new NumericStatistics(numbers);
-console.log('平均值:', stats.mean());
-console.log('中位数:', stats.median());
-console.log('众数:', stats.mode());
-console.log('极差:', stats.range());
-console.log('标准差:', stats.standardDeviation());
+// Collectable 操作示例
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)
+    .toOrdered();
+
+// 匹配检查
+console.log(data.anyMatch(n => n > 5)); // true
+console.log(data.allMatch(n => n < 20)); // true
+
+// 查找操作
+data.findFirst().ifPresent(n => console.log(n)); // 2
+data.findAny().ifPresent(n => console.log(n)); // 任意元素
+
+// 分组操作
+const grouped = data.groupBy(
+    n => n > 5 ? "large" : "small",
+    n => n * 2
+);
+// {small: [4, 8], large: [12, 16, 20]}
+
+// 归约操作
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
+
+// 输出操作
+data.join(", "); // "2, 4, 6, 8, 10"
 ```
 
----
-
-## 🛠️ 工具函数
-
-本库还导出许多**类型守卫**和**比较工具**：
-
-| 函数 | 用途 |
-|------|------|
-| `isString(x)` | string 类型守卫 |
-| `isNumber(x)` | number 类型守卫 |
-| `isBoolean(x)` | boolean 类型守卫 |
-| `isIterable(x)` | 检查对象是否可迭代 |
-| `useCompare(a, b)` | 通用比较函数 |
-| `useRandom(x)` | 伪随机数生成器（有趣） |
-
----
-
-## 🧩 高级用法：自定义生成器与窗口
-
-您可以创建自定义**生成器**用于无限或受控数据流：
+## 统计分析方法
+
+### NumericStatistics 方法
+
+| 方法 | 描述 | 时间复杂度 | 空间复杂度 |
+|------|------|------------|------------|
+| `range()` | 极差 | O(n) | O(1) |
+| `variance()` | 方差 | O(n) | O(1) |
+| `standardDeviation()` | 标准差 | O(n) | O(1) |
+| `mean()` | 平均值 | O(n) | O(1) |
+| `median()` | 中位数 | O(n log n) | O(n) |
+| `mode()` | 众数 | O(n) | O(n) |
+| `frequency()` | 频率分布 | O(n) | O(n) |
+| `summate()` | 求和 | O(n) | O(1) |
+| `quantile(quantile)` | 分位数 | O(n log n) | O(n) |
+| `interquartileRange()` | 四分位距 | O(n log n) | O(n) |
+| `skewness()` | 偏度 | O(n) | O(1) |
+| `kurtosis()` | 峰度 | O(n) | O(1) |
 
 ```typescript
-const gen = (accept: BiConsumer<number, bigint>, interrupt: Predicate<number>) => {
-  for (let i = 0; i < 10; i++) {
-    accept(i, BigInt(i));
-    if (i === 5) interrupt(i);
-  }
-};
-
-const s = new Semantic(gen);
+// 统计分析示例
+const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .toNumericStatistics();
+
+console.log("平均值:", numbers.mean()); // 5.5
+console.log("中位数:", numbers.median()); // 5.5
+console.log("标准差:", numbers.standardDeviation()); // ~2.87
+console.log("总和:", numbers.summate()); // 55
+
+// 使用映射器的统计分析
+const objects = from([
+    { value: 10 },
+    { value: 20 }, 
+    { value: 30 }
+]).toNumericStatistics();
+
+console.log("映射平均值:", objects.mean(obj => obj.value)); // 20
 ```
 
-或使用**滑动窗口**：
+## 性能选择指南
 
+### 选择无序收集器（性能优先）
 ```typescript
-const windowed = ordered.slide(3n, 2n); // 窗口大小为 3，步长为 2
+// 当不需要顺序保证时，使用无序收集器获得最佳性能
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // 最佳性能
 ```
 
----
-
-## 📄 许可证
-
-本项目采用 **MIT 许可证** – 可自由用于商业和个人用途。
-
----
-
-## 🙌 贡献
-
-欢迎提交 Pull Request、提出问题与想法！
-
----
-
-## 🚀 快速开始总结
-
-| 任务 | 方法 |
-|------|------|
-| 安全处理空值 | `Optional<T>` |
-| 创建流 | `from([...])`、`range()`、`fill()` |
-| 转换数据 | `map()`、`filter()` |
-| 排序数据 | `sorted()`、`toOrdered()` |
-| 不排序（最快 | `toUnordered()` ✅ |
-| 分组/聚合 | `toMap()`、`group()`、`Collector` |
-| 统计 | `NumericStatistics`、`mean()`、`median()` 等 |
+### 选择有序收集器（需要顺序）
+```typescript
+// 当需要保持元素顺序时，使用有序收集器
+const ordered = data.sorted(comparator);
+```
 
----
+### 选择窗口收集器（窗口操作）
+```typescript  
+// 需要进行窗口操作时
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // 滑动窗口
+```
 
-## 🔗 链接
+### 选择统计分析（数值计算）
+```typescript  
+// 需要进行统计分析时
+const stats = data
+    .toNumericStatistics(); // 数值统计
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 文档：参见源码 / 类型定义
+const bigIntStats = data
+    .toBigintStatistics(); // 大数统计
+```
 
----
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-**享受在 TypeScript 中进行可组合、类型安全、函数式的数据处理吧。** 🚀
+## 注意事项
 
---- 
+1. **排序操作的影响**：在有序收集器中，`sorted()` 操作会覆盖 `redirect`、`translate`、`shuffle`、`reverse` 的效果
+2. **性能考虑**：如果不需要顺序保证，优先使用 `toUnoredered()` 获得更好性能
+3. **内存使用**：排序操作需要 O(n) 的额外空间
+4. **实时数据**：Semantic 流适合处理实时数据，支持异步数据源
 
-✅ **记住：**  
-- `toUnordered()` → **不排序，最快**  
-- 其他方法（如 `sorted()`、`toOrdered()`）→ **会排序数据**
+这个库为 TypeScript 开发者提供了强大而灵活的流式处理能力，结合了函数式编程的优点和类型安全的保障。