semantic-typescript 0.6.0 → 0.7.1

package/readme.de.md

@@ -1,214 +1,267 @@
-# Semantic-TypeScript: Eine bahnbrechende Stream-Processing-Bibliothek
+# **Semantic‑TypeScript**
+**Ströme, indiziert.** Ihre Daten unter präziser Kontrolle.
 
-## Einführung
-Semantic-TypeScript stellt einen bedeutenden Fortschritt in der Stream-Processing-Technologie dar und vereint die effektivsten Konzepte aus JavaScript GeneratorFunctions, Java Streams und Datenbank-Indizierungs-Paradigmen. Ihr grundlegendes Designprinzip zielt darauf ab, durch ausgeklügelte verzögerte Auswertung (Lazy Evaluation) und intelligente Indizierung äußerst effiziente Datenverarbeitungspipelines zu konstruieren. Die Bibliothek bietet eine streng typensichere, funktional reine Streaming-Operation-Erfahrung, die speziell für die moderne TypeScript- und JavaScript-Entwicklung entwickelt wurde.
+---
 
-Im Gegensatz zu herkömmlichen synchronen Verarbeitungsarchitekturen implementiert Semantic-TypeScript ein einheitliches Modell, das sowohl synchrone (Iterable) als auch asynchrone (AsyncIterable) Datenquellen elegant behandelt. Während der Stream-Erzeugung werden der Fluss und die Beendigung von Daten präzise durch Callback-Mechanismen gesteuert, was es der Bibliothek ermöglicht, mit außergewöhnlicher Anmut zu arbeiten:
+### Überblick
 
--   Echtzeit-Datenströme (DOM-Events, WebSockets, Intervalle) mit deterministischer Kontrolle
--   Große Datensätze über speichereffiziente, verzögerte Pipelines
--   Komplexe Datentransformationen mit einer fließenden, deklarativen API
+Semantic‑TypeScript stellt eine bedeutende Weiterentwicklung in der Stream‑Verarbeitung dar und vereint elegant die effektivsten Paradigmen aus JavaScript‑Generatoren, Java‑Streams und MySQL‑artiger Indizierung. Die Grundidee ist sowohl leistungsfähig als auch bewusst gewählt: Ausnahmslos effiziente Datenverarbeitungspipelines durch intelligente Indizierung zu konstruieren, anstatt durch konventionelle Brute‑Force‑Iteration.
 
-Der innovative Ansatz der Bibliothek überdenkt grundlegend, wie Entwickler mit Datenfolgen interagieren, und bietet beispiellose Leistungsmerkmale und Entwicklerfreundlichkeit in einem einzigen, kohärenten Paket.
+Wo typische Bibliotheken synchrone Schleifen oder umständliche Promise‑Ketten erzwingen, bietet Semantic‑TypeScript eine **vollständig asynchrone**, funktional reine und rigoros typsichere Erfahrung, die ausdrücklich für die Anforderungen moderner Anwendungsentwicklung konzipiert ist.
 
-## Kernphilosophie: Trennung von Definition und Ausführung
-Eine zentrale architektonische Erkenntnis von Semantic-TypeScript ist die klare Trennung zwischen der Definition eines Streams und seiner Ausführung:
+Dieses Modell verkörpert eine raffinierte Form des Kontrollflusses: Daten werden nur dann an den nachgelagerten Verbraucher weitergegeben, wenn die vorgelagerte Pipeline explizit den `accept`‑Callback aufruft. Sie behalten die vollständige, granulare Kontrolle über den Zeitpunkt – die Verarbeitung erfolgt genau dann und nur dann, wenn es erforderlich ist.
 
--   **Semantic<E>**: Eine unveränderliche, verzögerte Blaupause einer Datentransformationspipeline. Sie definiert, welche Operationen (Filter, Map usw.) ausgeführt werden.
--   **Collectable<E>**: Eine materialisierte, ausführbare Ansicht des Streams. Sie wird von einem Semantic erhalten und stellt alle Terminaloperationen (collect, forEach usw.) zur Ausführung der Pipeline und Erzeugung eines Ergebnisses bereit.
+---
 
