semantic-typescript 0.0.8 → 0.1.4

package/readme.md

@@ -1,529 +1,426 @@
-# Semantic-TypeScript Stream Processing Framework
+# Semantic-TypeScript Stream Processing Library
 
 ## Introduction
 
-Semantic-TypeScript is a modern stream processing library inspired by JavaScript GeneratorFunction, Java Stream, and MySQL Index. The core design philosophy is based on constructing efficient data processing pipelines through data indexing, providing a type-safe, functional-style streaming operation experience for frontend development.
+Semantic-TypeScript is a modern stream processing library inspired by JavaScript GeneratorFunction, Java Stream, and MySQL Index. Its core design philosophy is based on building efficient data processing pipelines using data indexing, providing a type-safe, functional-style streaming operation experience for front-end development.
 
-Unlike traditional synchronous processing, Semantic employs an asynchronous processing model. When creating data streams, the timing of terminal data reception depends entirely on when upstream calls the `accept` and `interrupt` callback functions. This design enables the library to elegantly handle real-time data streams, large datasets, and asynchronous data sources.
+Unlike traditional synchronous processing, Semantic employs an asynchronous processing model. When creating a data stream, the time when the terminal receives data entirely depends on when the upstream calls the `accept` and `interrupt` callback functions. This design allows the library to elegantly handle real-time data streams, large datasets, and asynchronous data sources.
 
-## Core Features
+## Installation
 
-| Feature | Description | Advantage |
-|------|------|------|
-| **Type-Safe Generics** | Complete TypeScript type support | Compile-time error detection, better development experience |
-| **Functional Programming** | Immutable data structures and pure functions | More predictable code, easier testing and maintenance |
-| **Lazy Evaluation** | On-demand computation, performance optimisation | High memory efficiency when processing large datasets |
-| **Asynchronous Stream Processing** | Generator-based asynchronous data streams | Suitable for real-time data and event-driven scenarios |
-| **Multi-Paradigm Collectors** | Ordered, unordered, statistical collection strategies | Optimal strategy selection based on different scenarios |
-| **Statistical Analysis** | Built-in complete statistical calculation functions | Integrated data analysis and reporting generation |
-
-## Performance Considerations
-
-**Important Note**: The following methods sacrifice performance to collect and sort data, resulting in ordered data collections:
-- `toOrdered()`
-- `toWindow()`
-- `toNumericStatistics()`
-- `toBigIntStatistics()`
-- `sorted()`
-- `sorted(comparator)`
-
-Particularly important to note: `sorted()` and `sorted(comparator)` will override the results of the following methods:
-- `redirect(redirector)`
-- `translate(translator)` 
-- `shuffle(mapper)`
-
-## Factory Methods
-
-### Stream Creation Factories
+```bash
+npm install semantic-typescript
+```
 
-| Method | Signature | Description | Example |
-|------|------|------|------|
-| `blob` | `(blob: Blob, chunk?: bigint) => Semantic<Uint8Array>` | Convert Blob to byte stream | `blob(fileBlob, 1024n)` |
-| `empty` | `<E>() => Semantic<E>` | Create empty stream | `empty<number>()` |
-| `fill` | `<E>(element: E, count: bigint) => Semantic<E>` | Fill with specified number of elements | `fill("hello", 5n)` |
-| `from` | `<E>(iterable: Iterable<E>) => Semantic<E>` | Create stream from iterable object | `from([1, 2, 3])` |
-| `range` | `<N extends number\|bigint>(start: N, end: N, step?: N) => Semantic<N>` | Create numerical range stream | `range(1, 10, 2)` |
-| `iterate` | `<E>(generator: Generator<E>) => Semantic<E>` | Create stream from generator function | `iterate(myGenerator)` |
-| `websocket` | `(websocket: WebSocket) => Semantic<MessageEvent>` | Create event stream from WebSocket | `websocket(socket)` |
+## 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 |
+| `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 |
+| `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 |
+| `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 |
 
-**Code Example Supplement:**
 ```typescript
