semantic-typescript 0.1.4 → 0.2.5

package/readme.md

@@ -15,34 +15,40 @@ npm install semantic-typescript
 ## Basic Types
 
 | Type | Description |
-|------|------|
-| `Invalid<T>` | Type extending null or undefined |
-| `Valid<T>` | Type excluding null and undefined |
-| `MaybeInvalid<T>` | Type that may be null or undefined |
+|------|-------------|
+| `Invalid<T>` | Type that extends `null` or `undefined` |
+| `Valid<T>` | Type that excludes `null` and `undefined` |
+| `MaybeInvalid<T>` | Type that may be `null` or `undefined` |
 | `Primitive` | Collection of primitive types |
 | `MaybePrimitive<T>` | Type that may be a primitive type |
-| `OptionalSymbol` | Symbol identifier for the Optional class |
-| `SemanticSymbol` | Symbol identifier for the Semantic class |
-| `CollectorsSymbol` | Symbol identifier for the Collector class |
-| `CollectableSymbol` | Symbol identifier for the Collectable class |
-| `OrderedCollectableSymbol` | Symbol identifier for the OrderedCollectable class |
-| `WindowCollectableSymbol` | Symbol identifier for the WindowCollectable class |
-| `StatisticsSymbol` | Symbol identifier for the Statistics class |
-| `NumericStatisticsSymbol` | Symbol identifier for the NumericStatistics class |
-| `BigIntStatisticsSymbol` | Symbol identifier for the BigIntStatistics class |
-| `UnorderedCollectableSymbol` | Symbol identifier for the UnorderedCollectable class |
-| `Runnable` | Function with no parameters and no return value |
-| `Supplier<R>` | Function with no parameters returning R |
+| `OptionalSymbol` | Symbol identifier of the `Optional` class |
+| `SemanticSymbol` | Symbol identifier of the `Semantic` class |
+| `CollectorsSymbol` | Symbol identifier of the `Collector` class |
+| `CollectableSymbol` | Symbol identifier of the `Collectable` class |
+| `OrderedCollectableSymbol` | Symbol identifier of the `OrderedCollectable` class |
+| `WindowCollectableSymbol` | Symbol identifier of the `WindowCollectable` class |
+| `StatisticsSymbol` | Symbol identifier of the `Statistics` class |
+| `NumericStatisticsSymbol` | Symbol identifier of the `NumericStatistics` class |
+| `BigIntStatisticsSymbol` | Symbol identifier of the `BigIntStatistics` class |
+| `UnorderedCollectableSymbol` | Symbol identifier of the `UnorderedCollectable` class |
+
+## Functional Interfaces
+
+| Interface | Description |
+|-----------|-------------|
+| `Runnable` | Function with no parameters and no return value |  
+| `Supplier<R>` | Function with no parameters returning `R` |  
 | `Functional<T, R>` | Single-parameter transformation function |
-| `Predicate<T>` | Single-parameter predicate function |
 | `BiFunctional<T, U, R>` | Two-parameter transformation function |
-| `BiPredicate<T, U>` | Two-parameter predicate function |
-| `Comparator<T>` | Comparison function |
 | `TriFunctional<T, U, V, R>` | Three-parameter transformation function |
+| `Predicate<T>` | Single-parameter predicate function |
+| `BiPredicate<T, U>` | Two-parameter predicate function |
+| `TriPredicate<T, U, V>` | Three-parameter predicate function |
 | `Consumer<T>` | Single-parameter consumer function |
 | `BiConsumer<T, U>` | Two-parameter consumer function |
 | `TriConsumer<T, U, V>` | Three-parameter consumer function |
-| `Generator<T>` | Generator function |
+| `Comparator<T>` | Two-parameter comparison function |
+| `Generator<T>` | Generator function (core and foundation) |
 
 ```typescript
 // Type usage examples
@@ -125,7 +131,7 @@ const nullableOpt = Optional.ofNullable<string>(null);
 const nonNullOpt = Optional.ofNonNull("hello");
 
 presentOpt.ifPresent(val => console.log(val)); // Outputs 42
-console.log(emptyOpt.orElse(100)); // Outputs 100
+console.log(emptyOpt.get(100)); // Outputs 100
 ```
 
 ### Collector Factory Methods
