semantic-typescript 0.5.3 → 0.7.0

package/readme.ru.md

@@ -1,470 +1,224 @@
-# Библиотека потоковой обработки Semantic-TypeScript
+Перевод на русский, с учётом языковых норм, контекста и стилистических особенностей. Собственные имена не переведены:
 
-## Введение
+# Semantic-TypeScript
+Потоки данных, проиндексированные. Ваши данные под точным контролем.
 
-Semantic-TypeScript — это современная библиотека потоковой обработки, вдохновленная JavaScript GeneratorFunction, Java Stream и индексами MySQL. Её основная концепция дизайна основана на создании эффективных конвейеров обработки данных с использованием индексации данных, предоставляя типобезопасный, функциональный стиль операций потоков для разработки фронтенда.
+---
 
-В отличие от традиционной синхронной обработки, Semantic использует асинхронную модель обработки. При создании потока данных время, когда терминал получает данные, полностью зависит от того, когда вверх по потоку вызываются функции обратного вызова `accept` и `interrupt`. Этот дизайн позволяет библиотеке изящно обрабатывать потоки реального времени, большие наборы данных и асинхронные источники данных.
+### Обзор
 
-## Установка
+Semantic-TypeScript знаменует собой значительный скачок в развитии технологий обработки потоков данных, синтезируя наиболее эффективные концепции из JavaScript `GeneratorFunction`, Java Streams и индексирования в стиле MySQL. Его основная философия одновременно проста и мощна: создавайте исключительно эффективные конвейеры обработки данных с помощью интеллектуального индексирования, а не грубого перебора.
 
-```bash
-npm install semantic-typescript
-```
+Там, где обычные библиотеки навязывают синхронные циклы или громоздкие цепочки промисов, Semantic-TypeScript предлагает полностью асинхронный, функционально чистый и строго типобезопасный опыт, созданный для требований современной фронтенд-разработки.
 
-## Основные типы
-
-| Тип | Описание |
-|------|-------------|
-| `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>` | Функция генератора (основа и фундамент) |
+В этой элегантной модели данные достигают потребителя только тогда, когда вышестоящий конвейер явно вызывает коллбэки `accept` (и, опционально, `interrupt`). Вы полностью контролируете время — именно тогда, когда это необходимо.
 
-```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;
-```
+---
 
-## Типовые защитники
-
-| Функция | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `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) |
+### Почему разработчики выбирают его
 
-```typescript
-// Примеры использования типовых защитников
-let value: unknown = "hello";
-
-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);
-    }
-}
-```
+• Индексирование без шаблонного кода — каждый элемент несет свой естественный или специально созданный индекс.
 
-## Утилитные функции
+• Чистый функциональный стиль — с полным выведением типов TypeScript.
 
-| Функция | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `useCompare<T>(t1: T, t2: T): number` | Обобщенная функция сравнения | O(1) | O(1) |
-| `useRandom<T = number \| bigint>(index: T): T` | Генератор псевдослучайных чисел | O(log n) | O(1) |
+• Потоки событий без утечек — `useWindow`, `useDocument`, `useHTMLElement` и `useWebSocket` созданы с учетом безопасности. Вы задаете границу — с помощью `limit(n)`, `sub(start, end)` или `takeWhile(predicate)` — а библиотека управляет очисткой. Никаких зависших слушателей, никаких утечек памяти.
 
-```typescript
-// Примеры использования утилитных функций
-let numbers: Array<number> = [3, 1, 4, 1, 5];
-numbers.sort(useCompare); // [1, 1, 3, 4, 5]
+• Встроенная статистика — всесторонний анализ для чисел и bigint, включая средние значения, медианы, моду, дисперсию, асимметрию и эксцесс.
 