-import { from, range, fill, empty } from 'semantic-typescript';
-
-// Create stream from array
-const numberStream = from([1, 2, 3, 4, 5]);
-
-// Create numerical range stream
-const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
-
-// Fill with repeated elements
-const filledStream = fill("hello", 3n); // "hello", "hello", "hello"
-
-// Create empty stream
-const emptyStream = empty<number>();
+// Type usage examples
+const predicate: Predicate<number> = (n) => n > 0;
+const mapper: Functional<string, number> = (str) => str.length;
+const comparator: Comparator<number> = (a, b) => a - b;
 ```
 
-### Utility Function Factories
-
-| Method | Signature | Description | Example |
-|------|------|------|------|
-| `validate` | `<T>(t: MaybeInvalid<T>) => t is T` | Validate if value is valid | `validate(null)` → `false` |
-| `invalidate` | `<T>(t: MaybeInvalid<T>) => t is null\|undefined` | Validate if value is invalid | `invalidate(0)` → `false` |
-| `useCompare` | `<T>(t1: T, t2: T) => number` | Generic comparison function | `useCompare("a", "b")` → `-1` |
-| `useRandom` | `<T = number\|bigint>(index: T) => T` | Pseudorandom number generator | `useRandom(5)` → random number |
+## Type Guards
+
+| Function | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `validate<T>(t: MaybeInvalid<T>): t is T` | Validate value is not null or undefined | O(1) | O(1) |
+| `invalidate<T>(t: MaybeInvalid<T>): t is null \| undefined` | Validate value is null or undefined | O(1) | O(1) |
+| `isBoolean(t: unknown): t is boolean` | Check if it is a boolean | O(1) | O(1) |
+| `isString(t: unknown): t is string` | Check if it is a string | O(1) | O(1) |
+| `isNumber(t: unknown): t is number` | Check if it is a number | O(1) | O(1) |
+| `isFunction(t: unknown): t is Function` | Check if it is a function | O(1) | O(1) |
+| `isObject(t: unknown): t is object` | Check if it is an object | O(1) | O(1) |
+| `isSymbol(t: unknown): t is symbol` | Check if it is a Symbol | O(1) | O(1) |
+| `isBigint(t: unknown): t is bigint` | Check if it is a BigInt | O(1) | O(1) |
+| `isPrimitive(t: unknown): t is Primitive` | Check if it is a primitive type | O(1) | O(1) |
+| `isIterable(t: unknown): t is Iterable<unknown>` | Check if it is an iterable object | O(1) | O(1) |
+| `isOptional(t: unknown): t is Optional<unknown>` | Check if it is an Optional instance | O(1) | O(1) |
+| `isSemantic(t: unknown): t is Semantic<unknown>` | Check if it is a Semantic instance | O(1) | O(1) |
+| `isCollector(t: unknown): t is Collector<unknown, unknown, unknown>` | Check if it is a Collector instance | O(1) | O(1) |
+| `isCollectable(t: unknown): t is Collectable<unknown>` | Check if it is a Collectable instance | O(1) | O(1) |
+| `isOrderedCollectable(t: unknown): t is OrderedCollectable<unknown>` | Check if it is an OrderedCollectable instance | O(1) | O(1) |
+| `isWindowCollectable(t: unknown): t is WindowCollectable<unknown>` | Check if it is a WindowCollectable instance | O(1) | O(1) |
+| `isUnorderedCollectable(t: unknown): t is UnorderedCollectable<unknown>` | Check if it is an UnorderedCollectable instance | O(1) | O(1) |
+| `isStatistics(t: unknown): t is Statistics<unknown, number \| bigint>` | Check if it is a Statistics instance | O(1) | O(1) |
+| `isNumericStatistics(t: unknown): t is NumericStatistics<unknown>` | Check if it is a NumericStatistics instance | O(1) | O(1) |
+| `isBigIntStatistics(t: unknown): t is BigIntStatistics<unknown>` | Check if it is a BigIntStatistics instance | O(1) | O(1) |
 
-**Code Example Supplement:**
 ```typescript
-import { validate, invalidate, useCompare, useRandom } from 'semantic-typescript';
+// Type guard usage examples
+const value: unknown = "hello";
 
