semantic-typescript 0.0.6 → 0.0.8

package/readme.de.md

@@ -1,335 +1,529 @@
-# 📘 semantic-typescript
+# Semantic-TypeScript Stream Processing Framework
 
-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-Processing-Bibliothek, inspiriert von JavaScript GeneratorFunction, Java Stream und MySQL Index. Die Kern-Designphilosophie basiert auf dem Aufbau effizienter Datenverarbeitungspipelines durch Datenindizierung und bietet eine typsichere, funktionale Stream-Operation-Erfahrung für die Frontend-Entwicklung.
 
----
+Im Gegensatz zur traditionellen synchronen Verarbeitung verwendet Semantic ein asynchrones Verarbeitungsmodell. Beim Erstellen von Datenströmen hängt der Zeitpunkt des terminalen Datenempfangs vollständig davon ab, wann der Upstream die `accept`- und `interrupt`-Callback-Funktionen aufruft. Dieses Design ermöglicht es der Bibliothek, Echtzeit-Datenströme, große Datensätze und asynchrone Datenquellen elegant zu verarbeiten.
 
-## 🧩 Merkmale
+## Kernfunktionen
 
-- ✅ 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
+| Funktion | Beschreibung | Vorteil |
+|------|------|------|
+| **Typsichere Generics** | Vollständige TypeScript-Typunterstützung | Fehlererkennung zur Kompilierzeit, bessere Entwicklungserfahrung |
+| **Funktionale Programmierung** | Unveränderliche Datenstrukturen und reine Funktionen | Vorhersehbarerer Code, einfachere Tests und Wartung |
+| **Lazy Evaluation** | Bedarfsgerechte Berechnung, Leistungsoptimierung | Hohe Speichereffizienz bei der Verarbeitung großer Datensätze |
+| **Asynchrone Stream-Verarbeitung** | Generator-basierte asynchrone Datenströme | Geeignet für Echtzeitdaten und ereignisgesteuerte Szenarien |
+| **Multi-Paradigma-Sammler** | Geordnete, ungeordnete, statistische Sammlungsstrategien | Optimale Strategiewahl basierend auf verschiedenen Szenarien |
+| **Statistische Analyse** | Eingebaute vollständige statistische Berechnungsfunktionen | Integrierte Datenanalyse und Berichterstellungsgenerierung |
 
----
+## Leistungsüberlegungen
 
-## 📦 Installation
+**Wichtiger Hinweis**: Die folgenden Methoden opfern Leistung, um Daten zu sammeln und zu sortieren, was zu geordneten Datensammlungen führt:
+- `toOrdered()`
+- `toWindow()`
+- `toNumericStatistics()`
+- `toBigIntStatistics()`
+- `sorted()`
+- `sorted(comparator)`
 
-```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.
+Besonders wichtig zu beachten: `sorted()` und `sorted(comparator)` überschreiben die Ergebnisse der folgenden Methoden:
+- `redirect(redirector)`
+- `translate(translator)`
+- `shuffle(mapper)`
 
-#### Methoden:
+## Factory-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()` |
+### Stream-Erstellungs-Factories
 
-#### Beispiel:
+| Methode | Signatur | Beschreibung | Beispiel |
+|------|------|------|------|
+| `blob` | `(blob: Blob, chunk?: bigint) => Semantic<Uint8Array>` | Konvertiere Blob in Byte-Stream | `blob(fileBlob, 1024n)` |
+| `empty` | `<E>() => Semantic<E>` | Erstelle leeren Stream | `empty<number>()` |
+| `fill` | `<E>(element: E, count: bigint) => Semantic<E>` | Fülle mit angegebener Anzahl an Elementen | `fill("hallo", 5n)` |
+| `from` | `<E>(iterable: Iterable<E>) => Semantic<E>` | Erstelle Stream aus iterierbarem Objekt | `from([1, 2, 3])` |
+| `range` | `<N extends number\|bigint>(start: N, end: N, step?: N) => Semantic<N>` | Erstelle numerischen Bereichs-Stream | `range(1, 10, 2)` |
+| `iterate` | `<E>(generator: Generator<E>) => Semantic<E>` | Erstelle Stream aus Generator-Funktion | `iterate(myGenerator)` |
+| `websocket` | `(websocket: WebSocket) => Semantic<MessageEvent>` | Erstelle Ereignis-Stream aus WebSocket | `websocket(socket)` |
 
