semantic-typescript 0.0.7 → 0.1.4

package/readme.de.md

@@ -1,335 +1,427 @@
-# 📘 semantic-typescript
+# Semantic-TypeScript Stream-Verarbeitungsbibliothek
 
-Eine leistungsstarke, typsichere Utility-Bibliothek für die **semantische Datenverarbeitung** in TypeScript.  
-Sie bietet komponierbare, funktional-programmierende Konstrukte zur Arbeit mit Collections, Streams und Sequenzen – inklusive Unterstützung für Sortieren, Filtern, Gruppieren, Statistik und mehr.
+## Einführung
 
-Ob Sie **sortierte oder unsortierte Daten** verarbeiten, **statistische Analysen** durchführen oder einfach nur **operationen flüssig verketten** möchten – diese Bibliothek deckt Ihr Bedürfnis ab.
+Semantic-TypeScript ist eine moderne Stream-Verarbeitungsbibliothek, die von JavaScript GeneratorFunction, Java Stream und MySQL Index inspiriert wurde. Der Kernentwurf der Bibliothek basiert auf der Erstellung effizienter Datenverarbeitungspipelines mittels Datenindizes, um TypeScript-Entwicklern eine typsichere, funktionale Stream-Verarbeitungserfahrung zu bieten.
 
----
+Im Gegensatz zur traditionellen synchronen Verarbeitung verwendet Semantic einen asynchronen Verarbeitungsmodus. Beim Erstellen von Datenströmen hängt der Zeitpunkt des Datenempfangs vollständig davon ab, wann die Upstream-Quelle die `accept`- und `interrupt`-Callback-Funktionen aufruft. Dieser Entwurf ermöglicht der Bibliothek die elegante Verarbeitung von Echtzeit-Datenströmen, großen Datensätzen und asynchronen Datenquellen.
 
