semantic-typescript 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-typescript",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "dist/index.js",       
   "types": "dist/index.d.ts",    

package/readme.de.md

@@ -0,0 +1,335 @@
+# 📘 semantic-typescript
+
+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.
+
+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.
+
+---
+
+## 🧩 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
+
+```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:
+
+```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
+```
+
+---
+
+### 2. `Semantic<E>` – Lazy Datenstrom
+
+Ein **Lazy, komponierbarer Sequence-Typ**. Ähnlich wie Java Streams oder Kotlin Sequences.
+
+Erstellen Sie einen `Semantic`-Datenstrom mit Helfern wie `from()`, `range()`, `iterate()` oder `fill()`.
+
+#### Erzeugungsmethoden:
+
+| 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)` |
+
+#### Häufig verwendete Operatoren:
+
+| 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)` |
+
+---
+
+### 3. `toUnordered()` – 🚀 Am schnellsten, keine Sortierung
+
+Wenn Sie **keine bestimmte Reihenfolge** benötigen und den **schnellsten möglichen Durchsatz** wünschen, verwenden Sie:
+
+```typescript
+const fastest = semanticStream.toUnordered();
+```
+
+🔥 **Es wird kein Sortieralgorithmus verwendet.**  
+Idealerweise bei irrelevanter Reihenfolge und maximalem Performancebedarf.
+
+---
+
+### 4. `toOrdered()` und `sorted()` – Sortierte Ausgabe
+
+Wenn Sie eine **sortierte Ausgabe** benötigen, verwenden Sie:
+
+```typescript
+const ordered = semanticStream.sorted(); // Natürliche Sortierung
+const customSorted = semanticStream.sorted((a, b) => a - b); // Eigene Sortierlogik
+const orderedCollectable = semanticStream.toOrdered(); // Auch sortiert
+```
+
+⚠️ Diese Methoden **sortieren die Elemente**, entweder nach natürlicher Ordnung oder mit einem angegebenen Comparator.
+
+---
+
+### 5. `Collector<E, A, R>` – Datensammlung / Aggregation
+
+Mit Collectors können Sie Streams in **einzelne oder komplexe Strukturen** umwandeln.
+
+Eingebaute statische Factorys:
+
+```typescript
+Collector.full(identity, accumulator, finisher)
+Collector.shortable(identity, interruptor, accumulator, finisher)
+```
+
+In der Praxis werden Sie diese meist über die höherwertigen Methoden der `Collectable`-Klassen verwenden.
+
+---
+
+### 6. `Collectable<E>` (abstrakte Klasse)
+
+Basisklasse für:
+
+- `OrderedCollectable<E>` – Sortierte Ausgabe
+- `UnorderedCollectable<E>` – Keine Sortierung, schnellster Weg
+- `WindowCollectable<E>` – Gleitende Fenster
+- `Statistics<E, D>` – Statistische Aggregation
+
+#### Häufige Methoden (über Vererbung):
+
+| 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)` |
+
+---
+
+### 7. `OrderedCollectable<E>` – Sortierte Daten
+
+Wenn Sie möchten, dass die Elemente **automatisch sortiert** werden, verwenden Sie diese Klasse.
+
+Akzeptiert einen **benutzerdefinierten Comparator** oder nutzt die natürliche Sortierung.
+
+```typescript
+const sorted = new OrderedCollectable(stream);
+const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+```
+
+🔒 **Sortierte Ausgabe garantiert.**
+
+---
+
+### 8. `UnorderedCollectable<E>` – Keine Sortierung (🚀 Schnellster)
+
+Wenn Ihnen die **Reihenfolge egal** ist und Sie die **beste Performance** wünschen, verwenden Sie:
+
+```typescript
+const unordered = new UnorderedCollectable(stream);
+// Oder
+const fastest = semanticStream.toUnordered();
+```
+
+✅ **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
+
+```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());
+```
+
+---
+
+## 🛠️ 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:
+
+```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);
+```
+
+Oder **gleitende Fenster** verwenden:
+
+```typescript
+const windowed = ordered.slide(3n, 2n); // Fenstergröße 3, Schritt 2
+```
+
+---
+
+## 📄 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
+
+- 📦 npm: https://www.npmjs.com/package/semantic-typescript
+- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
+- 📘 Dokumentation: Siehe Quellcode / Typdefinitionen
+
+---
+
+**Genießen Sie komponierbares, typsicheres und funktionales Datenhandling in TypeScript.** 🚀
+
+--- 
+
+✅ **Wichtig:**  
+- `toUnordered()` → **Keine Sortierung, schnellster Weg**  
+- Alle anderen (z. B. `sorted()`, `toOrdered()`) → **Sortieren die Daten**