-let randomNum = useRandom(42); // Случайное число на основе семени
-```
+• Предсказуемая производительность — выбирайте между упорядоченными и неупорядоченными коллекторами в зависимости от ваших требований.
 
-## Фабричные методы
+• Эффективное использование памяти — потоки вычисляются лениво, что снимает проблемы с памятью.
 
-### Методы фабрики Optional
+• Без неопределенного поведения — TypeScript гарантирует типобезопасность и обработку null. Входные данные остаются неизменными, если явно не модифицированы в ваших функциях обратного вызова.
 
-| Метод | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `Optional.empty<T>()` | Создание пустого Optional | O(1) | O(1) |
-| `Optional.of<T>(value)` | Создание Optional с содержимым | O(1) | O(1) |
-| `Optional.ofNullable<T>(value)` | Создание потенциально пустого Optional | O(1) | O(1) |
-| `Optional.ofNonNull<T>(value)` | Создание не-пустого Optional | O(1) | O(1) |
+---
 
-```typescript
-// Примеры использования 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
+### Установка
+
+```bash
+npm install semantic-typescript
+```
+или
+```bash
+yarn add semantic-typescript
 ```
 
-### Методы фабрики Collector
+---
 
-| Метод | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `Collector.full(identity, accumulator, finisher)` | Создание полного коллектора | O(1) | O(1) |
-| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Создание прерываемого коллектора | O(1) | O(1) |
+### Быстрый старт
 
 ```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]); // Находит первый элемент
+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("Моё текущее настроение: 😊, а semantic — это 👍")
+  .toUnordered()
+  .log(); // Выводит строку
+
+// Безопасная сериализация объекта с циклическими ссылками
+let o = {
+  a: 1,
+  b: "текст",
+  c: [o.a, o.b, o.c] // Циклическая ссылка
+};
+// let text: string = JSON.stringify(o); // Выбросит ошибку
+let text: string = useStringify(o); // Безопасно возвращает `{a: 1, b: "текст", c: []}`
 ```
 
-### Методы фабрики 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)); // Получение сообщений
-```
+| Концепция | Назначение | Когда использовать |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | Основной конструктор для асинхронных потоков, событий и ленивых конвейеров. | События в реальном времени, WebSockets, слушатели DOM, долгоиграющие или бесконечные потоки. |
+| `SynchronousSemantic` | Конструктор для синхронных потоков в памяти или на основе циклов. | Статические данные, диапазоны, немедленная итерация. |
+| `toUnordered()` | Самый быстрый терминальный коллектор (индексирование на основе Map). | Критичные к производительности задачи (время и память O(n), без сортировки). |
+| `toOrdered()` | Отсортированный коллектор со стабильной индексацией. | Когда требуется стабильный порядок или доступ по индексу. |
+| `toNumericStatistics()` | Богатый числовой статистический анализ (среднее, медиана, дисперсия, асимметрия, эксцесс и т.д.). | Анализ данных и статистические вычисления. |
+| `toBigIntStatistics()` | Богатый статистический анализ для bigint. | Анализ данных и статистические вычисления для больших целых чисел. |
+| `toWindow()` | Поддержка скользящих и тайм-серийных окон. | Обработка временных рядов, пакетная обработка, оконные операции. |
 
-## Методы класса Semantic
-
-| Метод | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `concat(other)` | Объединение двух потоков | O(n) | O(1) |
-| `distinct()` | Удаление дубликатов | O(n) | O(n) |
-| `distinct(comparator)` | Удаление дубликатов с использованием компаратора | O(n²) | O(n) |
-| `dropWhile(predicate)` | Отброс элементов, удовлетворяющих условию | O(n) | O(1) |
-| `filter(predicate)` | Фильтрация элементов | O(n) | O(1) |
-| `flat(mapper)` | Плоское отображение | O(n × m) | O(1) |
-| `flatMap(mapper)` | Отображение в новый тип | O(n × m) | O(1) |
-| `limit(n)` | Ограничение количества элементов | O(n) | O(1) |
-| `map(mapper)` | Преобразование картой | O(n) | O(1) |
-| `peek(consumer)` | Просмотр элементов | O(n) | O(1) |
-| `redirect(redirector)` | Перенаправление индекса | O(n) | O(1) |
-| `reverse()` | Обращение потока | O(n) | O(1) |
-| `shuffle()` | Случайная перестановка | O(n) | O(1) |
-| `shuffle(mapper)` | Перестановка с использованием маппера | O(n) | O(1) |
-| `skip(n)` | Пропуск первых n элементов | O(n) | O(1) |
-| `sorted()` | Сортировка | O(n log n) | O(n) |
-| `sorted(comparator)` | Сортировка с использованием компаратора | O(n log n) | O(n) |
-| `sub(start, end)` | Получение подпотока | O(n) | O(1) |
-| `takeWhile(predicate)` | Получение элементов, удовлетворяющих условию | O(n) | O(1) |
-| `translate(offset)` | Перевод индекса | O(n) | O(1) |
-| `translate(translator)` | Перевод индекса с использованием транслятора | O(n) | O(1) |
+---
 
-```typescript
-// Примеры операций 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(); // Преобразование в массив
-```
+Важные правила использования
 
-## Методы преобразования Semantic
+1.  Потоки событий (`useWindow`, `useDocument`, `useHTMLElement`, `useWebSocket`, …) возвращают `AsynchronousSemantic`.
+    → Вы **должны** вызвать `.limit(n)`, `.sub(start, end)` или `.takeWhile()`, чтобы прекратить прослушивание. В противном случае слушатель останется активным.
 
-| Метод | Описание | Временная сложность | Пространственная сложность |
-|------------|------------|------------|------------|
-| `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) |
+2.  Терминальные операции (`.toArray()`, `.count()`, `.average()`, `.reduce()`, `.findFirst()` и т.д.) доступны только после преобразования в коллектор:
+    ```typescript
+    .toUnordered()   // Время и память O(n), без сортировки
+    // или
+    .toOrdered()     // Отсортирован, сохраняет порядок
+    ```
 