-Diese Trennung erzwingt ein klares mentales Modell und ermöglicht leistungsstarke Optimierungen, wie z. B. die Auswahl eines UnorderedCollectable, um unnötige Sortiervorgänge für maximale Geschwindigkeit zu überspringen.
+### Warum Entwickler Semantic‑TypeScript wählen
 
-## Warum Semantic-TypeScript wählen?
-Die Wahl der richtigen Bibliothek für die Verarbeitung von Datenströmen erfordert eine Abwägung zwischen Leistung, Typsicherheit und Ausdruckskraft. Semantic-TypeScript ist so konzipiert, dass es in all diesen Dimensionen herausragt.
+-   **Zero‑Boilerplate‑Indizierung** – Jedes Element besitzt inhärent seinen natürlichen oder maßgeschneiderten Index, wodurch manuelle Nachverfolgung entfällt.
+-   **Rein funktional & typsicher** – Genießen Sie vollständige, idiomatische TypeScript‑Inferenz zusammen mit unveränderlichen Operationen.
+-   **Leck‑sichere Ereignisströme** – Das `useSubscription`‑Muster wurde mit Ressourcensicherheit als erstem Prinzip entworfen. Sie definieren die logische Grenze – mittels `limit(n)`, `sub(start, end)` oder `takeWhile(predicate)` – und die Bibliothek verwaltet den vollständigen Abonnement‑Lebenszyklus. Dies stellt sicher, dass keine verbleibenden Listener und keine Speicherlecks entstehen.
+-   **Integrierte Statistik‑Suite** – Greifen Sie ohne externe Abhängigkeiten auf umfassende Analysen für sowohl `number`‑ als auch `bigint`‑Ströme zu, einschließlich Mittelwert, Median, Modus, Varianz, Schiefe und Kurtosis.
+-   **Vorhersehbare, fein abstimmbare Leistung** – Wählen Sie zwischen geordneten oder ungeordneten Sammlern, um Ihren genauen Leistungs‑ und Reihenfolgeanforderungen gerecht zu werden.
+-   **Inherent speichereffizient** – Ströme werden lazy evaluiert, verarbeiten Elemente bei Bedarf und entlasten so den Speicher.
+-   **Kein undefiniertes Verhalten** – TypeScript garantiert vollständige Typsicherheit und Nullsicherheit. Ihre Quelldaten bleiben unveränderlich, es sei denn, sie werden explizit in Ihren Callback‑Funktionen geändert.
 
-### 1. Ein einheitliches, typsicheres Paradigma für alle Datenfolgen
-Es bietet eine konsistente, deklarative API zur Verarbeitung jeder Datenfolge – sei es statische Arrays, Echtzeit-Ereignisse oder asynchrone Datenblöcke – und nutzt gleichzeitig die volle Leistungsfähigkeit von TypeScript, um eine Ende-zu-Ende-Typsicherheit zu gewährleisten. Dadurch wird eine ganze Klasse von Laufzeitfehlern eliminiert und die Stream-Manipulation in eine vorhersehbare, vom Compiler überprüfte Aktivität verwandelt.
+---
 
-### 2. Kompromisslose Leistung durch intelligente Verzögerung (Lazy Evaluation)
-Im Kern basiert die Bibliothek auf Lazy Evaluation. Operationen wie Filter, Map und FlatMap komponieren lediglich eine Verarbeitungspipeline; es wird keine Arbeit ausgeführt, bis eine Terminaloperation aufgerufen wird. Dies wird mit Short-Circuiting-Fähigkeiten (über limit, anyMatch oder benutzerdefinierte Unterbrechungs-Callbacks) kombiniert, wodurch die Verarbeitung vorzeitig gestoppt werden kann, was die Effizienz für große oder unendliche Ströme erheblich verbessert.
+### Installation
 
-### 3. Die Leistungsfähigkeit des `Collector<E, A, R>`-Musters
-Inspiriert von Java ist das Collector-Muster der Motor der Flexibilität. Es entkoppelt die Spezifikation, wie Stream-Elemente akkumuliert werden sollen, von der Ausführung des Streams selbst. Die Bibliothek bietet eine reichhaltige Auswahl an integrierten Collectors (toArray, groupBy, summate usw.) für alltägliche Aufgaben und macht es gleichzeitig einfach, eigene komplexe, wiederverwendbare Reduktionslogiken zu implementieren. Dies ist weitaus leistungsfähiger und komponierbarer als ein fester Satz von Terminalmethoden.
+Integrieren Sie Semantic‑TypeScript mit Ihrem bevorzugten Paketmanager in Ihr Projekt:
 
