semantic-typescript 0.6.0 → 0.7.1

package/readme.ru.md

@@ -1,205 +1,267 @@
-# Semantic-TypeScript: Библиотека потоковой обработки, меняющая парадигму
+# **Semantic‑TypeScript**
+**Потоки, индексированные.** Ваши данные под точным контролем.
 
-## Введение
-Semantic-TypeScript представляет собой значительный прогресс в технологии потоковой обработки, синтезируя наиболее эффективные концепции из JavaScript GeneratorFunctions, Java Streams и парадигм индексации баз данных. Его фундаментальный принцип проектирования сосредоточен на построении исключительно эффективных конвейеров обработки данных с помощью сложных вычислений с отложенным выполнением (lazy evaluation) и интеллектуальной индексации. Библиотека предоставляет строго типобезопасный, функционально чистый опыт работы с потоками, специально созданный для современной разработки на TypeScript и JavaScript.
+---
 
-В отличие от традиционных синхронных архитектур обработки, Semantic-TypeScript реализует унифицированную модель, которая изящно обрабатывает как синхронные (Iterable), так и асинхронные (AsyncIterable) источники данных. Во время генерации потока поток и завершение данных точно контролируются механизмами обратных вызовов (callback), что позволяет библиотеке исключительно элегантно обрабатывать:
-*   Потоки данных в реальном времени (события DOM, WebSockets, интервалы) с детерминированным управлением
-*   Большие наборы данных с помощью эффективных по памяти, "ленивых" (lazy) конвейеров
-*   Сложные преобразования данных с помощью беглого, декларативного API
+### Обзор
 
-Инновационный подход библиотеки фундаментально переосмысливает то, как разработчики взаимодействуют с последовательностями данных, предоставляя как беспрецедентные характеристики производительности, так и эргономику для разработчиков в едином, целостном пакете.
+Semantic‑TypeScript представляет значительный шаг вперёд в обработке потоков, элегантно **синтезируя** наиболее эффективные парадигмы из генераторов JavaScript, потоков Java и индексации в стиле MySQL. Его фундаментальная предпосылка одновременно мощна и продумана: создавать исключительно эффективные конвейеры обработки данных с помощью интеллектуальной индексации, а не посредством обычного полного перебора.
 
-## Основная философия: разделение определения и выполнения
-Ключевая архитектурная идея Semantic-TypeScript — это четкое разделение между определением потока и его выполнением:
-*   **Semantic<E>**: неизменяемый, "ленивый" (lazy) план конвейера преобразования данных. Он определяет, какие операции (filter, map и т.д.) будут выполнены.
-*   **Collectable<E>**: материализованное, исполняемое представление потока. Получается из Semantic и предоставляет все терминальные операции (collect, forEach и т.д.) для выполнения конвейера и получения результата.
+В то время как типичные библиотеки навязывают синхронные циклы или громоздкие цепочки обещаний (Promise), Semantic‑TypeScript предоставляет **полностью асинхронный**, функционально чистый и строго типобезопасный опыт, разработанный специально для требований современной разработки приложений.
 
-Это разделение обеспечивает четкую ментальную модель и открывает возможность мощных оптимизаций, таких как выбор UnorderedCollectable для пропуска ненужной сортировки для максимальной скорости.
+Эта модель воплощает утончённую форму управления потоком данных: данные передаются потребителю ниже по течению только тогда, когда вышестоящий конвейер явно вызывает обратный вызов `accept`. Вы сохраняете полный, детальный контроль над моментом обработки — она происходит именно тогда и только тогда, когда это необходимо.
 
-## Почему стоит выбрать Semantic-TypeScript?
-Выбор подходящей библиотеки для обработки потоков данных предполагает баланс между производительностью, типобезопасностью и выразительностью. Semantic-TypeScript создан для превосходства по всем этим параметрам.
+---
 
-### 1. Унифицированная, типобезопасная парадигма для всех последовательностей данных
-Он предоставляет единый, декларативный API для обработки любой последовательности данных — будь то статические массивы, события в реальном времени или асинхронные фрагменты (chunks) — при этом используя всю мощь TypeScript для обеспечения сквозной типобезопасности. Это устраняет целый класс ошибок времени выполнения и превращает манипуляции с потоками в предсказуемую, проверяемую компилятором деятельность.
+### Почему разработчики выбирают Semantic‑TypeScript
 