-```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
-
-| Метод | Описание | Временная сложность | Пространственная сложность |
-|------|------|------------|------------|
-| `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) |
+### Характеристики производительности
 
-```typescript
-// Примеры операций Collectable
-const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .filter(n => n % 2 === 0)
-    .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) | Да | Временные оконные операции. |
 
-// Проверки соответствия
-console.log(data.anyMatch(n => n > 5)); // true
-console.log(data.allMatch(n => n < 20)); // true
+Выбирайте `toUnordered()`, когда важна максимальная скорость. Используйте `toOrdered()` только тогда, когда вам требуется стабильный порядок или статистические методы, зависящие от отсортированных данных.
 
-// Операции поиска
-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
+| Особенность | Semantic-TypeScript | RxJS | Нативные асинхронные итераторы / Генераторы | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| Интеграция с TypeScript | Первоклассная, с глубокой типизацией и нативной осведомлённостью об индексе. | Отличная, но связана со сложными дженериками. | Хорошая, требует ручного описания типов. | Сильная, в функциональном стиле. |
+| Встроенный статистический анализ | Полная нативная поддержка для `number` и `bigint`. | Отсутствует нативно (требует пользовательских операторов). | Отсутствует. | Отсутствует. |
+| Индексирование и осведомленность о позиции | Нативное, мощное индексирование bigint для каждого элемента. | Требует пользовательских операторов (`scan`, `withLatestFrom`). | Требуется ручной счётчик. | Базовая, без встроенного индекса. |
+| Управление потоками событий | Специализированные, типобезопасные фабрики с явным контролем ранней остановки. | Мощное, но требует ручного управления подписками. | Ручной слушатель событий + отмена. | Хороший `fromEvent`, лёгкий. |
+| Производительность и эффективность памяти | Исключительные – оптимизированные коллекторы `toUnordered()` и `toOrdered()`. | Очень хорошая, но цепочки операторов добавляют накладные расходы. | Отличная (нулевые накладные расходы). | Отличная. |
+| Размер бандла | Очень лёгкий. | Большой (даже с tree-shaking). | Нулевой (нативный). | Маленький. |
+| Философия дизайна API | Функциональный паттерн коллектора с явным индексированием. | Реактивный паттерн Observable. | Паттерн Итератор / Генератор. | Функциональный, бесточечный. |
+| Раннее завершение и контроль | Явный (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Хороший (`take`, `takeUntil`, `first`). | Ручной (`break` в `for await…of`). | Хороший (`take`, `until`). |
+| Поддержка синхронных и асинхронных операций | Унифицированный API – первоклассная поддержка обоих. | В основном асинхронный. | Оба, но ручной. | В основном асинхронный. |
+| Кривая обучения | Плавная для разработчиков, знакомых с функциональным программированием и индексированными конвейерами. | Круче (много операторов, горячие/холодные observable). | Низкая. | Умеренная. |
 
-// Операции вывода
-data.join(", "); // "[2, 4, 6, 8, 10]"
-```
+Ключевые преимущества Semantic-TypeScript
 