-## 🧩 Merkmale
-
-- ✅ Vollständig **typsichere Generics**
-- ✅ **Funktionale Programmierung** (z. B. map, filter, reduce)
-- ✅ **Semantische Datenströme** (`Semantic<E>`) für **Lazy Evaluation**
-- ✅ **Collector** zum Umwandeln von Streams in konkrete Datenstrukturen
-- ✅ **Sortierte und unsortierte Collectables** – `toUnordered()` ist **am schnellsten (kein Sortieren**
-- ✅ **Sortieren** über `sorted()`, `toOrdered()`, Vergleichsfunktionen
-- ✅ **Statistische Analyse** (`Statistics`, `NumericStatistics`, `BigIntStatistics`)
-- ✅ **Optional<T>** – Monade für sicheres Arbeiten mit potenziell `null` oder `undefined`
-- ✅ **Iteratoren & Generatoren** basiertes Design – ideal auch für große oder asynchrone Daten
-
----
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install semantic-typescript
 ```
 
----
-
-## 🧠 Kernkonzepte
-
-### 1. `Optional<T>` – Sicheres Arbeiten mit Nullable-Werten
-
-Ein monadisches Container-Objekt für Werte, die `null` oder `undefined` sein können.
-
-#### Methoden:
-
-| Methode | Beschreibung | Beispiel |
-|--------|-------------|---------|
-| `of(value)` | Wert einpacken (kann null/undefined sein) | `Optional.of(null)` |
-| `ofNullable(v)` | Einpacken, null/undefined erlaubt | `Optional.ofNullable(someVar)` |
-| `ofNonNull(v)` | Einpacken, bei null/undefined wird eine Exception geworfen | `Optional.ofNonNull(5)` |
-| `get()` | Wert auslesen (bei leerem Optional: Exception) | `opt.get()` |
-| `getOrDefault(d)` | Wert auslesen oder Standardwert verwenden | `opt.getOrDefault(0)` |
-| `ifPresent(fn)` | Side-Effect ausführen, wenn Wert vorhanden | `opt.ifPresent(x => console.log(x))` |
-| `map(fn)` | Wert transformieren (wenn vorhanden) | `opt.map(x => x + 1)` |
-| `filter(fn)` | Nur Werte behalten, die den Prädikat erfüllen | `opt.filter(x => x > 0)` |
-| `isEmpty()` | Prüfen, ob das Optional leer ist | `opt.isEmpty()` |
-| `isPresent()` | Prüfen, ob ein Wert vorhanden ist | `opt.isPresent()` |
-
-#### Beispiel:
+## Grundlegende Typen
+
+| Typ | Beschreibung |
+|-----|-------------|
+| `Invalid<T>` | Typ, der null oder undefined erweitert |
+| `Valid<T>` | Typ, der null und undefined ausschließt |
+| `MaybeInvalid<T>` | Typ, der null oder undefined sein kann |
+| `Primitive` | Sammlung primitiver Typen |
+| `MaybePrimitive<T>` | Typ, der ein Primitiv sein kann |
+| `OptionalSymbol` | Symbolkennung für die Optional-Klasse |
+| `SemanticSymbol` | Symbolkennung für die Semantic-Klasse |
+| `CollectorsSymbol` | Symbolkennung für die Collector-Klasse |
+| `CollectableSymbol` | Symbolkennung für die Collectable-Klasse |
+| `OrderedCollectableSymbol` | Symbolkennung für die OrderedCollectable-Klasse |
+| `WindowCollectableSymbol` | Symbolkennung für die WindowCollectable-Klasse |
+| `StatisticsSymbol` | Symbolkennung für die Statistics-Klasse |
+| `NumericStatisticsSymbol` | Symbolkennung für die NumericStatistics-Klasse |
+| `BigIntStatisticsSymbol` | Symbolkennung für die BigIntStatistics-Klasse |
+| `UnorderedCollectableSymbol` | Symbolkennung für die UnorderedCollectable-Klasse |
+| `Runnable` | Funktion ohne Parameter und Rückgabewert |
+| `Supplier<R>` | Funktion ohne Parameter, die R zurückgibt |
+| `Functional<T, R>` | Ein-Parameter-Transformationsfunktion |
+| `Predicate<T>` | Ein-Parameter-Prüffunktion |
+| `BiFunctional<T, U, R>` | Zwei-Parameter-Transformationsfunktion |
+| `BiPredicate<T, U>` | Zwei-Parameter-Prüffunktion |
+| `Comparator<T>` | Vergleichsfunktion |
+| `TriFunctional<T, U, V, R>` | Drei-Parameter-Transformationsfunktion |
+| `Consumer<T>` | Ein-Parameter-Consumer-Funktion |
+| `BiConsumer<T, U>` | Zwei-Parameter-Consumer-Funktion |
+| `TriConsumer<T, U, V>` | Drei-Parameter-Consumer-Funktion |
+| `Generator<T>` | Generatorfunktion |
 
 ```typescript
-import { Optional } from 'semantic-typescript';
-
-const value: number | null = Math.random() > 0.5 ? 10 : null;
-
-const opt = Optional.ofNullable(value);
-
-const result = opt
-  .filter(v => v > 5)
-  .map(v => v * 2)
-  .getOrDefault(0);
-
-console.log(result); // 20 oder 0
+// Typverwendungsbeispiele
+const predicate: Predicate<number> = (n) => n > 0;
+const mapper: Functional<string, number> = (str) => str.length;
+const comparator: Comparator<number> = (a, b) => a - b;
 ```
 
----
+## Typwächter (Type Guards)
+
+| Funktion | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|----------|-------------|-----------------|-----------------|
+| `validate<T>(t: MaybeInvalid<T>): t is T` | Prüft, ob Wert nicht null oder undefined | O(1) | O(1) |
+| `invalidate<T>(t: MaybeInvalid<T>): t is null \| undefined` | Prüft, ob Wert null oder undefined | O(1) | O(1) |
+| `isBoolean(t: unknown): t is boolean` | Prüft auf Boolean | O(1) | O(1) |
+| `isString(t: unknown): t is string` | Prüft auf String | O(1) | O(1) |
+| `isNumber(t: unknown): t is number` | Prüft auf Number | O(1) | O(1) |
+| `isFunction(t: unknown): t is Function` | Prüft auf Function | O(1) | O(1) |
+| `isObject(t: unknown): t is object` | Prüft auf Object | O(1) | O(1) |
+| `isSymbol(t: unknown): t is symbol` | Prüft auf Symbol | O(1) | O(1) |
+| `isBigint(t: unknown): t is bigint` | Prüft auf BigInt | O(1) | O(1) |
+| `isPrimitive(t: unknown): t is Primitive` | Prüft auf Primitivtyp | O(1) | O(1) |
+| `isIterable(t: unknown): t is Iterable<unknown>` | Prüft auf Iterierbarkeit | O(1) | O(1) |
+| `isOptional(t: unknown): t is Optional<unknown>` | Prüft auf Optional-Instanz | O(1) | O(1) |
+| `isSemantic(t: unknown): t is Semantic<unknown>` | Prüft auf Semantic-Instanz | O(1) | O(1) |
+| `isCollector(t: unknown): t is Collector<unknown, unknown, unknown>` | Prüft auf Collector-Instanz | O(1) | O(1) |
+| `isCollectable(t: unknown): t is Collectable<unknown>` | Prüft auf Collectable-Instanz | O(1) | O(1) |
+| `isOrderedCollectable(t: unknown): t is OrderedCollectable<unknown>` | Prüft auf OrderedCollectable-Instanz | O(1) | O(1) |
+| `isWindowCollectable(t: unknown): t is WindowCollectable<unknown>` | Prüft auf WindowCollectable-Instanz | O(1) | O(1) |
+| `isUnorderedCollectable(t: unknown): t is UnorderedCollectable<unknown>` | Prüft auf UnorderedCollectable-Instanz | O(1) | O(1) |
+| `isStatistics(t: unknown): t is Statistics<unknown, number \| bigint>` | Prüft auf Statistics-Instanz | O(1) | O(1) |
+| `isNumericStatistics(t: unknown): t is NumericStatistics<unknown>` | Prüft auf NumericStatistics-Instanz | O(1) | O(1) |
+| `isBigIntStatistics(t: unknown): t is BigIntStatistics<unknown>` | Prüft auf BigIntStatistics-Instanz | O(1) | O(1) |
 
-### 2. `Semantic<E>` – Lazy Datenstrom
+```typescript
+// Typwächter-Verwendungsbeispiele
+const value: unknown = "hello";
 
-Ein **Lazy, komponierbarer Sequence-Typ**. Ähnlich wie Java Streams oder Kotlin Sequences.
+if (isString(value)) {
+    console.log(value.length); // Typsicher, value wird als string inferiert
+}
 
-Erstellen Sie einen `Semantic`-Datenstrom mit Helfern wie `from()`, `range()`, `iterate()` oder `fill()`.
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
+}
+```
 
-#### Erzeugungsmethoden:
+## Hilfsfunktionen
 
-| Funktion | Beschreibung | Beispiel |
-|----------|-------------|---------|
-| `from(iterable)` | Aus Array/Set/Iterable erstellen | `from([1, 2, 3])` |
-| `range(start, end, step?)` | Zahlenbereich erzeugen | `range(0, 5)` → 0,1,2,3,4 |
-| `fill(element, count)` | Einen Wert N-mal wiederholen | `fill('a', 3n)` |
-| `iterate(gen)` | Benutzerdefinierten Generator verwenden | `iterate(genFn)` |
+| Funktion | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|----------|-------------|-----------------|-----------------|
+| `useCompare<T>(t1: T, t2: T): number` | Allgemeine Vergleichsfunktion | O(1) | O(1) |
+| `useRandom<T = number \| bigint>(index: T): T` | Pseudozufallszahlengenerator | O(log n) | O(1) |
 
-#### Häufig verwendete Operatoren:
+```typescript
+// Hilfsfunktions-Verwendungsbeispiele
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-| Methode | Beschreibung | Beispiel |
-|--------|-------------|---------|
-| `map(fn)` | Jedes Element transformieren | `.map(x => x * 2)` |
-| `filter(fn)` | Nur Elemente behalten, die den Prädikat erfüllen | `.filter(x => x > 10)` |
-| `limit(n)` | Maximale Anzahl von N Elementen | `.limit(5)` |
-| `skip(n)` | Erste N Elemente überspringen | `.skip(2)` |
-| `distinct()` | Duplikate entfernen (nutzt intern Set) | `.distinct()` |
-| `sorted()` | Elemente sortieren (natürliche Reihenfolge) | `.sorted()` |
-| `sorted(comparator)` | Mit benutzerdefinierter Sortierfunktion | `.sorted((a, b) => a - b)` |
-| `toOrdered()` | Sortieren und `OrderedCollectable` zurückgeben | `.toOrdered()` |
-| `toUnordered()` | **Keine Sortierung** – schnellster Weg | `.toUnordered()` ✅ |
-| `collect(collector)` | Mit einem Collector aggregieren | `.collect(Collector.full(...))` |
-| `toArray()` | In Array umwandeln | `.toArray()` |
-| `toSet()` | In Set umwandeln | `.toSet()` |
-| `toMap(keyFn, valFn)` | In Map umwandeln | `.toMap(x => x.id, x => x)` |
+const randomNum = useRandom(42); // Seed-basierte Zufallszahl
+const randomBigInt = useRandom(1000n); // BigInt-Zufallszahl
+```
 
----
+## Fabrikmethoden
 
-### 3. `toUnordered()` – 🚀 Am schnellsten, keine Sortierung
+### Optional-Fabrikmethoden
 
-Wenn Sie **keine bestimmte Reihenfolge** benötigen und den **schnellsten möglichen Durchsatz** wünschen, verwenden Sie:
+| Methode | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|---------|-------------|-----------------|-----------------|
+| `Optional.empty<T>()` | Erstellt leeres Optional | O(1) | O(1) |
+| `Optional.of<T>(value)` | Erstellt Optional mit Wert | O(1) | O(1) |
+| `Optional.ofNullable<T>(value)` | Erstellt Optional, das null sein kann | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value)` | Erstellt nicht-null Optional | O(1) | O(1) |
 
 ```typescript
-const fastest = semanticStream.toUnordered();
+// Optional-Verwendungsbeispiele
+const emptyOpt = Optional.empty<number>();
+const presentOpt = Optional.of(42);
+const nullableOpt = Optional.ofNullable<string>(null);
+const nonNullOpt = Optional.ofNonNull("hello");
+
+presentOpt.ifPresent(val => console.log(val)); // Gibt 42 aus
+console.log(emptyOpt.orElse(100)); // Gibt 100 aus
 ```
 