-// Validate data validity
-const data: string | null = "hello";
-if (validate(data)) {
-    console.log(data.toUpperCase()); // Safe call because validate ensures data is not null
+if (isString(value)) {
+    console.log(value.length); // Type-safe, value inferred as string
 }
 
-const nullData: string | null = null;
-if (invalidate(nullData)) {
-    console.log("Data invalid"); // Will execute because invalidate detected null
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
 }
-
-// Compare values
-const comparison = useCompare("apple", "banana"); // -1
-
-// Generate random number
-const randomNum = useRandom(42); // Random number based on seed 42
 ```
 
-## Core Class Details
-
-### Optional<T> - Safe Null Value Handling
-
-The Optional class provides a functional approach to safely handle values that may be null or undefined.
+## Utility Functions
 
-| Method | Return Type | Description | Time Complexity |
-|------|----------|------|------------|
-| `filter(predicate: Predicate<T>)` | `Optional<T>` | Filter values satisfying condition | O(1) |
-| `get()` | `T` | Get value, throw error if empty | O(1) |
-| `getOrDefault(defaultValue: T)` | `T` | Get value or default value | O(1) |
-| `ifPresent(action: Consumer<T>)` | `void` | Execute action if value exists | O(1) |
-| `isEmpty()` | `boolean` | Check if empty | O(1) |
-| `isPresent()` | `boolean` | Check if value exists | O(1) |
-| `map<R>(mapper: Functional<T, R>)` | `Optional<R>` | Map and transform value | O(1) |
-| `static of<T>(value: MaybeInvalid<T>)` | `Optional<T>` | Create Optional instance | O(1) |
-| `static ofNullable<T>(value?)` | `Optional<T>` | Create nullable Optional | O(1) |
-| `static ofNonNull<T>(value: T)` | `Optional<T>` | Create non-null Optional | O(1) |
+| Function | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `useCompare<T>(t1: T, t2: T): number` | Generic comparison function | O(1) | O(1) |
+| `useRandom<T = number \| bigint>(index: T): T` | Pseudo-random number generator | O(log n) | O(1) |
 
-**Code Example Supplement:**
 ```typescript
-import { Optional } from 'semantic-typescript';
+// Utility function usage examples
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-// Create Optional instance
-const optionalValue = Optional.ofNullable<string>(Math.random() > 0.5 ? "hello" : null);
+const randomNum = useRandom(42); // Seed-based random number
+const randomBigInt = useRandom(1000n); // BigInt random number
+```
 
-// Chain operations
-const result = optionalValue
-    .filter(val => val.length > 3) // Filter values longer than 3
-    .map(val => val.toUpperCase()) // Convert to uppercase
-    .getOrDefault("default"); // Get value or default
+## Factory Methods
 
-console.log(result); // "HELLO" or "default"
+### Optional Factory Methods
 
-// Safe operations
-optionalValue.ifPresent(val => {
-    console.log(`Value exists: ${val}`);
-});
+| Method | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `Optional.empty<T>()` | Create an empty Optional | O(1) | O(1) |
+| `Optional.of<T>(value)` | Create an Optional containing a value | O(1) | O(1) |
+| `Optional.ofNullable<T>(value)` | Create a potentially empty Optional | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value)` | Create a non-null Optional | O(1) | O(1) |
 
-// Check status
-if (optionalValue.isPresent()) {
-    console.log("Has value");
-} else if (optionalValue.isEmpty()) {
-    console.log("Is empty");
-}
+```typescript
+// Optional usage examples
+const emptyOpt = Optional.empty<number>();
+const presentOpt = Optional.of(42);
+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
 ```
 
-### Semantic<E> - Lazy Data Stream
-
-Semantic is the core stream processing class, providing rich stream operators.
-
-#### Stream Transformation Operations
-
-| Method | Return Type | Description | Performance Impact |
-|------|----------|------|----------|
-| `concat(other: Semantic<E>)` | `Semantic<E>` | Concatenate two streams | O(n+m) |
-| `distinct()` | `Semantic<E>` | Remove duplicates (using Set) | O(n) |
-| `distinct(comparator)` | `Semantic<E>` | Custom comparator deduplication | O(n²) |
-| `dropWhile(predicate)` | `Semantic<E>` | Discard starting elements satisfying condition | O(n) |
-| `filter(predicate)` | `Semantic<E>` | Filter elements | O(n) |
-| `flat(mapper)` | `Semantic<E>` | Flatten nested streams | O(n×m) |
-| `flatMap(mapper)` | `Semantic<R>` | Map and flatten | O(n×m) |
-| `limit(n)` | `Semantic<E>` | Limit number of elements | O(n) |
-| `map(mapper)` | `Semantic<R>` | Map and transform elements | O(n) |
-| `peek(consumer)` | `Semantic<E>` | View elements without modification | O(n) |
-| `redirect(redirector)` | `Semantic<E>` | Redirect indices | O(n) |
-| `reverse()` | `Semantic<E>` | Reverse stream order | O(n) |
-| `shuffle()` | `Semantic<E>` | Randomly shuffle order | O(n) |
-| `shuffle(mapper)` | `Semantic<E>` | Custom shuffle logic | O(n) |
-| `skip(n)` | `Semantic<E>` | Skip first n elements | O(n) |
-| `sub(start, end)` | `Semantic<E>` | Get substream | O(n) |
-| `takeWhile(predicate)` | `Semantic<E>` | Get starting elements satisfying condition | O(n) |
-| `translate(offset)` | `Semantic<E>` | Translate indices | O(n) |
-| `translate(translator)` | `Semantic<E>` | Custom index transformation | O(n) |
-
-**Code Example Supplement:**
-```typescript
-import { from } from 'semantic-typescript';
+### Collector Factory Methods
 
-const stream = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+| Method | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `Collector.full(identity, accumulator, finisher)` | Create a full collector | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Create an interruptible collector | O(1) | O(1) |
 
-// Stream transformation operation examples
-const processedStream = stream
-    .filter(x => x % 2 === 0) // Filter even numbers
-    .map(x => x * 2) // Multiply each element by 2
-    .distinct() // Remove duplicates
-    .limit(3) // Limit to first 3 elements
-    .peek((val, index) => console.log(`Element ${val} at index ${index}`)); // View elements
+```typescript
+// Collector usage examples
+const sumCollector = Collector.full(
+    () => 0,
+    (sum, num) => sum + num,
+    result => result
+);
 
-// Note: The stream hasn't executed yet, needs conversion to Collectable for terminal operations
+const numbers = from([1, 2, 3, 4, 5]);
+const total = numbers.toUnoredered().collect(sumCollector); // 15
 ```
 
-#### Stream Terminal Operations
+### Semantic Factory Methods
 
-| Method | Return Type | Description | Performance Characteristics |
-|------|----------|------|----------|
-| `toOrdered()` | `OrderedCollectable<E>` | Convert to ordered collection | Sorting operation, lower performance |
-| `toUnordered()` | `UnorderedCollectable<E>` | Convert to unordered collection | Fastest, no sorting |
-| `toWindow()` | `WindowCollectable<E>` | Convert to window collection | Sorting operation, lower performance |
-| `toNumericStatistics()` | `Statistics<E, number>` | Numerical statistical analysis | Sorting operation, lower performance |
-| `toBigintStatistics()` | `Statistics<E, bigint>` | Big integer statistical analysis | Sorting operation, lower performance |
-| `sorted()` | `OrderedCollectable<E>` | Natural sorting | Overrides redirection results |
-| `sorted(comparator)` | `OrderedCollectable<E>` | Custom sorting | Overrides redirection results |
+| Method | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `blob(blob, chunkSize)` | Create a stream from a Blob | O(n) | O(chunkSize) |
+| `empty<E>()` | Create an empty stream | O(1) | O(1) |
+| `fill<E>(element, count)` | Create a filled stream | O(n) | O(1) |
+| `from<E>(iterable)` | Create a stream from an iterable object | O(1) | O(1) |
+| `interval(period, delay?)` | Create a timed interval stream | O(1)* | O(1) |
+| `iterate<E>(generator)` | Create a stream from a generator | O(1) | O(1) |
+| `range(start, end, step)` | Create a numerical range stream | O(n) | O(1) |
+| `websocket(websocket)` | Create a stream from a WebSocket | O(1) | O(1) |
 
-**Code Example Supplement:**
 ```typescript
-import { from } from 'semantic-typescript';
+// Semantic factory method usage examples
 
-const semanticStream = from([5, 2, 8, 1, 9, 3, 7, 4, 6]);
+// Create a stream from a Blob (chunked reading)
+blob(someBlob, 1024n)
+  .toUnordered()
+  .write(WritableStream)
+  .then(callback) // Write stream successful
+  .catch(writeFi); // Write stream failed
 
-// Convert to ordered collection (lower performance)
-const ordered = semanticStream.toOrdered();
+// Create an empty stream, won't execute until concatenated with other streams
+empty<string>()
+  .toUnordered()
+  .join(); //[]
 
-// Convert to unordered collection (fastest)
-const unordered = semanticStream.toUnordered();
+// Create a filled stream
+const filledStream = fill("hello", 3); // "hello", "hello", "hello"
 
-// Natural sorting
-const sortedNatural = semanticStream.sorted();
+// Create a timed stream with initial 2-second delay and 5-second execution period, implemented based on timer mechanism; may experience time drift due to system scheduling precision limitations.
+const intervalStream = interval(5000, 2000);
 
-// Custom sorting
-const sortedCustom = semanticStream.sorted((a, b) => b - a); // Descending sort
+// Create a stream from an iterable object
+const numberStream = from([1, 2, 3, 4, 5]);
+const stringStream = from(new Set(["Alex", "Bob"]));
 
-// Convert to statistical object
-const stats = semanticStream.toNumericStatistics();
+// Create a range stream
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
 
-// Note: Must call above methods through Semantic instance to get Collectable before using terminal methods
+// WebSocket event stream
+const ws = new WebSocket("ws://localhost:8080");
+websocket(ws)
+  .filter((event)=> event.type === "message"); // Only listen to message events
+  .toUnordered() // Generally not ordered for events
+  .forEach((event)=> receive(event)); // Receive messages
 ```
 
-### Collector<E, A, R> - Data Collector
-
-Collectors are used to aggregate stream data into specific structures.
+## Semantic Class Methods
+
+| Method | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `concat(other)` | Concatenate two streams | O(n) | O(1) |
+| `distinct()` | Remove duplicates | O(n) | O(n) |
+| `distinct(comparator)` | Remove duplicates using a comparator | O(n²) | O(n) |
+| `dropWhile(predicate)` | Discard elements satisfying condition | O(n) | O(1) |
+| `filter(predicate)` | Filter elements | O(n) | O(1) |
+| `flat(mapper)` | Flattening map | O(n × m) | O(1) |
+| `flatMap(mapper)` | Flattening map to new type | O(n × m) | O(1) |
+| `limit(n)` | Limit number of elements | O(n) | O(1) |
+| `map(mapper)` | Map transformation | O(n) | O(1) |
+| `peek(consumer)` | Peek at elements | O(n) | O(1) |
+| `redirect(redirector)` | Redirect index | O(n) | O(1) |
+| `reverse()` | Reverse stream | O(n) | O(1) |
+| `shuffle()` | Randomly shuffle | O(n) | O(1) |
+| `shuffle(mapper)` | Shuffle using a mapper | O(n) | O(1) |
+| `skip(n)` | Skip first n elements | O(n) | O(1) |
+| `sorted()` | Sort | O(n log n) | O(n) |
+| `sorted(comparator)` | Sort using a comparator | O(n log n) | O(n) |
+| `sub(start, end)` | Get substream | O(n) | O(1) |
+| `takeWhile(predicate)` | Get elements satisfying condition | O(n) | O(1) |
+| `translate(offset)` | Translate index | O(n) | O(1) |
+| `translate(translator)` | Translate index using a translator | O(n) | O(1) |
 
-| Method | Description | Usage Scenario |
-|------|------|----------|
-| `collect(generator)` | Execute data collection | Stream terminal operation |
-| `static full(identity, accumulator, finisher)` | Create complete collector | Requires complete processing |
-| `static shortable(identity, interruptor, accumulator, finisher)` | Create interruptible collector | May terminate early |
-
-**Code Example Supplement:**
 ```typescript
-import { Collector } from 'semantic-typescript';
-
-// Create custom collector
-const sumCollector = Collector.full(
-    () => 0, // Initial value
-    (acc, value) => acc + value, // Accumulator
-    result => result // Finisher function
-);
-
-// Use collector (requires conversion from Semantic to Collectable first)
-const numbers = from([1, 2, 3, 4, 5]);
-const sum = numbers.toUnordered().collect(sumCollector); // 15
+// Semantic operation examples
+const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)        // Filter even numbers
+    .map(n => n * 2)                 // Multiply by 2
+    .skip(1)                         // Skip the first
+    .limit(3)                        // Limit to 3 elements
+    .toArray();                      // Convert to array
+// Result: [8, 12, 20]
+
+// Complex operation example
+const complexResult = range(1, 100, 1)
+    .flatMap(n => from([n, n * 2])) // Map each element to two
+    .distinct()                      // Remove duplicates
+    .shuffle()                       // Shuffle order
+    .takeWhile(n => n < 50)         // Take elements less than 50
+    .toOrdered()                     // Convert to ordered collector
+    .toArray();                      // Convert to array
 ```
 
-### Collectable<E> - Collectable Data Abstract Class
-
-Provides rich data aggregation and transformation methods. **Note: Must first obtain Collectable instance by calling sorted(), toOrdered() etc. through Semantic instance before using the following methods.**
+## Collector Conversion Methods
 
-#### Data Query Operations
+| Method | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `toUnoredered()` | Convert to unordered collector (performance first) | 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) |
+| `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) |
 