-## Методы статистического анализа
-
-### Методы 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) |
+•   Уникальные встроенные возможности статистики и индексирования, исключающие необходимость ручного `reduce` или внешних библиотек.
 
-```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
-```
+•   Явный контроль над потоками событий предотвращает утечки памяти, характерные для RxJS.
 
-## Руководство по выбору производительности
+•   Унифицированный синхронный/асинхронный дизайн предоставляет единый, последовательный API для различных случаев использования.
 
-### Выбор неупорядоченного коллектора (приоритет производительности)
-```typescript
-// Когда не требуется гарантия порядка, используйте неупорядоченный коллектор для лучшей производительности
-let highPerformance = data
-    .filter(predicate)
-    .map(mapper)
-    .toUnordered(); // Лучшая производительность
-```
+Это сравнение показывает, почему Semantic-TypeScript особенно хорошо подходит для современных TypeScript фронтенд-приложений, которые требуют производительности, типобезопасности и богатой аналитики без церемоний традиционных реактивных библиотек.
 
-### Выбор упорядоченного коллектора (требуется порядок)
-```typescript
-// Когда необходимо сохранить порядок элементов, используйте упорядоченный коллектор
-let ordered = data.sorted(comparator);
-```
+---
 
-### Выбор оконного коллектора (оконные операции)
-```typescript
-// Когда требуются оконные операции
-let windowed: WindowCollectable<number> = data
-    .toWindow()
-    .slide(5n, 2n); // Скользящее окно
-```
+### Готовы исследовать?
 
-### Выбор статистического анализа (числовые вычисления)
-```typescript
-// Когда требуется статистический анализ
-let statistics: NumericStatistics<number> = data
-    .toNumericStatistics(); // Числовая статистика
+Semantic-TypeScript превращает сложные потоки данных в читаемые, компонуемые и высокопроизводительные конвейеры. Обрабатываете ли вы события пользовательского интерфейса в реальном времени, обрабатываете большие наборы данных или создаёте аналитические панели — он предоставляет мощь индексирования уровня баз данных с элегантностью функционального программирования.
 
-let bigIntStatistics: BigintStatistics<bigint> = data
-    .toBigintStatistics(); // Статистика больших целых чисел
-```
+Следующие шаги:
+
+•   Изучите полностью типизированный API в своей IDE (все экспорты из основного пакета).
 
-[GitHub](https://github.com/eloyhere/semantic-typescript)
-[NPMJS](https://www.npmjs.com/package/semantic-typescript)
+•   Присоединяйтесь к растущему сообществу разработчиков, которые заменили запутанные асинхронные итераторы чистыми Semantic-конвейерами.
 
-## Важные замечания
+Semantic-TypeScript — где потоки встречаются со структурой.
 
-1. **Влияние операций сортировки**: В упорядоченных коллекторах операция `sorted()` переопределяет эффекты `redirect`, `translate`, `shuffle`, `reverse`.
-2. **Рассмотрение производительности**: Если не требуется гарантия порядка, предпочтение следует отдавать использованию `toUnordered()` для улучшения производительности.
-3. **Использование памяти**: Операции сортировки требуют дополнительного пространства O(n).
-4. **Реальное время**: Потоки Semantic подходят для обработки данных в реальном времени и поддерживают асинхронные источники данных.
+Начните строить сегодня и ощутите разницу, которую приносит продуманное индексирование.
 
-Эта библиотека предоставляет разработчикам TypeScript мощные и гибкие возможности потоковой обработки, сочетая преимущества функционального программирования с гарантиями типобезопасности.
+Стройте с ясностью, действуйте с уверенностью и преобразуйте данные осмысленно.