semantic-typescript 0.6.0 → 0.7.0

package/readme.tw.md

@@ -1,214 +1,223 @@
-# Semantic-TypeScript：一款範式轉換的串流處理函式庫
+# Semantic-TypeScript
+Flow, Indexed. Ваши данные — под точным контролем.
 
-## 簡介
-Semantic-TypeScript 代表了串流處理技術的一項重大進步，它綜合了 JavaScript GeneratorFunctions、Java Streams 和資料庫索引範式中最有效的概念。其基礎設計原則的核心是透過複雜的惰性求值和智慧索引建構極其高效的資料處理管道。該函式庫提供了一個嚴格型別安全、函數式純正的串流式操作體驗，專門為現代 TypeScript 和 JavaScript 開發而設計。
+---
 
-與傳統的同步處理架構相比，Semantic-TypeScript 實現了一個統一模型，優雅地處理同步（Iterable）和非同步（AsyncIterable）資料來源。在串流生成過程中，資料的流動和終止由回呼機制精確控制，使函式庫能夠以超凡的優雅處理：
+### Обзор
 
-- 具有確定性控制的即時資料流（DOM 事件、WebSockets、時間間隔）
-- 透過記憶體高效的惰性管道處理大規模資料集
-- 透過流暢、宣告式的 API 進行複雜的資料轉換
+Semantic-TypeScript знаменует собой значительный скачок в технологии потоковой обработки данных, синтезируя наиболее эффективные концепции из JavaScript `GeneratorFunction`, Java Streams и MySQL-стиля индексирования. Его основная философия одновременно проста и мощна: создавать исключительно эффективные конвейеры обработки данных с помощью интеллектуального индексирования, а не грубого перебора.
 
-該函式庫的創新方法從根本上重新構想了開發者與資料序列互動的方式，在一個單一、內聚的套件中同時提供了前所未有的效能特性和開發者體驗。
+В то время как обычные библиотеки навязывают синхронные циклы или громоздкие цепочки промисов, Semantic-TypeScript обеспечивает полностью асинхронный, функционально чистый и строго типобезопасный опыт, созданный для требований современной фронтенд-разработки.
 
-## 核心理念：定義與執行的分離
-Semantic-TypeScript 的一個關鍵架構洞見是清晰地分離串流的定義和執行：
+В этой элегантной модели данные доходят до потребителя только тогда, когда вышестоящий конвейер явно вызывает колбэки `accept` (и опционально `interrupt`). Вы полностью контролируете время — именно тогда, когда это необходимо.
 
-- **Semantic<E>**：一個不可變的、惰性的資料轉換管道藍圖。它定義了將執行哪些操作（過濾、映射等）
-- **Collectable<E>**：一個已實例化的、可執行的串流視圖。它是從 Semantic 獲取的，並提供所有終端操作（收集、遍歷等）來執行管道並產生結果
+---
 
-這種分離強化了清晰的心智模型，並釋放了強大的最佳化能力，例如選擇 UnorderedCollectable 來跳過不必要的排序以實現最大速度。
+### Почему разработчики выбирают его
 
-## 為什麼選擇 Semantic-TypeScript？
-為資料串流處理選擇合適的函式庫需要在效能、型別安全性和表達能力之間取得平衡。Semantic-TypeScript 的設計旨在所有這些維度上都表現出色。
+• Индексирование без шаблонного кода — каждый элемент несёт свой естественный или специально заданный индекс.
 
-### 1. 適用於所有資料序列的統一、型別安全範式
-它為處理任何資料序列（無論是靜態陣列、即時事件還是非同步區塊）提供了一致的宣告式 API，同時利用 TypeScript 的全部功能確保端到端的型別安全。這消除了一整類執行時錯誤，並將串流操作轉變為可預測的、經過編譯器驗證的活動。
+• Чистый функциональный стиль — с полным выводом типов TypeScript.
 