-### 4. Erstklassige Unterstützung für moderne Web- und asynchrone Daten
-Semantic-TypeScript ist für die moderne Entwicklung konzipiert. Es bietet native Factory-Methoden für moderne Web-Quellen:
-
--   `useFrom(iterable)`, `useRange()` für statische Daten
--   `useInterval()`, `useAnimationFrame()` für zeitbasierte Ströme
--   `useBlob()` für die blockweise Verarbeitung von Binärdaten
--   `useWebSocket()`, `useDocument()`, `useWindow()` für Echtzeit-Ereignisströme
-
-### 5. Jenseits der grundlegenden Aggregation: Integrierte statistische Analyse
-Gehen Sie über einfache Summen und Durchschnitte hinaus. Die Bibliothek bietet dedizierte NumericStatistics- und BigIntStatistics-Schnittstellen, die sofortigen Zugang zu fortschrittlichen statistischen Kennzahlen direkt aus Ihren Strömen ermöglichen – Varianz, Standardabweichung, Median, Schiefe und Kurtosis. Dies verwandelt komplexe Datenanalysen in eine einzelne Codezeile.
-
-### 6. Für eine hervorragende Entwickler-Ergonomie gestaltet
--   **Fließende, verkettbare API**: Schreiben Sie komplexe Datenpipelines als lesbare, sequentielle Ketten.
--   **Umfassendes Utility-Set**: Wesentliche Guards (isFunction, isIterable), Utilities (useCompare, useTraverse) und funktionale Schnittstellen sind enthalten.
--   **Optional<T>-Integration**: Modelliert sicher das Fehlen eines Werts und eliminiert Nullzeiger-Probleme.
--   **Leistungsanleitung**: Klare Hinweise, wann ungeordnete Sammlungen für Geschwindigkeit gegenüber geordneten für die Reihenfolge zu verwenden sind.
-
-## Installation
 ```bash
 npm install semantic-typescript
 ```
+oder
+```bash
+yarn add semantic-typescript
+```
+
+---
 
-## Kernkonzepte in der Praxis
+### Praktische Einführung
 
