semantic-typescript 0.2.6 → 0.2.9

package/readme.ru.md

@@ -2,9 +2,9 @@
 
 ## Введение
 
-Semantic-TypeScript — это современная библиотека для обработки потоков, вдохновленная JavaScript GeneratorFunction, Java Stream и MySQL Index. Основной дизайн библиотеки основан на построении эффективных конвейеров обработки данных с использованием индексов данных, предоставляя фронтенд-разработчикам типобезопасный, функциональный опыт работы с потоками.
+Semantic-TypeScript — это современная библиотека потоковой обработки, вдохновленная JavaScript GeneratorFunction, Java Stream и индексами MySQL. Её основная концепция дизайна основана на создании эффективных конвейеров обработки данных с использованием индексации данных, предоставляя типобезопасный, функциональный стиль операций потоков для разработки фронтенда.
 
-В отличие от традиционной синхронной обработки, Semantic использует асинхронный режим обработки. При создании потоков данных время получения данных терминалом полностью зависит от того, когда вышестоящий источник вызывает функции обратного вызова `accept` и `interrupt`. Этот дизайн позволяет библиотеке изящно обрабатывать потоки данных в реальном времени, большие наборы данных и асинхронные источники данных.
+В отличие от традиционной синхронной обработки, Semantic использует асинхронную модель обработки. При создании потока данных время, когда терминал получает данные, полностью зависит от того, когда вверх по потоку вызываются функции обратного вызова `accept` и `interrupt`. Этот дизайн позволяет библиотеке изящно обрабатывать потоки реального времени, большие наборы данных и асинхронные источники данных.
 
 ## Установка
 
@@ -12,15 +12,15 @@ Semantic-TypeScript — это современная библиотека дл
 npm install semantic-typescript
 ```
 
-## Базовые типы
+## Основные типы
 
 | Тип | Описание |
 |------|-------------|
 | `Invalid<T>` | Тип, расширяющий `null` или `undefined` |
 | `Valid<T>` | Тип, исключающий `null` и `undefined` |
 | `MaybeInvalid<T>` | Тип, который может быть `null` или `undefined` |
-| `Primitive` | Набор примитивных типов |
-| `MaybePrimitive<T>` | Тип, который может быть примитивным |
+| `Primitive` | Коллекция примитивных типов |
+| `MaybePrimitive<T>` | Тип, который может быть примитивным типом |
 | `OptionalSymbol` | Символьный идентификатор класса `Optional` |
 | `SemanticSymbol` | Символьный идентификатор класса `Semantic` |
 | `CollectorsSymbol` | Символьный идентификатор класса `Collector` |
@@ -38,325 +38,327 @@ npm install semantic-typescript
 |-----------|-------------|
 | `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>` | Генераторная функция (ядро и основа) |
+| `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>` | Функция генератора (основа и фундамент) |
 
 ```typescript
 // Примеры использования типов
-const predicate: Predicate<number> = (n) => n > 0;
-const mapper: Functional<string, number> = (str) => str.length;
-const comparator: Comparator<number> = (a, b) => a - b;
+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;
 ```
 
-## Защитники типов (Type Guards)
+## Типовые защитники
 
 | Функция | Описание | Временная сложность | Пространственная сложность |
-|---------|----------|-------------------|--------------------------|
-| `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` | Проверяет boolean | O(1) | O(1) |
-| `isString(t: unknown): t is string` | Проверяет string | O(1) | O(1) |
-| `isNumber(t: unknown): t is number` | Проверяет number | O(1) | O(1) |
-| `isFunction(t: unknown): t is Function` | Проверяет function | O(1) | O(1) |
-| `isObject(t: unknown): t is object` | Проверяет object | O(1) | O(1) |
-| `isSymbol(t: unknown): t is symbol` | Проверяет 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) |
+|------|------|------------|------------|
+| `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
-// Примеры использования защитников типов
-const value: unknown = "hello";
+// Примеры использования типовых защитников
+let value: unknown = "hello";
 
 if (isString(value)) {
-    console.log(value.length); // Типобезопасно, value выводится как string
+    console.log(value.length); // Типобезопасно, значение выводится как строка
 }
 
 if (isOptional(someValue)) {
-    someValue.ifPresent(val => console.log(val));
+    someValue.ifPresent((value): void => console.log(val));
+}
+
+if(isIterable(value)){
+    // Типобезопасно, теперь это итерируемый объект.
+    for(let item of value){
+        console.log(item);
+    }
 }
 ```
 
 ## Утилитные функции
 
 | Функция | Описание | Временная сложность | Пространственная сложность |
-|---------|----------|-------------------|--------------------------|
-| `useCompare<T>(t1: T, t2: T): number` | Универсальная функция сравнения | O(1) | O(1) |
+|------|------|------------|------------|
+| `useCompare<T>(t1: T, t2: T): number` | Обобщенная функция сравнения | O(1) | O(1) |
 | `useRandom<T = number \| bigint>(index: T): T` | Генератор псевдослучайных чисел | O(log n) | O(1) |
 
 ```typescript
 // Примеры использования утилитных функций