-| Method | Return Type | Description | Example |
-|------|----------|------|------|
-| `anyMatch(predicate)` | `boolean` | Whether any element matches | `anyMatch(x => x > 0)` |
-| `allMatch(predicate)` | `boolean` | Whether all elements match | `allMatch(x => x > 0)` |
-| `count()` | `bigint` | Element count statistics | `count()` → `5n` |
-| `isEmpty()` | `boolean` | Whether stream is empty | `isEmpty()` |
-| `findAny()` | `Optional<E>` | Find any element | `findAny()` |
-| `findFirst()` | `Optional<E>` | Find first element | `findFirst()` |
-| `findLast()` | `Optional<E>` | Find last element | `findLast()` |
-
-**Code Example Supplement:**
 ```typescript
-import { from } from 'semantic-typescript';
-
-const numbers = from([1, 2, 3, 4, 5]);
-
-// Must convert to Collectable before using terminal methods
-const collectable = numbers.toUnordered();
-
-// Data query operations
-const hasEven = collectable.anyMatch(x => x % 2 === 0); // true
-const allPositive = collectable.allMatch(x => x > 0); // true
-const count = collectable.count(); // 5n
-const isEmpty = collectable.isEmpty(); // false
-const firstElement = collectable.findFirst(); // Optional.of(1)
-const anyElement = collectable.findAny(); // Any element
+// 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
+});
 ```
 