-### 1. Streams erstellen (Semantic)
-Streams können aus verschiedenen Quellen mithilfe von Factory-Funktionen erstellt werden.
+Die folgenden Beispiele demonstrieren Kernkonzepte, von grundlegenden Transformationen bis zur praktischen Ereignisbehandlung.
 
 ```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
+import { useOf, useFrom, useRange, useSubscription, useText, useStringify } from "semantic-typescript";
+
+// ====================================================================
+// BEISPIEL 1: Grundlegende Operationen & numerische Statistik
+// ====================================================================
+// Demonstriert Mapping und terminale Statistikoperationen. Nach der Transformation muss die Pipeline in einen Statistik‑Collector umgewandelt werden, bevor terminale Methoden wie `.summate()` aufgerufen werden können.
+
+const numericSum: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)        // Verdoppelt jedes Element: [20, 40, 60, 80]
+  .toNumericStatistics()                     // In einen Statistik‑Collector umwandeln
+  .summate();                               // Terminale Operation: 200
+
+// Weitere statistische Methoden (verfügbar nach .toNumericStatistics()):
+// .average(), .median(), .mode(), .variance(), .skewness(), .kurtosis()
+
+// ====================================================================
+// BEISPIEL 2: BigInt‑Statistik
+// ====================================================================
+// Funktioniert identisch zur numerischen Statistik, ist jedoch für BigInt‑Daten optimiert.
+
+const bigintSum: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2n)       // BigInt‑Arithmetik
+  .toBigIntStatistics()                      // In BigInt‑Statistik‑Collector umwandeln
+  .summate();                                // Terminale Operation: 200n
+
+// ====================================================================
+// BEISPIEL 3: Indexmanipulation zur Stromumkehrung
+// ====================================================================
+// Veranschaulicht die Neuanordnung von Elementen durch strategische Neuzuweisung ihrer Indizes mithilfe der `.redirect()`‑Methode, was benutzerdefinierte Muster wie Umkehrung ermöglicht.
+
+const reversedArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .redirect((_element: number, index: bigint): bigint => -index) // Auf negative Indizes abbilden
+  .toOrdered()  // Essentiell: Sammelt Elemente sortiert nach ihren neuen Indizes
+  .toArray();   // Ergebnis: [5, 4, 3, 2, 1]
+
+// Für einfache Umkehrung ist auch `.reverse()` verfügbar.
+
+// ====================================================================
+// BEISPIEL 4: Strom‑Mischen (Shuffle)
+// ====================================================================
+// Permutiert Elementindizes zufällig mit einem In‑Place‑Shuffle‑Algorithmus.
+
+const shuffledArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .shuffle()      // Weist Indizes zufällig neu zu
+  .toOrdered()    // Sortiert nach den neuen zufälligen Indizes
+  .toArray();     // Z.B.: [2, 5, 1, 4, 3] (variiert bei jeder Ausführung)
+
+// ====================================================================
+// BEISPIEL 5: Zirkuläre Strom‑Rotation
+// ====================================================================
+// Verschiebt Elemente zyklisch. Positive Werte rotieren nach rechts; negative Werte nach links.
+
+// Rechts‑Rotation um 2 Positionen
+const rightRotated: number[] = useFrom([1, 2, 3, 4, 5])
+  .translate(2)   // Verschiebt Indizes um 2 nach rechts
+  .toOrdered()
+  .toArray();     // Ergebnis: [4, 5, 1, 2, 3]
+
+// ====================================================================
+// BEISPIEL 6: Lazy Evaluation mit unendlichen Bereichen
+// ====================================================================
+// Verarbeitet theoretisch unendliche Ströme lazy, berechnet Elemente nur bei Bedarf.
+
+const firstTenMultiples: bigint[] = useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)  // Behält Vielfache von 17
+  .limit(10n)                   // Kritisch: Stoppt nach dem 10. Treffer
+  .toUnordered()                // Keine Sortierung erforderlich
+  .toArray();                   // Ergebnis: [0, 17, 34, 51, 68, 85, 102, 119, 136, 153]
+
+// Ohne `.limit(10n)` würde die Pipeline alle eine Million Elemente verarbeiten.
+
+// ====================================================================
+// BEISPIEL 7: Zusammensetzung einer komplexen Pipeline
+// ====================================================================
+// Demonstriert die sequentielle Komposition mehrerer Operationen.
+
+const complexResult: number[] = useRange(1n, 100n)
+  .map(n => Number(n) * 2)
+  .filter(n => n > 50)
+  .shuffle()
+  .limit(5n)
+  .translate(2)
+  .toOrdered()
+  .toArray();
+
+// ====================================================================
+// BEISPIEL 8: Verwaltete DOM‑Ereignis‑Abonnements
+// ====================================================================
+// Hört auf Browser‑Ereignisse mit automatischer, lecksicherer Bereinigung.
+// Der `.limit(n)`‑Aufruf definiert die Grenze für die automatische Listener‑Entfernung.
+
+// Definiere einen Abonnenten für ein Window‑Ziel
+const windowSubscriber = {
+    mount: (target: Window): void => { /* Setup‑Logik */ },
+    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‑Logik */ }
+};
+
+useSubscription(window, windowSubscriber, "resize")
+  .limit(5n) // Automatische Abmeldung nach 5 Ereignissen
+  .toUnordered()
+  .forEach((ev: Event, idx) =>
+    console.log(`Größenänderung #${idx}: ${(ev.target as Window).innerWidth}x${(ev.target as Window).innerHeight}`)
+  );
+
+// ====================================================================
+// BEISPIEL 9: String‑Verarbeitung nach Unicode‑Codepunkten
+// ====================================================================
+// Iteriert korrekt über einen String, behandelt Multi‑Byte‑Unicode‑Zeichen.
 
-// Aus einem statischen Array
-const staticStream = useFrom([1, 2, 3, 4, 5]);
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // Gibt jedes Zeichen (inkl. Emoji) in einer neuen Zeile aus.
 