-🔥 **Es wird kein Sortieralgorithmus verwendet.**  
-Idealerweise bei irrelevanter Reihenfolge und maximalem Performancebedarf.
-
----
+### Collector-Fabrikmethoden
 
-### 4. `toOrdered()` und `sorted()` – Sortierte Ausgabe
-
-Wenn Sie eine **sortierte Ausgabe** benötigen, verwenden Sie:
+| Methode | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|---------|-------------|-----------------|-----------------|
+| `Collector.full(identity, accumulator, finisher)` | Erstellt vollständigen Collector | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Erstellt unterbrechbaren Collector | O(1) | O(1) |
 
 ```typescript
-const ordered = semanticStream.sorted(); // Natürliche Sortierung
-const customSorted = semanticStream.sorted((a, b) => a - b); // Eigene Sortierlogik
-const orderedCollectable = semanticStream.toOrdered(); // Auch sortiert
+// Collector-Verwendungsbeispiele
+const sumCollector = Collector.full(
+    () => 0,
+    (sum, num) => sum + num,
+    result => result
+);
+
+const numbers = from([1, 2, 3, 4, 5]);
+const total = numbers.toUnoredered().collect(sumCollector); // 15
 ```
 
-⚠️ Diese Methoden **sortieren die Elemente**, entweder nach natürlicher Ordnung oder mit einem angegebenen Comparator.
-
----
+### Semantic-Fabrikmethoden
 