-#### Data Aggregation Operations
-
-| Method | Return Type | Description | Complexity |
-|------|----------|------|--------|
-| `group(classifier)` | `Map<K, E[]>` | Group by classifier | O(n) |
-| `groupBy(keyExtractor, valueExtractor)` | `Map<K, V[]>` | Group by key-value extractors | O(n) |
-| `join()` | `string` | Join as string | O(n) |
-| `join(delimiter)` | `string` | Join with delimiter | O(n) |
-| `partition(count)` | `E[][]` | Partition by count | O(n) |
-| `partitionBy(classifier)` | `E[][]` | Partition by classifier | O(n) |
-| `reduce(accumulator)` | `Optional<E>` | Reduction operation | O(n) |
-| `reduce(identity, accumulator)` | `E` | Reduction with identity | O(n) |
-| `toArray()` | `E[]` | Convert to array | O(n) |
-| `toMap(keyExtractor, valueExtractor)` | `Map<K, V>` | Convert to Map | O(n) |
-| `toSet()` | `Set<E>` | Convert to Set | O(n) |
-
-**Code Example Supplement:**
+## Collectable Collection Methods
+
+| Method | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `anyMatch(predicate)` | Whether any element matches | O(n) | O(1) |
+| `allMatch(predicate)` | Whether all elements match | O(n) | O(1) |
+| `count()` | Element count | O(n) | O(1) |
+| `isEmpty()` | Whether it is empty | O(1) | O(1) |
+| `findAny()` | Find any element | O(n) | O(1) |
+| `findFirst()` | Find the first element | O(n) | O(1) |
+| `findLast()` | Find the last element | O(n) | O(1) |
+| `forEach(action)` | Iterate over all elements | O(n) | O(1) |
+| `group(classifier)` | Group by classifier | O(n) | O(n) |
+| `groupBy(keyExtractor, valueExtractor)` | Group by key-value extractor | O(n) | O(n) |
+| `join()` | Join as string | O(n) | O(n) |
+| `join(delimiter)` | Join using a delimiter | O(n) | O(n) |
+| `nonMatch(predicate)` | Whether no elements match | O(n) | O(1) |
+| `partition(count)` | Partition by count | O(n) | O(n) |
+| `partitionBy(classifier)` | Partition by classifier | O(n) | O(n) |
+| `reduce(accumulator)` | Reduction operation | O(n) | O(1) |
+| `reduce(identity, accumulator)` | Reduction with initial value | O(n) | O(1) |
+| `toArray()` | Convert to array | O(n) | O(n) |
+| `toMap(keyExtractor, valueExtractor)` | Convert to Map | O(n) | O(n) |
+| `toSet()` | Convert to Set | O(n) | O(n) |
+| `write(stream)` | Write to stream | O(n) | O(1) |
+
 ```typescript
-import { from } from 'semantic-typescript';
+// Collectable operation examples
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)
+    .toOrdered();
 
-const people = from([
-    { name: "Alice", age: 25, city: "New York" },
-    { name: "Bob", age: 30, city: "London" },
-    { name: "Charlie", age: 25, city: "New York" }
-]);
+// Match checks
+console.log(data.anyMatch(n => n > 5)); // true
+console.log(data.allMatch(n => n < 20)); // true
 
-// Must convert to Collectable before using aggregation operations
-const collectable = people.toUnordered();
+// Find operations
+data.findFirst().ifPresent(n => console.log(n)); // 2
+data.findAny().ifPresent(n => console.log(n)); // Any element
 
 // Grouping operations
-const byCity = collectable.group(person => person.city);
-// Map { "New York" => [{name: "Alice", ...}, {name: "Charlie", ...}], "London" => [{name: "Bob", ...}] }
-
-const byAge = collectable.groupBy(
-    person => person.age,
-    person => person.name
+const grouped = data.groupBy(
+    n => n > 5 ? "large" : "small",
+    n => n * 2
 );
-// Map { 25 => ["Alice", "Charlie"], 30 => ["Bob"] }
-
-// Convert to collections
-const array = collectable.toArray(); // Original array
-const set = collectable.toSet(); // Set collection
-const map = collectable.toMap(
-    person => person.name,
-    person => person.age
-); // Map { "Alice" => 25, "Bob" => 30, "Charlie" => 25 }
+// {small: [4, 8], large: [12, 16, 20]}
 
 // Reduction operations
-const totalAge = collectable.reduce(0, (acc, person) => acc + person.age); // 80
-const oldest = collectable.reduce((a, b) => a.age > b.age ? a : b); // Optional.of({name: "Bob", age: 30, ...})
-```
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
 
