semantic-typescript 0.6.0 → 0.7.0

package/readme.md

@@ -1,214 +1,213 @@
-# Semantic-TypeScript: A Paradigm-Shifting Stream Processing Library
-
-## Introduction
-Semantic-TypeScript represents a significant advancement in stream processing technology, synthesising the most effective concepts from JavaScript GeneratorFunctions, Java Streams, and database indexing paradigms. Its foundational design principle is centred on constructing exceptionally efficient data processing pipelines through sophisticated, lazy evaluation and intelligent indexing. The library delivers a rigorously type-safe, functionally pure streaming operation experience specifically engineered for contemporary TypeScript and JavaScript development.
-
-In contrast to conventional synchronous processing architectures, Semantic-TypeScript implements a unified model that gracefully handles both synchronous (Iterable) and asynchronous (AsyncIterable) data sources. During stream generation, the flow and termination of data are precisely controlled by callback mechanisms, enabling the library to handle with exceptional grace:
-
-- Real-time data streams (DOM events, WebSockets, intervals) with deterministic control
-- Large-scale datasets through memory-efficient, lazy pipelines
-- Complex data transformations with a fluent, declarative API
-
-The library's innovative approach fundamentally reimagines how developers interact with sequences of data, providing both unprecedented performance characteristics and developer ergonomics in a single, cohesive package.
-
-## Core Philosophy: Separation of Definition and Execution
-A key architectural insight of Semantic-TypeScript is the clear separation between a stream's definition and its execution:
-
-- **Semantic<E>**: An immutable, lazy blueprint of a data transformation pipeline. It defines what operations (filter, map, etc.) will be performed
-- **Collectable<E>**: A materialised, executable view of the stream. It is obtained from a Semantic and provides all terminal operations (collect, forEach, etc.) to execute the pipeline and produce a result
-
-This separation enforces a clean mental model and unlocks powerful optimisations, such as choosing an UnorderedCollectable to skip unnecessary sorting for maximum speed.
-
-## Why Choose Semantic-TypeScript?
-Selecting the right library for data stream processing involves balancing performance, type safety, and expressiveness. Semantic-TypeScript is engineered to excel across all these dimensions.
-
-### 1. A Unified, Type-Safe Paradigm for All Data Sequences
-It provides a consistent, declarative API for processing any data sequence—be it static arrays, real-time events, or asynchronous chunks—while leveraging TypeScript's full power to ensure end-to-end type safety. This eliminates a whole class of runtime errors and transforms stream manipulation into a predictable, compiler-verified activity.
-
-### 2. Uncompromising Performance with Intelligent Laziness
-At its core, the library is built on lazy evaluation. Operations like filter, map, and flatMap merely compose a processing pipeline; no work is done until a terminal operation is invoked. This is coupled with short-circuiting capabilities (via limit, anyMatch, or custom interrupt callbacks), which allows processing to stop early, dramatically improving efficiency for large or infinite streams.
-
-### 3. The Power of the `Collector<E, A, R>` Pattern
-Inspired by Java, the Collector pattern is the engine of flexibility. It decouples the specification of how to accumulate stream elements from the execution of the stream itself. The library provides a rich set of built-in collectors (toArray, groupBy, summate, etc.) for everyday tasks, while making it trivial to implement your own complex, reusable reduction logic. This is far more powerful and composable than a fixed set of terminal methods.
-
-### 4. First-Class Support for Modern Web & Async Data
-Semantic-TypeScript is designed for contemporary development. It offers native factory methods for modern web sources:
-
-- `useFrom(iterable)`, `useRange()` for static data
-- `useInterval()`, `useAnimationFrame()` for time-based streams
-- `useBlob()` for chunked binary data processing
-- `useWebSocket()`, `useDocument()`, `useWindow()` for real-time event streams
-
-### 5. Beyond Basic Aggregation: Built-in Statistical Analysis
-Move beyond simple sums and averages. The library provides dedicated NumericStatistics and BigIntStatistics interfaces, offering immediate access to advanced statistical measures directly from your streams—variance, standard deviation, median, skewness, and kurtosis. This turns complex data analysis into a one-liner.
-
-### 6. Designed for Developer Ergonomics
-- **Fluent, Chainable API**: Write complex data pipelines as readable, sequential chains
-- **Comprehensive Utility Suite**: Essential guards (isFunction, isIterable), utilities (useCompare, useTraverse), and functional interfaces included
-- **Optional<T> Integration**: Safely models the absence of a value, eliminating null-pointer concerns
-- **Performance Guidance**: Clear guidance on when to use unordered collection for speed versus ordered for sequence
-
-## Installation
-```bash
-npm install semantic-typescript
-```
-
-## Core Concepts in Practice
-
-### 1. Creating Streams (Semantic)
-Streams can be created from various sources using factory functions.
-
-```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
-
-// From a static array
-const staticStream = useFrom([1, 2, 3, 4, 5]);
-
-// From an asynchronous generator
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
-
-// A time-based stream
-const tickStream = useInterval(1000); // emits every second
-
-// A DOM event stream (see crucial note below)
-const clickStream = useDocument('click');
-```
-
-### 2. Transforming Streams (Intermediate Operations)
-Operations are lazily chained to define the pipeline.
-
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0)  // Keep only even numbers
-  .map(x => x * 10)          // Multiply by 10
-  .flatMap(x => [x, x + 1])  // Transform each element into two
-  .distinct();               // Remove duplicates
-
-// Nothing has been executed yet
-```
-
-### 3. Executing Streams (Terminal Operations)
-To get a result, you must obtain a Collectable and invoke a terminal operation.
-
-```typescript
-// Get an unordered collectable for performance
-const resultArray = await processedStream.toUnordered().toArray();
-console.log(resultArray); // e.g., [20, 21, 40, 41]
-
-// Use a built-in collector
-const sum = await processedStream.toUnordered().collect(useSummate());
-console.log(sum);
-
-// Or use the generic collect method
-const customResult = await processedStream.toOrdered().collect(
-  () => new Map<number, number>(),
-  (map, element, index) => map.set(index, element),
-  map => map
-);
-```
-
-### 4. Crucial: Working with Event Streams
-Event streams (useDocument, useWindow, useHTMLElement, useWebSocket) are infinite by nature. You must use operations like sub, takeWhile, or limit to define when to stop collecting events and complete the stream. Otherwise, the terminal operation will wait indefinitely.
-
-```typescript
-import { useDocument } from 'semantic-typescript';
-
-// Collect only the first 5 clicks
-const first5Clicks = await useDocument('click')
-  .limit(5) // <- Essential: limits the stream to 5 events
-  .toUnordered()
-  .toArray();
-
-// Collect clicks for a 10-second window
-const clicksIn10s = await useDocument('click')
-  .takeWhile((_, index, startTime = Date.now()) => Date.now() - startTime < 10000)
-  .toUnordered()
-  .toArray();
-
-// Collect clicks from index 2 to 5 (0-based)
-const specificClicks = await useDocument('click')
-  .sub(2n, 6n) // <- Takes elements with index 2, 3, 4, 5
-  .toUnordered()
-  .toArray();
-```
-
-**Key Insight**: The event (e.g., a MouseEvent) and its sequential firing index (as a bigint) are passed together through the pipeline via the `accept(event, index)` callback.
-
-### 5. Leveraging Statistics
-```typescript
-const numericStream = useFrom([10, 20, 30, 40, 50]).toNumeric();
-
-const average = await numericStream.average();
-const median = await numericStream.median();
-const standardDeviation = await numericStream.standardDeviation();
-const skewness = await numericStream.skewness();
-
-console.log(`Average: ${average}, Median: ${median}, StdDev: ${standardDeviation}`);
-```
-
-## Main Features
-- **Dual Stream Types**: Full support for both SynchronousSemantic (for Iterable) and AsynchronousSemantic (for AsyncIterable and events)
-- **Rich Operation Set**: filter, map, flatMap, concat, distinct, sorted, limit, skip, peek, reverse, shuffle
-- **Flexible Terminal Operations**: collect (with custom collectors), toArray, toSet, toMap, forEach, reduce, findFirst, anyMatch, allMatch, count
-- **Advanced Collectors**: Built-in collectors for joining, groupingBy, partitioningBy, summing, averaging, maxBy, minBy
-- **Statistical Module**: Ready-to-use methods for mean, median, mode, variance, standardDeviation, range, quantiles, skewness, kurtosis on numeric/bigint streams
-- **Utility Functions**: Type guards (isPromise, isAsyncIterable), comparators (useCompare), traversal (useTraverse), and conversion hooks
-- **Optional<T>**: A monadic container for nullable values, integrated with find operations
-
-## API Overview
-### Core Classes & Interfaces
-- `Semantic<E>` / `AsynchronousSemantic<E>`: The abstract stream definition
-- `Collectable<E>` / `AsynchronousCollectable<E>`: The executable stream with terminal operations
-- `OrderedCollectable<E>` / `UnorderedCollectable<E>`: Materialised versions optimised for order-sensitive or order-insensitive operations
-- `Collector<E, A, R>`: The abstraction for mutable reduction operations
-
-### Factory Functions (use*)
-- **From Sources**: useFrom, useRange, useFill, useEmpty
-- **From Time**: useInterval, useAnimationFrame
-- **From Web APIs**: useBlob, useDocument, useWindow, useHTMLElement, useWebSocket
-- **Collectors**: useToArray, useGroupBy, useSummate, useJoin, etc.
-
-## Performance Notes
-- **Lazy Evaluation**: Pipelines are composed without execution until a terminal operation is called
-- **Short-Circuiting**: Operations like limit, anyMatch, and findFirst will stop processing elements as soon as the result is determined
-- **Ordered vs Unordered**:
-  - Use `.toUnordered()` for terminal operations when the order of the source elements does not matter to your result (e.g., for sum, max, or toSet). This can allow internal optimisations that skip costly sorting steps
-  - Use `.toOrdered()` when sequence is important (e.g., for toArray where order must be preserved)
-
-## Getting Started Example
-```typescript
-import { useFrom, useSummate, useGroupBy } from 'semantic-typescript';
-
-interface Transaction {
-  id: number;
-  amount: number;
-  category: string;
-}
-
-const transactions: Transaction[] = [
-  { id: 1, amount: 100, category: 'Food' },
-  { id: 2, amount: 200, category: 'Electronics' },
-  { id: 3, amount: 50, category: 'Food' },
-  { id: 4, amount: 300, category: 'Electronics' },
-];
-
-// Calculate total amount per category
-const totalsByCategory = await useFrom(transactions)
-  .toUnordered()
-  .collect(
-    useGroupBy(
-      t => t.category,
-      t => t.amount,
-      useSummate() // Collector for the values
-    )
-  );
-
-console.log(totalsByCategory); // Map { 'Food' => 150, 'Electronics' => 500 }
-```
-
-Semantic-TypeScript is built for developers who seek a rigorously designed, type-safe, and high-performance stream processing library. It brings the power of enterprise-level data transformation patterns to the TypeScript ecosystem, perfectly suited for data-intensive front-end applications, Node.js data processing, and any scenario where elegant, efficient handling of sequences is required.
-
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript) 
+# **Semantic-TypeScript**
+**Flow, Indexed.** Your data, under precise control.
+
+---
+
+### Overview
+
+Semantic-TypeScript marks a significant leap forward in stream processing technology, **synthesising** the most effective concepts from JavaScript `GeneratorFunction`, Java Streams, and MySQL-style indexing. Its core philosophy is both simple and powerful: construct exceptionally efficient data-processing pipelines through intelligent indexing, not through brute-force iteration.
+
+Where conventional libraries impose synchronous loops or unwieldy promise chains, Semantic-TypeScript delivers a **fully asynchronous**, functionally pure, and rigorously type-safe experience, designed for the demands of modern front-end development.
+
+In its elegant model, data only reaches the consumer when the upstream pipeline explicitly invokes the `accept` (and optionally `interrupt`) callbacks. You have complete control over the timing—exactly when it is needed.
+
+---
+
+### Why Developers Prefer It
+
+- **Zero-Boilerplate Indexing** — every element carries its natural or bespoke index.
+- **Pure Functional Style** — with full TypeScript inference.
+- **Leak-Proof Event Streams** — `useWindow`, `useDocument`, `useHTMLElement`, and `useWebSocket` are built with safety in mind. You define the boundary—using `limit(n)`, `sub(start, end)`, or `takeWhile(predicate)`—and the library manages the cleanup. No lingering listeners, no memory leaks.
+- **Built-in Statistics** — comprehensive numeric and bigint analytics including averages, medians, modes, variance, skewness, and kurtosis.
+- **Predictable Performance** — choose between ordered or unordered collectors based on your requirements.
+- **Memory-Efficient** — streams are evaluated lazily, alleviating memory concerns.
+- **No Undefined Behaviour** — TypeScript guarantees type safety and nullability. Input data remains unmodified unless explicitly altered within your callback functions.
+
+---
+
+### Installation
+
+```bash
+npm install semantic-typescript
+```
+or
+```bash
+yarn add semantic-typescript
+```
+
+---
+
+### Quick Start
+
+```typescript
+import { useOf, useFrom, useRange, useWindow, useHTMLElement, useWebSocket, useText, useStringify } from "semantic-typescript";
+
+// Numeric statistics
+let summate: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)
+  .toNumericStatistics()  // Required before terminal operation
+  .summate();             // 200
+
+// Bigint statistics
+let summate: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2)
+  .toBigIntStatistics()   // Required before terminal operation
+  .summate();             // 200n
+
+// Reverse a stream by index
+useFrom([1, 2, 3, 4, 5])
+  .redirect((element: E, index: bigint): bigint => -index) // Negative index for reversal
+  .toOrdered() // Call toOrdered() to preserve index order
+  .toArray(); // [5, 4, 3, 2, 1]
+
+// Shuffle a stream
+useFrom([1, 2, 3, 4, 5])
+  .shuffle()
+  .toOrdered()
+  .toArray(); // e.g., [2, 5, 1, 4, 3]
+
+// Translate elements within a stream
+useFrom([1, 2, 3, 4, 5])
+  .translate(2)  // Shift elements right by 2 positions
+  .toOrdered()
+  .toArray(); // [4, 5, 1, 2, 3]
+
+useFrom([1, 2, 3, 4, 5])
+  .translate(-2) // Shift elements left by 2 positions
+  .toOrdered()
+  .toArray(); // [3, 4, 5, 1, 2]
+
+// Infinite range with early termination
+useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)
+  .limit(10n)          // Stop after 10 elements
+  .toUnordered()
+  .toArray();
+
+// Real-time window resize (stops automatically after 5 events)
+useWindow("resize")
+  .limit(5n)          // Crucial for event streams
+  .toUnordered()
+  .forEach((ev, idx) => console.log(`Resize #${idx}`));
+
+// Listen to an HTML element
+// <input id="input" type="text"/>
+useHTMLElement("#input", "change")
+  .limit(1)
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
+
+// Listen to multiple elements and events
+useHTMLElement("input", ["change", "keyup"])
+  .takeWhile((event: Event): boolean => validate(event))
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
+
+// Listen to a WebSocket
+let webSocket = new WebSocket("ws://localhost:8080");
+webSocket.addEventListener("close", (): void => {
+  webSocket.close();  // Manage the WebSocket lifecycle manually
+});
+useWebSocket(webSocket, "message")
+  .limit(1)
+  .toUnordered()
+  .forEach((message: MessageEvent) => console.log(message.data));
+
+// Iterate over a string by code point
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // Outputs the string
+
+// Safely stringify an object with circular references
+let o = {
+  a: 1,
+  b: "text",
+  c: [o.a, o.b, o.c] // Circular reference
+};
+// let text: string = JSON.stringify(o); // Throws an error
+let text: string = useStringify(o); // Safely yields `{a: 1, b: "text", c: []}`
+```
+
+---
+
+### Core Concepts
+
+| Concept | Purpose | When to Use |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | Core builder for asynchronous streams, events, and lazy pipelines. | Real-time events, WebSockets, DOM listeners, long-running or infinite streams. |
+| `SynchronousSemantic` | Builder for synchronous, in-memory, or loop-based streams. | Static data, ranges, immediate iteration. |
+| `toUnordered()` | Fastest terminal collector (Map-based indexing). | Performance-critical paths (O(n) time & space, no sorting). |
+| `toOrdered()` | Sorted, index-stable collector. | When stable ordering or indexed access is required. |
+| `toNumericStatistics()` | Rich numeric statistical analysis (mean, median, variance, skewness, kurtosis, etc.). | Data analytics and statistical computations. |
+| `toBigIntStatistics()` | Rich bigint statistical analysis. | Data analytics and statistical computations for large integers. |
+| `toWindow()` | Sliding and tumbling window support. | Time-series processing, batching, and windowed operations. |
+
+---
+
+**Important Usage Rules**
+
+1.  **Event streams** (`useWindow`, `useDocument`, `useHTMLElement`, `useWebSocket`, …) return an `AsynchronousSemantic`.
+    → You **must** call `.limit(n)`, `.sub(start, end)`, or `.takeWhile()` to cease listening. Otherwise, the listener remains active.
+
+2.  **Terminal operations** (`.toArray()`, `.count()`, `.average()`, `.reduce()`, `.findFirst()`, etc.) are **only available after** conversion to a collector:
+    ```typescript
+    .toUnordered()   // O(n) time & space, no sorting
+    // or
+    .toOrdered()     // Sorted, maintains order
+    ```
+
+---
+
+### Performance Characteristics
+
+| Collector | Time Complexity | Space Complexity | Sorted? | Best For |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | No | Raw speed, order not required. |
+| `toOrdered()` | O(2n) | O(n) | Yes | Stable ordering, indexed access, analytics. |
+| `toNumericStatistics()` | O(2n) | O(n) | Yes | Statistical operations requiring sorted data. |
+| `toBigIntStatistics()` | O(2n) | O(n) | Yes | Statistical operations for bigint. |
+| `toWindow()` | O(2n) | O(n) | Yes | Time-based windowing operations. |
+
+Opt for `toUnordered()` when speed is paramount. Use `toOrdered()` only when you require stable ordering or statistical methods that depend on sorted data.
+
+---
+
+**Comparison with Other Front-End Stream Processors**
+
+| Feature | Semantic-TypeScript | RxJS | Native Async Iterators / Generators | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **TypeScript Integration** | First-class, deeply typed with native index awareness. | Excellent, but involves complex generics. | Good, requires manual typing. | Strong, functional-first style. |
+| **Built-in Statistical Analysis** | Comprehensive native support for `number` and `bigint`. | Not available natively (requires custom operators). | None. | None. |
+| **Indexing & Position Awareness** | Native, powerful bigint indexing on every element. | Requires custom operators (`scan`, `withLatestFrom`). | Manual counter required. | Basic, no built-in index. |
+| **Event Stream Management** | Dedicated, type-safe factories with explicit early-stop control. | Powerful but requires manual subscription management. | Manual event listener + cancellation. | Good `fromEvent`, lightweight. |
+| **Performance & Memory Efficiency** | Exceptional – optimised `toUnordered()` and `toOrdered()` collectors. | Very good, but operator chains add overhead. | Excellent (zero overhead). | Excellent. |
+| **Bundle Size** | Very lightweight. | Large (even with tree-shaking). | Zero (native). | Small. |
+| **API Design Philosophy** | Functional collector pattern with explicit indexing. | Reactive Observable pattern. | Iterator / Generator pattern. | Functional, point-free. |
+| **Early Termination & Control** | Explicit (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Good (`take`, `takeUntil`, `first`). | Manual (`break` in `for await…of`). | Good (`take`, `until`). |
+| **Synchronous & Asynchronous Support** | Unified API – first-class support for both. | Primarily asynchronous. | Both, but manual. | Primarily asynchronous. |
+| **Learning Curve** | Gentle for developers familiar with functional and indexed pipelines. | Steeper (many operators, hot/cold observables). | Low. | Moderate. |
+
+**Key Advantages of Semantic-TypeScript**
+
+*   Unique built-in statistical and indexing capabilities, eliminating the need for manual `reduce` or external libraries.
+*   Explicit control over event streams prevents the memory leaks common in RxJS.
+*   A unified synchronous/asynchronous design provides a single, consistent API for diverse use cases.
+
+This comparison illustrates why Semantic-TypeScript is particularly well-suited for modern TypeScript front-end applications that demand performance, type safety, and rich analytics without the ceremony of traditional reactive libraries.
+
+---
+
+### Ready to Explore?
+
+Semantic-TypeScript transforms complex data flows into readable, composable, and high-performance pipelines. Whether you are handling real-time UI events, processing large datasets, or building analytics dashboards, it provides the power of database-grade indexing with the elegance of functional programming.
+
+**Next Steps:**
+
+*   Browse the fully typed API in your IDE (all exports are from the main package).
+*   Join the growing community of developers who have replaced convoluted async iterators with clean Semantic pipelines.
+
+**Semantic-TypeScript** — where streams meet structure.
+
+Begin building today and experience the difference that thoughtful indexing delivers.
+
+**Build with clarity, proceed with confidence, and transform data with intent.**