semantic-typescript 0.6.0 → 0.7.0

package/readme.de.md

@@ -1,214 +1,213 @@
-# Semantic-TypeScript: Eine bahnbrechende Stream-Processing-Bibliothek
+# **Semantic-TypeScript**
+**Flow, Indexed.** 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:
+### Übersicht
 
--   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 einen bedeutenden Fortschritt in der Stream-Verarbeitungstechnologie dar, indem es die effektivsten Konzepte von JavaScript-`GeneratorFunction`, Java Streams und MySQL-ähnlicher Indexierung **synthetisiert**. Die Kernphilosophie ist ebenso einfach wie mächtig: Konstruieren Sie außergewöhnlich effiziente Datenverarbeitungspipelines durch intelligente Indexierung, nicht durch rohe 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.
+Während konventionelle Bibliotheken synchrone Schleifen oder umständliche Promise-Ketten aufzwingen, bietet Semantic-TypeScript ein **vollständig asynchrones**, funktional reines und rigoros typsicheres Erlebnis, das für die Anforderungen moderner Frontend-Entwicklung 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:
+In seinem eleganten Modell erreichen Daten den Consumer nur dann, wenn die vorgelagerte Pipeline explizit die `accept`- (und optional `interrupt`-) Callbacks aufruft. Sie haben die vollständige Kontrolle über den Zeitpunkt – genau dann, wenn er benötigt wird.
 
--   **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 es bevorzugen
 
-## 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-Indexierung** – jedes Element trägt seinen natürlichen oder individuellen Index.
+-   **Rein funktionaler Stil** — mit vollständiger TypeScript-Inferenz.
+-   **Speicherleck-sichere Event-Streams** – `useWindow`, `useDocument`, `useHTMLElement` und `useWebSocket` sind mit Sicherheit im Hinterkopf entwickelt. Sie definieren die Grenze – mittels `limit(n)`, `sub(start, end)` oder `takeWhile(predicate)` – und die Bibliothek übernimmt die Aufräumarbeit. Keine hängen gebliebenen Listener, keine Speicherlecks.
+-   **Integrierte Statistik** – umfassende numerische und BigInt-Analysen inklusive Mittelwerten, Medianen, Modus, Varianz, Schiefe und Kurtosis.
+-   **Vorhersehbare Performance** – wählen Sie basierend auf Ihren Anforderungen zwischen geordneten und ungeordneten Kollektoren.
+-   **Speichereffizient** – Streams werden lazy evaluiert, was Speicherbedenken mindert.
+-   **Kein undefiniertes Verhalten** – TypeScript garantiert Typsicherheit und Null-Sicherheit. Eingabedaten bleiben unverändert, es sei denn, sie werden explizit in Ihren Callback-Funktionen modifiziert.
 
-### 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.
+```bash
+npm install semantic-typescript
+```
+oder
+```bash
+yarn add semantic-typescript
+```
 
-### 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
+### Schnellstart
 
-### 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.
+```typescript
+import { useOf, useFrom, useRange, useWindow, useHTMLElement, useWebSocket, useText, useStringify } from "semantic-typescript";
+
+// Numerische Statistiken
+let summate: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)
+  .toNumericStatistics()  // Erforderlich vor Terminal-Operation
+  .summate();             // 200
+
+// BigInt-Statistiken
+let summate: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2)
+  .toBigIntStatistics()   // Erforderlich vor Terminal-Operation
+  .summate();             // 200n
+
+// Einen Stream per Index umkehren
+useFrom([1, 2, 3, 4, 5])
+  .redirect((element: E, index: bigint): bigint => -index) // Negativer Index zur Umkehrung
+  .toOrdered() // toOrdered() aufrufen, um die Indexreihenfolge zu erhalten
+  .toArray(); // [5, 4, 3, 2, 1]
+
+// Einen Stream mischen
+useFrom([1, 2, 3, 4, 5])
+  .shuffle()
+  .toOrdered()
+  .toArray(); // z.B. [2, 5, 1, 4, 3]
+
+// Elemente innerhalb eines Streams verschieben
+useFrom([1, 2, 3, 4, 5])
+  .translate(2)  // Elemente um 2 Positionen nach rechts verschieben
+  .toOrdered()
+  .toArray(); // [4, 5, 1, 2, 3]
+
+useFrom([1, 2, 3, 4, 5])
+  .translate(-2) // Elemente um 2 Positionen nach links verschieben
+  .toOrdered()
+  .toArray(); // [3, 4, 5, 1, 2]
+
+// Unendlicher Bereich mit frühem Abbruch
+useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)
+  .limit(10n)          // Nach 10 Elementen stoppen
+  .toUnordered()
+  .toArray();
 
-### 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.
+// Echtzeit-Fenster-Größenänderung (stoppt automatisch nach 5 Events)
+useWindow("resize")
+  .limit(5n)          // Entscheidend für Event-Streams
+  .toUnordered()
+  .forEach((ev, idx) => console.log(`Größenänderung #${idx}`));
 