-### 5. `Collector<E, A, R>` – Datensammlung / Aggregation
+| Methode | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|---------|--------------|-----------------|-----------------|
+| `blob(blob, chunkSize)` | Erzeugt Stream aus Blob | O(n) | O(chunkSize) |
+| `empty<E>()` | Erzeugt leeren Stream | O(1) | O(1) |
+| `fill<E>(element, count)` | Erzeugt gefüllten Stream | O(n) | O(1) |
+| `from<E>(iterable)` | Erzeugt Stream aus iterierbarem Objekt | O(1) | O(1) |
+| `interval(period, delay?)` | Erzeugt regelmäßigen Intervall-Stream | O(1)* | O(1) |
+| `iterate<E>(generator)` | Erzeugt Stream aus Generator | O(1) | O(1) |
+| `range(start, end, step)` | Erzeugt numerischen Bereichs-Stream | O(n) | O(1) |
+| `websocket(websocket)` | Erzeugt Stream aus WebSocket | O(1) | O(1) |
 
-Mit Collectors können Sie Streams in **einzelne oder komplexe Strukturen** umwandeln.
+```typescript
+// Beispiel zur Verwendung der Semantic-Fabrikmethoden
+
+// Stream aus Blob erzeugen (chunkweises Lesen)
+blob(someBlob, 1024n)
+  .toUnordered()
+  .write(WritableStream)
+  .then(callback) // Stream-Schreibvorgang erfolgreich
+  .catch(writeFi); // Stream-Schreibvorgang fehlgeschlagen
+
+// Leeren Stream erzeugen, der erst nach Verknüpfung mit anderen Streams ausgeführt wird
+empty<string>()
+  .toUnordered()
+  .join(); //[]
+
+// Gefüllten Stream erzeugen
+const filledStream = fill("hello", 3); // "hello", "hello", "hello"
+
+// Zeitgesteuerten Stream mit 2 Sekunden anfänglicher Verzögerung und 5 Sekunden Zyklus erzeugen, 
+// implementiert über Timer-Mechanismus, mögliche Zeitabweichungen aufgrund von System-Schedulereinschränkungen.
+const intervalStream = interval(5000, 2000);
+
+// Stream aus iterierbarem Objekt erzeugen
+const numberStream = from([1, 2, 3, 4, 5]);
+const stringStream = from(new Set(["Alex", "Bob"]));
+
+// Bereichs-Stream erzeugen
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
+
+// WebSocket-Ereignisstream
+const ws = new WebSocket("ws://localhost:8080");
+websocket(ws)
+  .filter((event)=> event.type === "message") // Nur Nachrichtenereignisse überwachen
+  .toUnordered() // Für Ereignisse normalerweise ungeordnet
+  .forEach((event)=> receive(event)); // Nachrichten empfangen
+```
 