-const numbers = [3, 1, 4, 1, 5];
+let numbers: Array<number> = [3, 1, 4, 1, 5];
 numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-const randomNum = useRandom(42); // Случайное число на основе seed
-const randomBigInt = useRandom(1000n); // Случайное BigInt число
+let randomNum = useRandom(42); // Случайное число на основе семени
 ```
 
 ## Фабричные методы
 
-### Фабричные методы Optional
+### Методы фабрики Optional
 
 | Метод | Описание | Временная сложность | Пространственная сложность |
-|-------|----------|-------------------|--------------------------|
-| `Optional.empty<T>()` | Создает пустой Optional | O(1) | O(1) |
-| `Optional.of<T>(value)` | Создает Optional со значением | O(1) | O(1) |
-| `Optional.ofNullable<T>(value)` | Создает Optional, допускающий null | O(1) | O(1) |
-| `Optional.ofNonNull<T>(value)` | Создает не-null Optional | O(1) | O(1) |
+|------|------|------------|------------|
+| `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
-const emptyOpt = Optional.empty<number>();
-const presentOpt = Optional.of(42);
-const nullableOpt = Optional.ofNullable<string>(null);
-const nonNullOpt = Optional.ofNonNull("hello");
+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 => console.log(val)); // Выводит 42
-console.log(emptyOpt.orElse(100)); // Выводит 100
+presentOpt.ifPresent((val: number): void => console.log(val)); // Выводит 42
+console.log(emptyOpt.get(100)); // Выводит 100
 ```
 
-### Фабричные методы Collector
+### Методы фабрики Collector
 
 | Метод | Описание | Временная сложность | Пространственная сложность |
-|-------|----------|-------------------|--------------------------|
-| `Collector.full(identity, accumulator, finisher)` | Создает полный сборщик | O(1) | O(1) |
-| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Создает прерываемый сборщик | O(1) | O(1) |
+|------|------|------------|------------|
+| `Collector.full(identity, accumulator, finisher)` | Создание полного коллектора | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Создание прерываемого коллектора | O(1) | O(1) |
 
 ```typescript
 // Примеры преобразования коллекторов
-const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
+let numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
 
-// Производительность в приоритете: используем неупорядоченный коллектор
-const unordered = numbers
-    .filter(n => n > 3)
-    .toUnoredered();
+// Приоритет производительности: использование неупорядоченного коллектора для лучшей производительности
+let unordered = numbers
+    .filter((n: number): boolean => n > 3)
+    .toUnordered(); // Лучшая производительность
 
-// Нужна сортировка: используем упорядоченный коллектор  
-const ordered = numbers.sorted();
+// Необходимость в сортировке: использование упорядоченного коллектора
+let ordered = numbers.sorted();
 
-// Подсчитывает количество элементов
+// Подсчет элементов
 let count = Collector.full(
-    () => 0, // Начальное значение
-    (accumulator, element) => accumulator + element, // Аккумулировать
-    (accumulator) => accumulator // Завершить
+    (): 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]); // Считает из итерируемого объекта
+count.collect(from([1,2,3,4,5])); // Подсчет из потока
+count.collect([1,2,3,4,5]); // Подсчет из итерируемого объекта
 
 let find = Collector.shortable(
-    () => Optional.empty(), // Начальное значение
-    (element, index, accumulator) => accumulator.isPresent(), // Прервать
-    (accumulator, element, index) => Optional.of(element), // Аккумулировать
-    (accumulator) => accumulator // Завершить
+    (): 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]); // Находит первый элемент
 ```
 
-### Фабричные методы Semantic
+### Методы фабрики Semantic
 
 | Метод | Описание | Временная сложность | Пространственная сложность |
-|-------|----------|---------------------|----------------------------|
-| `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) |
-| `generate<E>(element, interrupt)` | Создает поток из генератора | 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) |
+|------|------|------------|------------|
+| `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
+// Примеры использования фабричных методов Semantic
 
-// Создать поток из Blob (чтение частями)
+// Создание потока из Blob (чтение блоками)
 blob(someBlob, 1024n)
-  .toUnordered()
-  .write(WritableStream)
-  .then(callback) // Запись потока успешна
-  .catch(writeFi); // Запись потока не удалась
+    .toUnordered()
+    .write(WritableStream)
+    .then(callback) // Успешная запись потока
+    .catch(callback); // Ошибка записи потока
 
-// Создать пустой поток, который не будет выполняться до конкатенации с другими потоками
+// Создание пустого потока, который не будет выполнен до объединения с другими потоками
 empty<string>()
-  .toUnordered()
-  .join(); //[]
+    .toUnordered()
+    .join(); // []
 
-// Создать заполненный поток
+// Создание заполненного потока
 const filledStream = fill("hello", 3); // "hello", "hello", "hello"
 
-// Создать временной поток с начальной задержкой 2 секунды и циклом выполнения 5 секунд,
-// реализованный через механизм таймера, возможны временные отклонения
-// из-за ограничений системного планирования.
+// Создание временного потока с начальной задержкой в 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)=> event.type === "message") // Отслеживать только события сообщений
-  .toUnordered() // Для событий обычно без сортировки
-  .forEach((event)=> receive(event)); // Получать сообщения
+  .filter((event): boolean => event.type === "message") // Слушать только сообщения
+  .toUnordered() // Обычно события неупорядочены
+  .forEach((event): void => receive(event)); // Получение сообщений
 ```
 
 ## Методы класса 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) |