-### 2. 以智慧惰性求值實現的不妥協效能
-該函式庫的核心建立在惰性求值之上。諸如過濾器、映射和扁平映射等操作僅僅是組合一個處理管道；直到呼叫終端操作時，實際工作才會執行。這結合了短路功能（透過限制、任何匹配或自訂中斷回呼），允許處理提前停止，從而極大地提高了大型或無限串流的處理效率。
+• Защищённые от утечек потоковые события — `useWindow`, `useDocument`, `useHTMLElement` и `useWebSocket` созданы с учётом безопасности. Вы определяете границу — с помощью `limit(n)`, `sub(start, end)` или `takeWhile(predicate)` — а библиотека управляет очисткой. Никаких зависших слушателей, никаких утечек памяти.
 
-### 3. `Collector<E, A, R>` 模式的強大之處
-受 Java 啟發，收集器模式是靈活性的引擎。它將如何累積串流元素的規範與串流本身的執行解耦。該函式庫為日常任務提供了一組豐富的內建收集器（toArray、groupBy、summate 等），同時使實現您自己複雜的、可重用的歸約邏輯變得非常簡單。這比固定的一組終端方法要強大和可組合得多。
+• Встроенная статистика — всесторонний анализ для чисел (`number`) и больших целых (`bigint`), включая средние значения, медианы, моду, дисперсию, асимметрию и эксцесс.
 
-### 4. 對現代 Web 和非同步資料的一流支援
-Semantic-TypeScript 專為當代開發而設計。它為現代網路來源提供了原生工廠方法：
+• Предсказуемая производительность — выбирайте между упорядоченными (`ordered`) и неупорядоченными (`unordered`) коллекторами в зависимости от ваших требований.
 
-- `useFrom(iterable)`, `useRange()` 用於靜態資料
-- `useInterval()`, `useAnimationFrame()` 用於基於時間的串流
-- `useBlob()` 用於分塊二進位資料處理
-- `useWebSocket()`, `useDocument()`, `useWindow()` 用於即時事件流
+• Эффективное использование памяти — потоки вычисляются лениво, что снимает проблемы с памятью.
 
-### 5. 超越基本聚合：內建統計分析
-超越簡單的求和與平均。該函式庫提供了專用的 NumericStatistics 和 BigIntStatistics 介面，可以直接從您的串流中即時存取進階統計指標——變異數、標準差、中位數、偏度和峰度。這將複雜的資料分析變成了一行程式碼。
+• Никакого неопределённого поведения — TypeScript гарантирует типобезопасность и обработку null/undefined. Входные данные остаются неизменными, если вы явно не изменяете их в своих функциях обратного вызова.
 
-### 6. 為開發者體驗而設計
-- **流暢、可鏈式呼叫的 API**：將複雜的資料管道編寫為可讀的、順序鏈
-- **全面的工具套件**：包含必要的守衛（isFunction, isIterable）、實用程式（useCompare, useTraverse）和函數式介面
-- **Optional<T> 整合**：安全地建模值的缺失，消除了空指標的擔憂
-- **效能指南**：清楚地指導何時使用無序集合以獲得速度，何時使用有序集合以保持序列
+---
+
+### Установка
 
-## 安裝
 ```bash
 npm install semantic-typescript
 ```
+или
+```bash
+yarn add semantic-typescript
+```
 
-## 核心概念實踐
+---
 
-### 1. 建立串流 (Semantic)
-可以使用工廠函數從各種來源建立串流。
+### Быстрый старт
 
 ```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-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
+
+// Статистика для больших целых
+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();
 
-// 從靜態陣列建立
-const staticStream = useFrom([1, 2, 3, 4, 5]);
+// События изменения размера окна в реальном времени (автоматически останавливается после 5 событий)
+useWindow("resize")
+  .limit(5n)          // Критически важно для потоков событий
+  .toUnordered()
+  .forEach((ev, idx) => console.log(`Изменение размера #${idx}`));
 