-Eingebaute statische Factorys:
+## Semantic-Klassenmethoden
+
+| Methode | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|---------|-------------|-----------------|-----------------|
+| `concat(other)` | Verbindet zwei Streams | O(n) | O(1) |
+| `distinct()` | Entfernt Duplikate | O(n) | O(n) |
+| `distinct(comparator)` | Entfernt Duplikate mit Comparator | O(n²) | O(n) |
+| `dropWhile(predicate)` | Verwirft Elemente, die Prädikat erfüllen | O(n) | O(1) |
+| `filter(predicate)` | Filtert Elemente | O(n) | O(1) |
+| `flat(mapper)` | Flache Abbildung | O(n × m) | O(1) |
+| `flatMap(mapper)` | Flache Abbildung auf neuen Typ | O(n × m) | O(1) |
+| `limit(n)` | Begrenzt Elementanzahl | O(n) | O(1) |
+| `map(mapper)` | Transformationsabbildung | O(n) | O(1) |
+| `peek(consumer)` | Zeigt Elemente an | O(n) | O(1) |
+| `redirect(redirector)` | Index-Umleitung | O(n) | O(1) |
+| `reverse()` | Kehrt Stream um | O(n) | O(1) |
+| `shuffle()` | Zufällige Neuanordnung | O(n) | O(1) |
+| `shuffle(mapper)` | Neuanordnung mit Mapper | O(n) | O(1) |
+| `skip(n)` | Überspringt erste n Elemente | O(n) | O(1) |
+| `sorted()` | Sortiert | O(n log n) | O(n) |
+| `sorted(comparator)` | Sortiert mit Comparator | O(n log n) | O(n) |
+| `sub(start, end)` | Erstellt Substream | O(n) | O(1) |
+| `takeWhile(predicate)` | Nimmt Elemente, die Prädikat erfüllen | O(n) | O(1) |
+| `translate(offset)` | Index-Translation | O(n) | O(1) |
+| `translate(translator)` | Index-Translation mit Translator | O(n) | O(1) |
 
 ```typescript
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// Semantic-Operationsbeispiele
+const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)        // Filtert gerade Zahlen
+    .map(n => n * 2)                 // Multipliziert mit 2
+    .skip(1)                         // Überspringt erstes Element
+    .limit(3)                        // Begrenzt auf 3 Elemente
+    .toArray();                      // Konvertiert zu Array
+// Ergebnis: [8, 12, 20]
+
+// Komplexe Operationsbeispiele
+const complexResult = range(1, 100, 1)
+    .flatMap(n => from([n, n * 2])) // Abbildet jedes Element zu zwei Elementen
+    .distinct()                      // Entfernt Duplikate
+    .shuffle()                       // Mischt zufällig
+    .takeWhile(n => n < 50)         // Nimmt Elemente < 50
+    .toOrdered()                     // Konvertiert zu geordnetem Collector
+    .toArray();                      // Konvertiert zu Array
 ```
 
-In der Praxis werden Sie diese meist über die höherwertigen Methoden der `Collectable`-Klassen verwenden.
+## Collector-Transformationsmethoden
 
----
+| Methode | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|---------|-------------|-----------------|-----------------|
+| `toUnoredered()` | Konvertiert zu ungeordnetem Collector (Leistungspriorität) | O(1) | O(1) |
+| `toOrdered()` | Konvertiert zu geordnetem Collector | O(1) | O(1) |
+| `sorted()` | Sortiert und konvertiert zu geordnetem Collector | O(n log n) | O(n) |
+| `toWindow()` | Konvertiert zu Fenster-Collector | O(1) | O(1) |
+| `toNumericStatistics()` | Konvertiert zu numerischer Statistik | O(1) | O(1) |
+| `toBigintStatistics()` | Konvertiert zu BigInt-Statistik | O(1) | O(1) |
 