-### 2. Непреклонная производительность с интеллектуальной "ленивостью" (Laziness)
-В своей основе библиотека построена на отложенном выполнении (lazy evaluation). Операции, такие как filter, map и flatMap, лишь составляют конвейер обработки; никакая работа не выполняется до тех пор, пока не будет вызвана терминальная операция. Это сочетается с возможностями короткого замыкания (short-circuiting) (через limit, anyMatch или пользовательские прерывающие обратные вызовы), что позволяет остановить обработку досрочно, значительно повышая эффективность для больших или бесконечных потоков.
+-   **Индексация без шаблонного кода** – Каждый элемент по своей природе обладает своим естественным или кастомным индексом, что устраняет необходимость ручного отслеживания.
+-   **Чисто функциональный и типобезопасный** – Наслаждайтесь полным, идиоматическим выводом типов TypeScript вместе с неизменяемыми операциями.
+-   **Потоки событий без утечек** – Паттерн `useSubscription` разработан с безопасностью ресурсов в качестве первого принципа. Вы определяете логическую границу — используя `limit(n)`, `sub(start, end)` или `takeWhile(predicate)` — а библиотека полностью управляет жизненным циклом подписки. Это гарантирует отсутствие зависших слушателей и утечек памяти.
+-   **Встроенный статистический набор** – Получайте доступ к комплексному анализу для потоков как `number`, так и `bigint`, включая средние значения, медианы, моду, дисперсию, асимметрию (скошенность) и эксцесс, без внешних зависимостей.
+-   **Предсказуемая, настраиваемая производительность** – Выбирайте между упорядоченными или неупорядоченными сборщиками в соответствии с вашими точными требованиями к производительности и порядку.
+-   **Внутренне эффективно по памяти** – Потоки вычисляются лениво, обрабатывая элементы по требованию, чтобы снизить нагрузку на память.
+-   **Никакого неопределённого поведения** – TypeScript гарантирует полную типобезопасность и null-безопасность. Ваши исходные данные остаются неизменными, если не модифицированы явно в ваших функциях обратного вызова.
 
-### 3. Сила паттерна `Collector<E, A, R>`
-Вдохновленный Java, паттерн Collector — это двигатель гибкости. Он отделяет спецификацию того, как накапливать элементы потока, от самого выполнения потока. Библиотека предоставляет богатый набор встроенных коллекторов (collectors) (toArray, groupBy, summate и т.д.) для повседневных задач, позволяя при этом с легкостью реализовывать собственную сложную, повторно используемую логику свёртки (reduction). Это намного мощнее и композируемее, чем фиксированный набор терминальных методов.
+---
 
-### 4. Поддержка современного веба и асинхронных данных "из коробки"
-Semantic-TypeScript создан для современной разработки. Он предлагает нативные фабричные методы для современных веб-источников:
-*   `useFrom(iterable)`, `useRange()` для статических данных
-*   `useInterval()`, `useAnimationFrame()` для потоков, основанных на времени
-*   `useBlob()` для обработки бинарных данных фрагментами (chunked)
-*   `useWebSocket()`, `useDocument()`, `useWindow()` для потоков событий в реальном времени
+### Установка
 
-### 5. За пределами базовой агрегации: встроенный статистический анализ
-Выходите за рамки простых сумм и средних значений. Библиотека предоставляет специальные интерфейсы NumericStatistics и BigIntStatistics, предлагая немедленный доступ к расширенным статистическим показателям напрямую из ваших потоков — дисперсия, стандартное отклонение, медиана, асимметрия (skewness) и эксцесс (kurtosis). Это превращает сложный анализ данных в однострочник.
+Интегрируйте Semantic‑TypeScript в ваш проект с помощью предпочитаемого менеджера пакетов:
 
-### 6. Спроектирован с учетом эргономики разработчика
-*   **Беглый, цепочечный (chainable) API**: Пишите сложные конвейеры данных в виде читаемых, последовательных цепочек.
-*   **Комплексный набор утилит**: Включены основные защиты (isFunction, isIterable), утилиты (useCompare, useTraverse) и функциональные интерфейсы.
-*   **Интеграция с Optional&lt;T&gt;**: Безопасно моделирует отсутствие значения, устраняя проблемы с нулевыми указателями (null-pointer).
-*   **Рекомендации по производительности**: Четкие указания, когда использовать неупорядоченную (unordered) коллекцию для скорости, а когда упорядоченную (ordered) для последовательности.
-
-## Установка
 ```bash
 npm install semantic-typescript
 ```