-## Installation
-```bash
-npm install semantic-typescript
+// Auf ein HTML-Element hören
+// <input id="input" type="text"/>
+useHTMLElement("#input", "change")
+  .limit(1)
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
+
+// Auf mehrere Elemente und Events hören
+useHTMLElement("input", ["change", "keyup"])
+  .takeWhile((event: Event): boolean => validate(event))
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
+
+// Auf einen WebSocket hören
+let webSocket = new WebSocket("ws://localhost:8080");
+webSocket.addEventListener("close", (): void => {
+  webSocket.close();  // WebSocket-Lebenszyklus manuell verwalten
+});
+useWebSocket(webSocket, "message")
+  .limit(1)
+  .toUnordered()
+  .forEach((message: MessageEvent) => console.log(message.data));
+
+// Über einen String Code-Punkt für Code-Punkt iterieren
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // Gibt den String aus
+
+// Ein Objekt mit Zirkelbezügen sicher in einen String umwandeln
+let o = {
+  a: 1,
+  b: "text",
+  c: [o.a, o.b, o.c] // Zirkelbezug
+};
+// let text: string = JSON.stringify(o); // Wirft einen Fehler
+let text: string = useStringify(o); // Ergibt sicher `{a: 1, b: "text", c: []}`
 ```
 
-## Kernkonzepte in der Praxis
+---
 
-### 1. Streams erstellen (Semantic)
-Streams können aus verschiedenen Quellen mithilfe von Factory-Funktionen erstellt werden.
+### Kernkonzepte
 
-```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
+| Konzept | Zweck | Wann zu verwenden |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | Kern-Builder für asynchrone Streams, Events und faule Pipelines. | Echtzeit-Events, WebSockets, DOM-Listener, lang laufende oder unendliche Streams. |
+| `SynchronousSemantic` | Builder für synchrone, im Speicher basierte oder schleifenbasierte Streams. | Statische Daten, Bereiche, sofortige Iteration. |
+| `toUnordered()` | Schnellster Terminal-Kollektor (Map-basierte Indexierung). | Leistungskritische Pfade (O(n) Zeit & Speicher, keine Sortierung). |
+| `toOrdered()` | Sortierter, indexstabiler Kollektor. | Wenn stabile Ordnung oder indexbasierter Zugriff erforderlich ist. |
+| `toNumericStatistics()` | Umfangreiche numerische statistische Analyse (Mittelwert, Median, Varianz, Schiefe, Kurtosis etc.). | Datenanalyse und statistische Berechnungen. |
+| `toBigIntStatistics()` | Umfangreiche BigInt-Statistikanalyse. | Datenanalyse und statistische Berechnungen für große Integer. |
+| `toWindow()` | Unterstützung für gleitende und fallende Fenster. | Zeitreihenverarbeitung, Batching und Fensteroperationen. |
 
-// Aus einem statischen Array
-const staticStream = useFrom([1, 2, 3, 4, 5]);
+---
 
-// Aus einem asynchronen Generator
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
+**Wichtige Nutzungsregeln**
 
-// Ein zeitbasierter Stream
-const tickStream = useInterval(1000); // emittiert jede Sekunde
+1.  **Event-Streams** (`useWindow`, `useDocument`, `useHTMLElement`, `useWebSocket`, …) geben ein `AsynchronousSemantic` zurück.
+    → Sie **müssen** `.limit(n)`, `.sub(start, end)` oder `.takeWhile()` aufrufen, um das Lauschen zu beenden. Andernfalls bleibt der Listener aktiv.
 
-// Ein DOM-Ereignisstream (siehe wichtigen Hinweis unten)
-const clickStream = useDocument('click');
-```
+2.  **Terminale Operationen** (`.toArray()`, `.count()`, `.average()`, `.reduce()`, `.findFirst()`, etc.) sind **nur verfügbar nach** der Konvertierung in einen Kollektor:
+    ```typescript
+    .toUnordered()   // O(n) Zeit & Speicher, keine Sortierung
+    // oder
+    .toOrdered()     // Sortiert, behält die Reihenfolge bei
+    ```
 