+**Code-Beispiel-Ergänzung:**
 ```typescript
-import { Optional } from 'semantic-typescript';
+import { from, range, fill, empty } from 'semantic-typescript';
 
-const value: number | null = Math.random() > 0.5 ? 10 : null;
+// Erstelle Stream aus Array
+const numberStream = from([1, 2, 3, 4, 5]);
 
-const opt = Optional.ofNullable(value);
+// Erstelle numerischen Bereichs-Stream
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
 
-const result = opt
-  .filter(v => v > 5)
-  .map(v => v * 2)
-  .getOrDefault(0);
+// Fülle mit wiederholten Elementen
+const filledStream = fill("hallo", 3n); // "hallo", "hallo", "hallo"
 
-console.log(result); // 20 oder 0
+// Erstelle leeren Stream
+const emptyStream = empty<number>();
 ```
 
----
+### Hilfsfunktions-Factories
 
-### 2. `Semantic<E>` – Lazy Datenstrom
+| Methode | Signatur | Beschreibung | Beispiel |
+|------|------|------|------|
+| `validate` | `<T>(t: MaybeInvalid<T>) => t is T` | Validiere ob Wert gültig ist | `validate(null)` → `false` |
+| `invalidate` | `<T>(t: MaybeInvalid<T>) => t is null\|undefined` | Validiere ob Wert ungültig ist | `invalidate(0)` → `false` |
+| `useCompare` | `<T>(t1: T, t2: T) => number` | Generische Vergleichsfunktion | `useCompare("a", "b")` → `-1` |
+| `useRandom` | `<T = number\|bigint>(index: T) => T` | Pseudozufallszahlengenerator | `useRandom(5)` → Zufallszahl |
 
-Ein **Lazy, komponierbarer Sequence-Typ**. Ähnlich wie Java Streams oder Kotlin Sequences.
+**Code-Beispiel-Ergänzung:**
+```typescript
+import { validate, invalidate, useCompare, useRandom } from 'semantic-typescript';
 
-Erstellen Sie einen `Semantic`-Datenstrom mit Helfern wie `from()`, `range()`, `iterate()` oder `fill()`.
+// Validiere Datenvalidität
+const data: string | null = "hallo";
+if (validate(data)) {
+    console.log(data.toUpperCase()); // Sichere Aufruf, da validate sicherstellt, dass Daten nicht null sind
+}
 
-#### Erzeugungsmethoden:
+const nullData: string | null = null;
+if (invalidate(nullData)) {
+    console.log("Daten ungültig"); // Wird ausgeführt, da invalidate null erkannt hat
+}
 
-| 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)` |
+// Vergleiche Werte
+const comparison = useCompare("Apfel", "Banane"); // -1
 
-#### Häufig verwendete Operatoren:
+// Generiere Zufallszahl
+const randomNum = useRandom(42); // Zufallszahl basierend auf Seed 42
+```
 
-| 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)` |
+## Kernklassen-Details
 
----
+### Optional<T> - Sichere Nullwert-Behandlung
 
-### 3. `toUnordered()` – 🚀 Am schnellsten, keine Sortierung
+Die Optional-Klasse bietet einen funktionalen Ansatz zur sicheren Handhabung von Werten, die null oder undefined sein könnten.
 
-Wenn Sie **keine bestimmte Reihenfolge** benötigen und den **schnellsten möglichen Durchsatz** wünschen, verwenden Sie:
+| Methode | Rückgabetyp | Beschreibung | Zeitkomplexität |
+|------|----------|------|------------|
+| `filter(predicate: Predicate<T>)` | `Optional<T>` | Filtere Werte, die Bedingung erfüllen | O(1) |
+| `get()` | `T` | Hole Wert, wirft Fehler wenn leer | O(1) |
+| `getOrDefault(defaultValue: T)` | `T` | Hole Wert oder Standardwert | O(1) |
+| `ifPresent(action: Consumer<T>)` | `void` | Führe Aktion aus wenn Wert existiert | O(1) |
+| `isEmpty()` | `boolean` | Prüfe ob leer | O(1) |
+| `isPresent()` | `boolean` | Prüfe ob Wert existiert | O(1) |
+| `map<R>(mapper: Functional<T, R>)` | `Optional<R>` | Mappe und transformiere Wert | O(1) |
+| `static of<T>(value: MaybeInvalid<T>)` | `Optional<T>` | Erstelle Optional-Instanz | O(1) |
+| `static ofNullable<T>(value?)` | `Optional<T>` | Erstelle nullable Optional | O(1) |
+| `static ofNonNull<T>(value: T)` | `Optional<T>` | Erstelle Non-Null Optional | O(1) |
 
