semantic-typescript 0.5.3 → 0.6.0

package/readme.ru.md

@@ -1,470 +1,205 @@
-# Библиотека потоковой обработки Semantic-TypeScript
+# Semantic-TypeScript: Библиотека потоковой обработки, меняющая парадигму
 
 ## Введение
+Semantic-TypeScript представляет собой значительный прогресс в технологии потоковой обработки, синтезируя наиболее эффективные концепции из JavaScript GeneratorFunctions, Java Streams и парадигм индексации баз данных. Его фундаментальный принцип проектирования сосредоточен на построении исключительно эффективных конвейеров обработки данных с помощью сложных вычислений с отложенным выполнением (lazy evaluation) и интеллектуальной индексации. Библиотека предоставляет строго типобезопасный, функционально чистый опыт работы с потоками, специально созданный для современной разработки на TypeScript и JavaScript.
 
-Semantic-TypeScript — это современная библиотека потоковой обработки, вдохновленная JavaScript GeneratorFunction, Java Stream и индексами MySQL. Её основная концепция дизайна основана на создании эффективных конвейеров обработки данных с использованием индексации данных, предоставляя типобезопасный, функциональный стиль операций потоков для разработки фронтенда.
+В отличие от традиционных синхронных архитектур обработки, Semantic-TypeScript реализует унифицированную модель, которая изящно обрабатывает как синхронные (Iterable), так и асинхронные (AsyncIterable) источники данных. Во время генерации потока поток и завершение данных точно контролируются механизмами обратных вызовов (callback), что позволяет библиотеке исключительно элегантно обрабатывать:
+*   Потоки данных в реальном времени (события DOM, WebSockets, интервалы) с детерминированным управлением
+*   Большие наборы данных с помощью эффективных по памяти, "ленивых" (lazy) конвейеров
+*   Сложные преобразования данных с помощью беглого, декларативного API
 
-В отличие от традиционной синхронной обработки, Semantic использует асинхронную модель обработки. При создании потока данных время, когда терминал получает данные, полностью зависит от того, когда вверх по потоку вызываются функции обратного вызова `accept` и `interrupt`. Этот дизайн позволяет библиотеке изящно обрабатывать потоки реального времени, большие наборы данных и асинхронные источники данных.
+Инновационный подход библиотеки фундаментально переосмысливает то, как разработчики взаимодействуют с последовательностями данных, предоставляя как беспрецедентные характеристики производительности, так и эргономику для разработчиков в едином, целостном пакете.
 
-## Установка
+## Основная философия: разделение определения и выполнения
+Ключевая архитектурная идея Semantic-TypeScript — это четкое разделение между определением потока и его выполнением:
+*   **Semantic<E>**: неизменяемый, "ленивый" (lazy) план конвейера преобразования данных. Он определяет, какие операции (filter, map и т.д.) будут выполнены.
+*   **Collectable<E>**: материализованное, исполняемое представление потока. Получается из Semantic и предоставляет все терминальные операции (collect, forEach и т.д.) для выполнения конвейера и получения результата.
 
-```bash
-npm install semantic-typescript
-```
+Это разделение обеспечивает четкую ментальную модель и открывает возможность мощных оптимизаций, таких как выбор UnorderedCollectable для пропуска ненужной сортировки для максимальной скорости.
 
-## Основные типы
-
-| Тип | Описание |
-|------|-------------|
-| `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>` | Функция одного параметра для преобразования |
-| `BiFunctional<T, U, R>` | Функция двух параметров для преобразования |
-| `TriFunctional<T, U, V, R>` | Функция трех параметров для преобразования |
-| `Predicate<T>` | Функция одного параметра для утверждения |
-| `BiPredicate<T, U>` | Функция двух параметров для утверждения |
-| `TriPredicate<T, U, V>` | Функция трех параметров для утверждения |
-| `Consumer<T>` | Функция одного параметра для потребления |
-| `BiConsumer<T, U>` | Функция двух параметров для потребления |
-| `TriConsumer<T, U, V>` | Функция трех параметров для потребления |
-| `Comparator<T>` | Функция двух параметров для сравнения |
-| `Generator<T>` | Функция генератора (основа и фундамент) |
+## Почему стоит выбрать Semantic-TypeScript?
+Выбор подходящей библиотеки для обработки потоков данных предполагает баланс между производительностью, типобезопасностью и выразительностью. Semantic-TypeScript создан для превосходства по всем этим параметрам.
 