+|------|------|------------|------------|
+| `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) |
+| `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();                      // Преобразует в массив
+    .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();                      // Преобразует в массив
+    .flatMap(n => from([n, n * 2])) // Каждый элемент к двум
+    .distinct() // Удаление дубликатов
+    .shuffle() // Перемешивание порядка
+    .takeWhile(n => n < 50) // Взятие элементов меньше 50
+    .toOrdered() // Преобразование в упорядоченный коллектор
+    .toArray(); // Преобразование в массив
 ```
 
-## Семантические методы преобразования
+## Методы преобразования 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) |
+| `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) |
 
 ```typescript
-// Преобразовать в массив, отсортированный по возрастанию
-from([6,4,3,5,2]) // Создаёт поток
-    .sorted() // Сортирует поток по возрастанию
+// Примеры преобразований
+from([6, 4, 3, 5, 2]) // Создание потока
+    .sorted() // Сортировка потока по возрастанию
     .toArray(); // [2, 3, 4, 5, 6]
 
-// Преобразовать в массив, отсортированный по убыванию
-from([6,4,3,5,2]) // Создаёт поток
-    .soted((a, b) => b - a) // Сортирует поток по убыванию
+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() // Сохраняет перенаправленный порядок
+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`
+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() // Гарантирует обращённый порядок
+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`
+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]) // Создание потока
+    .toWindow(); // Преобразование в оконный коллектор
 
-// Преобразовать в числовую статистику
-from([6, 4, 3, 5, 2]).toNumericStatistics();
+from([6, 4, 3, 5, 2]) // Создание потока
+    .toNumericStatistics(); // Преобразование в числовую статистику
 
-// Преобразовать в статистику BigInt
-from([6n, 4n, 3n, 5n, 2n]).toBigintStatistics();
+from([6n, 4n, 3n, 5n, 2n]) // Создание потока
+    .toBigintStatistics(); // Преобразование в статистику BigInt
 
-// Определить пользовательский коллектор для сбора данных
-let customizedCollector = from([1, 2, 3, 4, 5]).toCollectable((generator: Generator<E>) => new CustomizedCollector(generator));
+// Определение настраиваемого коллектора для сбора данных
+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)` | Преобразует в Map | O(n) | O(n) |
-| `toSet()` | Преобразует в Set | O(n) | O(n) |
-| `write(stream)` | Записывает в поток | O(n) | O(1) |
+|------|------|------------|------------|
+| `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
@@ -364,7 +366,7 @@ 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
 
@@ -373,17 +375,13 @@ data.findFirst().ifPresent(n => console.log(n)); // 2
 data.findAny().ifPresent(n => console.log(n)); // Любой элемент
 
 // Операции группировки
-const grouped = data.groupBy(
-    n => n > 5 ? "large" : "small",
-    n => n * 2
-);
-// {small: [4, 8], large: [12, 16, 20]}
+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"
+data.join(", "); // "[2, 4, 6, 8, 10]"
 ```
 
 ## Методы статистического анализа
@@ -391,8 +389,8 @@ data.join(", "); // "2, 4, 6, 8, 10"
 ### Методы NumericStatistics
 
 | Метод | Описание | Временная сложность | Пространственная сложность |
