semantic-typescript 0.0.1 → 0.0.3

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**

package/readme.fr.md

@@ -0,0 +1,335 @@
+# 📘 semantic-typescript
+
+Une bibliothèque TypeScript puissante et typée en toute sécurité, conçue pour le **traitement sémantique de données**.  
+Elle fournit des constructions fonctionnelles composites pour travailler avec des collections, des flux et des séquences — avec prise en charge du tri, du filtrage, du regroupement, des statistiques et bien plus encore.
+
+Que vous traitiez des **données ordonnées ou non ordonnées**, effectuiez des **analyses statistiques**, ou que vous souhaitiez simplement **chaîner des opérations de manière fluide**, cette bibliothèque est faite pour vous.
+
+---
+
+## 🧩 Caractéristiques
+
+- ✅ **Génériques typés en toute sécurité** dans toute la bibliothèque
+- ✅ Style **programmation fonctionnelle** (map, filter, reduce, etc.)
+- ✅ **Flux de données sémantiques** (`Semantic<E>`) pour une **évaluation paresseuse**
+- ✅ **Collecteurs** pour transformer des flux en structures concrètes
+- ✅ **Collectables ordonnés et non ordonnés** — `toUnordered()` est **le plus rapide (pas de tri)**
+- ✅ **Tri** via `sorted()`, `toOrdered()`, comparateurs personnalisés
+- ✅ **Analyse statistique** (`Statistics`, `NumericStatistics`, `BigIntStatistics`)
+- ✅ **Optional<T>** — monade pour manipuler en toute sécurité les valeurs nulles
+- ✅ Conception basée sur les **itérateurs et générateurs** — adaptée aux gros volumes ou données asynchrones
+
+---
+
+## 📦 Installation
+
+```bash
+npm install semantic-typescript
+```
+
+---
+
+## 🧠 Concepts clés
+
+### 1. `Optional<T>` — Gestion sûre des valeurs nulles
+
+Un conteneur monadique pour des valeurs pouvant être `null` ou `undefined`.
+
+#### Méthodes :
+
+| Méthode | Description | Exemple |
+|--------|-------------|---------|
+| `of(value)` | Envelopper une valeur (peut être nulle) | `Optional.of(null)` |
+| `ofNullable(v)` | Envelopper, autorise les valeurs nulles | `Optional.ofNullable(someVar)` |
+| `ofNonNull(v)` | Envelopper, lève une erreur si null/undefined | `Optional.ofNonNull(5)` |
+| `get()` | Obtenir la valeur (ou lever une exception si vide) | `opt.get()` |
+| `getOrDefault(d)` | Obtenir la valeur ou une valeur par défaut | `opt.getOrDefault(0)` |
+| `ifPresent(fn)` | Exécuter un effet de bord si la valeur existe | `opt.ifPresent(x => console.log(x))` |
+| `map(fn)` | Transformer la valeur si elle existe | `opt.map(x => x + 1)` |
+| `filter(fn)` | Conserver la valeur seulement si le prédicat est vrai | `opt.filter(x => x > 0)` |
+| `isEmpty()` | Vérifie si la valeur est absente | `opt.isEmpty()` |
+| `isPresent()` | Vérifie si une valeur est présente | `opt.isPresent()` |
+
+#### Exemple :
+
+```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 ou 0
+```
+
+---
+
+### 2. `Semantic<E>` — Flux de données paresseux
+
+Un **flux séquentiel paresseux et composite**. Similaire aux Java Streams ou aux Kotlin Sequences.
+
+Créez un `Semantic` à l’aide d’assistants comme `from()`, `range()`, `iterate()` ou `fill()`.
+
+#### Créateurs :
+
+| Fonction | Description | Exemple |
+|----------|-------------|---------|
+| `from(iterable)` | Créer à partir d’un Array, Set, Iterable | `from([1, 2, 3])` |
+| `range(start, end, step?)` | Générer une plage de nombres | `range(0, 5)` → 0,1,2,3,4 |
+| `fill(element, count)` | Répéter un élément N fois | `fill('a', 3n)` |
+| `iterate(gen)` | Utiliser une fonction générateur personnalisée | `iterate(genFn)` |
+
+#### Opérateurs courants :
+
+| Méthode | Description | Exemple |
+|--------|-------------|---------|
+| `map(fn)` | Transformer chaque élément | `.map(x => x * 2)` |
+| `filter(fn)` | Conserver les éléments répondant au prédicat | `.filter(x => x > 10)` |
+| `limit(n)` | Limiter aux N premiers éléments | `.limit(5)` |
+| `skip(n)` | Ignorer les N premiers éléments | `.skip(2)` |
+| `distinct()` | Supprimer les doublons (utilise Set par défaut) | `.distinct()` |
+| `sorted()` | Trier les éléments (ordre naturel) | `.sorted()` |
+| `sorted(comparator)` | Trier avec un comparateur personnalisé | `.sorted((a, b) => a - b)` |
+| `toOrdered()` | Trier et retourner un `OrderedCollectable` | `.toOrdered()` |
+| `toUnordered()` | **Pas de tri** — le plus rapide | `.toUnordered()` ✅ |
+| `collect(collector)` | Aggréger avec un `Collector` | `.collect(Collector.full(...))` |
+| `toArray()` | Convertir en tableau | `.toArray()` |
+| `toSet()` | Convertir en Set | `.toSet()` |
+| `toMap(keyFn, valFn)` | Convertir en Map | `.toMap(x => x.id, x => x)` |
+
+---
+
+### 3. `toUnordered()` — 🚀 Le plus rapide, sans tri
+
+Si vous **n’avez pas besoin d’ordre** et que vous souhaitez les **meilleures performances possibles**, utilisez :
+
+```typescript
+const fastest = semanticStream.toUnordered();
+```
+
+🔥 **Aucun algorithme de tri n’est appliqué.**  
+Parfait lorsque l’ordre n’a pas d’importance et que la vitesse est cruciale.
+
+---
+
+### 4. `toOrdered()` et `sorted()` — Résultats triés
+
+Si vous avez besoin d’un **résultat trié**, utilisez :
+
+```typescript
+const ordered = semanticStream.sorted(); // Tri naturel
+const customSorted = semanticStream.sorted((a, b) => a - b); // Comparateur personnalisé
+const orderedCollectable = semanticStream.toOrdered(); // Aussi trié
+```
+
+⚠️ Ces méthodes **trient les éléments**, en utilisant l’ordre naturel ou un comparateur fourni.
+
+---
+
+### 5. `Collector<E, A, R>` — Agrégation de données
+
+Les collecteurs vous permettent de **réduire un flux en une structure unique ou complexe**.
+
+Des factories statiques sont disponibles :
+
+```typescript
+Collector.full(identity, accumulator, finisher)
+Collector.shortable(identity, interruptor, accumulator, finisher)
+```
+
+Mais vous utiliserez surtout les méthodes haut niveau fournies par les classes `Collectable`.
+
+---
+
+### 6. `Collectable<E>` (classe abstraite)
+
+Classe de base pour :
+
+- `OrderedCollectable<E>` — Résultats triés
+- `UnorderedCollectable<E>` — Pas de tri, le plus rapide
+- `WindowCollectable<E>` — Fenêtres glissantes
+- `Statistics<E, D>` — Statistiques agrégées
+
+#### Méthodes communes (via héritage) :
+
+| Méthode | Description | Exemple |
+|--------|-------------|---------|
+| `count()` | Compter les éléments | `.count()` |
+| `toArray()` | Convertir en tableau | `.toArray()` |
+| `toSet()` | Convertir en Set | `.toSet()` |
+| `toMap(k, v)` | Convertir en Map | `.toMap(x => x.id, x => x)` |
+| `group(k)` | Regrouper par clé | `.group(x => x.category)` |
+| `findAny()` | Trouver un élément quelconque (Optional) | `.findAny()` |
+| `findFirst()` | Trouver le premier élément (Optional) | `.findFirst()` |
+| `reduce(...)` | Réduction personnalisée | `.reduce((a,b) => a + b, 0)` |
+
+---
+
+### 7. `OrderedCollectable<E>` — Données triées
+
+Si vous souhaitez que les éléments soient **triés automatiquement**, utilisez cette classe.
+
+Elle accepte un **comparateur personnalisé** ou utilise l’ordre naturel.
+
+```typescript
+const sorted = new OrderedCollectable(stream);
+const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+```
+
+🔒 **Le tri est garanti.**
+
+---
+
+### 8. `UnorderedCollectable<E>` — Pas de tri (🚀 Le plus rapide)
+
+Si vous **n’avez pas besoin de tri** et que vous voulez les **meilleures performances**, utilisez :
+
+```typescript
+const unordered = new UnorderedCollectable(stream);
+// OU
+const fastest = semanticStream.toUnordered();
+```
+
+✅ **Aucun algorithme de tri n’est exécuté**  
+✅ **Meilleure performance lorsque l’ordre n’a pas d’importance**
+
+---
+
+### 9. `Statistics<E, D>` — Analyse statistique
+
+Classe abstraite pour analyser des données numériques.
+
+#### Sous-classes :
+
+- `NumericStatistics<E>` — Pour des valeurs de type `number`
+- `BigIntStatistics<E>` — Pour des valeurs de type `bigint`
+
+##### Méthodes statistiques courantes :
+
+| Méthode | Description | Exemple |
+|--------|-------------|---------|
+| `mean()` | Moyenne | `.mean()` |
+| `median()` | Médiane | `.median()` |
+| `mode()` | Mode (valeur la plus fréquente) | `.mode()` |
+| `minimum()` | Minimum | `.minimum()` |
+| `maximum()` | Maximum | `.maximum()` |
+| `range()` | Écart (max - min) | `.range()` |
+| `variance()` | Variance | `.variance()` |
+| `standardDeviation()` | Écart-type | `.standardDeviation()` |
+| `summate()` | Somme | `.summate()` |
+| `quantile(q)` | Valeur au quantile q (0–1) | `.quantile(0.5)` → médiane |
+| `frequency()` | Fréquence sous forme de Map | `.frequency()` |
+
+---
+
+## 🧪 Exemple complet
+
+```typescript
+import { from, toUnordered, toOrdered, sorted, NumericStatistics } from 'semantic-typescript';
+
+// Données d'exemple
+const numbers = from([10, 2, 8, 4, 5, 6]);
+
+// 🚀 Le plus rapide : pas de tri
+const fastest = numbers.toUnordered();
+console.log(fastest.toArray()); // ex: [10, 2, 8, 4, 5, 6] (ordre d'origine)
+
+// 🔢 Tri naturel
+const ordered = numbers.sorted();
+console.log(ordered.toArray()); // [2, 4, 5, 6, 8, 10]
+
+// 📊 Statistiques
+const stats = new NumericStatistics(numbers);
+console.log('Moyenne:', stats.mean());
+console.log('Médiane:', stats.median());
+console.log('Mode:', stats.mode());
+console.log('Écart:', stats.range());
+console.log('Écart-type:', stats.standardDeviation());
+```
+
+---
+
+## 🛠️ Fonctions utilitaires
+
+La bibliothèque exporte aussi plusieurs **tests de type (type guards)** et **outils de comparaison** :
+
+| Fonction | But |
+|----------|-----|
+| `isString(x)` | Test de type pour `string` |
+| `isNumber(x)` | Test de type pour `number` |
+| `isBoolean(x)` | Test de type pour `boolean` |
+| `isIterable(x)` | Vérifie si un objet est itérable |
+| `useCompare(a, b)` | Fonction de comparaison universelle |
+| `useRandom(x)` | Générateur de nombre aléatoire (divertissant) |
+
+---
+
+## 🧩 Avancé : Générateurs personnalisés et fenêtres
+
+Vous pouvez créer des **générateurs personnalisés** pour des flux de données contrôlés ou infinis :
+
+```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);
+```
+
+Ou utiliser des **fenêtres glissantes** :
+
+```typescript
+const windowed = ordered.slide(3n, 2n); // fenêtres de taille 3, pas de 2
+```
+
+---
+
+## 📄 Licence
+
+Ce projet est sous **licence MIT** — libre pour un usage commercial ou personnel.
+
+---
+
+## 🙌 Contribution
+
+Les pull requests, problèmes (issues) et idées sont les bienvenus !
+
+---
+
+## 🚀 Résumé du démarrage rapide
+
+| Tâche | Méthode |
+|-------|---------|
+| Gérer les valeurs nulles | `Optional<T>` |
+| Créer un flux | `from([...])`, `range()`, `fill()` |
+| Transformer des données | `map()`, `filter()` |
+| Trier des données | `sorted()`, `toOrdered()` |
+| Pas de tri (le plus rapide) | `toUnordered()` ✅ |
+| Regrouper / Aggréger | `toMap()`, `group()`, `Collector` |
+| Statistiques | `NumericStatistics`, `mean()`, `median()`, etc. |
+
+---
+
+## 🔗 Liens
+
+- 📦 npm: https://www.npmjs.com/package/semantic-typescript
+- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
+- 📘 Documentation : voir le code source / définitions de type
+
+---
+
+**Profitez d’un traitement de données fonctionnel, typé et composable en TypeScript.** 🚀
+
+--- 
+
+✅ **À retenir :**  
+- `toUnordered()` → **Pas de tri, le plus rapide**  
+- Les autres (`sorted()`, `toOrdered()`, etc.) → **Tri des données**