-// 從非同步產生器建立
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
+// Прослушивание HTML-элемента
+// <input id="input" type="text"/>
+useHTMLElement("#input", "change")
+  .limit(1)
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
 
-// 一個基於時間的串流
-const tickStream = useInterval(1000); // 每秒發射一次
+// Прослушивание нескольких элементов и событий
+useHTMLElement("input", ["change", "keyup"])
+  .takeWhile((event: Event): boolean => validate(event))
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
 
-// 一個 DOM 事件流（參見下面的重要說明）
-const clickStream = useDocument('click');
+// Прослушивание 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: []}`
 ```
 
-### 2. 轉換串流（中間操作）
-透過鏈式惰性呼叫來定義管道。
+---
 
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0)  // 僅保留偶數
-  .map(x => x * 10)          // 乘以 10
-  .flatMap(x => [x, x + 1])  // 將每個元素轉換為兩個
-  .distinct();               // 移除重複項
+### Основные концепции
 
-// 此時尚未執行任何操作
-```
+| Концепция | Назначение | Когда использовать |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | Основной строитель для асинхронных потоков, событий и ленивых конвейеров. | События в реальном времени, WebSocket, слушатели DOM, долгие или бесконечные потоки. |
+| `SynchronousSemantic` | Строитель для синхронных, хранящихся в памяти или основанных на циклах потоков. | Статические данные, диапазоны, немедленная итерация. |
+| `toUnordered()` | Самый быстрый терминальный коллектор (индексирование на основе Map). | Критичные к производительности сценарии (O(n) время и память, без сортировки). |
+| `toOrdered()` | Упорядоченный, стабильный по индексам коллектор. | Когда требуется стабильный порядок или доступ по индексу. |
+| `toNumericStatistics()` | Богатый числовой статистический анализ (среднее, медиана, дисперсия, асимметрия, эксцесс и т.д.). | Аналитика данных и статистические вычисления. |
+| `toBigIntStatistics()` | Богатый статистический анализ для больших целых (`bigint`). | Аналитика данных и статистические вычисления для больших целых чисел. |
+| `toWindow()` | Поддержка скользящих и фиксированных окон. | Обработка временных рядов, пакетная обработка и оконные операции. |
 
-### 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 等操作來定義何時停止收集事件並完成串流。否則，終端操作將無限期等待。
+1.  Потоки событий (`useWindow`, `useDocument`, `useHTMLElement`, `useWebSocket`, …) возвращают `AsynchronousSemantic`.
+    → Вы **должны** вызвать `.limit(n)`, `.sub(start, end)` или `.takeWhile()`, чтобы прекратить прослушивание. Иначе слушатель останется активным.
 