-```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;
-```
+### 1. Унифицированная, типобезопасная парадигма для всех последовательностей данных
+Он предоставляет единый, декларативный API для обработки любой последовательности данных — будь то статические массивы, события в реальном времени или асинхронные фрагменты (chunks) — при этом используя всю мощь TypeScript для обеспечения сквозной типобезопасности. Это устраняет целый класс ошибок времени выполнения и превращает манипуляции с потоками в предсказуемую, проверяемую компилятором деятельность.
 
-## Типовые защитники
-
-| Функция | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `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` | Проверить, является ли это символом | 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) |
-| `isPromise(t: unknown): t is Promise<unknown>` | Проверить, является ли это объектом Promise | O(1) | O(1) |
-| `isAsync(t: unknown): t is AsyncFunction` | Проверить, является ли это AsyncFunction | O(1) | O(1) |
+### 2. Непреклонная производительность с интеллектуальной "ленивостью" (Laziness)
+В своей основе библиотека построена на отложенном выполнении (lazy evaluation). Операции, такие как filter, map и flatMap, лишь составляют конвейер обработки; никакая работа не выполняется до тех пор, пока не будет вызвана терминальная операция. Это сочетается с возможностями короткого замыкания (short-circuiting) (через limit, anyMatch или пользовательские прерывающие обратные вызовы), что позволяет остановить обработку досрочно, значительно повышая эффективность для больших или бесконечных потоков.
 
-```typescript
-// Примеры использования типовых защитников
-let value: unknown = "hello";
+### 3. Сила паттерна `Collector<E, A, R>`
+Вдохновленный Java, паттерн Collector — это двигатель гибкости. Он отделяет спецификацию того, как накапливать элементы потока, от самого выполнения потока. Библиотека предоставляет богатый набор встроенных коллекторов (collectors) (toArray, groupBy, summate и т.д.) для повседневных задач, позволяя при этом с легкостью реализовывать собственную сложную, повторно используемую логику свёртки (reduction). Это намного мощнее и композируемее, чем фиксированный набор терминальных методов.
 
-if (isString(value)) {
-    console.log(value.length); // Типобезопасно, значение выводится как строка
-}
-
-if (isOptional(someValue)) {
-    someValue.ifPresent((value): void => console.log(val));
-}
-
-if(isIterable(value)){
-    // Типобезопасно, теперь это итерируемый объект.
-    for(let item of value){
-        console.log(item);
-    }
-}
-```
+### 4. Поддержка современного веба и асинхронных данных "из коробки"
+Semantic-TypeScript создан для современной разработки. Он предлагает нативные фабричные методы для современных веб-источников:
+*   `useFrom(iterable)`, `useRange()` для статических данных
+*   `useInterval()`, `useAnimationFrame()` для потоков, основанных на времени
+*   `useBlob()` для обработки бинарных данных фрагментами (chunked)
+*   `useWebSocket()`, `useDocument()`, `useWindow()` для потоков событий в реальном времени
 
-## Утилитные функции
+### 5. За пределами базовой агрегации: встроенный статистический анализ
+Выходите за рамки простых сумм и средних значений. Библиотека предоставляет специальные интерфейсы NumericStatistics и BigIntStatistics, предлагая немедленный доступ к расширенным статистическим показателям напрямую из ваших потоков — дисперсия, стандартное отклонение, медиана, асимметрия (skewness) и эксцесс (kurtosis). Это превращает сложный анализ данных в однострочник.
 