-// Aus einem asynchronen Generator
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
+// ====================================================================
+// BEISPIEL 10: Sichere Stringifizierung zirkulärer Referenzen
+// ====================================================================
+// Serialisiert sicher Objekte, die zirkuläre Referenzen enthalten.
 
-// Ein zeitbasierter Stream
-const tickStream = useInterval(1000); // emittiert jede Sekunde
+const obj = {
+  a: 1,
+  b: "text"
+};
+(obj as any).c = [obj.a, obj.b, (obj as any).c]; // Führt zirkuläre Referenz ein
 
-// Ein DOM-Ereignisstream (siehe wichtigen Hinweis unten)
-const clickStream = useDocument('click');
+// const text: string = JSON.stringify(obj); // Wirft einen Fehler
+const text: string = useStringify(obj); // Ergibt sicher `{a: 1, b: "text", c: []}`
 ```
 
-### 2. Streams transformieren (Zwischenoperationen)
-Operationen werden träge verkettet, um die Pipeline zu definieren.
+---
 
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0)  // Nur gerade Zahlen behalten
-  .map(x => x * 10)          // Mit 10 multiplizieren
-  .flatMap(x => [x, x + 1])  // Jedes Element in zwei umwandeln
-  .distinct();               // Duplikate entfernen
+### Kernkonzepte
 
-// Bisher wurde noch nichts ausgeführt
-```
+| Konzept | Zweck | Hauptanwendungsfall |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | Der Kern‑Builder für asynchrone Ströme, Ereignisse und push‑basierte lazy Pipelines. | Echtzeit‑Ereignisse, WebSockets, DOM‑Listener oder jeder langlebige/unendliche Strom. |
+| `SynchronousSemantic` | Der Builder für synchrone, speicherinterne oder pull‑basierte eager Ströme. | Statische Daten, endliche Bereiche oder sofortige Iterationsaufgaben. |
+| `toUnordered()` | Der schnellste terminale Collector, verwendet eine Map zur Indexspeicherung. | Leistungskritische Pfade, bei denen stabile Reihenfolge nicht erforderlich ist (O(n) Zeit & Speicher). |
+| `toOrdered()` | Ein sortierter, indexstabiler terminaler Collector. | Wenn die Elementreihenfolge erhalten bleiben muss oder Indexzugriff benötigt wird. |
+| `toNumericStatistics()` | Ein Collector, der umfangreiche statistische Analysen auf `number`‑Strömen ermöglicht. | Datenanalyse, Metriken und statistische Berechnungen. |
+| `toBigIntStatistics()` | Ein Collector, der umfangreiche statistische Analysen auf `bigint`‑Strömen ermöglicht. | Analyse und Statistik für große Integer‑Datensätze. |
+| `toWindow()` | Bietet Sliding‑ und Tumbling‑Window‑Operationen über einen Strom. | Zeitreihenanalyse, Batch‑Verarbeitung und Fenster‑Aggregationen. |
 
-### 3. Streams ausführen (Terminaloperationen)
-Um ein Ergebnis zu erhalten, müssen Sie ein Collectable erhalten und eine Terminaloperation aufrufen.
+---
 
-```typescript
-// Ein ungeordnetes Collectable für Leistung erhalten
-const resultArray = await processedStream.toUnordered().toArray();
-console.log(resultArray); // z.B. [20, 21, 40, 41]
-
-// Einen eingebauten Collector verwenden
-const sum = await processedStream.toUnordered().collect(useSummate());
-console.log(sum);
-
-// Oder die generische collect-Methode verwenden
-const customResult = await processedStream.toOrdered().collect(
-  () => new Map<number, number>(),
-  (map, element, index) => map.set(index, element),
-  map => map
-);
-```
+**Wesentliche Nutzungsregeln**
 
-### 4. Wichtig: Umgang mit Ereignisströmen
-Ereignisströme (useDocument, useWindow, useHTMLElement, useWebSocket) sind von Natur aus unendlich. Sie müssen Operationen wie sub, takeWhile oder limit verwenden, um zu definieren, wann das Sammeln von Ereignissen beendet und der Stream abgeschlossen werden soll. Andernfalls wartet die Terminaloperation unendlich lange.
+1.  **Ereignisströme** (erstellt über Fabriken wie `useSubscription`) geben ein `AsynchronousSemantic` zurück.
+    → Sie **müssen** eine grenzendefinierende Methode wie `.limit(n)`, `.sub(start, end)` oder `.takeWhile(predicate)` aufrufen, um den Listener zu beenden. Andernfalls bleibt das Abonnement aktiv.
 