-### Specific Collector Implementations
-
-#### UnorderedCollectable<E>
-- **Characteristics**: Fastest collector, no sorting
-- **Usage Scenarios**: Order unimportant, maximum performance desired
-- **Methods**: Inherits all Collectable methods
-
-#### OrderedCollectable<E> 
-- **Characteristics**: Guarantees element order, lower performance
-- **Usage Scenarios**: Require sorted results
-- **Special Methods**: Inherits all methods, maintains internal sort state
+// Output operations
+data.join(", "); // "2, 4, 6, 8, 10"
+```
 
-#### WindowCollectable<E>
-- **Characteristics**: Supports sliding window operations
-- **Usage Scenarios**: Time series data analysis
-- **Special Methods**:
-  - `slide(size, step)` - Sliding window
-  - `tumble(size)` - Tumbling window
+## Statistical Analysis Methods
+
+### NumericStatistics Methods
+
+| Method | Description | Time Complexity | Space Complexity |
+|------|------|------------|------------|
+| `range()` | Range | O(n) | O(1) |
+| `variance()` | Variance | O(n) | O(1) |
+| `standardDeviation()` | Standard deviation | O(n) | O(1) |
+| `mean()` | Mean | O(n) | O(1) |
+| `median()` | Median | O(n log n) | O(n) |
+| `mode()` | Mode | O(n) | O(n) |
+| `frequency()` | Frequency distribution | O(n) | O(n) |
+| `summate()` | Summation | O(n) | O(1) |
+| `quantile(quantile)` | Quantile | O(n log n) | O(n) |
+| `interquartileRange()` | Interquartile range | O(n log n) | O(n) |
+| `skewness()` | Skewness | O(n) | O(1) |
+| `kurtosis()` | Kurtosis | O(n) | O(1) |
 
-**Code Example Supplement:**
 ```typescript