+**Code-Beispiel-Ergänzung:**
 ```typescript
-const fastest = semanticStream.toUnordered();
-```
+import { Optional } from 'semantic-typescript';
 
-🔥 **Es wird kein Sortieralgorithmus verwendet.**  
-Idealerweise bei irrelevanter Reihenfolge und maximalem Performancebedarf.
+// Erstelle Optional-Instanz
+const optionalValue = Optional.ofNullable<string>(Math.random() > 0.5 ? "hallo" : null);
 
----
+// Kettenoperationen
+const result = optionalValue
+    .filter(val => val.length > 3) // Filtere Werte länger als 3
+    .map(val => val.toUpperCase()) // Konvertiere zu Großbuchstaben
+    .getOrDefault("standard"); // Hole Wert oder Standard
 
-### 4. `toOrdered()` und `sorted()` – Sortierte Ausgabe
+console.log(result); // "HALLO" oder "standard"
 
-Wenn Sie eine **sortierte Ausgabe** benötigen, verwenden Sie:
+// Sichere Operationen
+optionalValue.ifPresent(val => {
+    console.log(`Wert existiert: ${val}`);
+});
 
-```typescript
-const ordered = semanticStream.sorted(); // Natürliche Sortierung
-const customSorted = semanticStream.sorted((a, b) => a - b); // Eigene Sortierlogik
-const orderedCollectable = semanticStream.toOrdered(); // Auch sortiert
+// Prüfe Status
+if (optionalValue.isPresent()) {
+    console.log("Hat Wert");
+} else if (optionalValue.isEmpty()) {
+    console.log("Ist leer");
+}
 ```
 