-### 6. `Collectable<E>` (abstrakte Klasse)
-
-Basisklasse für:
+```typescript
+// Collector-Transformationsbeispiele
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
 
-- `OrderedCollectable<E>` – Sortierte Ausgabe
-- `UnorderedCollectable<E>` – Keine Sortierung, schnellster Weg
-- `WindowCollectable<E>` – Gleitende Fenster
-- `Statistics<E, D>` – Statistische Aggregation
+// Leistungspriorität: Ungeordneten Collector verwenden
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
 
-#### Häufige Methoden (über Vererbung):
+// Sortierung benötigt: Geordneten Collector verwenden  
+const ordered = numbers.sorted();
 
-| Methode | Beschreibung | Beispiel |
-|--------|-------------|---------|
-| `count()` | Anzahl der Elemente | `.count()` |
-| `toArray()` | In Array umwandeln | `.toArray()` |
-| `toSet()` | In Set umwandeln | `.toSet()` |
-| `toMap(k, v)` | In Map umwandeln | `.toMap(x => x.id, x => x)` |
-| `group(k)` | Nach Schlüssel gruppieren | `.group(x => x.category)` |
-| `findAny()` | Beliebiges passendes Element (Optional) | `.findAny()` |
-| `findFirst()` | Erstes Element (Optional) | `.findFirst()` |
-| `reduce(...)` | Benutzerdefiniertes Reduzieren | `.reduce((a,b) => a + b, 0)` |
+// Statistische Analyse: Statistik-Collector verwenden
+const stats = numbers
+    .toNumericStatistics();
 
----
+console.log(stats.mean());        // Durchschnitt
+console.log(stats.median());      // Median
+console.log(stats.standardDeviation()); // Standardabweichung
 
-### 7. `OrderedCollectable<E>` – Sortierte Daten
+// Fensteroperationen
+const windowed = numbers
+    .toWindow()
+    .tumble(3n); // Fenster mit je 3 Elementen
 
-Wenn Sie möchten, dass die Elemente **automatisch sortiert** werden, verwenden Sie diese Klasse.
+windowed.forEach(window => {
+    console.log(window.toArray()); // Inhalt jedes Fensters
+});
+```
 
-Akzeptiert einen **benutzerdefinierten Comparator** oder nutzt die natürliche Sortierung.
+## Collectable-Sammelmethoden
+
+| Methode | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|---------|-------------|-----------------|-----------------|
+| `anyMatch(predicate)` | Prüft auf existierende Übereinstimmung | O(n) | O(1) |
+| `allMatch(predicate)` | Prüft auf vollständige Übereinstimmung | O(n) | O(1) |
+| `count()` | Elementzählung | O(n) | O(1) |
+| `isEmpty()` | Prüft auf Leerheit | O(1) | O(1) |
+| `findAny()` | Findet beliebiges Element | O(n) | O(1) |
+| `findFirst()` | Findet erstes Element | O(n) | O(1) |
+| `findLast()` | Findet letztes Element | O(n) | O(1) |
+| `forEach(action)` | Iteriert über alle Elemente | O(n) | O(1) |
+| `group(classifier)` | Gruppiert nach Klassifikator | O(n) | O(n) |
+| `groupBy(keyExtractor, valueExtractor)` | Gruppiert nach Schlüssel-Wert-Extraktor | O(n) | O(n) |
+| `join()` | Verbindet zu String | O(n) | O(n) |
+| `join(delimiter)` | Verbindet mit Trennzeichen | O(n) | O(n) |
+| `nonMatch(predicate)` | Prüft auf keine Übereinstimmung | O(n) | O(1) |
+| `partition(count)` | Partitioniert nach Anzahl | O(n) | O(n) |
+| `partitionBy(classifier)` | Partitioniert nach Klassifikator | O(n) | O(n) |
+| `reduce(accumulator)` | Reduktionsoperation | O(n) | O(1) |
+| `reduce(identity, accumulator)` | Reduktion mit Initialwert | O(n) | O(1) |
+| `toArray()` | Konvertiert zu Array | O(n) | O(n) |
+| `toMap(keyExtractor, valueExtractor)` | Konvertiert zu Map | O(n) | O(n) |
+| `toSet()` | Konvertiert zu Set | O(n) | O(n) |
+| `write(stream)` | Schreibt in Stream | O(n) | O(1) |
 
 ```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// Collectable-Operationsbeispiele
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)
+    .toOrdered();
+
+// Übereinstimmungsprüfungen
+console.log(data.anyMatch(n => n > 5)); // true
+console.log(data.allMatch(n => n < 20)); // true
+
+// Suchoperationen
+data.findFirst().ifPresent(n => console.log(n)); // 2
+data.findAny().ifPresent(n => console.log(n)); // Beliebiges Element
+
+// Gruppierungsoperationen
+const grouped = data.groupBy(
+    n => n > 5 ? "large" : "small",
+    n => n * 2
+);
+// {small: [4, 8], large: [12, 16, 20]}
+
+// Reduktionsoperationen
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
+
+// Ausgabeoperationen
+data.join(", "); // "2, 4, 6, 8, 10"
 ```
 