+или
+```bash
+yarn add semantic-typescript
+```
 
-## Основные концепции на практике
+---
+
+### Практическое введение
+
+Следующие примеры демонстрируют ключевые концепции, от базовых преобразований до обработки событий в реальных условиях.
 
-### 1. Создание потоков (Semantic)
-Потоки можно создавать из различных источников с помощью фабричных функций.
 ```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
+import { useOf, useFrom, useRange, useSubscription, useText, useStringify } from "semantic-typescript";
+
+// ====================================================================
+// ПРИМЕР 1: Базовые операции и числовая статистика
+// ====================================================================
+// Демонстрирует операции отображения (map) и терминальные статистические операции. После преобразования конвейер должен быть преобразован в сборщик статистики, прежде чем можно будет вызывать терминальные методы, такие как `.summate()`.
+
+const numericSum: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)        // Удваивает каждый элемент: [20, 40, 60, 80]
+  .toNumericStatistics()                    // Преобразует в сборщик статистики
+  .summate();                               // Терминальная операция: 200
+
+// Другие статистические методы (доступны после `.toNumericStatistics()`):
+// .average(), .median(), .mode(), .variance(), .skewness(), .kurtosis()
+
+// ====================================================================
+// ПРИМЕР 2: Статистика BigInt
+// ====================================================================
+// Работает идентично числовой статистике, но оптимизирован для данных BigInt.
+
+const bigintSum: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2n)       // Арифметика BigInt
+  .toBigIntStatistics()                     // Преобразует в сборщик статистики BigInt
+  .summate();                               // Терминальная операция: 200n
+
+// ====================================================================
+// ПРИМЕР 3: Манипуляции с индексами для обращения потока
+// ====================================================================
+// Иллюстрирует переупорядочивание элементов путём стратегического перераспределения их индексов с помощью метода `.redirect()`, позволяя создавать пользовательские шаблоны, такие как обращение.
+
+const reversedArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .redirect((_element: number, index: bigint): bigint => -index) // Отображает на отрицательные индексы
+  .toOrdered()  // Важно: собирает элементы, отсортированные по их новым индексам
+  .toArray();   // Результат: [5, 4, 3, 2, 1]
+
+// Для простого обращения также доступен `.reverse()`.
+
+// ====================================================================
+// ПРИМЕР 4: Перемешивание (Shuffle) потока
+// ====================================================================
+// Случайным образом переставляет индексы элементов, используя алгоритм перемешивания на месте (in‑place).
+
+const shuffledArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .shuffle()      // Случайно перераспределяет индексы
+  .toOrdered()    // Сортирует по новым случайным индексам
+  .toArray();     // Например: [2, 5, 1, 4, 3] (варьируется при каждом выполнении)
+
+// ====================================================================
+// ПРИМЕР 5: Циклический сдвиг потока
+// ====================================================================
+// Циклически сдвигает элементы. Положительные значения вращают вправо; отрицательные — влево.
+
+// Вращение вправо на 2 позиции
+const rightRotated: number[] = useFrom([1, 2, 3, 4, 5])
+  .translate(2)   // Сдвигает индексы на 2 вправо
+  .toOrdered()
+  .toArray();     // Результат: [4, 5, 1, 2, 3]
+
+// ====================================================================
+// ПРИМЕР 6: Ленивое вычисление с бесконечными диапазонами
+// ====================================================================
+// Обрабатывает теоретически бесконечные потоки лениво, вычисляя элементы только тогда, когда они нужны.
+
+const firstTenMultiples: bigint[] = useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)  // Сохраняет кратные 17
+  .limit(10n)                   // Критично: останавливается после 10-го совпадения
+  .toUnordered()                // Сортировка не требуется
+  .toArray();                   // Результат: [0, 17, 34, 51, 68, 85, 102, 119, 136, 153]
+
+// Без `.limit(10n)` конвейер обработал бы все миллион элементов.
+
+// ====================================================================
+// ПРИМЕР 7: Компоновка сложного конвейера
+// ====================================================================
+// Демонстрирует последовательную композицию нескольких операций.
+
+const complexResult: number[] = useRange(1n, 100n)
+  .map(n => Number(n) * 2)
+  .filter(n => n > 50)
+  .shuffle()
+  .limit(5n)
+  .translate(2)
+  .toOrdered()
+  .toArray();
 
-// Из статического массива
-const staticStream = useFrom([1, 2, 3, 4, 5]);
+// ====================================================================
+// ПРИМЕР 8: Управляемая подписка на события DOM
+// ====================================================================
+// Прослушивает события браузера с автоматической очисткой, защищённой от утечек.
+// Вызов `.limit(n)` определяет границу для автоматического удаления слушателя.
+
+// Определяем подписчика для цели Window
+const windowSubscriber = {
+    mount: (target: Window): void => { /* Логика настройки */ },
+    subscribe: (target: Window, event: keyof WindowEventMap, handler: EventListener): void => {
+        target.addEventListener(event, handler);
+    },
+    unsubscribe: (target: Window, event: keyof WindowEventMap, handler: EventListener): void => {
+        target.removeEventListener(event, handler);
+    },
+    unmount: (): void => { /* Логика очистки */ }
+};
+
+useSubscription(window, windowSubscriber, "resize")
+  .limit(5n) // Автоматически отписывается после 5 событий
+  .toUnordered()
+  .forEach((ev: Event, idx) =>
+    console.log(`Изменение размера #${idx}: ${(ev.target as Window).innerWidth}x${(ev.target as Window).innerHeight}`)
+  );
 