-import { from } from 'semantic-typescript';
-
-const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-// Unordered collector (fastest)
-const unordered = data.toUnordered();
-const unorderedArray = unordered.toArray(); // May maintain original order [1, 2, 3, ...]
-
-// Ordered collector
-const ordered = data.toOrdered();
-const orderedArray = ordered.toArray(); // Guaranteed sorted [1, 2, 3, ...]
-
-// Window collector
-const windowed = data.toWindow();
-const slidingWindows = windowed.slide(3n, 2n); // Window size 3, step 2
-// Window 1: [1, 2, 3], Window 2: [3, 4, 5], Window 3: [5, 6, 7], ...
-
-const tumblingWindows = windowed.tumble(4n); // Tumbling window size 4
-// Window 1: [1, 2, 3, 4], Window 2: [5, 6, 7, 8], ...
+// Statistical analysis examples
+const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .toNumericStatistics();
+
+console.log("Mean:", numbers.mean()); // 5.5
+console.log("Median:", numbers.median()); // 5.5
+console.log("Standard deviation:", numbers.standardDeviation()); // ~2.87
+console.log("Sum:", numbers.summate()); // 55
+
+// Statistical analysis using mappers
+const objects = from([
+    { value: 10 },
+    { value: 20 }, 
+    { value: 30 }
+]).toNumericStatistics();
+
+console.log("Mapped mean:", objects.mean(obj => obj.value)); // 20
 ```
 
-### Statistics<E, D> - Statistical Analysis
-
-Statistical analysis base class providing rich statistical calculation methods. **Note: Must first obtain Statistics instance by calling toNumericStatistics() or toBigIntStatistics() through Semantic instance before using the following methods.**
-
-#### Statistical Calculation Operations
-
-| Method | Return Type | Description | Algorithm Complexity |
-|------|----------|------|------------|
-| `maximum()` | `Optional<E>` | Maximum value | O(n) |
-| `minimum()` | `Optional<E>` | Minimum value | O(n) |
-| `range()` | `D` | Range (max-min) | O(n) |
-| `variance()` | `D` | Variance | O(n) |
-| `standardDeviation()` | `D` | Standard deviation | O(n) |
-| `mean()` | `D` | Mean value | O(n) |
-| `median()` | `D` | Median value | O(n log n) |
-| `mode()` | `D` | Mode value | O(n) |
-| `frequency()` | `Map<D, bigint>` | Frequency distribution | O(n) |
-| `summate()` | `D` | Summation | O(n) |
-| `quantile(quantile)` | `D` | Quantile | O(n log n) |
-| `interquartileRange()` | `D` | Interquartile range | O(n log n) |
-| `skewness()` | `D` | Skewness | O(n) |
-| `kurtosis()` | `D` | Kurtosis | O(n) |
-
-**Code Example Supplement:**
+## Performance Selection Guide
+
+### Choose Unordered Collector (Performance First)
 ```typescript
-import { from } from 'semantic-typescript';
-
-const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-// Must convert to statistical object before using statistical methods
-const stats = numbers.toNumericStatistics();
-
-// Basic statistics
-const count = stats.count(); // 10n
-const max = stats.maximum(); // Optional.of(10)
-const min = stats.minimum(); // Optional.of(1)
-const range = stats.range(); // 9
-const mean = stats.mean(); // 5.5
-const median = stats.median(); // 5.5
-const sum = stats.summate(); // 55
-
-// Advanced statistics
-const variance = stats.variance(); // 8.25
-const stdDev = stats.standardDeviation(); // 2.872
-const mode = stats.mode(); // Any value (since all appear once)
-const q1 = stats.quantile(0.25); // 3.25
-const q3 = stats.quantile(0.75); // 7.75
-const iqr = stats.interquartileRange(); // 4.5
-
-// Frequency distribution
-const freq = stats.frequency(); // Map {1 => 1n, 2 => 1n, ...}
+// When order guarantee is not needed, use unordered collector for best performance
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // Best performance
 ```
 
-#### Specific Statistical Implementation Classes
-
-**NumericStatistics<E>**
-- Handles number type statistical analysis
-- All statistical calculations return number type
-
-**BigIntStatistics<E>**  
-- Handles bigint type statistical analysis
-- All statistical calculations return bigint type
-
-**Code Example Supplement:**
+### Choose Ordered Collector (Order Required)
 ```typescript
