semantic-typescript 0.6.0 → 0.7.1

package/readme.md

@@ -1,214 +1,270 @@
-# 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 represents a significant evolution in stream processing, elegantly **synthesising** the most effective paradigms from JavaScript generators, Java Streams, and MySQL-style indexing. Its foundational premise is both powerful and deliberate: to construct exceptionally efficient data‑processing pipelines through intelligent indexing, rather than through conventional brute‑force iteration.
+
+Where typical libraries enforce synchronous loops or unwieldy promise chains, Semantic‑TypeScript provides a **fully asynchronous**, functionally pure, and rigorously type‑safe experience, designed expressly for the demands of modern application development.
+
+This model embodies a refined form of control flow: data only proceeds to the consumer when the upstream pipeline explicitly invokes the `accept` callback. You retain complete, granular command over timing—processing occurs precisely when, and only when, it is required.
+
+---
+
+### Why Developers Choose Semantic‑TypeScript
+
+- **Zero‑Boilerplate Indexing** – Every element inherently possesses its natural or bespoke index, eliminating manual tracking.
+- **Purely Functional & Type‑Safe** – Enjoy full, idiomatic TypeScript inference alongside immutable operations.
+- **Leak‑Proof Event Streams** – The `useSubscription` pattern is designed with resource safety as a first principle. You define the logical boundary—using `limit(n)`, `sub(start, end)`, or `takeWhile(predicate)`—and the library manages the complete subscription lifecycle. This ensures no lingering listeners and no memory leaks.
+- **Built‑in Statistical Suite** – Access comprehensive analytics for both `number` and `bigint` streams, including averages, medians, modes, variance, skewness, and kurtosis without external dependencies.
+- **Predictable, Tunable Performance** – Select between ordered or unordered collectors to match your exact performance and ordering requirements.
+- **Inherently Memory‑Efficient** – Streams are evaluated lazily, processing elements on‑demand to alleviate memory pressure.
+- **No Undefined Behaviour** – TypeScript guarantees complete type safety and nullability. Your source data remains immutable unless explicitly altered within your callback functions.
+
+---
+
+### Installation
+
+Integrate Semantic‑TypeScript into your project using your preferred package manager:
+
+```bash
+npm install semantic-typescript
+```
+or
+```bash
+yarn add semantic-typescript
+```
+
+---
+
+### A Practical Introduction
+
+The following examples demonstrate core concepts, from foundational transformations to real‑world event handling.
+
+```typescript
+import { useOf, useFrom, useRange, useSubscription, useText, useStringify } from "semantic-typescript";
+
+// ====================================================================
+// EXAMPLE 1: Foundational Operations & Numeric Statistics
+// ====================================================================
+// Demonstrates mapping and terminal statistical operations. After transformation,
+// the pipeline must be converted to a statistics collector before calling
+// terminal methods like `.summate()`.
+
+const numericSum: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)        // Double each element: [20, 40, 60, 80]
+  .toNumericStatistics()                     // Convert to a statistics collector
+  .summate();                               // Terminal operation: 200
+
+// Additional statistical methods (available after .toNumericStatistics()):
+// .average(), .median(), .mode(), .variance(), .skewness(), .kurtosis()
+
+// ====================================================================
+// EXAMPLE 2: BigInt Statistics
+// ====================================================================
+// Operates identically to numeric statistics but is optimised for BigInt data.
+
+const bigintSum: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2n)       // BigInt arithmetic
+  .toBigIntStatistics()                      // Convert to BigInt statistics collector
+  .summate();                                // Terminal operation: 200n
+
+// ====================================================================
+// EXAMPLE 3: Index Manipulation for Stream Reversal
+// ====================================================================
+// Illustrates reordering elements by strategically reassigning their indices
+// using the `.redirect()` method, enabling custom patterns like reversal.
+
+const reversedArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .redirect((_element: number, index: bigint): bigint => -index) // Map to negative indices
+  .toOrdered()  // Essential: collects elements sorted by their new indices
+  .toArray();   // Result: [5, 4, 3, 2, 1]
+
+// For simple reversal, `.reverse()` is also available.
+
+// ====================================================================
+// EXAMPLE 4: Stream Shuffling
+// ====================================================================
+// Randomly permutes element indices using an in-place shuffle algorithm.
+
+const shuffledArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .shuffle()      // Randomly reassigns indices
+  .toOrdered()    // Orders by the new random indices
+  .toArray();     // e.g., [2, 5, 1, 4, 3] (varies per execution)
+
+// ====================================================================
+// EXAMPLE 5: Circular Stream Rotation
+// ====================================================================
+// Shifts elements cyclically. Positive values rotate right; negative values rotate left.
+
+// Right rotation by 2 positions
+const rightRotated: number[] = useFrom([1, 2, 3, 4, 5])
+  .translate(2)   // Shift indices right by 2
+  .toOrdered()
+  .toArray();     // Result: [4, 5, 1, 2, 3]
+
+// ====================================================================
+// EXAMPLE 6: Lazy Evaluation with Infinite Ranges
+// ====================================================================
+// Processes theoretically infinite streams lazily, computing elements only as needed.
+
+const firstTenMultiples: bigint[] = useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)  // Keep multiples of 17
+  .limit(10n)                   // Critical: stops after the 10th match
+  .toUnordered()                // No sorting required
+  .toArray();                   // Result: [0, 17, 34, 51, 68, 85, 102, 119, 136, 153]
+
+// Without `.limit(10n)`, the pipeline would process all one million elements.
+
+// ====================================================================
+// EXAMPLE 7: Composing a Complex Pipeline
+// ====================================================================
+// Demonstrates sequential composition of multiple operations.
+
+const complexResult: number[] = useRange(1n, 100n)
+  .map(n => Number(n) * 2)
+  .filter(n => n > 50)
+  .shuffle()
+  .limit(5n)
+  .translate(2)
+  .toOrdered()
+  .toArray();
+
+// ====================================================================
+// EXAMPLE 8: Managed DOM Event Subscription
+// ====================================================================
+// Listens to browser events with automatic, leak-proof cleanup.
+// The `.limit(n)` call defines the boundary for automatic listener removal.
+
+// Define a subscriber for a Window target
+const windowSubscriber = {
+    mount: (target: Window): void => { /* Setup logic */ },
+    subscribe: (target: Window, event: keyof WindowEventMap, handler: EventListener): void => {
+        target.addEventListener(event, handler);
+    },
+    unsubscribe: (target: Window, event: keyof WindowEventMap, handler: EventListener): void => {
+        target.removeEventListener(event, handler);
+    },
+    unmount: (): void => { /* Cleanup logic */ }
+};
+
+useSubscription(window, windowSubscriber, "resize")
+  .limit(5n) // Automatically unsubscribes after 5 events
+  .toUnordered()
+  .forEach((ev: Event, idx) =>
+    console.log(`Resize #${idx}: ${(ev.target as Window).innerWidth}x${(ev.target as Window).innerHeight}`)
+  );
+
+// ====================================================================
+// EXAMPLE 9: String Processing by Unicode Code Points
+// ====================================================================
+// Iterates over a string correctly, handling multi-byte Unicode characters.
+
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // Logs each character, including emoji, on a new line.
+
+// ====================================================================
+// EXAMPLE 10: Safe Circular Reference Stringification
+// ====================================================================
+// Safely serialises objects containing circular references.
+
+const obj = {
+  a: 1,
+  b: "text"
+};
+(obj as any).c = [obj.a, obj.b, (obj as any).c]; // Introduce circularity
+
+// const text: string = JSON.stringify(obj); // Throws an error
+const text: string = useStringify(obj); // Safely yields `{a: 1, b: "text", c: []}`
+```
+
+---
+
+### Core Concepts
+
+| Concept | Purpose | Primary Use Case |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | The core builder for asynchronous streams, events, and lazy, push‑based pipelines. | Real‑time events, WebSockets, DOM listeners, or any long‑running/infinite stream. |
+| `SynchronousSemantic` | The builder for synchronous, in‑memory, or eager, pull‑based streams. | Static data, finite ranges, or immediate iteration tasks. |
+| `toUnordered()` | The fastest terminal collector, using a Map for index storage. | Performance‑critical paths where stable order is not required (O(n) time & space). |
+| `toOrdered()` | A sorted, index‑stable terminal collector. | When element order must be preserved or indexed access is needed. |
+| `toNumericStatistics()` | A collector enabling rich statistical analysis on `number` streams. | Data analytics, metrics, and statistical computations. |
+| `toBigIntStatistics()` | A collector enabling rich statistical analysis on `bigint` streams. | Analytics and statistics for large integer datasets. |
+| `toWindow()` | Provides sliding and tumbling window operations over a stream. | Time‑series analysis, batch processing, and windowed aggregations. |
+
+---
+
+**Essential Usage Rules**
+
+1.  **Event streams** (created via factories like `useSubscription`) return an `AsynchronousSemantic`.
+    → You **must** call a boundary‑defining method like `.limit(n)`, `.sub(start, end)`, or `.takeWhile(predicate)` to terminate the listener. Failure to do so will leave the subscription active.
+
+2.  **Terminal operations** (`.toArray()`, `.count()`, `.forEach()`, `.findFirst()`, etc.) are **only available after** converting the pipeline to a collector:
+    ```typescript
+    .toUnordered()   // For maximum speed, order not guaranteed.
+    // or
+    .toOrdered()     // For stable, sorted output.
+    // or
+    .toNumericStatistics() // For statistical methods.
+    ```
+
+---
+
+### Performance Characteristics
+
+| Collector | Time Complexity | Space Complexity | Order Guarantee? | Ideal Scenario |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | No | Raw throughput is key; final order is irrelevant. |
+| `toOrdered()` | O(n log n) | O(n) | Yes (sorted) | Stable ordering, indexed access, or pre‑sorting for statistics. |
+| `toNumericStatistics()` | O(n log n) | O(n) | Yes (internal sort) | Performing statistical operations which require sorted data. |
+| `toBigIntStatistics()` | O(n log n) | O(n) | Yes (internal sort) | Statistical operations on BigInt data. |
+| `toWindow()` | O(n log n) | O(n) | Yes (internal sort) | Windowing operations which benefit from sorted indices. |
+
+Select `toUnordered()` when absolute speed is paramount. Opt for `toOrdered()` or a statistics collector only when your logic depends on element order.
+
+---
+
+**Comparative Analysis with Contemporary Stream Libraries**
+
+| Feature | Semantic‑TypeScript | RxJS | Native Async Iterators / Generators | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **TypeScript Integration** | First‑class, deeply typed with inherent index awareness. | Excellent, though often involving complex generic chains. | Good, but requires manual type annotations. | Strong, with a functional‑first typing style. |
+| **Built‑in Statistical Analysis** | Comprehensive native support for `number` and `bigint`. | Not available natively (requires custom operators or other libraries). | None. | None. |
+| **Indexing & Position Awareness** | Native, powerful BigInt indexing on every element. | Requires custom operators (e.g., `scan`, `withLatestFrom`). | Manual counter management is necessary. | Basic, no built‑in index property. |
+| **Event Stream Management** | Dedicated, type‑safe factories with explicit, declarative lifecycle control. | Powerful but requires careful manual subscription management to prevent leaks. | Manual event listener attachment and cancellation token management. | Good `fromEvent`, generally lightweight. |
+| **Performance & Memory** | Exceptional – offers optimised `toUnordered()` and `toOrdered()` collectors. | Very good, though deep operator chains can introduce overhead. | Excellent (minimal native overhead). | Excellent. |
+| **Bundle Size** | Very lightweight. | Substantial (even with tree‑shaking). | Zero (native language feature). | Small. |
+| **API Design Philosophy** | Functional collector pattern with explicit indexing semantics. | Reactive Observable pattern. | Imperative Iterator / declarative Generator pattern. | Functional, point‑free composition. |
+| **Flow Control** | Explicit (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Good (`take`, `takeUntil`, `first`). | Manual (`break` in loops). | Good (`take`, `until`). |
+| **Sync & Async Support** | Unified API – first‑class support for both paradigms. | Primarily asynchronous. | Both supported, but with manual bridging. | Primarily asynchronous. |
+| **Learning Curve** | Gentle for developers familiar with functional and indexed collection pipelines. | Steeper (extensive operator lexicon, hot/cold observable concepts). | Low to moderate. | Moderate. |
+
+**The Semantic‑TypeScript Advantage**
+
+*   **Unique Capabilities:** Integrated statistical and indexing features eliminate the need for manual `reduce` operations or supplementary data‑analysis libraries.
+*   **Predictable Resource Management:** Explicit control over event streams prevents the memory leaks that can be subtle in RxJS applications.
+*   **Unified Design:** A consistent API for both synchronous and asynchronous workflows reduces cognitive load and code duplication.
+
+This comparison highlights why Semantic‑TypeScript is particularly well‑suited for modern TypeScript applications that demand high performance, robust type safety, and rich data‑processing features without the complexity of traditional reactive frameworks.
+
+---
+
+### Begin Your Exploration
+
+Semantic‑TypeScript transforms intricate data flows into readable, composable, and high‑performance pipelines. Whether you are handling real‑time UI events, processing substantial datasets, or constructing analytical dashboards, it delivers the power of database‑grade indexing with the elegance of functional programming.
+
+**Your Next Steps:**
+
+*   Explore the fully typed API directly within your IDE (all exports are available from the main package entry point).
+*   Join the growing community of developers who have replaced convoluted async iterators and complex reactive chains with clear, intentional Semantic pipelines.
+
+**Semantic‑TypeScript** — where streams meet structure.
+
+Begin building today and experience the tangible difference that thoughtful indexing delivers.
+
+**Build with clarity, proceed with confidence, and transform data with intent.**
+
+MIT © Eloy Kim