-⚠️ Diese Methoden **sortieren die Elemente**, entweder nach natürlicher Ordnung oder mit einem angegebenen Comparator.
-
----
-
-### 5. `Collector<E, A, R>` – Datensammlung / Aggregation
+### Semantic<E> - Lazy Datenstrom
+
+Semantic ist die Kern-Stream-Verarbeitungsklasse und bietet reichhaltige Stream-Operatoren.
+
+#### Stream-Transformations-Operationen
+
+| Methode | Rückgabetyp | Beschreibung | Leistungsauswirkung |
+|------|----------|------|----------|
+| `concat(other: Semantic<E>)` | `Semantic<E>` | Verkette zwei Streams | O(n+m) |
+| `distinct()` | `Semantic<E>` | Entferne Duplikate (mit Set) | O(n) |
+| `distinct(comparator)` | `Semantic<E>` | Benutzerdefinierte Comparator-Deduplizierung | O(n²) |
+| `dropWhile(predicate)` | `Semantic<E>` | Verwerfe Startelemente, die Bedingung erfüllen | O(n) |
+| `filter(predicate)` | `Semantic<E>` | Filtere Elemente | O(n) |
+| `flat(mapper)` | `Semantic<E>` | Glätte verschachtelte Streams | O(n×m) |
+| `flatMap(mapper)` | `Semantic<R>` | Mappe und glätte | O(n×m) |
+| `limit(n)` | `Semantic<E>` | Begrenze Anzahl der Elemente | O(n) |
+| `map(mapper)` | `Semantic<R>` | Mappe und transformiere Elemente | O(n) |
+| `peek(consumer)` | `Semantic<E>` | Betrachte Elemente ohne Modifikation | O(n) |
+| `redirect(redirector)` | `Semantic<E>` | Leite Indizes um | O(n) |
+| `reverse()` | `Semantic<E>` | Kehre Stream-Reihenfolge um | O(n) |
+| `shuffle()` | `Semantic<E>` | Mische Reihenfolge zufällig | O(n) |
+| `shuffle(mapper)` | `Semantic<E>` | Benutzerdefinierte Shuffle-Logik | O(n) |
+| `skip(n)` | `Semantic<E>` | Überspringe erste n Elemente | O(n) |
+| `sub(start, end)` | `Semantic<E>` | Hole Substream | O(n) |
+| `takeWhile(predicate)` | `Semantic<E>` | Hole Startelemente, die Bedingung erfüllen | O(n) |
+| `translate(offset)` | `Semantic<E>` | Übersetze Indizes | O(n) |
+| `translate(translator)` | `Semantic<E>` | Benutzerdefinierte Index-Transformation | O(n) |
+
+**Code-Beispiel-Ergänzung:**
+```typescript
+import { from } from 'semantic-typescript';
 
-Mit Collectors können Sie Streams in **einzelne oder komplexe Strukturen** umwandeln.
+const stream = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
 
-Eingebaute statische Factorys:
+// Stream-Transformations-Operationsbeispiele
+const processedStream = stream
+    .filter(x => x % 2 === 0) // Filtere gerade Zahlen
+    .map(x => x * 2) // Multipliziere jedes Element mit 2
+    .distinct() // Entferne Duplikate
+    .limit(3) // Begrenze auf erste 3 Elemente
+    .peek((val, index) => console.log(`Element ${val} an Index ${index}`)); // Betrachte Elemente
 
-```typescript
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// Hinweis: Der Stream wurde noch nicht ausgeführt, muss zu Collectable konvertiert werden für Terminaloperationen
 ```
 
-In der Praxis werden Sie diese meist über die höherwertigen Methoden der `Collectable`-Klassen verwenden.
-
----
+#### Stream-Terminaloperationen
 
-### 6. `Collectable<E>` (abstrakte Klasse)
+| Methode | Rückgabetyp | Beschreibung | Leistungscharakteristiken |
+|------|----------|------|----------|
+| `toOrdered()` | `OrderedCollectable<E>` | Konvertiere zu geordneter Sammlung | Sortieroperation, geringere Leistung |
+| `toUnordered()` | `UnorderedCollectable<E>` | Konvertiere zu ungeordneter Sammlung | Schnellste, keine Sortierung |
+| `toWindow()` | `WindowCollectable<E>` | Konvertiere zu Fenster-Sammlung | Sortieroperation, geringere Leistung |
+| `toNumericStatistics()` | `Statistics<E, number>` | Numerische statistische Analyse | Sortieroperation, geringere Leistung |
+| `toBigintStatistics()` | `Statistics<E, bigint>` | Big Integer statistische Analyse | Sortieroperation, geringere Leistung |
+| `sorted()` | `OrderedCollectable<E>` | Natürliche Sortierung | Überschreibt Umleitungsergebnisse |
+| `sorted(comparator)` | `OrderedCollectable<E>` | Benutzerdefinierte Sortierung | Überschreibt Umleitungsergebnisse |
 
-Basisklasse für:
-
-- `OrderedCollectable<E>` – Sortierte Ausgabe
-- `UnorderedCollectable<E>` – Keine Sortierung, schnellster Weg
-- `WindowCollectable<E>` – Gleitende Fenster
-- `Statistics<E, D>` – Statistische Aggregation
+**Code-Beispiel-Ergänzung:**
+```typescript
+import { from } from 'semantic-typescript';
 
-#### Häufige Methoden (über Vererbung):
+const semanticStream = from([5, 2, 8, 1, 9, 3, 7, 4, 6]);
 
-| 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)` |
+// Konvertiere zu geordneter Sammlung (geringere Leistung)
+const ordered = semanticStream.toOrdered();
 
----
+// Konvertiere zu ungeordneter Sammlung (schnellste)
+const unordered = semanticStream.toUnordered();
 
-### 7. `OrderedCollectable<E>` – Sortierte Daten
+// Natürliche Sortierung
+const sortedNatural = semanticStream.sorted();
 
-Wenn Sie möchten, dass die Elemente **automatisch sortiert** werden, verwenden Sie diese Klasse.
+// Benutzerdefinierte Sortierung
+const sortedCustom = semanticStream.sorted((a, b) => b - a); // Absteigende Sortierung
 
-Akzeptiert einen **benutzerdefinierten Comparator** oder nutzt die natürliche Sortierung.
+// Konvertiere zu statistischem Objekt
+const stats = semanticStream.toNumericStatistics();
 
-```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// Hinweis: Muss obige Methoden durch Semantic-Instanz aufrufen, um Collectable zu erhalten, bevor Terminalmethoden verwendet werden
 ```
 
-🔒 **Sortierte Ausgabe garantiert.**
-
----
+### Collector<E, A, R> - Datensammler
 
-### 8. `UnorderedCollectable<E>` – Keine Sortierung (🚀 Schnellster)
+Collectors werden verwendet, um Stream-Daten in spezifische Strukturen zu aggregieren.
 
-Wenn Ihnen die **Reihenfolge egal** ist und Sie die **beste Performance** wünschen, verwenden Sie:
+| Methode | Beschreibung | Verwendungsszenario |
+|------|------|----------|
+| `collect(generator)` | Führe Datensammlung aus | Stream-Terminaloperation |
+| `static full(identity, accumulator, finisher)` | Erstelle vollständigen Collector | Erfordert vollständige Verarbeitung |
+| `static shortable(identity, interruptor, accumulator, finisher)` | Erstelle unterbrechbaren Collector | Kann vorzeitig beendet werden |
 
+**Code-Beispiel-Ergänzung:**
 ```typescript