-```typescript
-import { useDocument } from 'semantic-typescript';
+2.  Терминальные операции (`.toArray()`, `.count()`, `.average()`, `.reduce()`, `.findFirst()` и т.д.) доступны только после преобразования в коллектор:
+    ```typescript
+    .toUnordered()   // O(n) время и память, без сортировки
+    // или
+    .toOrdered()     // Отсортировано, сохраняет порядок
+    ```
 
-// 僅收集前 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();
-```
+| Коллектор | Временная сложность | Пространственная сложность | Отсортирован? | Лучше всего для |
+| :--- | :--- | :--- | :--- | :--- |
+| `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) | Да | Временные оконные операции. |
 
-**關鍵見解**：事件（例如 MouseEvent）及其順序觸發索引（作為大整數）透過 `accept(event, index)` 回呼一起在管道中傳遞。
+Выбирайте `toUnordered()`, когда важнее всего скорость. Используйте `toOrdered()` только когда вам требуется стабильный порядок или статистические методы, зависящие от отсортированных данных.
 
-### 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}`);
-```
+| Особенность | Semantic-TypeScript | RxJS | Нативные асинхронные итераторы / Генераторы | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| Интеграция с TypeScript | Первоклассная, с глубокой типизацией и встроенной осведомлённостью об индексах. | Отличная, но связана со сложными дженериками. | Хорошая, требует ручного описания типов. | Сильная, функционально-ориентированный стиль. |
+| Встроенный статистический анализ | Полная нативная поддержка для `number` и `bigint`. | Недоступен нативно (требует пользовательских операторов). | Отсутствует. | Отсутствует. |
+| Индексирование и осведомлённость о позиции | Нативное, мощное индексирование с помощью `bigint` для каждого элемента. | Требует пользовательских операторов (`scan`, `withLatestFrom`). | Требуется ручной счётчик. | Базовое, без встроенного индекса. |
+| Управление потоками событий | Специализированные, типобезопасные фабрики с явным контролем ранней остановки. | Мощное, но требует ручного управления подписками. | Ручной слушатель событий + отмена. | Хороший `fromEvent`, лёгкий. |
+| Производительность и эффективность памяти | Выдающаяся – оптимизированные коллекторы `toUnordered()` и `toOrdered()`. | Очень хорошая, но цепочки операторов добавляют накладные расходы. | Отличная (нулевые накладные расходы). | Отличная. |
+| Размер бандла | Очень лёгкий. | Большой (даже с tree-shaking). | Нулевой (нативный). | Маленький. |
+| Философия дизайна API | Функциональный паттерн коллекторов с явным индексированием. | Реактивный паттерн Observable. | Паттерн Итератор / Генератор. | Функциональный, бесточечный (`point-free`). |
+| Ранняя остановка и контроль | Явный (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Хороший (`take`, `takeUntil`, `first`). | Ручной (`break` в `for await…of`). | Хороший (`take`, `until`). |
+| Поддержка синхронных и асинхронных операций | Единый API – первоклассная поддержка обоих. | В основном асинхронный. | Оба, но ручной. | В основном асинхронный. |
+| Кривая обучения | Пологая для разработчиков, знакомых с функциональными и индексированными конвейерами. | Круче (много операторов, горячие/холодные Observable). | Низкая. | Умеренная. |
 
-## 主要特性
-- **雙流類型**：完全支援同步語意（用於 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
+
+•   Уникальные встроенные возможности статистики и индексирования, устраняющие необходимость в ручном `reduce` или внешних библиотеках.
+
+•   Явный контроль над потоками событий предотвращает утечки памяти, типичные для RxJS.
+
+•   Единый синхронный/асинхронный дизайн предоставляет единый, последовательный API для различных случаев использования.
+
+Это сравнение показывает, почему Semantic-TypeScript особенно хорошо подходит для современных TypeScript фронтенд-приложений, которые требуют производительности, типобезопасности и богатой аналитики без сложностей традиционных реактивных библиотек.
+
+---
+
+### Готовы исследовать?
+
+Semantic-TypeScript превращает сложные потоки данных в читаемые, комбинируемые и высокопроизводительные конвейеры. Обрабатываете ли вы события пользовательского интерфейса в реальном времени, обрабатываете большие наборы данных или создаёте аналитические панели — он предоставляет мощь индексирования уровня базы данных с элегантностью функционального программирования.
+
+Следующие шаги:
+
+•   Изучите полностью типизированный API в своей IDE (все экспорты из основного пакета).
+
+•   Присоединяйтесь к растущему сообществу разработчиков, заменивших запутанные асинхронные итераторы на чистые конвейеры Semantic.
+
+
+Semantic-TypeScript — где потоки встречаются со структурой.
 
-Semantic-TypeScript 是為那些尋求嚴格設計、型別安全和高效能串流處理函式庫的開發者而建構的。它將企業級資料轉換模式的力量帶入了 TypeScript 生態系統，非常適合資料密集型前端應用程式、Node.js 資料處理，以及任何需要優雅、高效處理序列的場景。
+Начните создавать сегодня и почувствуйте разницу, которую даёт продуманное индексирование.
 
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript) 
+Стройте ясно, действуйте уверенно и преобразуйте данные с намерением.