-```typescript
-import { useDocument } from 'semantic-typescript';
+2.  **Terminale Operationen** (`.toArray()`, `.count()`, `.forEach()`, `.findFirst()`, etc.) sind **erst nach** der Umwandlung der Pipeline in einen Collector **verfügbar**:
+    ```typescript
+    .toUnordered()   // Für maximale Geschwindigkeit, Reihenfolge nicht garantiert.
+    // oder
+    .toOrdered()     // Für stabile, sortierte Ausgabe.
+    // oder
+    .toNumericStatistics() // Für statistische Methoden.
+    ```
 
-// Nur die ersten 5 Klicks sammeln
-const first5Clicks = await useDocument('click')
-  .limit(5) // <- Essentiell: Begrenzt den Stream auf 5 Ereignisse
-  .toUnordered()
-  .toArray();
+---
 
-// Klicks in einem 10-Sekunden-Fenster sammeln
-const clicksIn10s = await useDocument('click')
-  .takeWhile((_, index, startTime = Date.now()) => Date.now() - startTime < 10000)
-  .toUnordered()
-  .toArray();
+### Leistungsmerkmale
 
-// Klicks von Index 2 bis 5 sammeln (0-basiert)
-const specificClicks = await useDocument('click')
-  .sub(2n, 6n) // <- Nimmt Elemente mit Index 2, 3, 4, 5
-  .toUnordered()
-  .toArray();
-```
+| Collector | Zeitkomplexität | Speicherkomplexität | Reihenfolge garantiert? | Ideales Szenario |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | Nein | Rohdurchsatz ist entscheidend; Endreihenfolge irrelevant. |
+| `toOrdered()` | O(n log n) | O(n) | Ja (sortiert) | Stabile Reihenfolge, Indexzugriff oder Vorsortierung für Statistiken. |
+| `toNumericStatistics()` | O(n log n) | O(n) | Ja (interne Sortierung) | Durchführung statistischer Operationen, die sortierte Daten erfordern. |
+| `toBigIntStatistics()` | O(n log n) | O(n) | Ja (interne Sortierung) | Statistische Operationen auf BigInt‑Daten. |
+| `toWindow()` | O(n log n) | O(n) | Ja (interne Sortierung) | Fensteroperationen, die von sortierten Indizes profitieren. |
 
-**Wichtige Erkenntnis**: Das Ereignis (z. B. ein MouseEvent) und sein sequenzieller Auslöseindex (als BigInt) werden über den Callback `accept(event, index)` gemeinsam durch die Pipeline geleitet.
+Wählen Sie `toUnordered()`, wenn absolute Geschwindigkeit entscheidend ist. Entscheiden Sie sich nur dann für `toOrdered()` oder einen Statistik‑Collector, wenn Ihre Logik von der Elementreihenfolge abhängt.
 