-const unordered = new UnorderedCollectable(stream);
-// Oder
-const fastest = semanticStream.toUnordered();
+import { Collector } from 'semantic-typescript';
+
+// Erstelle benutzerdefinierten Collector
+const sumCollector = Collector.full(
+    () => 0, // Initialwert
+    (acc, value) => acc + value, // Akkumulator
+    result => result // Finisher-Funktion
+);
+
+// Verwende Collector (erfordert Konvertierung von Semantic zu Collectable zuerst)
+const numbers = from([1, 2, 3, 4, 5]);
+const sum = numbers.toUnordered().collect(sumCollector); // 15
 ```
 
-✅ **Kein Sortieralgorithmus wird ausgeführt**  
-✅ **Beste Performance, wenn Reihenfolge keine Rolle spielt**
-
----
+### Collectable<E> - Sammelbare Daten Abstrakte Klasse
 
-### 9. `Statistics<E, D>` – Statistische Analyse
+Bietet reichhaltige Datenaggregations- und Transformationsmethoden. **Hinweis: Muss zuerst Collectable-Instanz erhalten, indem sorted(), toOrdered() etc. durch Semantic-Instanz aufgerufen werden, bevor die folgenden Methoden verwendet werden können.**
 
-Abstrakte Basisklasse zur Analyse numerischer Daten.
+#### Datenabfrage-Operationen
 
-#### Unterklassen:
+| Methode | Rückgabetyp | Beschreibung | Beispiel |
+|------|----------|------|------|
+| `anyMatch(predicate)` | `boolean` | Ob irgendein Element übereinstimmt | `anyMatch(x => x > 0)` |
+| `allMatch(predicate)` | `boolean` | Ob alle Elemente übereinstimmen | `allMatch(x => x > 0)` |
+| `count()` | `bigint` | Elementanzahl-Statistiken | `count()` → `5n` |
+| `isEmpty()` | `boolean` | Ob Stream leer ist | `isEmpty()` |
+| `findAny()` | `Optional<E>` | Finde irgendein Element | `findAny()` |
+| `findFirst()` | `Optional<E>` | Finde erstes Element | `findFirst()` |
+| `findLast()` | `Optional<E>` | Finde letztes Element | `findLast()` |
 
-- `NumericStatistics<E>` – Für `number`-Werte
-- `BigIntStatistics<E>` – Für `bigint`-Werte
-
-##### Häufig verwendete statistische Methoden:
+**Code-Beispiel-Ergänzung:**
+```typescript
+import { from } from 'semantic-typescript';
 
-| 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()` |
+const numbers = from([1, 2, 3, 4, 5]);
 
----
+// Muss zu Collectable konvertiert werden, bevor Terminalmethoden verwendet werden
+const collectable = numbers.toUnordered();
 
-## 🧪 Vollständiges Beispiel
+// Datenabfrage-Operationen
+const hasEven = collectable.anyMatch(x => x % 2 === 0); // true
+const allPositive = collectable.allMatch(x => x > 0); // true
+const count = collectable.count(); // 5n
+const isEmpty = collectable.isEmpty(); // false
+const firstElement = collectable.findFirst(); // Optional.of(1)
+const anyElement = collectable.findAny(); // Irgendein Element
+```
 