@@ -136,15 +142,34 @@ console.log(emptyOpt.orElse(100)); // Outputs 100
 | `Collector.shortable(identity, interruptor, accumulator, finisher)` | Create an interruptible collector | O(1) | O(1) |
 
 ```typescript
-// Collector usage examples
-const sumCollector = Collector.full(
-    () => 0,
-    (sum, num) => sum + num,
-    result => result
-);
+// Collector conversion examples
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
 
-const numbers = from([1, 2, 3, 4, 5]);
-const total = numbers.toUnoredered().collect(sumCollector); // 15
+// Performance first: use unordered collector
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
+
+// Sorting needed: use ordered collector  
+const ordered = numbers.sorted();
+
+// Counts the number of elements
+let count = Collector.full(
+    () => 0, // Initial value
+    (accumulator, element) => accumulator + element, // Accumulate
+    (accumulator) => accumulator // Finish
+);
+count.collect(from([1,2,3,4,5])); // Counts from a stream
+count.collect([1,2,3,4,5]); // Counts from an iterable object
+
+let find = Collector.shortable(
+    () => Optional.empty(), // Initial value
+    (element, index, accumulator) => accumulator.isPresent(), // Interrupt
+    (accumulator, element, index) => Optional.of(element), // Accumulate
+    (accumulator) => accumulator // Finish
+);
+find.collect(from([1,2,3,4,5])); // Finds the first element
+find.collect([1,2,3,4,5]); // Finds the first element
 ```
 
 ### Semantic Factory Methods
@@ -168,7 +193,7 @@ blob(someBlob, 1024n)
   .toUnordered()
   .write(WritableStream)
   .then(callback) // Write stream successful
-  .catch(writeFi); // Write stream failed
+  .catch(callback); // Write stream failed
 
 // Create an empty stream, won't execute until concatenated with other streams
 empty<string>()
@@ -229,6 +254,7 @@ const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
     .map(n => n * 2)                 // Multiply by 2
     .skip(1)                         // Skip the first
     .limit(3)                        // Limit to 3 elements
+    .toUnordered()                   // Convert to unordered collector
     .toArray();                      // Convert to array
 // Result: [8, 12, 20]
 
@@ -242,47 +268,65 @@ const complexResult = range(1, 100, 1)
     .toArray();                      // Convert to array
 ```
 
-## Collector Conversion Methods
+## Semantic Conversion Methods
 
 | Method | Description | Time Complexity | Space Complexity |
-|------|------|------------|------------|
-| `toUnoredered()` | Convert to unordered collector (performance first) | O(1) | O(1) |
+|------------|------------|------------|------------|
+| `sorted()` | Convert to ordered collector | O(n log n) | O(n) |
+| `toUnordered()` | Convert to unordered collector | O(1) | O(1) |
 | `toOrdered()` | Convert to ordered collector | O(1) | O(1) |
-| `sorted()` | Sort and convert to ordered collector | O(n log n) | O(n) |
+| `toNumericStatistics()` | Convert to numeric statistics | O(n) | O(1) |
+| `toBigintStatistics()` | Convert to bigint statistics | O(n) | O(1) |
 | `toWindow()` | Convert to window collector | O(1) | O(1) |
-| `toNumericStatistics()` | Convert to numerical statistics | O(1) | O(1) |
-| `toBigintStatistics()` | Convert to big integer statistics | O(1) | O(1) |
+| `toCollectable()` | Convert to `UnorderdCollectable` | O(n) | O(1) |
+| `toCollectable(mapper)` | Convert to customized collectable | O(n) | O(1) |
 
 ```typescript