-🔒 **Sortierte Ausgabe garantiert.**
-
----
-
-### 8. `UnorderedCollectable<E>` – Keine Sortierung (🚀 Schnellster)
-
-Wenn Ihnen die **Reihenfolge egal** ist und Sie die **beste Performance** wünschen, verwenden Sie:
+## Statistische Analysemethoden
+
+### NumericStatistics-Methoden
+
+| Methode | Beschreibung | Zeitkomplexität | Raumkomplexität |
+|---------|-------------|-----------------|-----------------|
+| `range()` | Spannweite | O(n) | O(1) |
+| `variance()` | Varianz | O(n) | O(1) |
+| `standardDeviation()` | Standardabweichung | O(n) | O(1) |
+| `mean()` | Mittelwert | O(n) | O(1) |
+| `median()` | Median | O(n log n) | O(n) |
+| `mode()` | Modus | O(n) | O(n) |
+| `frequency()` | Häufigkeitsverteilung | O(n) | O(n) |
+| `summate()` | Summierung | O(n) | O(1) |
+| `quantile(quantile)` | Quantil | O(n log n) | O(n) |
+| `interquartileRange()` | Interquartilsabstand | O(n log n) | O(n) |
+| `skewness()` | Schiefe | O(n) | O(1) |
+| `kurtosis()` | Wölbung | O(n) | O(1) |
 
 ```typescript
-const unordered = new UnorderedCollectable(stream);
-// Oder
-const fastest = semanticStream.toUnordered();
+// Statistische Analysebeispiele
+const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .toNumericStatistics();
+
+console.log("Mittelwert:", numbers.mean()); // 5.5
+console.log("Median:", numbers.median()); // 5.5
+console.log("Standardabweichung:", numbers.standardDeviation()); // ~2.87
+console.log("Summe:", numbers.summate()); // 55
+
+// Statistische Analyse mit Mapper
+const objects = from([
+    { value: 10 },
+    { value: 20 }, 
+    { value: 30 }
+]).toNumericStatistics();
+
+console.log("Gemappter Mittelwert:", objects.mean(obj => obj.value)); // 20
 ```
 
-✅ **Kein Sortieralgorithmus wird ausgeführt**  
-✅ **Beste Performance, wenn Reihenfolge keine Rolle spielt**
-
----
-
-### 9. `Statistics<E, D>` – Statistische Analyse
-
-Abstrakte Basisklasse zur Analyse numerischer Daten.
-
-#### Unterklassen:
-
-- `NumericStatistics<E>` – Für `number`-Werte
-- `BigIntStatistics<E>` – Für `bigint`-Werte
-
-##### Häufig verwendete statistische Methoden:
-
-| Methode | Beschreibung | Beispiel |
-|--------|-------------|---------|
-| `mean()` | Mittelwert | `.mean()` |
-| `median()` | Median | `.median()` |
-| `mode()` | Modalwert (häufigster Wert) | `.mode()` |
-| `minimum()` | Minimum | `.minimum()` |
-| `maximum()` | Maximum | `.maximum()` |
-| `range()` | Maximum − Minimum | `.range()` |
-| `variance()` | Varianz | `.variance()` |
-| `standardDeviation()` | Standardabweichung | `.standardDeviation()` |
-| `summate()` | Summe aller Werte | `.summate()` |
-| `quantile(q)` | Quantil bei q (0–1) | `.quantile(0.5)` → Median |
-| `frequency()` | Häufigkeit als Map | `.frequency()` |
-
----
-
-## 🧪 Vollständiges Beispiel
+## Leistungsauswahlleitfaden
 
+### Ungeordneten Collector wählen (Leistungspriorität)
 ```typescript
-import { from, toUnordered, toOrdered, sorted, NumericStatistics } from 'semantic-typescript';
-
-// Beispiel-Daten
-const numbers = from([10, 2, 8, 4, 5, 6]);
-
-// 🚀 Schnellster Weg: keine Sortierung
-const fastest = numbers.toUnordered();
-console.log(fastest.toArray()); // z.B. [10, 2, 8, 4, 5, 6] (wie eingegeben)
-
-// 🔢 Natürlich sortiert
-const ordered = numbers.sorted();
-console.log(ordered.toArray()); // [2, 4, 5, 6, 8, 10]
-
-// 📊 Statistik auswerten
-const stats = new NumericStatistics(numbers);
-console.log('Mittelwert:', stats.mean());
-console.log('Median:', stats.median());
-console.log('Modalwert:', stats.mode());
-console.log('Bereich:', stats.range());
-console.log('Standardabweichung:', stats.standardDeviation());
+// Wenn keine Reihenfolgegarantie benötigt wird
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // Beste Leistung
 ```
 