-### 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
+### Leistungsmerkmale
 
-// Bisher wurde noch nichts ausgeführt
-```
+| Kollektor | Zeitkomplexität | Speicherkomplexität | Sortiert? | Am besten für |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | Nein | Rohgeschwindigkeit, Reihenfolge nicht erforderlich. |
+| `toOrdered()` | O(2n) | O(n) | Ja | Stabile Ordnung, indexierter Zugriff, Analysen. |
+| `toNumericStatistics()` | O(2n) | O(n) | Ja | Statistische Operationen, die sortierte Daten erfordern. |
+| `toBigIntStatistics()` | O(2n) | O(n) | Ja | Statistische Operationen für BigInt. |
+| `toWindow()` | O(2n) | O(n) | Ja | Zeitbasierte Fensteroperationen. |
 
-### 3. Streams ausführen (Terminaloperationen)
-Um ein Ergebnis zu erhalten, müssen Sie ein Collectable erhalten und eine Terminaloperation aufrufen.
+Setzen Sie auf `toUnordered()`, wenn Geschwindigkeit oberste Priorität hat. Verwenden Sie `toOrdered()` nur, wenn Sie eine stabile Ordnung oder statistische Methoden benötigen, die von sortierten Daten abhängen.
 
-```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
-);
-```
+---
 
-### 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.
+**Vergleich mit anderen Frontend-Stream-Prozessoren**
 
-```typescript
-import { useDocument } from 'semantic-typescript';
+| Feature | Semantic-TypeScript | RxJS | Native Async Iteratoren / Generatoren | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **TypeScript-Integration** | Erstklassig, tief typisiert mit nativer Index-Awareness. | Ausgezeichnet, aber mit komplexen Generics. | Gut, erfordert manuelle Typisierung. | Starker, funktionaler Stil. |
+| **Integrierte statistische Analyse** | Umfassende native Unterstützung für `number` und `bigint`. | Nicht nativ verfügbar (benötigt benutzerdefinierte Operatoren). | Keine. | Keine. |
+| **Indexierung & Positionsbewusstsein** | Native, mächtige BigInt-Indexierung für jedes Element. | Benötigt benutzerdefinierte Operatoren (`scan`, `withLatestFrom`). | Manueller Zähler erforderlich. | Grundlegend, kein eingebauter Index. |
+| **Event-Stream-Management** | Dedizierte, typsichere Fabriken mit expliziter Frühstopp-Kontrolle. | Leistungsstark, aber erfordert manuelles Abonnement-Management. | Manueller Event-Listener + Abbruch. | Gute `fromEvent`, leichtgewichtig. |
+| **Leistung & Speichereffizienz** | Hervorragend – optimierte `toUnordered()`- und `toOrdered()`-Kollektoren. | Sehr gut, aber Operator-Ketten verursachen Overhead. | Ausgezeichnet (kein Overhead). | Ausgezeichnet. |
+| **Bundle-Größe** | Sehr leichtgewichtig. | Groß (auch mit Tree-Shaking). | Null (nativ). | Klein. |
+| **API-Design-Philosophie** | Funktionales Kollektor-Muster mit expliziter Indexierung. | Reaktives Observable-Muster. | Iterator- / Generator-Muster. | Funktional, point-free. |
+| **Frühe Beendigung & Kontrolle** | Explizit (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Gut (`take`, `takeUntil`, `first`). | Manuell (`break` in `for await…of`). | Gut (`take`, `until`). |
+| **Synchroner & asynchroner Support** | Vereinheitlichte API – erstklassiger Support für beides. | Hauptsächlich asynchron. | Beides, aber manuell. | Hauptsächlich asynchron. |
+| **Lernkurve** | Flach für Entwickler, die mit funktionalen und indizierten Pipelines vertraut sind. | Steiler (viele Operatoren, heiße/kalte Observables). | Niedrig. | Mittel. |
 
-// Nur die ersten 5 Klicks sammeln
-const first5Clicks = await useDocument('click')
-  .limit(5) // <- Essentiell: Begrenzt den Stream auf 5 Ereignisse
-  .toUnordered()
-  .toArray();
+**Hauptvorteile von Semantic-TypeScript**
 
-// Klicks in einem 10-Sekunden-Fenster sammeln
-const clicksIn10s = await useDocument('click')
-  .takeWhile((_, index, startTime = Date.now()) => Date.now() - startTime < 10000)
-  .toUnordered()
-  .toArray();
+*   Einzigartige, eingebaute statistische und Indexierungs-Fähigkeiten, die manuelles `reduce` oder externe Bibliotheken überflüssig machen.
+*   Explizite Kontrolle über Event-Streams verhindert die bei RxJS häufigen Speicherlecks.
+*   Ein einheitliches, synchrones/asynchrones Design bietet eine einzige, konsistente API für diverse Anwendungsfälle.
 
-// 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();
-```
+Dieser Vergleich veranschaulicht, warum Semantic-TypeScript besonders gut für moderne TypeScript-Frontend-Anwendungen geeignet ist, die Leistung, Typsicherheit und umfangreiche Analysen ohne den Aufwand traditioneller reaktiver Bibliotheken fordern.
 
-**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.
+---
 
-### 5. Statistikfunktionen nutzen
-```typescript
-const numericStream = useFrom([10, 20, 30, 40, 50]).toNumeric();
+### Bereit zu erkunden?
 
-const average = await numericStream.average();
-const median = await numericStream.median();
-const standardDeviation = await numericStream.standardDeviation();
-const skewness = await numericStream.skewness();
+Semantic-TypeScript verwandelt komplexe Datenflüsse in lesbare, komponierbare und hochperformante Pipelines. Egal, ob Sie Echtzeit-UI-Events verarbeiten, große Datensätze verarbeiten oder Analyse-Dashboards erstellen – es bietet die Leistungsfähigkeit von Datenbank-gradiger Indexierung mit der Eleganz der funktionalen Programmierung.
 
-console.log(`Durchschnitt: ${average}, Median: ${median}, Standardabweichung: ${standardDeviation}`);
-```
+**Nächste Schritte:**
 
-## 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
-    )
-  );
-
-console.log(totalsByCategory); // Map { 'Food' => 150, 'Electronics' => 500 }
-```
+*   Durchsuchen Sie die vollständig typisierte API in Ihrer IDE (alle Exporte stammen aus dem Hauptpaket).
+*   Treten Sie der wachsenden Community von Entwicklern bei, die verschachtelte asynchrone Iteratoren durch saubere Semantic-Pipelines ersetzt haben.
+
+**Semantic-TypeScript** – wo Streams auf Struktur treffen.
 
-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.
+Beginnen Sie noch heute mit der Entwicklung und erleben Sie den Unterschied, den durchdachte Indexierung bewirkt.
 
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript) 
+**Erstellen Sie mit Klarheit, agieren Sie mit Zuversicht und transformieren Sie Daten mit Absicht.**