-// Collector conversion examples
-const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
-
-// Performance first: use unordered collector
-const unordered = numbers
-    .filter(n => n > 3)
-    .toUnoredered();
-
-// Need sorting: use ordered collector  
-const ordered = numbers
-    .sorted()
-    .toOrdered();
-
-// Statistical analysis: use statistical collector
-const stats = numbers
-    .toNumericStatistics();
-
-console.log(stats.mean());        // Average value
-console.log(stats.median());      // Median value
-console.log(stats.standardDeviation()); // Standard deviation
-
-// Window operations
-const windowed = numbers
-    .toWindow()
-    .tumble(3n); // Every 3 elements form a window
-
-windowed.forEach(window => {
-    console.log(window.toArray()); // Contents of each window
-});
+// Convert to an ascending sorted array
+from([6,4,3,5,2]) // Creates a stream
+    .sorted() // Sorts the stream in ascending order
+    .toArray(); // [2, 3, 4, 5, 6]
+
+// Convert to a descending sorted array
+from([6,4,3,5,2]) // Creates a stream
+    .soted((a, b) => b - a) // Sorts the stream in descending order
+    .toArray(); // [6, 5, 4, 3, 2]
+
+// Redirect to a reversed array
+from([6,4,3,5,2])
+    .redirect((element, index) => -index) // Redirects to reversed order
+    .toOrderd() // Keeps the redirected order
+    .toArray(); // [2, 5, 3, 4, 6]
+
+// Ignore redirections to reverse array
+from([6,4,3,5,2])
+    .redirect((element, index) => -index) // Redirects to reversed order
+    .toUnorderd() // Drops the redirected order. This operation will ignore `redirect`, `reverse`, `shuffle` and `translate` operations
+    .toArray(); // [2, 5, 3, 4, 6]
+
+// Reverse the stream into an array
+from([6, 4, 3, 5, 2])
+    .reverse() // Reverses the stream
+    .toOrdered() // Guarantees the reversed order
+    .toArray(); // [2, 5, 3, 4, 6]
+
+// Overwrite the shuffled stream into an array
+from([6, 4, 3, 5, 2])
+    .shuffle() // Shuffles the stream
+    .sorted() // Overwrites the shuffled order. This operation will overwrite `redirect`, `reverse`, `shuffle` and `translate` operations
+    .toArray(); // [2, 5, 3, 4, 6]
+
+// Convert to window collector
+from([6, 4, 3, 5, 2]).toWindow();
+
+// Convert to numeric statistics
+from([6, 4, 3, 5, 2]).toNumericStatistics();
+
+// Convert to bigint statistics
+from([6n, 4n, 3n, 5n, 2n]).toBigintStatistics();
+
+// Defines a customized collector to collect data
+let customizedCollector = from([1, 2, 3, 4, 5]).toCollectable((generator: Generator<E>) => new CustomizedCollector(generator));
 ```
 
 ## Collectable Collection Methods
@@ -336,7 +380,7 @@ const grouped = data.groupBy(
 const sum = data.reduce(0, (acc, n) => acc + n); // 30
 
 // Output operations
-data.join(", "); // "2, 4, 6, 8, 10"
+data.join(", "); // "[2, 4, 6, 8, 10]"
 ```
 
 ## Statistical Analysis Methods
@@ -423,4 +467,7 @@ const bigIntStats = data
 3. **Memory Usage**: Sorting operations require O(n) additional space
 4. **Real-time Data**: Semantic streams are suitable for processing real-time data and support asynchronous data sources
 
-This library provides TypeScript developers with powerful and flexible streaming capabilities, combining the benefits of functional programming with type safety guarantees.
+
+This library provides TypeScript developers with powerful and flexible streaming capabilities, combining the benefits of functional programming with type safety guarantees.
+
+

package/readme.ru.md

@@ -15,34 +15,40 @@ npm install 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 |
+|------|-------------|
+| `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>` | Функция преобразования с одним параметром |
-| `Predicate<T>` | Предикатная функция с одним параметром |
 | `BiFunctional<T, U, R>` | Функция преобразования с двумя параметрами |
-| `BiPredicate<T, U>` | Предикатная функция с двумя параметрами |
-| `Comparator<T>` | Функция сравнения |
 | `TriFunctional<T, U, V, R>` | Функция преобразования с тремя параметрами |
-| `Consumer<T>` | Потребительская функция с одним параметром |
-| `BiConsumer<T, U>` | Потребительская функция с двумя параметрами |
-| `TriConsumer<T, U, V>` | Потребительская функция с тремя параметрами |
-| `Generator<T>` | Функция-генератор |
+| `Predicate<T>` | Предикатная функция с одним параметром |
+| `BiPredicate<T, U>` | Предикатная функция с двумя параметрами |
+| `TriPredicate<T, U, V>` | Предикатная функция с тремя параметрами |
+| `Consumer<T>` | Функция-потребитель с одним параметром |
+| `BiConsumer<T, U>` | Функция-потребитель с двумя параметрами |
+| `TriConsumer<T, U, V>` | Функция-потребитель с тремя параметрами |
+| `Comparator<T>` | Функция сравнения с двумя параметрами |
+| `Generator<T>` | Генераторная функция (ядро и основа) |
 
 ```typescript
 // Примеры использования типов
@@ -136,15 +142,34 @@ console.log(emptyOpt.orElse(100)); // Выводит 100
 | `Collector.shortable(identity, interruptor, accumulator, finisher)` | Создает прерываемый сборщик | O(1) | O(1) |
 
 ```typescript