----
-
-## 🛠️ Hilfsfunktionen
-
-Die Bibliothek exportiert auch zahlreiche **Typ-Guards** und **Vergleichsfunktionen**:
-
-| Funktion | Zweck |
-|----------|-------|
-| `isString(x)` | Typ-Guard für `string` |
-| `isNumber(x)` | Typ-Guard für `number` |
-| `isBoolean(x)` | Typ-Guard für `boolean` |
-| `isIterable(x)` | Prüft, ob ein Objekt iterierbar ist |
-| `useCompare(a, b)` | Universelle Vergleichsfunktion |
-| `useRandom(x)` | Pseudo-Zufallszahlengenerator (spielerisch) |
-
----
-
-## 🧩 Erweitert: Eigene Generatoren & Fenster
-
-Sie können eigene **Generatoren** für kontrollierte oder unendliche Datenströme erstellen:
-
+### Geordneten Collector wählen (Reihenfolge benötigt)
 ```typescript
-const gen = (accept: BiConsumer<number, bigint>, interrupt: Predicate<number>) => {
-  for (let i = 0; i < 10; i++) {
-    accept(i, BigInt(i));
-    if (i === 5) interrupt(i);
-  }
-};
-
-const s = new Semantic(gen);
+// Wenn Elementreihenfolge beibehalten werden muss
+const ordered = data
+    .sorted(comparator) // Sortierung überschreibt Umleitungseffekte
+    .toOrdered(); // Beibehaltung der Reihenfolge
 ```
 
-Oder **gleitende Fenster** verwenden:
-
+### Fenster-Collector wählen (Fensteroperationen)
 ```typescript
-const windowed = ordered.slide(3n, 2n); // Fenstergröße 3, Schritt 2
+// Bei Fensteroperationsbedarf
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // Gleitendes Fenster
 ```
 
----
-
-## 📄 Lizenz
-
-Dieses Projekt steht unter der **MIT-Lizenz** – kostenlos für kommerzielle und private Nutzung.
-
----
-
-## 🙌 Mitwirken
-
-Pull Requests, Issues und Ideen sind willkommen!
-
----
-
-## 🚀 Schnellstart-Zusammenfassung
-
-| Aufgabe | Methode |
-|--------|---------|
-| Null-sicheres Arbeiten | `Optional<T>` |
-| Stream erstellen | `from([...])`, `range()`, `fill()` |
-| Daten transformieren | `map()`, `filter()` |
-| Daten sortieren | `sorted()`, `toOrdered()` |
-| Keine Sortierung (schnell) | `toUnordered()` ✅ |
-| Gruppieren / Aggregieren | `toMap()`, `group()`, `Collector` |
-| Statistik | `NumericStatistics`, `mean()`, `median()` usw. |
-
----
-
-## 🔗 Links
+### Statistische Analyse wählen (Numerische Berechnungen)
+```typescript
+// Bei statistischem Analysebedarf
+const stats = data
+    .toNumericStatistics(); // Numerische Statistik
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 Dokumentation: Siehe Quellcode / Typdefinitionen
+const bigIntStats = data
+    .toBigintStatistics(); // BigInt-Statistik
+```
 
----
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-**Genießen Sie komponierbares, typsicheres und funktionales Datenhandling in TypeScript.** 🚀
+## Wichtige Hinweise
 
---- 
+1. **Auswirkungen von Sortieroperationen**: In geordneten Collectors überschreibt `sorted()` die Effekte von `redirect`, `translate`, `shuffle`, `reverse`
+2. **Leistungsüberlegungen**: Bei fehlender Reihenfolgeanforderung priorisiert `toUnoredered()` verwenden
+3. **Speichernutzung**: Sortieroperationen benötigen O(n) zusätzlichen Speicher
+4. **Echtzeitdaten**: Semantic-Streams eignen sich für Echtzeitdaten und unterstützen asynchrone Datenquellen
 
-✅ **Wichtig:**  
-- `toUnordered()` → **Keine Sortierung, schnellster Weg**  
-- Alle anderen (z. B. `sorted()`, `toOrdered()`) → **Sortieren die Daten**
+Diese Bibliothek bietet TypeScript-Entwicklern leistungsstarke und flexible Stream-Verarbeitungsfähigkeiten, die die Vorteile der funktionalen Programmierung mit Typsicherheit kombinieren.