+#### Datenaggregations-Operationen
+
+| Methode | Rückgabetyp | Beschreibung | Komplexität |
+|------|----------|------|--------|
+| `group(classifier)` | `Map<K, E[]>` | Gruppiere nach Classifier | O(n) |
+| `groupBy(keyExtractor, valueExtractor)` | `Map<K, V[]>` | Gruppiere nach Schlüssel-Wert-Extraktoren | O(n) |
+| `join()` | `string` | Verbinde als String | O(n) |
+| `join(delimiter)` | `string` | Verbinde mit Trennzeichen | O(n) |
+| `partition(count)` | `E[][]` | Partitioniere nach Anzahl | O(n) |
+| `partitionBy(classifier)` | `E[][]` | Partitioniere nach Classifier | O(n) |
+| `reduce(accumulator)` | `Optional<E>` | Reduktionsoperation | O(n) |
+| `reduce(identity, accumulator)` | `E` | Reduktion mit Identität | O(n) |
+| `toArray()` | `E[]` | Konvertiere zu Array | O(n) |
+| `toMap(keyExtractor, valueExtractor)` | `Map<K, V>` | Konvertiere zu Map | O(n) |
+| `toSet()` | `Set<E>` | Konvertiere zu Set | O(n) |
+
+**Code-Beispiel-Ergänzung:**
 ```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());
+import { from } from 'semantic-typescript';
+
+const people = from([
+    { name: "Alice", age: 25, city: "New York" },
+    { name: "Bob", age: 30, city: "London" },
+    { name: "Charlie", age: 25, city: "New York" }
+]);
+
+// Muss zu Collectable konvertiert werden, bevor Aggregationsoperationen verwendet werden
+const collectable = people.toUnordered();
+
+// Gruppierungsoperationen
+const byCity = collectable.group(person => person.city);
+// Map { "New York" => [{name: "Alice", ...}, {name: "Charlie", ...}], "London" => [{name: "Bob", ...}] }
+
+const byAge = collectable.groupBy(
+    person => person.age,
+    person => person.name
+);
+// Map { 25 => ["Alice", "Charlie"], 30 => ["Bob"] }
+
+// Konvertiere zu Sammlungen
+const array = collectable.toArray(); // Ursprüngliches Array
+const set = collectable.toSet(); // Set-Sammlung
+const map = collectable.toMap(
+    person => person.name,
+    person => person.age
+); // Map { "Alice" => 25, "Bob" => 30, "Charlie" => 25 }
+
+// Reduktionsoperationen
+const totalAge = collectable.reduce(0, (acc, person) => acc + person.age); // 80
+const oldest = collectable.reduce((a, b) => a.age > b.age ? a : b); // Optional.of({name: "Bob", age: 30, ...})
 ```
 
----
+### Spezifische Collector-Implementierungen
 
-## 🛠️ Hilfsfunktionen
+#### UnorderedCollectable<E>
+- **Charakteristiken**: Schnellster Collector, keine Sortierung
+- **Verwendungsszenarien**: Reihenfolge unwichtig, maximale Leistung gewünscht
+- **Methoden**: Erbt alle Collectable-Methoden
 
-Die Bibliothek exportiert auch zahlreiche **Typ-Guards** und **Vergleichsfunktionen**:
+#### OrderedCollectable<E>
+- **Charakteristiken**: Garantiert Elementreihenfolge, geringere Leistung
+- **Verwendungsszenarien**: Erfordern sortierte Ergebnisse
+- **Spezielle Methoden**: Erbt alle Methoden, behält internen Sortierzustand bei
 
-| 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) |
+#### WindowCollectable<E>
+- **Charakteristiken**: Unterstützt Gleitfenster-Operationen
+- **Verwendungsszenarien**: Zeitreihendatenanalyse
+- **Spezielle Methoden**:
+  - `slide(size, step)` - Gleitfenster
+  - `tumble(size)` - Tumbling-Fenster
 