-| Функция | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `useCompare<T>(t1: T, t2: T): number` | Обобщенная функция сравнения | O(1) | O(1) |
-| `useRandom<T = number \| bigint>(index: T): T` | Генератор псевдослучайных чисел | O(log n) | O(1) |
+### 6. Спроектирован с учетом эргономики разработчика
+*   **Беглый, цепочечный (chainable) API**: Пишите сложные конвейеры данных в виде читаемых, последовательных цепочек.
+*   **Комплексный набор утилит**: Включены основные защиты (isFunction, isIterable), утилиты (useCompare, useTraverse) и функциональные интерфейсы.
+*   **Интеграция с Optional&lt;T&gt;**: Безопасно моделирует отсутствие значения, устраняя проблемы с нулевыми указателями (null-pointer).
+*   **Рекомендации по производительности**: Четкие указания, когда использовать неупорядоченную (unordered) коллекцию для скорости, а когда упорядоченную (ordered) для последовательности.
 
-```typescript
-// Примеры использования утилитных функций
-let numbers: Array<number> = [3, 1, 4, 1, 5];
-numbers.sort(useCompare); // [1, 1, 3, 4, 5]
-
-let randomNum = useRandom(42); // Случайное число на основе семени
+## Установка
+```bash
+npm install semantic-typescript
 ```
 
-## Фабричные методы
-
-### Методы фабрики 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) |
+## Основные концепции на практике
 
+### 1. Создание потоков (Semantic)
+Потоки можно создавать из различных источников с помощью фабричных функций.
 ```typescript
-// Примеры использования Optional
-let empty: Optional<number> = Optional.empty();
-let present: Optional<number> = Optional.of(42);
-let nullable: Optional<string> = Optional.ofNullable<string>(null);
-let nonNull: Optional<string> = Optional.ofNonNull("hello");
-
-presentOpt.ifPresent((val: number): void => console.log(val)); // Выводит 42
-console.log(emptyOpt.get(100)); // Выводит 100
-```
+import { useFrom, useInterval, useDocument } from 'semantic-typescript';
 
-### Методы фабрики Collector
+// Из статического массива
+const staticStream = useFrom([1, 2, 3, 4, 5]);
 
-| Метод | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `Collector.full(identity, accumulator, finisher)` | Создание полного коллектора | O(1) | O(1) |
-| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Создание прерываемого коллектора | O(1) | O(1) |
+// Из асинхронного генератора
+const asyncStream = useFrom(async function*() {
+  yield 1;
+  yield 2;
+});
 
-```typescript
-// Примеры преобразования коллекторов
-let numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
-
-// Приоритет производительности: использование неупорядоченного коллектора для лучшей производительности
-let unordered = numbers
-    .filter((n: number): boolean => n > 3)
-    .toUnordered(); // Лучшая производительность
-
-// Необходимость в сортировке: использование упорядоченного коллектора
-let ordered = numbers.sorted();
-
-// Подсчет элементов
-let count = Collector.full(
-    (): number => 0, // Начальное значение
-    (accumulator: number, element: number): number => accumulator + element, // Аккумуляция
-    (accumulator: number): number => accumulator // Завершение
-);
-count.collect(from([1,2,3,4,5])); // Подсчет из потока
-count.collect([1,2,3,4,5]); // Подсчет из итерируемого объекта
-
-let find = 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 // Завершение
-);
-find.collect(from([1,2,3,4,5])); // Находит первый элемент
-find.collect([1,2,3,4,5]); // Находит первый элемент
-```
+// Поток на основе времени
+const tickStream = useInterval(1000); // испускает значение каждую секунду
 
-### Методы фабрики Semantic
-
-| Метод | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `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) |
-
-```typescript
-// Примеры использования фабричных методов Semantic
-
-// Создание потока из Blob (чтение блоками)
-blob(someBlob, 1024n)
-    .toUnordered()
-    .write(WritableStream)
-    .then(callback) // Успешная запись потока
-    .catch(callback); // Ошибка записи потока
-
-// Создание пустого потока, который не будет выполнен до объединения с другими потоками
-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): boolean => event.type === "message") // Слушать только сообщения
-  .toUnordered() // Обычно события неупорядочены
-  .forEach((event): void => receive(event)); // Получение сообщений
+// Поток событий DOM (см. важное примечание ниже)
+const clickStream = useDocument('click');
 ```
 