-import { from } from 'semantic-typescript';
-
-// Numerical statistics
-const numberData = from([10, 20, 30, 40, 50]);
-const numericStats = numberData.toNumericStatistics();
-
-console.log(numericStats.mean()); // 30
-console.log(numericStats.summate()); // 150
-
-// Big integer statistics
-const bigintData = from([100n, 200n, 300n, 400n, 500n]);
-const bigintStats = bigintData.toBigIntStatistics();
+// When element order needs to be maintained, use ordered collector
+const ordered = data.sorted(comparator);
+```
 
-console.log(bigintStats.mean()); // 300n
-console.log(bigintStats.summate()); // 1500n
+### Choose Window Collector (Window Operations)
+```typescript  
+// When window operations are needed
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // Sliding window
+```
 
-// Statistics using mapper functions
-const objectData = from([
-    { value: 15 },
-    { value: 25 }, 
-    { value: 35 },
-    { value: 45 }
-]);
+### Choose Statistical Analysis (Numerical Calculations)
+```typescript  
+// When statistical analysis is needed
+const stats = data
+    .toNumericStatistics(); // Numerical statistics
 
-const objectStats = objectData.toNumericStatistics();
-const meanWithMapper = objectStats.mean(obj => obj.value); // 30
-const sumWithMapper = objectStats.summate(obj => obj.value); // 120
+const bigIntStats = data
+    .toBigintStatistics(); // Big integer statistics
 ```
 
-## Complete Usage Example
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-```typescript
-import { from, validate, invalidate } from 'semantic-typescript';
-
-// 1. Create data stream
-const rawData = [5, 2, 8, 1, null, 9, 3, undefined, 7, 4, 6];
-const semanticStream = from(rawData);
-
-// 2. Stream processing pipeline
-const processedStream = semanticStream
-    .filter(val => validate(val)) // Filter out null and undefined
-    .map(val => val! * 2) // Multiply each value by 2 (using ! because validate ensures not empty)
-    .distinct(); // Remove duplicates
-
-// 3. Convert to Collectable and use terminal operations
-const collectable = processedStream.toUnordered();
-
-// 4. Data validation and usage
-if (!collectable.isEmpty()) {
-    const results = collectable
-        .filter(x => x > 5) // Filter again
-        .toArray(); // Convert to array
-    
-    console.log("Processing results:", results); // [16, 18, 14, 8, 12]
-    
-    // Statistical information
-    const stats = processedStream.toNumericStatistics();
-    console.log("Mean value:", stats.mean()); // 11.2
-    console.log("Total sum:", stats.summate()); // 56
-}
+## Important Notes
 
-// 5. Handle potentially invalid data
-const potentiallyInvalidData: Array<number | null> = [1, null, 3, 4, null];
-const validData = potentiallyInvalidData.filter(validate);
-const invalidData = potentiallyInvalidData.filter(invalidate);
-
-console.log("Valid data:", validData); // [1, 3, 4]
-console.log("Invalid data:", invalidData); // [null, null]
-```
+1. **Impact of Sorting Operations**: In ordered collectors, the `sorted()` operation overrides the effects of `redirect`, `translate`, `shuffle`, `reverse`
+2. **Performance Considerations**: If order guarantee is not needed, prioritise using `toUnoredered()` for better performance
+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
 
-## Important Usage Rules Summary
-
-1. **Create Stream**: Use `from()`, `range()`, `fill()` etc. factory methods to create Semantic instances
-2. **Stream Transformation**: Call `map()`, `filter()`, `distinct()` etc. methods on Semantic instances
-3. **Convert to Collectable**: Must call one of the following methods through Semantic instance:
-   - `toOrdered()` - Ordered collector
-   - `toUnordered()` - Unordered collector (fastest)
-   - `toWindow()` - Window collector  
-   - `toNumericStatistics()` - Numerical statistics
-   - `toBigIntStatistics()` - Big integer statistics
-   - `sorted()` - Natural sorting
-   - `sorted(comparator)` - Custom sorting
-4. **Terminal Operations**: Call `toArray()`, `count()`, `summate()` etc. terminal methods on Collectable instances
-5. **Data Validation**: Use `validate()` to ensure data is not null/undefined, use `invalidate()` to check invalid data
-
-This design ensures type safety and performance optimisation while providing rich stream processing functionality.
+This library provides TypeScript developers with powerful and flexible streaming capabilities, combining the benefits of functional programming with type safety guarantees.