----
+**Code-Beispiel-Ergänzung:**
+```typescript
+import { from } from 'semantic-typescript';
 
-## 🧩 Erweitert: Eigene Generatoren & Fenster
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
 
-Sie können eigene **Generatoren** für kontrollierte oder unendliche Datenströme erstellen:
+// Ungeordneter Collector (schnellste)
+const unordered = data.toUnordered();
+const unorderedArray = unordered.toArray(); // Kann ursprüngliche Reihenfolge beibehalten [1, 2, 3, ...]
 
-```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);
-```
+// Geordneter Collector
+const ordered = data.toOrdered();
+const orderedArray = ordered.toArray(); // Garantiert sortiert [1, 2, 3, ...]
 
-Oder **gleitende Fenster** verwenden:
+// Fenster-Collector
+const windowed = data.toWindow();
+const slidingWindows = windowed.slide(3n, 2n); // Fenstergröße 3, Schritt 2
+// Fenster 1: [1, 2, 3], Fenster 2: [3, 4, 5], Fenster 3: [5, 6, 7], ...
 
-```typescript
-const windowed = ordered.slide(3n, 2n); // Fenstergröße 3, Schritt 2
+const tumblingWindows = windowed.tumble(4n); // Tumbling-Fenster Größe 4
+// Fenster 1: [1, 2, 3, 4], Fenster 2: [5, 6, 7, 8], ...
 ```
 
----
-
-## 📄 Lizenz
-
-Dieses Projekt steht unter der **MIT-Lizenz** – kostenlos für kommerzielle und private Nutzung.
+### Statistics<E, D> - Statistische Analyse
+
+Statistische Analyse-Basisklasse, die reichhaltige statistische Berechnungsmethoden bietet. **Hinweis: Muss zuerst Statistics-Instanz erhalten, indem toNumericStatistics() oder toBigIntStatistics() durch Semantic-Instanz aufgerufen werden, bevor die folgenden Methoden verwendet werden können.**
+
+#### Statistische Berechnungs-Operationen
+
+| Methode | Rückgabetyp | Beschreibung | Algorithmus-Komplexität |
+|------|----------|------|------------|
+| `maximum()` | `Optional<E>` | Maximalwert | O(n) |
+| `minimum()` | `Optional<E>` | Minimalwert | O(n) |
+| `range()` | `D` | Bereich (max-min) | O(n) |
+| `variance()` | `D` | Varianz | O(n) |
+| `standardDeviation()` | `D` | Standardabweichung | O(n) |
+| `mean()` | `D` | Mittelwert | O(n) |
+| `median()` | `D` | Medianwert | O(n log n) |
+| `mode()` | `D` | Modalwert | O(n) |
+| `frequency()` | `Map<D, bigint>` | Häufigkeitsverteilung | O(n) |
+| `summate()` | `D` | Summierung | O(n) |
+| `quantile(quantile)` | `D` | Quantil | O(n log n) |
+| `interquartileRange()` | `D` | Interquartilsabstand | O(n log n) |
+| `skewness()` | `D` | Schiefe | O(n) |
+| `kurtosis()` | `D` | Kurtosis | O(n) |
+
+**Code-Beispiel-Ergänzung:**
+```typescript
+import { from } from 'semantic-typescript';
+
+const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+// Muss zu statistischem Objekt konvertiert werden, bevor statistische Methoden verwendet werden
+const stats = numbers.toNumericStatistics();
+
+// Grundlegende Statistiken
+const count = stats.count(); // 10n
+const max = stats.maximum(); // Optional.of(10)
+const min = stats.minimum(); // Optional.of(1)
+const range = stats.range(); // 9
+const mean = stats.mean(); // 5.5
+const median = stats.median(); // 5.5
+const sum = stats.summate(); // 55
+
+// Erweiterte Statistiken
+const variance = stats.variance(); // 8.25
+const stdDev = stats.standardDeviation(); // 2.872
+const mode = stats.mode(); // Irgendein Wert (da alle einmal erscheinen)
+const q1 = stats.quantile(0.25); // 3.25
+const q3 = stats.quantile(0.75); // 7.75
+const iqr = stats.interquartileRange(); // 4.5
+
+// Häufigkeitsverteilung
+const freq = stats.frequency(); // Map {1 => 1n, 2 => 1n, ...}
+```
 
----
+#### Spezifische Statistische Implementierungsklassen
 
-## 🙌 Mitwirken
+**NumericStatistics<E>**
+- Verarbeitet number-Typ statistische Analyse
+- Alle statistischen Berechnungen geben number-Typ zurück
 
-Pull Requests, Issues und Ideen sind willkommen!
+**BigIntStatistics<E>**
+- Verarbeitet bigint-Typ statistische Analyse
+- Alle statistischen Berechnungen geben bigint-Typ zurück
 
----
+**Code-Beispiel-Ergänzung:**
+```typescript
+import { from } from 'semantic-typescript';
 
-## 🚀 Schnellstart-Zusammenfassung
+// Numerische Statistiken
+const numberData = from([10, 20, 30, 40, 50]);
+const numericStats = numberData.toNumericStatistics();
 
-| 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. |
+console.log(numericStats.mean()); // 30
+console.log(numericStats.summate()); // 150
 