package/readme.es.md

@@ -0,0 +1,335 @@
+# 📘 semantic-typescript
+
+Una poderosa biblioteca de utilidades para **procesamiento semántico de datos** en TypeScript, completamente **segura y tipada**.  
+Proporciona construcciones funcionales compuestas para trabajar con colecciones, flujos y secuencias — con soporte para ordenar, filtrar, agrupar, realizar análisis estadísticos y más.
+
+Ya sea que estés procesando **datos ordenados o no ordenados**, realizando **análisis estadísticos**, o simplemente **encadenando operaciones de forma fluida**, esta biblioteca está diseñada para cubrir todas tus necesidades.
+
+---
+
+## 🧩 Características
+
+- ✅ **Genéricos tipados de forma segura** en toda la biblioteca
+- ✅ Estilo **funcional** (map, filter, reduce, etc.)
+- ✅ **Flujos de datos semánticos** (`Semantic<E>`) para evaluación diferida (lazy)
+- ✅ **Coleccionadores (Collectors)** para transformar flujos en estructuras concretas
+- ✅ **Collectables ordenados y no ordenados** — `toUnordered()` es **el más rápido (sin ordenar)**
+- ✅ **Soporte para ordenar** mediante `sorted()`, `toOrdered()`, y comparadores personalizados
+- ✅ **Análisis estadístico** (`Statistics`, `NumericStatistics`, `BigIntStatistics`)
+- ✅ **Optional<T>** — monada para manejar valores nulos de forma segura
+- ✅ Diseño basado en **iteradores y generadores** — ideal para grandes volúmenes o datos asíncronos
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install semantic-typescript
+```
+
+---
+
+## 🧠 Conceptos clave
+
+### 1. `Optional<T>` — Manejo seguro de valores nulos
+
+Un contenedor monádico para valores que pueden ser `null` o `undefined`.
+
+#### Métodos:
+
+| Método | Descripción | Ejemplo |
+|--------|-------------|---------|
+| `of(value)` | Envolver un valor (puede ser nulo) | `Optional.of(null)` |
+| `ofNullable(v)` | Envolver, permite valores nulos | `Optional.ofNullable(someVar)` |
+| `ofNonNull(v)` | Envolver, lanza excepción si es nulo/undefined | `Optional.ofNonNull(5)` |
+| `get()` | Obtener el valor (o lanzar excepción si está vacío) | `opt.get()` |
+| `getOrDefault(d)` | Obtener el valor o un valor por defecto | `opt.getOrDefault(0)` |
+| `ifPresent(fn)` | Ejecutar un efecto secundario si hay valor | `opt.ifPresent(x => console.log(x))` |
+| `map(fn)` | Transformar el valor si existe | `opt.map(x => x + 1)` |
+| `filter(fn)` | Conservar el valor solo si cumple el predicado | `opt.filter(x => x > 0)` |
+| `isEmpty()` | Verificar si está vacío | `opt.isEmpty()` |
+| `isPresent()` | Verificar si tiene un valor | `opt.isPresent()` |
+
+#### Ejemplo:
+
+```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 o 0
+```
+
+---
+
+### 2. `Semantic<E>` — Flujo de datos diferido
+
+Un **flujo secuencial diferido y compuesto**. Similar a Java Streams o Kotlin Sequences.
+
+Puedes crear un `Semantic` usando funciones como `from()`, `range()`, `iterate()` o `fill()`.
+
+#### Creadores:
+
+| Función | Descripción | Ejemplo |
+|--------|-------------|---------|
+| `from(iterable)` | Crear desde un Array, Set, Iterable | `from([1, 2, 3])` |
+| `range(start, end, step?)` | Generar una secuencia de números | `range(0, 5)` → 0,1,2,3,4 |
+| `fill(element, count)` | Repetir un elemento N veces | `fill('a', 3n)` |
+| `iterate(gen)` | Usar una función generadora personalizada | `iterate(genFn)` |
+
+#### Operadores comunes:
+
+| Método | Descripción | Ejemplo |
+|--------|-------------|---------|
+| `map(fn)` | Transformar cada elemento | `.map(x => x * 2)` |
+| `filter(fn)` | Conservar elementos que cumplen el predicado | `.filter(x => x > 10)` |
+| `limit(n)` | Limitar a los primeros N elementos | `.limit(5)` |
+| `skip(n)` | Saltar los primeros N elementos | `.skip(2)` |
+| `distinct()` | Eliminar duplicados (usa Set por defecto) | `.distinct()` |
+| `sorted()` | Ordenar elementos (orden natural) | `.sorted()` |
+| `sorted(comparator)` | Ordenar con un comparador personalizado | `.sorted((a, b) => a - b)` |
+| `toOrdered()` | Ordenar y devolver un `OrderedCollectable` | `.toOrdered()` |
+| `toUnordered()` | **Sin ordenar** — el más rápido | `.toUnordered()` ✅ |
+| `collect(collector)` | Agregar usando un `Collector` | `.collect(Collector.full(...))` |
+| `toArray()` | Convertir a Array | `.toArray()` |
+| `toSet()` | Convertir a Set | `.toSet()` |
+| `toMap(keyFn, valFn)` | Convertir a Map | `.toMap(x => x.id, x => x)` |
+
+---
+
+### 3. `toUnordered()` — 🚀 El más rápido, sin ordenar
+
+Si **no necesitas orden** y quieres el **máximo rendimiento**, utiliza:
+
+```typescript
+const fastest = semanticStream.toUnordered();
+```
+
+🔥 **No se aplica ningún algoritmo de ordenamiento.**  
+Ideal cuando el orden no importa y la velocidad es prioritaria.
+
+---
+
+### 4. `toOrdered()` y `sorted()` — Resultados ordenados
+
+Si necesitas un **resultado ordenado**, puedes usar:
+
+```typescript
+const ordered = semanticStream.sorted(); // Orden natural
+const customSorted = semanticStream.sorted((a, b) => a - b); // Comparador personalizado
+const orderedCollectable = semanticStream.toOrdered(); // También ordenado
+```
+
+⚠️ Estos métodos **ordenarán los elementos**, usando orden natural o el comparador dado.
+
+---
+
+### 5. `Collector<E, A, R>` — Agregación de datos
+
+Los **colectores** te permiten **reducir un flujo a una estructura única o compleja**.
+
+Existen fábricas estáticas como:
+
+```typescript
+Collector.full(identity, accumulator, finisher)
+Collector.shortable(identity, interruptor, accumulator, finisher)
+```
+
+Pero normalmente los usarás a través de métodos de alto nivel en las clases `Collectable`.
+
+---
+
+### 6. `Collectable<E>` (clase abstracta)
+
+Clase base para:
+
+- `OrderedCollectable<E>` — Resultados ordenados
+- `UnorderedCollectable<E>` — Sin ordenar, el más rápido
+- `WindowCollectable<E>` — Ventanas deslizantes
+- `Statistics<E, D>` — Estadísticas agregadas
+
+#### Métodos comunes (heredados):
+
+| Método | Descripción | Ejemplo |
+|--------|-------------|---------|
+| `count()` | Contar elementos | `.count()` |
+| `toArray()` | Convertir a Array | `.toArray()` |
+| `toSet()` | Convertir a Set | `.toSet()` |
+| `toMap(k, v)` | Convertir a Map | `.toMap(x => x.id, x => x)` |
+| `group(k)` | Agrupar por clave | `.group(x => x.category)` |
+| `findAny()` | Encontrar cualquier elemento (Optional) | `.findAny()` |
+| `findFirst()` | Encontrar el primer elemento (Optional) | `.findFirst()` |
+| `reduce(...)` | Reducción personalizada | `.reduce((a,b) => a + b, 0)` |
+
+---
+
+### 7. `OrderedCollectable<E>` — Datos ordenados
+
+Si deseas que los elementos estén **ordenados automáticamente**, usa esta clase.
+
+Acepta un **comparador personalizado** o el orden natural.
+
+```typescript
+const sorted = new OrderedCollectable(stream);
+const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+```
+
+🔒 **El orden está garantizado.**
+
+---
+
+### 8. `UnorderedCollectable<E>` — Sin ordenar (🚀 Más rápido)
+
+Si **no te importa el orden** y buscas el **mejor rendimiento**, usa:
+
+```typescript
+const unordered = new UnorderedCollectable(stream);
+// O
+const fastest = semanticStream.toUnordered();
+```
+
+✅ **No se ejecuta ningún algoritmo de ordenamiento**  
+✅ **Mejor rendimiento cuando el orden no importa**
+
+---
+
+### 9. `Statistics<E, D>` — Análisis estadístico
+
+Clase abstracta para analizar datos numéricos.
+
+#### Subclases:
+
+- `NumericStatistics<E>` — Para valores `number`
+- `BigIntStatistics<E>` — Para valores `bigint`
+
+##### Métodos estadísticos comunes:
+
+| Método | Descripción | Ejemplo |
+|--------|-------------|---------|
+| `mean()` | Media | `.mean()` |
+| `median()` | Mediana | `.median()` |
+| `mode()` | Moda (valor más frecuente) | `.mode()` |
+| `minimum()` | Mínimo | `.minimum()` |
+| `maximum()` | Máximo | `.maximum()` |
+| `range()` | Rango (máximo - mínimo) | `.range()` |
+| `variance()` | Varianza | `.variance()` |
+| `standardDeviation()` | Desviación estándar | `.standardDeviation()` |
+| `summate()` | Suma total | `.summate()` |
+| `quantile(q)` | Valor en el percentil q (0–1) | `.quantile(0.5)` → mediana |
+| `frequency()` | Frecuencia como Map | `.frequency()` |
+
+---
+
+## 🧪 Ejemplo completo
+
+```typescript
+import { from, toUnordered, toOrdered, sorted, NumericStatistics } from 'semantic-typescript';
+
+// Datos de ejemplo
+const numbers = from([10, 2, 8, 4, 5, 6]);
+
+// 🚀 Más rápido: sin ordenar
+const fastest = numbers.toUnordered();
+console.log(fastest.toArray()); // Ej: [10, 2, 8, 4, 5, 6] (orden original)
+
+// 🔢 Orden natural
+const ordered = numbers.sorted();
+console.log(ordered.toArray()); // [2, 4, 5, 6, 8, 10]
+
+// 📊 Estadísticas
+const stats = new NumericStatistics(numbers);
+console.log('Media:', stats.mean());
+console.log('Mediana:', stats.median());
+console.log('Moda:', stats.mode());
+console.log('Rango:', stats.range());
+console.log('Desviación estándar:', stats.standardDeviation());
+```
+
+---
+
+## 🛠️ Funciones útiles
+
+La librería también exporta varias **guardas de tipo (type guards)** y **herramientas de comparación**:
+
+| Función | Propósito |
+|--------|-----------|
+| `isString(x)` | Guarda de tipo para `string` |
+| `isNumber(x)` | Guarda de tipo para `number` |
+| `isBoolean(x)` | Guarda de tipo para `boolean` |
+| `isIterable(x)` | Comprueba si un objeto es iterable |
+| `useCompare(a, b)` | Función de comparación universal |
+| `useRandom(x)` | Generador de números aleatorios (divertido) |
+
+---
+
+## 🧩 Avanzado: Generadores personalizados y ventanas
+
+Puedes crear **generadores personalizados** para flujos controlados o infinitos:
+
+```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);
+```
+
+O usar **ventanas deslizantes (sliding windows)**:
+
+```typescript
+const windowed = ordered.slide(3n, 2n); // Ventanas de tamaño 3, salto de 2
+```
+
+---
+
+## 📄 Licencia
+
+Este proyecto está bajo la licencia **MIT** — libre para uso comercial y personal.
+
+---
+
+## 🙌 Contribuir
+
+¡Pull requests, issues y sugerencias son bienvenidos!
+
+---
+
+## 🚀 Resumen rápido
+
+| Tarea | Método |
+|-------|--------|
+| Manejar nulos con seguridad | `Optional<T>` |
+| Crear un flujo | `from([...])`, `range()`, `fill()` |
+| Transformar datos | `map()`, `filter()` |
+| Ordenar datos | `sorted()`, `toOrdered()` |
+| Sin ordenar (más rápido) | `toUnordered()` ✅ |
+| Agrupar / Agregar | `toMap()`, `group()`, `Collector` |
+| Estadísticas | `NumericStatistics`, `mean()`, `median()`, etc. |
+
+---
+
+## 🔗 Enlaces
+
+- 📦 npm: https://www.npmjs.com/package/semantic-typescript
+- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
+- 📘 Documentación: Ver código fuente / definiciones de tipo
+
+---
+
+**Disfruta del procesamiento de datos funcional, seguro y compuesto en TypeScript.** 🚀
+
+--- 
+
+✅ **Recuerda:**  
+- `toUnordered()` → **Sin ordenar, más rápido**  
+- Los demás (`sorted()`, `toOrdered()`, etc.) → **Ordenan los datos**