-### 5. Statistikfunktionen nutzen
-```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();
+**Vergleichende Analyse mit modernen Stream‑Bibliotheken**
 
-console.log(`Durchschnitt: ${average}, Median: ${median}, Standardabweichung: ${standardDeviation}`);
-```
+| Merkmal | Semantic‑TypeScript | RxJS | Native Async Iterators / Generators | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **TypeScript‑Integration** | Erstklassig, tief typisiert mit inhärenter Index‑Wahrnehmung. | Hervorragend, beinhaltet jedoch oft komplexe Generika‑Ketten. | Gut, erfordert jedoch manuelle Typannotationen. | Stark, mit funktional‑first‑Typisierungsstil. |
+| **Integrierte Statistik‑Analyse** | Umfassende native Unterstützung für `number` und `bigint`. | Nicht nativ verfügbar (erfordert benutzerdefinierte Operatoren oder andere Bibliotheken). | Keine. | Keine. |
+| **Indizierung & Positionsbewusstsein** | Native, leistungsstarke BigInt‑Indizierung für jedes Element. | Erfordert benutzerdefinierte Operatoren (z.B. `scan`, `withLatestFrom`). | Manuelle Zählerverwaltung notwendig. | Basis, keine integrierte Index‑Eigenschaft. |
+| **Ereignisstrom‑Management** | Dedizierte, typsichere Fabriken mit expliziter, deklarativer Lebenszyklus‑Steuerung. | Leistungsstark, erfordert jedoch sorgfältige manuelle Abonnementverwaltung, um Lecks zu verhindern. | Manuelles Anhängen von Event‑Listenern und Verwaltung von Abbruchtokens. | Gutes `fromEvent`, generell leichtgewichtig. |
+| **Leistung & Speicher** | Herausragend – bietet optimierte `toUnordered()` und `toOrdered()` Collector. | Sehr gut, tiefe Operator‑Ketten können jedoch Overhead einführen. | Hervorragend (minimaler nativer Overhead). | Hervorragend. |
+| **Bundle‑Größe** | Sehr leichtgewichtig. | Substantiell (selbst mit Tree‑Shaking). | Null (natives Sprachfeature). | Klein. |
+| **API‑Design‑Philosophie** | Funktionales Collector‑Muster mit expliziter Index‑Semantik. | Reaktives Observable‑Muster. | Imperatives Iterator / deklaratives Generator‑Muster. | Funktional, point‑free Komposition. |
+| **Flusskontrolle** | Explizit (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Gut (`take`, `takeUntil`, `first`). | Manuell (`break` in Schleifen). | Gut (`take`, `until`). |
+| **Sync & Async Support** | Vereinheitlichte API – Erstklassiger Support für beide Paradigmen. | Hauptsächlich asynchron. | Beide unterstützt, aber mit manueller Brücke. | Hauptsächlich asynchron. |
+| **Lernkurve** | Flach für Entwickler, die mit funktionalen und indizierten Collection‑Pipelines vertraut sind. | Steiler (umfangreicher Operator‑Wortschatz, Hot/Cold‑Observable‑Konzepte). | Niedrig bis mittel. | Mittel. |
 
-## Hauptmerkmale
--   **Duale Stream-Typen**: Volle Unterstützung für sowohl SynchronousSemantic (für Iterable) als auch AsynchronousSemantic (für AsyncIterable und Ereignisse)
--   **Umfangreicher Operationensatz**: filter, map, flatMap, concat, distinct, sorted, limit, skip, peek, reverse, shuffle
--   **Flexible Terminaloperationen**: collect (mit benutzerdefinierten Collectors), toArray, toSet, toMap, forEach, reduce, findFirst, anyMatch, allMatch, count
--   **Erweiterte Collector**: Eingebaute Collector für joining, groupingBy, partitioningBy, summing, averaging, maxBy, minBy
--   **Statistikmodul**: Gebrauchsfertige Methoden für Mittelwert, Median, Modus, Varianz, Standardabweichung, Bereich, Quantile, Schiefe, Kurtosis für numerische/BigInt-Streams
--   **Hilfsfunktionen**: Typ-Guards (isPromise, isAsyncIterable), Komparatoren (useCompare), Traversal (useTraverse) und Konvertierungs-Hooks
--   **Optional<T>**: Ein monadischer Container für nullable Werte, integriert mit Suchoperationen
-
-## API-Übersicht
-### Kernklassen und -schnittstellen
--   `Semantic<E>` / `AsynchronousSemantic<E>`: Die abstrakte Stream-Definition
--   `Collectable<E>` / `AsynchronousCollectable<E>`: Der ausführbare Stream mit Terminaloperationen
--   `OrderedCollectable<E>` / `UnorderedCollectable<E>`: Materialisierte Versionen, optimiert für reihenfolgensensitive oder reihenfolgenunempfindliche Operationen
--   `Collector<E, A, R>`: Die Abstraktion für mutable Reduktionsoperationen
-
-### Factory-Funktionen (use*)
--   **Aus Quellen**: useFrom, useRange, useFill, useEmpty
--   **Aus Zeit**: useInterval, useAnimationFrame
--   **Aus Web-APIs**: useBlob, useDocument, useWindow, useHTMLElement, useWebSocket
--   **Collector**: useToArray, useGroupBy, useSummate, useJoin, usw.
-
-## Leistungshinweise
--   **Lazy Evaluation**: Pipelines werden ohne Ausführung komponiert, bis eine Terminaloperation aufgerufen wird
--   **Short-Circuiting**: Operationen wie limit, anyMatch und findFirst stoppen die Verarbeitung von Elementen, sobald das Ergebnis bestimmt ist
--   **Geordnet vs. Ungeordnet**:
-    -   Verwenden Sie `.toUnordered()` für Terminaloperationen, wenn die Reihenfolge der Quellelemente für Ihr Ergebnis keine Rolle spielt (z. B. für Summe, Maximum oder toSet). Dies kann interne Optimierungen ermöglichen, die kostspielige Sortierschritte überspringen
-    -   Verwenden Sie `.toOrdered()`, wenn die Reihenfolge wichtig ist (z. B. für toArray, bei dem die Reihenfolge erhalten bleiben muss)
-
-## Einstiegsbeispiel
-```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' },
-];
-
-// Gesamtbetrag pro Kategorie berechnen
-const totalsByCategory = await useFrom(transactions)
-  .toUnordered()
-  .collect(
-    useGroupBy(
-      t => t.category,
-      t => t.amount,
-      useSummate() // Collector für die Werte
-    )
-  );
+**Der Semantic‑TypeScript‑Vorteil**
 
-console.log(totalsByCategory); // Map { 'Food' => 150, 'Electronics' => 500 }
-```
+*   **Einzigartige Fähigkeiten:** Integrierte Statistik‑ und Index‑Funktionen eliminieren die Notwendigkeit manueller `reduce`‑Operationen oder ergänzender Datenanalyse‑Bibliotheken.
+*   **Vorhersehbare Ressourcenverwaltung:** Explizite Kontrolle über Ereignisströme verhindert die speicherlecks, die in RxJS‑Anwendungen subtil auftreten können.
+*   **Vereinheitlichtes Design:** Eine konsistente API für sowohl synchrone als auch asynchrone Workflows reduziert kognitive Belastung und Code‑Duplizierung.
+
+Dieser Vergleich unterstreicht, warum Semantic‑TypeScript besonders gut für moderne TypeScript‑Anwendungen geeignet ist, die hohe Leistung, robuste Typsicherheit und umfangreiche Datenverarbeitungsfunktionen ohne die Komplexität traditioneller reaktiver Frameworks erfordern.
+
+---
+
+### Beginnen Sie Ihre Erkundung
+
+Semantic‑TypeScript verwandelt komplexe Datenflüsse in lesbare, komponierbare und hochleistungsfähige Pipelines. Egal, ob Sie Echtzeit‑UI‑Ereignisse verarbeiten, umfangreiche Datensätze bearbeiten oder Analyse‑Dashboards erstellen – es bietet die Leistung von Datenbank‑Level‑Indizierung mit der Eleganz der funktionalen Programmierung.
+
+**Ihre nächsten Schritte:**
+
+*   Erkunden Sie die vollständig typisierte API direkt in Ihrer IDE (alle Exporte sind über den Hauptpaket‑Einstiegspunkt verfügbar).
+*   Werden Sie Teil der wachsenden Community von Entwicklern, die komplexe asynchrone Iteratoren und reaktive Ketten durch klare, intentionale Semantic‑Pipelines ersetzt haben.
+
+**Semantic‑TypeScript** – wo Ströme auf Struktur treffen.
+
+Beginnen Sie noch heute mit dem Bauen und erleben Sie den spürbaren Unterschied, den durchdachte Indizierung bringt.
 
-Semantic-TypeScript wurde für Entwickler gebaut, die eine streng entworfene, typsichere und leistungsstarke Stream-Processing-Bibliothek suchen. Es bringt die Leistungsfähigkeit von Unternehmens-Datentransformationsmustern in das TypeScript-Ökosystem und eignet sich perfekt für datenintensive Frontend-Anwendungen, Node.js-Datenverarbeitung und jedes Szenario, in dem elegante, effiziente Handhabung von Sequenzen erforderlich ist.
+**Bauen Sie mit Klarheit, handeln Sie mit Vertrauen und transformieren Sie Daten mit Absicht.**
 
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript) 
+MIT © Eloy Kim