-## Методы класса 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) |
-
+### 2. Преобразование потоков (Промежуточные операции)
+Операции лениво объединяются в цепочку для определения конвейера.
 ```typescript
-// Примеры операций 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 элементов
-    .toUnordered() // Преобразование в неупорядоченный коллектор
-    .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(); // Преобразование в массив
+const processedStream = staticStream
+  .filter(x => x % 2 === 0) // Оставляем только четные числа
+  .map(x => x * 10)         // Умножаем на 10
+  .flatMap(x => [x, x + 1]) // Преобразуем каждый элемент в два
+  .distinct();              // Удаляем дубликаты
+// Пока ничего не было выполнено
 ```
 
-## Методы преобразования Semantic
-
-| Метод | Описание | Временная сложность | Пространственная сложность |
-|------------|------------|------------|------------|
-| `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) |
-
+### 3. Выполнение потоков (Терминальные операции)
+Чтобы получить результат, вы должны получить Collectable и вызвать терминальную операцию.
 ```typescript
-// Примеры преобразований
-from([6, 4, 3, 5, 2]) // Создание потока
-    .sorted() // Сортировка потока по возрастанию
-    .toArray(); // [2, 3, 4, 5, 6]
-
-from([6, 4, 3, 5, 2]) // Создание потока
-    .soted((a, b) => b - a) // Сортировка потока по убыванию
-    .toArray(); // [6, 5, 4, 3, 2]
-
-from([6, 4, 3, 5, 2]) // Создание потока
-    .redirect((element, index) => -index) // Перенаправление в обратном порядке
-    .toOrderd() // Сохранение перенаправленного порядка
-    .toArray(); // [2, 5, 3, 4, 6]
-
-from([6, 4, 3, 5, 2]) // Создание потока
-    .redirect((element, index) => -index) // Перенаправление в обратном порядке
-    .toUnorderd() // Игнорирование перенаправления. Эта операция игнорирует `redirect`, `reverse`, `shuffle` и `translate`
-    .toArray(); // [2, 5, 3, 4, 6]
-
-from([6, 4, 3, 5, 2]) // Создание потока
-    .reverse() // Обращение потока
-    .toOrdered() // Гарантия обращенного порядка
-    .toArray(); // [2, 5, 3, 4, 6]
-
-from([6, 4, 3, 5, 2]) // Создание потока
-    .shuffle() // Перемешивание потока
-    .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(); // Преобразование в числовую статистику
-
-from([6n, 4n, 3n, 5n, 2n]) // Создание потока
-    .toBigintStatistics(); // Преобразование в статистику BigInt
-
-// Определение настраиваемого коллектора для сбора данных
-let customizedCollector = from([1, 2, 3, 4, 5])
-    .toCollectable((generator: Generator<E>) => new CustomizedCollector(generator));
+// Получаем неупорядоченный 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
+);
 ```
 
-## Методы сбора 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)` | Преобразование в карту | O(n) | O(n) |
-| `toSet()` | Преобразование в множество | O(n) | O(n) |
-| `write(stream)` | Запись в поток | O(n) | O(1) |
-
+### 4. Важно: Работа с потоками событий
+Потоки событий (useDocument, useWindow, useHTMLElement, useWebSocket) по своей природе бесконечны. Вы должны использовать операции, такие как sub, takeWhile или limit, чтобы определить, когда прекратить сбор событий и завершить поток. В противном случае терминальная операция будет ждать неопределенно долго.
 ```typescript
-// Примеры операций 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 ? "большой" : "маленький", n => n * 2); // {маленький: [4, 8], большой: [12, 16, 20]}
-
-// Операции уменьшения
-const sum = data.reduce(0, (acc, n) => acc + n); // 30
-
-// Операции вывода
-data.join(", "); // "[2, 4, 6, 8, 10]"
+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-based)
+const specificClicks = await useDocument('click')
+  .sub(2n, 6n) // <- Берет элементы с индексами 2, 3, 4, 5
+  .toUnordered()
+  .toArray();
 ```