-// Из асинхронного генератора
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
+// ====================================================================
+// ПРИМЕР 9: Обработка строк по кодпоинтам Unicode
+// ====================================================================
+// Корректно перебирает строку, обрабатывая многобайтовые символы Unicode.
 
-// Поток на основе времени
-const tickStream = useInterval(1000); // испускает значение каждую секунду
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // Выводит каждый символ (включая эмодзи) с новой строки.
 
-// Поток событий DOM (см. важное примечание ниже)
-const clickStream = useDocument('click');
-```
+// ====================================================================
+// ПРИМЕР 10: Безопасное строковое представление объектов с циклическими ссылками
+// ====================================================================
+// Безопасно сериализует объекты, содержащие циклические ссылки.
 
-### 2. Преобразование потоков (Промежуточные операции)
-Операции лениво объединяются в цепочку для определения конвейера.
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0) // Оставляем только четные числа
-  .map(x => x * 10)         // Умножаем на 10
-  .flatMap(x => [x, x + 1]) // Преобразуем каждый элемент в два
-  .distinct();              // Удаляем дубликаты
-// Пока ничего не было выполнено
-```
+const obj = {
+  a: 1,
+  b: "текст"
+};
+(obj as any).c = [obj.a, obj.b, (obj as any).c]; // Вводит циклическую ссылку
 
-### 3. Выполнение потоков (Терминальные операции)
-Чтобы получить результат, вы должны получить Collectable и вызвать терминальную операцию.
-```typescript
-// Получаем неупорядоченный collectable для производительности
-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
-);
+// const text: string = JSON.stringify(obj); // Выбрасывает ошибку
+const text: string = useStringify(obj); // Безопасно выдаёт `{a: 1, b: "текст", c: []}`
 ```
 
-### 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();
+| Концепция | Цель | Основной вариант использования |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | Основной построитель для асинхронных потоков, событий и ленивых конвейеров, основанных на проталкивании (push). | События в реальном времени, WebSockets, слушатели DOM или любые длительные/бесконечные потоки. |
+| `SynchronousSemantic` | Построитель для синхронных, находящихся в памяти или основанных на вытягивании (pull) немедленных (eager) потоков. | Статические данные, конечные диапазоны или задачи немедленной итерации. |
+| `toUnordered()` | Самый быстрый терминальный сборщик, использует Map для хранения индексов. | Критичные к производительности пути, где стабильный порядок не требуется (время и пространство O(n)). |
+| `toOrdered()` | Упорядоченный, стабильный по индексам терминальный сборщик. | Когда порядок элементов должен быть сохранён или требуется доступ по индексу. |
+| `toNumericStatistics()` | Сборщик, позволяющий проводить расширенный статистический анализ потоков типа `number`. | Анализ данных, метрики и статистические вычисления. |
+| `toBigIntStatistics()` | Сборщик, позволяющий проводить расширенный статистический анализ потоков типа `bigint`. | Анализ и статистика для наборов данных с большими целыми числами. |
+| `toWindow()` | Предоставляет операции скользящего (sliding) и фиксированного (tumbling) окна над потоком. | Анализ временных рядов, пакетная обработка и оконные агрегации. |
 
