semantic-typescript 0.6.0 → 0.7.0

package/package.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/eloyhere"
   },
   "description": "A modern type-safe stream processing library inspired by JavaScript Generator, Java Stream, and MySQL Index. Supports lazy evaluation, async streams, statistics, and IO-like operations.",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "readme": "readme.md",
   "main": "dist/index.js",
@@ -36,7 +36,8 @@
     "blob-stream",
     "websocket-stream",
     "frontend",
-    "bigInt"
+    "bigInt",
+    "semantic"
   ],
   "repository": {
     "type": "git",

package/readme.cn.md

@@ -1,214 +1,213 @@
-# Semantic-TypeScript：一款范式转换的流处理库
-
-## 简介
-Semantic-TypeScript 代表了流处理技术的一项重大进步，它综合了 JavaScript GeneratorFunctions、Java Streams 和数据库索引范式中最有效的概念。其基础设计原则的核心是通过复杂的惰性求值和智能索引构建极其高效的数据处理管道。该库提供了一个严格类型安全、函数式纯正的流式操作体验，专门为现代 TypeScript 和 JavaScript 开发而设计。
-
-与传统的同步处理架构相比，Semantic-TypeScript 实现了一个统一模型，优雅地处理同步（Iterable）和异步（AsyncIterable）数据源。在流生成过程中，数据的流动和终止由回调机制精确控制，使库能够以超凡的优雅处理：
-
-- 具有确定性控制的实时数据流（DOM 事件、WebSockets、时间间隔）
-- 通过内存高效的惰性管道处理大规模数据集
-- 通过流畅、声明式的 API 进行复杂的数据转换
-
-该库的创新方法从根本上重新构想了开发者与数据序列交互的方式，在一个单一、内聚的包中同时提供了前所未有的性能特性和开发者体验。
-
-## 核心理念：定义与执行的分离
-Semantic-TypeScript 的一个关键架构洞见是清晰地分离流的定义和执行：
-
-- **Semantic<E>**：一个不可变的、惰性的数据转换管道蓝图。它定义了将执行哪些操作（过滤、映射等）
-- **Collectable<E>**：一个已实例化的、可执行的流视图。它是从 Semantic 获取的，并提供所有终端操作（收集、遍历等）来执行管道并生成结果
-
-这种分离强化了清晰的心智模型，并释放了强大的优化能力，例如选择 UnorderedCollectable 来跳过不必要的排序以实现最大速度。
-
-## 为什么选择 Semantic-TypeScript？
-为数据流处理选择合适的库需要在性能、类型安全性和表达能力之间取得平衡。Semantic-TypeScript 的设计旨在所有这些维度上都表现出色。
-
-### 1. 适用于所有数据序列的统一、类型安全范式
-它为处理任何数据序列（无论是静态数组、实时事件还是异步块）提供了一致的声明式 API，同时利用 TypeScript 的全部功能确保端到端的类型安全。这消除了一整类运行时错误，并将流操作转变为可预测的、经过编译器验证的活动。
-
-### 2. 以智能惰性求值实现的不妥协性能
-该库的核心建立在惰性求值之上。诸如过滤器、映射和扁平映射等操作仅仅是组合一个处理管道；直到调用终端操作时，实际工作才会执行。这结合了短路功能（通过限制、任何匹配或自定义中断回调），允许处理提前停止，从而极大地提高了大型或无限流的处理效率。
-
-### 3. `Collector<E, A, R>` 模式的强大之处
-受 Java 启发，收集器模式是灵活性的引擎。它将如何累积流元素的规范与流本身的执行解耦。该库为日常任务提供了一组丰富的内置收集器（toArray、groupBy、summate 等），同时使实现您自己复杂的、可重用的归约逻辑变得非常简单。这比固定的一组终端方法要强大和可组合得多。
-
-### 4. 对现代 Web 和异步数据的一流支持
-Semantic-TypeScript 专为当代开发而设计。它为现代网络源提供了本机工厂方法：
-
-- `useFrom(iterable)`, `useRange()` 用于静态数据
-- `useInterval()`, `useAnimationFrame()` 用于基于时间的流
-- `useBlob()` 用于分块二进制数据处理
-- `useWebSocket()`, `useDocument()`, `useWindow()` 用于实时事件流
-
-### 5. 超越基本聚合：内置统计分析
-超越简单的求和与平均。该库提供了专用的 NumericStatistics 和 BigIntStatistics 接口，可以直接从您的流中即时访问高级统计指标——方差、标准差、中位数、偏度和峰度。这将复杂的数据分析变成了一行代码。
-
-### 6. 为开发者体验而设计
-- **流畅、可链式调用的 API**：将复杂的数据管道编写为可读的、顺序链
-- **全面的工具套件**：包含必要的守卫（isFunction, isIterable）、实用程序（useCompare, useTraverse）和函数式接口
-- **Optional<T> 集成**：安全地建模值的缺失，消除了空指针的担忧
-- **性能指南**：清楚地指导何时使用无序集合以获得速度，何时使用有序集合以保持序列
-
-## 安装
-```bash
-npm install semantic-typescript
-```
-
-## 核心概念实践
-
-### 1. 创建流 (Semantic)
-可以使用工厂函数从各种源创建流。
-
-```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
-
-// 从静态数组创建
-const staticStream = useFrom([1, 2, 3, 4, 5]);
-
-// 从异步生成器创建
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
-
-// 一个基于时间的流
-const tickStream = useInterval(1000); // 每秒发射一次
-
-// 一个 DOM 事件流（参见下面的重要说明）
-const clickStream = useDocument('click');
-```
-
-### 2. 转换流（中间操作）
-通过链式惰性调用来定义管道。
-
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0)  // 仅保留偶数
-  .map(x => x * 10)          // 乘以 10
-  .flatMap(x => [x, x + 1])  // 将每个元素转换为两个
-  .distinct();               // 移除重复项
-
-// 此时尚未执行任何操作
-```
-
-### 3. 执行流（终端操作）
-要获得结果，必须获取一个 Collectable 并调用终端操作。
-
-```typescript
-// 获取一个无序收集器以提高性能
-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
-);
-```
-
-### 4. 关键：处理事件流
-事件流（useDocument, useWindow, useHTMLElement, useWebSocket）本质上是无限的。您必须使用诸如 sub、takeWhile 或 limit 等操作来定义何时停止收集事件并完成流。否则，终端操作将无限期等待。
-
-```typescript
-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
-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();
-
-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
-import { useFrom, useSummate, useGroupBy } from 'semantic-typescript';
-
-interface Transaction {
-  id: number;
-  amount: number;
-  category: string;
-}
-
-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 }
-```
-
-Semantic-TypeScript 是为那些寻求严格设计、类型安全和高性能流处理库的开发者而构建的。它将企业级数据转换模式的力量带入了 TypeScript 生态系统，非常适合数据密集型前端应用程序、Node.js 数据处理，以及任何需要优雅、高效处理序列的场景。
-
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript) 
+# **Semantic-TypeScript**
+**流，索引化。** 您的数据，尽在掌控。
+
+---
+
+### 概述
+
+Semantic-TypeScript 是流处理技术的一次重大飞跃，它**集大成**了 JavaScript `GeneratorFunction`、Java Streams 和 MySQL 式索引中最有效的概念。其核心理念既简单又强大：通过智能索引而非暴力迭代，来构建高效的数据处理管道。
+
+当传统库强制使用同步循环或笨拙的 Promise 链时，Semantic-TypeScript 提供了一种**完全异步**、函数式纯粹且类型安全的体验，专为现代前端开发的需求而设计。
+
+在其优雅的模型中，数据仅在上游管道显式调用 `accept`（以及可选的 `interrupt`）回调时才会抵达消费者。您完全掌控时机——就在您需要的时候。
+
+---
+
+### 开发者为何青睐它
+
+-   **零样板索引** — 每个元素都携带其自然或自定义索引。
+-   **函数式纯粹风格** — 具备完整的 TypeScript 类型推断。
+-   **防泄漏事件流** — `useWindow`、`useDocument`、`useHTMLElement` 和 `useWebSocket` 在设计时就考虑了安全性。您通过 `limit(n)`、`sub(start, end)` 或 `takeWhile(predicate)` 定义边界，库则负责清理。没有残留的监听器，没有内存泄漏。
+-   **开箱即用的统计** — 全面的数值和 bigint 分析，包括平均值、中位数、众数、方差、偏度和峰度。
+-   **可预测的性能** — 根据需求在有序和无序收集器之间选择。
+-   **内存高效** — 流采用惰性求值，无需担心内存问题。
+-   **无未定义行为** — TypeScript 保证类型安全和可空性。除非在回调函数中显式修改，否则输入数据保持不变。
+
+---
+
+### 安装
+
+```bash
+npm install semantic-typescript
+```
+或
+```bash
+yarn add semantic-typescript
+```
+
+---
+
+### 快速开始
+
+```typescript
+import { useOf, useFrom, useRange, useWindow, useHTMLElement, useWebSocket, useText, useStringify } from "semantic-typescript";
+
+// 数值统计
+let summate: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)
+  .toNumericStatistics()  // 终结操作前必需
+  .summate();             // 200
+
+// Bigint 统计
+let summate: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2)
+  .toBigIntStatistics()   // 终结操作前必需
+  .summate();             // 200n
+
+// 通过索引反转流
+useFrom([1, 2, 3, 4, 5])
+  .redirect((element: E, index: bigint): bigint => -index) // 负索引以实现反转
+  .toOrdered() // 调用 toOrdered() 以保持索引顺序
+  .toArray(); // [5, 4, 3, 2, 1]
+
+// 打乱流
+useFrom([1, 2, 3, 4, 5])
+  .shuffle()
+  .toOrdered()
+  .toArray(); // 例如：[2, 5, 1, 4, 3]
+
+// 在流内平移元素
+useFrom([1, 2, 3, 4, 5])
+  .translate(2)  // 将元素向右移动 2 位
+  .toOrdered()
+  .toArray(); // [4, 5, 1, 2, 3]
+
+useFrom([1, 2, 3, 4, 5])
+  .translate(-2) // 将元素向左移动 2 位
+  .toOrdered()
+  .toArray(); // [3, 4, 5, 1, 2]
+
+// 无限范围与提前终止
+useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)
+  .limit(10n)          // 在 10 个元素后停止
+  .toUnordered()
+  .toArray();
+
+// 实时窗口大小调整（5 次事件后自动停止）
+useWindow("resize")
+  .limit(5n)          // 对事件流至关重要
+  .toUnordered()
+  .forEach((ev, idx) => console.log(`调整大小 #${idx}`));
+
+// 监听 HTML 元素
+// <input id="input" type="text"/>
+useHTMLElement("#input", "change")
+  .limit(1)
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
+
+// 监听多个元素和事件
+useHTMLElement("input", ["change", "keyup"])
+  .takeWhile((event: Event): boolean => validate(event))
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
+
+// 监听 WebSocket
+let webSocket = new WebSocket("ws://localhost:8080");
+webSocket.addEventListener("close", (): void => {
+  webSocket.close();  // 需手动管理 WebSocket 生命周期
+});
+useWebSocket(webSocket, "message")
+  .limit(1)
+  .toUnordered()
+  .forEach((message: MessageEvent) => console.log(message.data));
+
+// 按码点迭代字符串
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // 输出字符串
+
+// 安全地字符串化包含循环引用的对象
+let o = {
+  a: 1,
+  b: "text",
+  c: [o.a, o.b, o.c] // 循环引用
+};
+// let text: string = JSON.stringify(o); // 抛出错误
+let text: string = useStringify(o); // 安全地生成 `{a: 1, b: "text", c: []}`
+```
+
+---
+
+### 核心概念
+
+| 概念 | 目的 | 何时使用 |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | 用于异步流、事件和惰性管道的核心构建器。 | 实时事件、WebSocket、DOM 监听器、长时间运行或无限流。 |
+| `SynchronousSemantic` | 用于同步、内存中或基于循环的流的构建器。 | 静态数据、范围、立即迭代。 |
+| `toUnordered()` | 最快的终结收集器（基于 Map 的索引）。 | 性能关键路径（O(n) 时间与空间，无排序）。 |
+| `toOrdered()` | 有序的、索引稳定的收集器。 | 当需要稳定排序或索引访问时。 |
+| `toNumericStatistics()` | 丰富的数值统计分析（均值、中位数、方差、偏度、峰度等）。 | 数据分析和统计计算。 |
+| `toBigIntStatistics()` | 丰富的 bigint 统计分析。 | 针对大整数的数据分析和统计计算。 |
+| `toWindow()` | 滑动和滚动窗口支持。 | 时间序列处理、批处理和窗口化操作。 |
+
+---
+
+**重要使用规则**
+
+1.  **事件流**（`useWindow`、`useDocument`、`useHTMLElement`、`useWebSocket`……）返回一个 `AsynchronousSemantic`。
+    → 您**必须**调用 `.limit(n)`、`.sub(start, end)` 或 `.takeWhile()` 来停止监听。否则，监听器将保持活动状态。
+
+2.  **终结操作**（`.toArray()`、`.count()`、`.average()`、`.reduce()`、`.findFirst()` 等）**仅在**转换为收集器**之后**可用：
+    ```typescript
+    .toUnordered()   // O(n) 时间与空间，无排序
+    // 或
+    .toOrdered()     // 已排序，保持顺序
+    ```
+
+---
+
+### 性能特征
+
+| 收集器 | 时间复杂度 | 空间复杂度 | 是否排序？ | 最佳适用场景 |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | 否 | 追求原始速度，顺序不重要时。 |
+| `toOrdered()` | O(2n) | O(n) | 是 | 需要稳定排序、索引访问或分析时。 |
+| `toNumericStatistics()` | O(2n) | O(n) | 是 | 需要排序数据的统计操作。 |
+| `toBigIntStatistics()` | O(2n) | O(n) | 是 | 针对 bigint 的统计操作。 |
+| `toWindow()` | O(2n) | O(n) | 是 | 基于时间的窗口化操作。 |
+
+当速度至上时，选择 `toUnordered()`。仅当您需要稳定排序或依赖于排序数据的统计方法时，才使用 `toOrdered()`。
+
+---
+
+**与其他前端流处理器的对比**
+
+| 特性 | Semantic-TypeScript | RxJS | 原生 Async Iterators / Generators | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **TypeScript 集成** | 一流的深度类型支持，具备原生索引感知。 | 优秀，但涉及复杂的泛型。 | 良好，需要手动类型标注。 | 强大，函数式优先风格。 |
+| **内置统计分析** | 对 `number` 和 `bigint` 的全面原生支持。 | 非原生支持（需要自定义操作符）。 | 无。 | 无。 |
+| **索引与位置感知** | 原生、强大的每个元素 bigint 索引。 | 需要自定义操作符（`scan`、`withLatestFrom`）。 | 需要手动计数器。 | 基础，无内置索引。 |
+| **事件流管理** | 专用的、类型安全的工厂函数，具备显式的提前停止控制。 | 强大但需要手动管理订阅。 | 手动事件监听器 + 取消。 | 良好的 `fromEvent`，轻量。 |
+| **性能与内存效率** | 卓越——优化的 `toUnordered()` 和 `toOrdered()` 收集器。 | 非常好，但操作符链会带来开销。 | 优秀（零开销）。 | 优秀。 |
+| **包体积** | 非常轻量。 | 较大（即使进行 Tree Shaking）。 | 零（原生）。 | 小。 |
+| **API 设计理念** | 函数式收集器模式，具有显式索引。 | 响应式 Observable 模式。 | 迭代器 / 生成器模式。 | 函数式，无点风格。 |
+| **提前终止与控制** | 显式（`interrupt`、`.limit()`、`.takeWhile()`、`.sub()`）。 | 良好（`take`、`takeUntil`、`first`）。 | 手动（在 `for await…of` 中使用 `break`）。 | 良好（`take`、`until`）。 |
+| **同步与异步支持** | 统一的 API——对两者都提供一流支持。 | 主要是异步。 | 两者都支持，但需手动处理。 | 主要是异步。 |
+| **学习曲线** | 对于熟悉函数式和索引管道的开发者来说很平缓。 | 较陡峭（众多操作符、热/冷 Observable）。 | 低。 | 中等。 |
+
+**Semantic-TypeScript 的主要优势**
+
+*   独特的内置统计和索引功能，无需手动 `reduce` 或外部库。
+*   对事件流的显式控制，防止了 RxJS 中常见的内存泄漏。
+*   统一的同步/异步设计，为多样化的用例提供了单一、一致的 API。
+
+此对比说明了为何 Semantic-TypeScript 特别适合那些需要高性能、类型安全和丰富分析功能，而又不希望陷入传统响应式库繁琐仪式感的现代 TypeScript 前端应用。
+
+---
+
+### 准备探索？
+
+Semantic-TypeScript 将复杂的数据流转化为可读、可组合且高性能的管道。无论您是处理实时 UI 事件、处理大型数据集还是构建分析仪表板，它都能提供数据库级索引的强大功能与函数式编程的优雅。
+
+**下一步：**
+
+*   在您的 IDE 中浏览完整的类型化 API（所有导出均来自主包）。
+*   加入不断壮大的开发者社区，他们已用清晰的 Semantic 管道取代了复杂的异步迭代器。
+
+**Semantic-TypeScript** — 流与结构的交汇点。
+
+立即开始构建，体验精心设计的索引所带来的不同。
+
+**构建清晰，运行自信，让数据流转尽在掌控。**