-// Примеры использования Collector
-const sumCollector = Collector.full(
-    () => 0,
-    (sum, num) => sum + num,
-    result => result
-);
+// Примеры преобразования коллекторов
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
+
+// Производительность в приоритете: используем неупорядоченный коллектор
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
+
+// Нужна сортировка: используем упорядоченный коллектор  
+const ordered = numbers.sorted();
 
-const numbers = from([1, 2, 3, 4, 5]);
-const total = numbers.toUnoredered().collect(sumCollector); // 15
+// Подсчитывает количество элементов
+let count = Collector.full(
+    () => 0, // Начальное значение
+    (accumulator, element) => accumulator + element, // Аккумулировать
+    (accumulator) => accumulator // Завершить
+);
+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 // Завершить
+);
+find.collect(from([1,2,3,4,5])); // Находит первый элемент
+find.collect([1,2,3,4,5]); // Находит первый элемент
 ```
 
 ### Фабричные методы Semantic
@@ -155,6 +180,7 @@ const total = numbers.toUnoredered().collect(sumCollector); // 15
 | `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) |
@@ -231,6 +257,7 @@ const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
     .map(n => n * 2)                 // Умножает на 2
     .skip(1)                         // Пропускает первый
     .limit(3)                        // Ограничивает 3 элементами
+    .toUnordered()                    // Преобразует в неупорядоченный сборщик
     .toArray();                      // Преобразует в массив
 // Результат: [8, 12, 20]
 
@@ -244,47 +271,65 @@ const complexResult = range(1, 100, 1)
     .toArray();                      // Преобразует в массив
 ```
 
-## Методы преобразования сборщиков
+## Семантические методы преобразования
 
 | Метод | Описание | Временная сложность | Пространственная сложность |
-|-------|----------|-------------------|--------------------------|
-| `toUnoredered()` | Преобразует в неупорядоченный сборщик (приоритет производительности) | O(1) | O(1) |
-| `toOrdered()` | Преобразует в упорядоченный сборщик | O(1) | O(1) |
-| `sorted()` | Сортирует и преобразует в упорядоченный сборщик | O(n log n) | O(n) |
-| `toWindow()` | Преобразует в оконный сборщик | O(1) | O(1) |
-| `toNumericStatistics()` | Преобразует в числовую статистику | O(1) | O(1) |
-| `toBigintStatistics()` | Преобразует в BigInt статистику | O(1) | 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
-// Примеры преобразования сборщиков
-const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
-
-// Приоритет производительности: Использовать неупорядоченный сборщик
-const unordered = numbers
-    .filter(n => n > 3)
-    .toUnoredered();
-
-// Нужна сортировка: Использовать упорядоченный сборщик  
-const ordered = numbers
-    .sorted()
-    .toOrdered();
-
-// Статистический анализ: Использовать статистический сборщик
-const stats = numbers
-    .toNumericStatistics();
-
-console.log(stats.mean());        // Среднее значение
-console.log(stats.median());      // Медиана
-console.log(stats.standardDeviation()); // Стандартное отклонение
-
-// Оконные операции
-const windowed = numbers
-    .toWindow()
-    .tumble(3n); // Окно из 3 элементов
-
-windowed.forEach(window => {
-    console.log(window.toArray()); // Содержимое каждого окна
-});
+// Преобразовать в массив, отсортированный по возрастанию
+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();
+
+// Преобразовать в статистику BigInt
+from([6n, 4n, 3n, 5n, 2n]).toBigintStatistics();
+
+// Определить пользовательский коллектор для сбора данных
+let customizedCollector = from([1, 2, 3, 4, 5]).toCollectable((generator: Generator<E>) => new CustomizedCollector(generator));
 ```
 
 ## Методы сбора Collectable