-// Собираем клики с индекса 2 по 5 (0-based)
-const specificClicks = await useDocument('click')
-  .sub(2n, 6n) // <- Берет элементы с индексами 2, 3, 4, 5
-  .toUnordered()
-  .toArray();
-```
-**Ключевое понимание**: Событие (например, MouseEvent) и его порядковый индекс срабатывания (в виде bigint) передаются вместе через конвейер с помощью обратного вызова `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();
+1.  **Потоки событий** (созданные через фабрики, такие как `useSubscription`) возвращают `AsynchronousSemantic`.
+    → Вы **должны** вызвать метод, определяющий границу, такой как `.limit(n)`, `.sub(start, end)` или `.takeWhile(predicate)`, чтобы завершить прослушивание. В противном случае подписка останется активной.
 
-console.log(`Среднее: ${average}, Медиана: ${median}, Стандартное отклонение: ${standardDeviation}`);
-```
+2.  **Терминальные операции** (`.toArray()`, `.count()`, `.forEach()`, `.findFirst()` и т.д.) доступны **только после** преобразования конвейера в сборщик:
+    ```typescript
+    .toUnordered()   // Для максимальной скорости, порядок не гарантируется.
+    // или
+    .toOrdered()     // Для стабильного, отсортированного вывода.
+    // или
+    .toNumericStatistics() // Для статистических методов.
+    ```
 
-## Основные возможности
-*   **Двойные типы потоков**: Полная поддержка как SynchronousSemantic (для Iterable), так и AsynchronousSemantic (для AsyncIterable и событий)
-*   **Богатый набор операций**: filter, map, flatMap, concat, distinct, sorted, limit, skip, peek, reverse, shuffle
-*   **Гибкие терминальные операции**: collect (с пользовательскими коллекторами), toArray, toSet, toMap, forEach, reduce, findFirst, anyMatch, allMatch, count
-*   **Продвинутые коллекторы**: Встроенные коллекторы для joining, groupingBy, partitioningBy, summing, averaging, maxBy, minBy
-*   **Статистический модуль**: Готовые к использованию методы для mean, median, mode, variance, standardDeviation, range, quantiles, skewness, kurtosis для числовых/bigint потоков
-*   **Вспомогательные функции**: Защитники типов (type guards) (isPromise, isAsyncIterable), компараторы (useCompare), обход (useTraverse) и хуки преобразования
-*   **Optional&lt;T&gt;**: Монадический контейнер для нулабельных значений, интегрированный с операциями поиска (find)
-
-## Обзор API
-### Основные классы и интерфейсы
-*   `Semantic<E>` / `AsynchronousSemantic<E>`: Абстрактное определение потока
-*   `Collectable<E>` / `AsynchronousCollectable<E>`: Исполняемый поток с терминальными операциями
-*   `OrderedCollectable<E>` / `UnorderedCollectable<E>`: Материализованные версии, оптимизированные для операций, чувствительных или нечувствительных к порядку
-*   `Collector<E, A, R>`: Абстракция для изменяемых (mutable) операций свёртки (reduction)
-
-### Фабричные функции (use*)
-*   **Из источников**: useFrom, useRange, useFill, useEmpty
-*   **Из времени**: useInterval, useAnimationFrame
-*   **Из веб-API**: useBlob, useDocument, useWindow, useHTMLElement, useWebSocket
-*   **Коллекторы**: useToArray, useGroupBy, useSummate, useJoin и т.д.
-
-## Примечания по производительности
-*   **Отложенное выполнение (Lazy Evaluation)**: Конвейеры составляются без выполнения до тех пор, пока не будет вызвана терминальная операция.
-*   **Короткое замыкание (Short-Circuiting)**: Операции, такие как limit, anyMatch и findFirst, остановят обработку элементов, как только результат будет определен.
-*   **Упорядоченное (Ordered) vs Неупорядоченное (Unordered)**:
-    *   Используйте `.toUnordered()` для терминальных операций, когда порядок исходных элементов не имеет значения для вашего результата (например, для sum, max или toSet). Это может позволить внутренние оптимизации, пропускающие затратные шаги сортировки.
-    *   Используйте `.toOrdered()`, когда важна последовательность (например, для toArray, где порядок должен быть сохранен).
-
-## Пример для начала работы
-```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 }
-```
+### Характеристики производительности
+
+| Сборщик | Временная сложность | Пространственная сложность | Порядок гарантирован? | Идеальный сценарий |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | Нет | Важна необработанная пропускная способность; конечный порядок не важен. |
+| `toOrdered()` | O(n log n) | O(n) | Да (отсортирован) | Стабильный порядок, доступ по индексу или предварительная сортировка для статистики. |
+| `toNumericStatistics()` | O(n log n) | O(n) | Да (внутренняя сортировка) | Выполнение статистических операций, требующих отсортированных данных. |
+| `toBigIntStatistics()` | O(n log n) | O(n) | Да (внутренняя сортировка) | Статистические операции над данными BigInt. |
+| `toWindow()` | O(n log n) | O(n) | Да (внутренняя сортировка) | Оконные операции, выигрывающие от отсортированных индексов. |
+
+Выбирайте `toUnordered()`, когда абсолютная скорость первостепенна. Выбирайте `toOrdered()` или статистический сборщик только в том случае, если ваша логика зависит от порядка элементов.
+
+---
+
+**Сравнительный анализ с современными потоковыми библиотеками**
+
+| Особенность | Semantic‑TypeScript | RxJS | Нативные Async Iterators / Generators | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **Интеграция с TypeScript** | Первоклассная, с глубокой типизацией и внутренней осведомлённостью об индексах. | Отличная, но часто связана со сложными цепочками обобщений (generics). | Хорошая, но требуются ручные аннотации типов. | Сильная, с функционально-ориентированным стилем типизации. |
+| **Встроенный статистический анализ** | Полная встроенная поддержка для `number` и `bigint`. | Недоступна нативно (требует пользовательских операторов или других библиотек). | Отсутствует. | Отсутствует. |
+| **Индексация и осведомлённость о позиции** | Встроенная, мощная индексация BigInt для каждого элемента. | Требует пользовательских операторов (напр., `scan`, `withLatestFrom`). | Требуется ручное управление счётчиком. | Базовая, без встроенного свойства индекса. |
+| **Управление потоками событий** | Специализированные, типобезопасные фабрики с явным, декларативным управлением жизненным циклом. | Мощное, но требует тщательного ручного управления подписками для предотвращения утечек. | Ручное присоединение слушателей событий и управление токенами отмены. | Хороший `fromEvent`, как правило, лёгкий. |
+| **Производительность и память** | Исключительная – предлагает оптимизированные сборщики `toUnordered()` и `toOrdered()`. | Очень хорошая, хотя глубокие цепочки операторов могут вносить накладные расходы. | Отличная (минимальные нативные накладные расходы). | Отличная. |
+| **Размер сборки (bundle)** | Очень лёгкий. | Существенный (даже с tree-shaking). | Нулевой (нативная функция языка). | Малый. |
+| **Философия дизайна API** | Функциональный паттерн сборщика с явной семантикой индексов. | Реактивный паттерн Observable. | Императивный Iterator / декларативный Generator паттерн. | Функциональный, бесточечная (point‑free) композиция. |
+| **Управление потоком** | Явное (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Хорошее (`take`, `takeUntil`, `first`). | Ручное (`break` в циклах). | Хорошее (`take`, `until`). |
+| **Поддержка синхронных и асинхронных операций** | Унифицированный API – первоклассная поддержка обеих парадигм. | В основном асинхронный. | Оба поддерживаются, но требуется ручной мост. | В основном асинхронный. |
+| **Кривая обучения** | Пологая для разработчиков, знакомых с функциональными и индексированными конвейерами коллекций. | Крутая (обширный словарь операторов, концепции горячих/холодных Observable). | Низкая до средней. | Средняя. |
+
+**Преимущество 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) 
+MIT © Eloy Kim