-|-------|----------|-------------------|--------------------------|
-| `range()` | Размах | O(n) | O(1) |
+|------|------|------------|------------|
+| `range()` | Диапазон | O(n) | O(1) |
 | `variance()` | Дисперсия | O(n) | O(1) |
 | `standardDeviation()` | Стандартное отклонение | O(n) | O(1) |
 | `mean()` | Среднее значение | O(n) | O(1) |
@@ -401,7 +399,7 @@ data.join(", "); // "2, 4, 6, 8, 10"
 | `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) |
+| `interquartileRange()` | Межквартильный размах | O(n log n) | O(n) |
 | `skewness()` | Асимметрия | O(n) | O(1) |
 | `kurtosis()` | Эксцесс | O(n) | O(1) |
 
@@ -410,54 +408,53 @@ data.join(", "); // "2, 4, 6, 8, 10"
 const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
     .toNumericStatistics();
 
-console.log("Среднее значение:", numbers.mean()); // 5.5
+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: 20 },
     { value: 30 }
 ]).toNumericStatistics();
-
-console.log("Отображенное среднее:", objects.mean(obj => obj.value)); // 20
+console.log("Преобразованное среднее:", objects.mean(obj => obj.value)); // 20
 ```
 
 ## Руководство по выбору производительности
 
-### Выбор неупорядоченного сборщика (Приоритет производительности)
+### Выбор неупорядоченного коллектора (приоритет производительности)
 ```typescript
-// Когда гарантия порядка не требуется
-const highPerformance = data
+// Когда не требуется гарантия порядка, используйте неупорядоченный коллектор для лучшей производительности
+let highPerformance = data
     .filter(predicate)
     .map(mapper)
-    .toUnoredered(); // Лучшая производительность
+    .toUnordered(); // Лучшая производительность
 ```
 
-### Выбор упорядоченного сборщика (Требуется порядок)
+### Выбор упорядоченного коллектора (требуется порядок)
 ```typescript
-// Когда порядок элементов должен сохраняться
-const ordered = data.sorted(comparator);
+// Когда необходимо сохранить порядок элементов, используйте упорядоченный коллектор
+let ordered = data.sorted(comparator);
 ```
 
-### Выбор оконного сборщика (Оконные операции)
+### Выбор оконного коллектора (оконные операции)
 ```typescript
 // Когда требуются оконные операции
-const windowed = data
+let windowed: WindowCollectable<number> = data
     .toWindow()
     .slide(5n, 2n); // Скользящее окно
 ```
 
-### Выбор статистического анализа (Численные вычисления)
+### Выбор статистического анализа (числовые вычисления)
 ```typescript
 // Когда требуется статистический анализ
-const stats = data
-    .toNumericStatistics(); // Численная статистика
+let statistics: NumericStatistics<number> = data
+    .toNumericStatistics(); // Числовая статистика
 
-const bigIntStats = data
-    .toBigintStatistics(); // BigInt статистика
+let bigIntStatistics: BigintStatistics<bigint> = data
+    .toBigintStatistics(); // Статистика больших целых чисел
 ```
 
 [GitHub](https://github.com/eloyhere/semantic-typescript)
@@ -465,9 +462,9 @@ const bigIntStats = data
 
 ## Важные замечания
 
-1. **Влияние операций сортировки**: В упорядоченных сборщиках операция `sorted()` перезаписывает эффекты `redirect`, `translate`, `shuffle`
-2. **Соображения производительности**: Если гарантия порядка не требуется, отдавайте приоритет `toUnoredered()` для лучшей производительности
-3. **Использование памяти**: Операции сортировки требуют O(n) дополнительного пространства
-4. **Данные реального времени**: Потоки Semantic идеально подходят для данных реального времени и поддерживают асинхронные источники данных
+1. **Влияние операций сортировки**: В упорядоченных коллекторах операция `sorted()` переопределяет эффекты `redirect`, `translate`, `shuffle`, `reverse`.
+2. **Рассмотрение производительности**: Если не требуется гарантия порядка, предпочтение следует отдавать использованию `toUnordered()` для улучшения производительности.
+3. **Использование памяти**: Операции сортировки требуют дополнительного пространства O(n).
+4. **Реальное время**: Потоки Semantic подходят для обработки данных в реальном времени и поддерживают асинхронные источники данных.
 
-Эта библиотека предоставляет TypeScript-разработчикам мощные и гибкие возможности обработки потоков, сочетая преимущества функционального программирования с типобезопасностью.
+Эта библиотека предоставляет разработчикам TypeScript мощные и гибкие возможности потоковой обработки, сочетая преимущества функционального программирования с гарантиями типобезопасности.