----
+// Big Integer Statistiken
+const bigintData = from([100n, 200n, 300n, 400n, 500n]);
+const bigintStats = bigintData.toBigIntStatistics();
 
-## 🔗 Links
+console.log(bigintStats.mean()); // 300n
+console.log(bigintStats.summate()); // 1500n
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 Dokumentation: Siehe Quellcode / Typdefinitionen
+// Statistiken mit Mapper-Funktionen
+const objectData = from([
+    { value: 15 },
+    { value: 25 },
+    { value: 35 },
+    { value: 45 }
+]);
 
----
+const objectStats = objectData.toNumericStatistics();
+const meanWithMapper = objectStats.mean(obj => obj.value); // 30
+const sumWithMapper = objectStats.summate(obj => obj.value); // 120
+```
 
-**Genießen Sie komponierbares, typsicheres und funktionales Datenhandling in TypeScript.** 🚀
+## Vollständiges Verwendungsbeispiel
 
---- 
+```typescript
+import { from, validate, invalidate } from 'semantic-typescript';
+
+// 1. Erstelle Datenstrom
+const rawData = [5, 2, 8, 1, null, 9, 3, undefined, 7, 4, 6];
+const semanticStream = from(rawData);
+
+// 2. Stream-Verarbeitungspipeline
+const processedStream = semanticStream
+    .filter(val => validate(val)) // Filtere null und undefined heraus
+    .map(val => val! * 2) // Multipliziere jeden Wert mit 2 (verwende !, da validate sicherstellt, dass nicht leer)
+    .distinct(); // Entferne Duplikate
+
+// 3. Konvertiere zu Collectable und verwende Terminaloperationen
+const collectable = processedStream.toUnordered();
+
+// 4. Datenvalidierung und Verwendung
+if (!collectable.isEmpty()) {
+    const results = collectable
+        .filter(x => x > 5) // Filtere erneut
+        .toArray(); // Konvertiere zu Array
+    
+    console.log("Verarbeitungsergebnisse:", results); // [16, 18, 14, 8, 12]
+    
+    // Statistische Informationen
+    const stats = processedStream.toNumericStatistics();
+    console.log("Mittelwert:", stats.mean()); // 11.2
+    console.log("Gesamtsumme:", stats.summate()); // 56
+}
+
+// 5. Behandle potenziell ungültige Daten
+const potentiallyInvalidData: Array<number | null> = [1, null, 3, 4, null];
+const validData = potentiallyInvalidData.filter(validate);
+const invalidData = potentiallyInvalidData.filter(invalidate);
+
+console.log("Gültige Daten:", validData); // [1, 3, 4]
+console.log("Ungültige Daten:", invalidData); // [null, null]
+```
 
-✅ **Wichtig:**  
-- `toUnordered()` → **Keine Sortierung, schnellster Weg**  
-- Alle anderen (z. B. `sorted()`, `toOrdered()`) → **Sortieren die Daten**
+## Wichtige Verwendungsregeln Zusammenfassung
+
+1. **Erstelle Stream**: Verwende `from()`, `range()`, `fill()` etc. Factory-Methoden, um Semantic-Instanzen zu erstellen
+2. **Stream-Transformation**: Rufe `map()`, `filter()`, `distinct()` etc. Methoden auf Semantic-Instanzen auf
+3. **Konvertiere zu Collectable**: Muss eine der folgenden Methoden durch Semantic-Instanz aufrufen:
+   - `toOrdered()` - Geordneter Collector
+   - `toUnordered()` - Ungeordneter Collector (schnellste)
+   - `toWindow()` - Fenster-Collector
+   - `toNumericStatistics()` - Numerische Statistiken
+   - `toBigIntStatistics()` - Big Integer Statistiken
+   - `sorted()` - Natürliche Sortierung
+   - `sorted(comparator)` - Benutzerdefinierte Sortierung
+4. **Terminaloperationen**: Rufe `toArray()`, `count()`, `summate()` etc. Terminalmethoden auf Collectable-Instanzen auf
+5. **Datenvalidierung**: Verwende `validate()` um sicherzustellen, dass Daten nicht null/undefined sind, verwende `invalidate()` um ungültige Daten zu prüfen
+
+Dieses Design gewährleistet Typsicherheit und Leistungsoptimierung, während es gleichzeitig reichhaltige Stream-Verarbeitungsfunktionalität bietet.