+**Ключевое понимание**: Событие (например, MouseEvent) и его порядковый индекс срабатывания (в виде bigint) передаются вместе через конвейер с помощью обратного вызова `accept(event, index)`.
 
-## Методы статистического анализа
-
-### Методы 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) |
-
+### 5. Использование статистики
 ```typescript
-// Примеры статистического анализа
-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
-```
+const numericStream = useFrom([10, 20, 30, 40, 50]).toNumeric();
 
-## Руководство по выбору производительности
-
-### Выбор неупорядоченного коллектора (приоритет производительности)
-```typescript
-// Когда не требуется гарантия порядка, используйте неупорядоченный коллектор для лучшей производительности
-let highPerformance = data
-    .filter(predicate)
-    .map(mapper)
-    .toUnordered(); // Лучшая производительность
-```
+const average = await numericStream.average();
+const median = await numericStream.median();
+const standardDeviation = await numericStream.standardDeviation();
+const skewness = await numericStream.skewness();
 
-### Выбор упорядоченного коллектора (требуется порядок)
-```typescript
-// Когда необходимо сохранить порядок элементов, используйте упорядоченный коллектор
-let ordered = data.sorted(comparator);
+console.log(`Среднее: ${average}, Медиана: ${median}, Стандартное отклонение: ${standardDeviation}`);
 ```
 
-### Выбор оконного коллектора (оконные операции)
+## Основные возможности
+*   **Двойные типы потоков**: Полная поддержка как 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
-// Когда требуются оконные операции
-let windowed: WindowCollectable<number> = data
-    .toWindow()
-    .slide(5n, 2n); // Скользящее окно
-```
+import { useFrom, useSummate, useGroupBy } from 'semantic-typescript';
 
-### Выбор статистического анализа (числовые вычисления)
-```typescript
-// Когда требуется статистический анализ
-let statistics: NumericStatistics<number> = data
-    .toNumericStatistics(); // Числовая статистика
+interface Transaction {
+  id: number;
+  amount: number;
+  category: string;
+}
 
-let bigIntStatistics: BigintStatistics<bigint> = data
-    .toBigintStatistics(); // Статистика больших целых чисел
+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 }
 ```
 
-[GitHub](https://github.com/eloyhere/semantic-typescript)
-[NPMJS](https://www.npmjs.com/package/semantic-typescript)
-
-## Важные замечания
-
-1. **Влияние операций сортировки**: В упорядоченных коллекторах операция `sorted()` переопределяет эффекты `redirect`, `translate`, `shuffle`, `reverse`.
-2. **Рассмотрение производительности**: Если не требуется гарантия порядка, предпочтение следует отдавать использованию `toUnordered()` для улучшения производительности.
-3. **Использование памяти**: Операции сортировки требуют дополнительного пространства O(n).
-4. **Реальное время**: Потоки Semantic подходят для обработки данных в реальном времени и поддерживают асинхронные источники данных.
+Semantic-TypeScript создан для разработчиков, которые ищут тщательно спроектированную, типобезопасную и высокопроизводительную библиотеку для потоковой обработки данных. Он привносит мощь шаблонов преобразования данных уровня предприятия в экосистему TypeScript, идеально подходящую для насыщенных данными фронтенд-приложений, обработки данных в Node.js и любого сценария, где требуется элегантная и эффективная обработка последовательностей.
 
-Эта библиотека предоставляет разработчикам TypeScript мощные и гибкие возможности потоковой обработки, сочетая преимущества функционального программирования с гарантиями типобезопасности.
+[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript)