semantic-typescript 0.0.7 → 0.1.4

package/readme.fr.md

@@ -1,335 +1,428 @@
-# 📘 semantic-typescript
+# Bibliothèque de Traitement de Flux 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.
+## Introduction
 
-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.
+Semantic-TypeScript est une bibliothèque moderne de traitement de flux inspirée par JavaScript GeneratorFunction, Java Stream et MySQL Index. La conception centrale de la bibliothèque repose sur la construction de pipelines efficaces de traitement de données utilisant des index de données, offrant aux développeurs frontend une expérience de traitement de flux avec sécurité de type et style fonctionnel.
 
----
+Contrairement au traitement synchrone traditionnel, Semantic adopte un mode de traitement asynchrone. Lors de la création de flux de données, le moment où le terminal reçoit les données dépend entièrement du moment où la source en amont appelle les fonctions de callback `accept` et `interrupt`. Cette conception permet à la bibliothèque de gérer élégamment les flux de données en temps réel, les grands ensembles de données et les sources de données asynchrones.
 
-## 🧩 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
+## 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 :
+## Types de Base
+
+| Type | Description |
+|------|-------------|
+| `Invalid<T>` | Type étendant null ou undefined |
+| `Valid<T>` | Type excluant null et undefined |
+| `MaybeInvalid<T>` | Type pouvant être null ou undefined |
+| `Primitive` | Collection de types primitifs |
+| `MaybePrimitive<T>` | Type pouvant être un primitif |
+| `OptionalSymbol` | Identificateur symbolique pour la classe Optional |
+| `SemanticSymbol` | Identificateur symbolique pour la classe Semantic |
+| `CollectorsSymbol` | Identificateur symbolique pour la classe Collector |
+| `CollectableSymbol` | Identificateur symbolique pour la classe Collectable |
+| `OrderedCollectableSymbol` | Identificateur symbolique pour la classe OrderedCollectable |
+| `WindowCollectableSymbol` | Identificateur symbolique pour la classe WindowCollectable |
+| `StatisticsSymbol` | Identificateur symbolique pour la classe Statistics |
+| `NumericStatisticsSymbol` | Identificateur symbolique pour la classe NumericStatistics |
+| `BigIntStatisticsSymbol` | Identificateur symbolique pour la classe BigIntStatistics |
+| `UnorderedCollectableSymbol` | Identificateur symbolique pour la classe UnorderedCollectable |
+| `Runnable` | Fonction sans paramètre ni valeur de retour |
+| `Supplier<R>` | Fonction sans paramètre retournant R |
+| `Functional<T, R>` | Fonction de transformation à un paramètre |
+| `Predicate<T>` | Fonction de prédicat à un paramètre |
+| `BiFunctional<T, U, R>` | Fonction de transformation à deux paramètres |
+| `BiPredicate<T, U>` | Fonction de prédicat à deux paramètres |
+| `Comparator<T>` | Fonction de comparaison |
+| `TriFunctional<T, U, V, R>` | Fonction de transformation à trois paramètres |
+| `Consumer<T>` | Fonction consommatrice à un paramètre |
+| `BiConsumer<T, U>` | Fonction consommatrice à deux paramètres |
+| `TriConsumer<T, U, V>` | Fonction consommatrice à trois paramètres |
+| `Generator<T>` | Fonction génératrice |
 
 ```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
+// Exemples d'utilisation des types
+const predicate: Predicate<number> = (n) => n > 0;
+const mapper: Functional<string, number> = (str) => str.length;
+const comparator: Comparator<number> = (a, b) => a - b;
 ```
 
----
+## Gardes de Type
+
+| Fonction | Description | Complexité Temporelle | Complexité Spatiale |
+|----------|-------------|----------------------|---------------------|
+| `validate<T>(t: MaybeInvalid<T>): t is T` | Valide que la valeur n'est pas null ou undefined | O(1) | O(1) |
+| `invalidate<T>(t: MaybeInvalid<T>): t is null \| undefined` | Valide que la valeur est null ou undefined | O(1) | O(1) |
+| `isBoolean(t: unknown): t is boolean` | Vérifie si c'est un booléen | O(1) | O(1) |
+| `isString(t: unknown): t is string` | Vérifie si c'est une chaîne | O(1) | O(1) |
+| `isNumber(t: unknown): t is number` | Vérifie si c'est un nombre | O(1) | O(1) |
+| `isFunction(t: unknown): t is Function` | Vérifie si c'est une fonction | O(1) | O(1) |
+| `isObject(t: unknown): t is object` | Vérifie si c'est un objet | O(1) | O(1) |
+| `isSymbol(t: unknown): t is symbol` | Vérifie si c'est un symbole | O(1) | O(1) |
+| `isBigint(t: unknown): t is bigint` | Vérifie si c'est un BigInt | O(1) | O(1) |
+| `isPrimitive(t: unknown): t is Primitive` | Vérifie si c'est un type primitif | O(1) | O(1) |
+| `isIterable(t: unknown): t is Iterable<unknown>` | Vérifie si c'est itérable | O(1) | O(1) |
+| `isOptional(t: unknown): t is Optional<unknown>` | Vérifie si c'est une instance d'Optional | O(1) | O(1) |
+| `isSemantic(t: unknown): t is Semantic<unknown>` | Vérifie si c'est une instance de Semantic | O(1) | O(1) |
+| `isCollector(t: unknown): t is Collector<unknown, unknown, unknown>` | Vérifie si c'est une instance de Collector | O(1) | O(1) |
+| `isCollectable(t: unknown): t is Collectable<unknown>` | Vérifie si c'est une instance de Collectable | O(1) | O(1) |
+| `isOrderedCollectable(t: unknown): t is OrderedCollectable<unknown>` | Vérifie si c'est une instance d'OrderedCollectable | O(1) | O(1) |
+| `isWindowCollectable(t: unknown): t is WindowCollectable<unknown>` | Vérifie si c'est une instance de WindowCollectable | O(1) | O(1) |
+| `isUnorderedCollectable(t: unknown): t is UnorderedCollectable<unknown>` | Vérifie si c'est une instance d'UnorderedCollectable | O(1) | O(1) |
+| `isStatistics(t: unknown): t is Statistics<unknown, number \| bigint>` | Vérifie si c'est une instance de Statistics | O(1) | O(1) |
+| `isNumericStatistics(t: unknown): t is NumericStatistics<unknown>` | Vérifie si c'est une instance de NumericStatistics | O(1) | O(1) |
+| `isBigIntStatistics(t: unknown): t is BigIntStatistics<unknown>` | Vérifie si c'est une instance de BigIntStatistics | O(1) | O(1) |
 
-### 2. `Semantic<E>` — Flux de données paresseux
+```typescript
+// Exemples d'utilisation des gardes de type
+const value: unknown = "hello";
 
-Un **flux séquentiel paresseux et composite**. Similaire aux Java Streams ou aux Kotlin Sequences.
+if (isString(value)) {
+    console.log(value.length); // Sécurité de type, value est inféré comme string
+}
 
-Créez un `Semantic` à l’aide d’assistants comme `from()`, `range()`, `iterate()` ou `fill()`.
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
+}
+```
 
-#### Créateurs :
+## Fonctions Utilitaires
 
-| 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)` |
+| Fonction | Description | Complexité Temporelle | Complexité Spatiale |
+|----------|-------------|----------------------|---------------------|
+| `useCompare<T>(t1: T, t2: T): number` | Fonction de comparaison universelle | O(1) | O(1) |
+| `useRandom<T = number \| bigint>(index: T): T` | Générateur de nombres pseudo-aléatoires | O(log n) | O(1) |
 
-#### Opérateurs courants :
+```typescript
+// Exemples d'utilisation des fonctions utilitaires
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-| 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)` |
+const randomNum = useRandom(42); // Nombre aléatoire basé sur seed
+const randomBigInt = useRandom(1000n); // Nombre BigInt aléatoire
+```
 
----
+## Méthodes d'Usine
 
-### 3. `toUnordered()` — 🚀 Le plus rapide, sans tri
+### Méthodes d'Usine d'Optional
 
-Si vous **n’avez pas besoin d’ordre** et que vous souhaitez les **meilleures performances possibles**, utilisez :
+| Méthode | Description | Complexité Temporelle | Complexité Spatiale |
+|---------|-------------|----------------------|---------------------|
+| `Optional.empty<T>()` | Crée un Optional vide | O(1) | O(1) |
+| `Optional.of<T>(value)` | Crée un Optional avec valeur | O(1) | O(1) |
+| `Optional.ofNullable<T>(value)` | Crée un Optional pouvant être null | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value)` | Crée un Optional non null | O(1) | O(1) |
 
 ```typescript
-const fastest = semanticStream.toUnordered();
+// Exemples d'utilisation d'Optional
+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)); // Affiche 42
+console.log(emptyOpt.orElse(100)); // Affiche 100
 ```
 
-🔥 **Aucun algorithme de tri n’est appliqué.**  
-Parfait lorsque l’ordre n’a pas d’importance et que la vitesse est cruciale.
-
----
+### Méthodes d'Usine de Collector
 
-### 4. `toOrdered()` et `sorted()` — Résultats triés
-
-Si vous avez besoin d’un **résultat trié**, utilisez :
+| Méthode | Description | Complexité Temporelle | Complexité Spatiale |
+|---------|-------------|----------------------|---------------------|
+| `Collector.full(identity, accumulator, finisher)` | Crée un collecteur complet | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Crée un collecteur interruptible | O(1) | O(1) |
 
 ```typescript
-const ordered = semanticStream.sorted(); // Tri naturel
-const customSorted = semanticStream.sorted((a, b) => a - b); // Comparateur personnalisé
-const orderedCollectable = semanticStream.toOrdered(); // Aussi trié
+// Exemples d'utilisation de Collector
+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
 ```
 
-⚠️ Ces méthodes **trient les éléments**, en utilisant l’ordre naturel ou un comparateur fourni.
-
----
+### Méthodes d'usine de Semantic
 
-### 5. `Collector<E, A, R>` — Agrégation de données
+| Méthode | Description | Complexité temporelle | Complexité spatiale |
+|---------|-------------|----------------------|----------------------|
+| `blob(blob, chunkSize)` | Crée un flux depuis un Blob | O(n) | O(chunkSize) |
+| `empty<E>()` | Crée un flux vide | O(1) | O(1) |
+| `fill<E>(element, count)` | Crée un flux rempli | O(n) | O(1) |
+| `from<E>(iterable)` | Crée un flux depuis un objet itérable | O(1) | O(1) |
+| `interval(period, delay?)` | Crée un flux d'intervalle régulier | O(1)* | O(1) |
+| `iterate<E>(generator)` | Crée un flux depuis un générateur | O(1) | O(1) |
+| `range(start, end, step)` | Crée un flux de plage numérique | O(n) | O(1) |
+| `websocket(websocket)` | Crée un flux depuis un WebSocket | O(1) | O(1) |
 
-Les collecteurs vous permettent de **réduire un flux en une structure unique ou complexe**.
+```typescript
+// Exemple d'utilisation des méthodes d'usine de Semantic
+
+// Créer un flux depuis un Blob (lecture par blocs)
+blob(someBlob, 1024n)
+  .toUnordered()
+  .write(WritableStream)
+  .then(callback) // Écriture de flux réussie
+  .catch(writeFi); // Échec de l'écriture de flux
+
+// Créer un flux vide qui ne s'exécutera qu'après concaténation avec d'autres flux
+empty<string>()
+  .toUnordered()
+  .join(); //[]
+
+// Créer un flux rempli
+const filledStream = fill("hello", 3); // "hello", "hello", "hello"
+
+// Créer un flux temporel avec délai initial de 2 secondes et cycle de 5 secondes,
+// implémenté via un mécanisme de temporisation, dérives temporelles possibles
+// dues aux limitations de planification du système.
+const intervalStream = interval(5000, 2000);
+
+// Créer un flux depuis un objet itérable
+const numberStream = from([1, 2, 3, 4, 5]);
+const stringStream = from(new Set(["Alex", "Bob"]));
+
+// Créer un flux de plage
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
+
+// Flux d'événements WebSocket
+const ws = new WebSocket("ws://localhost:8080");
+websocket(ws)
+  .filter((event)=> event.type === "message") // Surveiller uniquement les événements de message
+  .toUnordered() // Pour les événements généralement non triés
+  .forEach((event)=> receive(event)); // Recevoir les messages
+```
 
-Des factories statiques sont disponibles :
+## Méthodes de Classe Semantic
+
+| Méthode | Description | Complexité Temporelle | Complexité Spatiale |
+|---------|-------------|----------------------|---------------------|
+| `concat(other)` | Concatène deux flux | O(n) | O(1) |
+| `distinct()` | Supprime les doublons | O(n) | O(n) |
+| `distinct(comparator)` | Supprime les doublons avec comparateur | O(n²) | O(n) |
+| `dropWhile(predicate)` | Ignore les éléments satisfaisant le prédicat | O(n) | O(1) |
+| `filter(predicate)` | Filtre les éléments | O(n) | O(1) |
+| `flat(mapper)` | Aplatissement de mapping | O(n × m) | O(1) |
+| `flatMap(mapper)` | Aplatissement vers nouveau type | O(n × m) | O(1) |
+| `limit(n)` | Limite le nombre d'éléments | O(n) | O(1) |
+| `map(mapper)` | Transformation par mapping | O(n) | O(1) |
+| `peek(consumer)` | Inspecte les éléments | O(n) | O(1) |
+| `redirect(redirector)` | Redirection d'index | O(n) | O(1) |
+| `reverse()` | Inverse le flux | O(n) | O(1) |
+| `shuffle()` | Mélange aléatoire | O(n) | O(1) |
+| `shuffle(mapper)` | Mélange avec mapper | O(n) | O(1) |
+| `skip(n)` | Saute les n premiers éléments | O(n) | O(1) |
+| `sorted()` | Trie | O(n log n) | O(n) |
+| `sorted(comparator)` | Trie avec comparateur | O(n log n) | O(n) |
+| `sub(start, end)` | Obtient un sous-flux | O(n) | O(1) |
+| `takeWhile(predicate)` | Prend les éléments satisfaisant le prédicat | O(n) | O(1) |
+| `translate(offset)` | Translation d'index | O(n) | O(1) |
+| `translate(translator)` | Translation avec traducteur | O(n) | O(1) |
 
 ```typescript
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// Exemples d'opérations Semantic
+const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)        // Filtre les nombres pairs
+    .map(n => n * 2)                 // Multiplie par 2
+    .skip(1)                         // Saute le premier
+    .limit(3)                        // Limite à 3 éléments
+    .toArray();                      // Convertit en tableau
+// Résultat: [8, 12, 20]
+
+// Exemple d'opération complexe
+const complexResult = range(1, 100, 1)
+    .flatMap(n => from([n, n * 2])) // Map chaque élément vers deux éléments
+    .distinct()                      // Supprime les doublons
+    .shuffle()                       // Mélange aléatoirement
+    .takeWhile(n => n < 50)         // Prend les éléments < 50
+    .toOrdered()                     // Convertit en collecteur ordonné
+    .toArray();                      // Convertit en tableau
 ```
 
-Mais vous utiliserez surtout les méthodes haut niveau fournies par les classes `Collectable`.
+## Méthodes de Transformation de Collecteurs
 
----
+| Méthode | Description | Complexité Temporelle | Complexité Spatiale |
+|---------|-------------|----------------------|---------------------|
+| `toUnoredered()` | Convertit en collecteur non ordonné (priorité performance) | O(1) | O(1) |
+| `toOrdered()` | Convertit en collecteur ordonné | O(1) | O(1) |
+| `sorted()` | Trie et convertit en collecteur ordonné | O(n log n) | O(n) |
+| `toWindow()` | Convertit en collecteur de fenêtre | O(1) | O(1) |
+| `toNumericStatistics()` | Convertit en statistiques numériques | O(1) | O(1) |
+| `toBigintStatistics()` | Convertit en statistiques BigInt | O(1) | O(1) |
 
-### 6. `Collectable<E>` (classe abstraite)
-
-Classe de base pour :
+```typescript
+// Exemples de transformation de collecteurs
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
 
-- `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
+// Priorité performance: Utiliser collecteur non ordonné
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
 
-#### Méthodes communes (via héritage) :
+// Nécessite un tri: Utiliser collecteur ordonné  
+const ordered = numbers.sorted();
 
-| 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)` |
+// Analyse statistique: Utiliser collecteur statistique
+const stats = numbers
+    .toNumericStatistics();
 
----
+console.log(stats.mean());        // Moyenne
+console.log(stats.median());      // Médiane
+console.log(stats.standardDeviation()); // Écart-type
 
-### 7. `OrderedCollectable<E>` — Données triées
+// Opérations de fenêtre
+const windowed = numbers
+    .toWindow()
+    .tumble(3n); // Fenêtre de 3 éléments
 
-Si vous souhaitez que les éléments soient **triés automatiquement**, utilisez cette classe.
+windowed.forEach(window => {
+    console.log(window.toArray()); // Contenu de chaque fenêtre
+});
+```
 
-Elle accepte un **comparateur personnalisé** ou utilise l’ordre naturel.
+## Méthodes de Collecte de Collectable
+
+| Méthode | Description | Complexité Temporelle | Complexité Spatiale |
+|---------|-------------|----------------------|---------------------|
+| `anyMatch(predicate)` | Vérifie s'il existe une correspondance | O(n) | O(1) |
+| `allMatch(predicate)` | Vérifie si tous correspondent | O(n) | O(1) |
+| `count()` | Compte les éléments | O(n) | O(1) |
+| `isEmpty()` | Vérifie si vide | O(1) | O(1) |
+| `findAny()` | Trouve n'importe quel élément | O(n) | O(1) |
+| `findFirst()` | Trouve le premier élément | O(n) | O(1) |
+| `findLast()` | Trouve le dernier élément | O(n) | O(1) |
+| `forEach(action)` | Itère sur tous les éléments | O(n) | O(1) |
+| `group(classifier)` | Groupe par classificateur | O(n) | O(n) |
+| `groupBy(keyExtractor, valueExtractor)` | Groupe par extracteurs clé-valeur | O(n) | O(n) |
+| `join()` | Joint en chaîne | O(n) | O(n) |
+| `join(delimiter)` | Joint avec séparateur | O(n) | O(n) |
+| `nonMatch(predicate)` | Vérifie s'il n'y a pas de correspondance | O(n) | O(1) |
+| `partition(count)` | Partitionne par quantité | O(n) | O(n) |
+| `partitionBy(classifier)` | Partitionne par classificateur | O(n) | O(n) |
+| `reduce(accumulator)` | Opération de réduction | O(n) | O(1) |
+| `reduce(identity, accumulator)` | Réduction avec valeur initiale | O(n) | O(1) |
+| `toArray()` | Convertit en tableau | O(n) | O(n) |
+| `toMap(keyExtractor, valueExtractor)` | Convertit en Map | O(n) | O(n) |
+| `toSet()` | Convertit en Set | O(n) | O(n) |
+| `write(stream)` | Écrit dans le flux | O(n) | O(1) |
 
 ```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// Exemples d'opérations Collectable
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)
+    .toOrdered();
+
+// Vérifications de correspondance
+console.log(data.anyMatch(n => n > 5)); // true
+console.log(data.allMatch(n => n < 20)); // true
+
+// Opérations de recherche
+data.findFirst().ifPresent(n => console.log(n)); // 2
+data.findAny().ifPresent(n => console.log(n)); // Élément quelconque
+
+// Opérations de groupement
+const grouped = data.groupBy(
+    n => n > 5 ? "large" : "small",
+    n => n * 2
+);
+// {small: [4, 8], large: [12, 16, 20]}
+
+// Opérations de réduction
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
+
+// Opérations de sortie
+data.join(", "); // "2, 4, 6, 8, 10"
 ```
 
-🔒 **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 :
+## Méthodes d'Analyse Statistique
+
+### Méthodes de NumericStatistics
+
+| Méthode | Description | Complexité Temporelle | Complexité Spatiale |
+|---------|-------------|----------------------|---------------------|
+| `range()` | Plage | O(n) | O(1) |
+| `variance()` | Variance | O(n) | O(1) |
+| `standardDeviation()` | Écart-type | O(n) | O(1) |
+| `mean()` | Moyenne | O(n) | O(1) |
+| `median()` | Médiane | O(n log n) | O(n) |
+| `mode()` | Mode | O(n) | O(n) |
+| `frequency()` | Distribution de fréquence | O(n) | O(n) |
+| `summate()` | Sommation | O(n) | O(1) |
+| `quantile(quantile)` | Quantile | O(n log n) | O(n) |
+| `interquartileRange()` | Intervalle interquartile | O(n log n) | O(n) |
+| `skewness()` | Asymétrie | O(n) | O(1) |
+| `kurtosis()` | Aplatissement | O(n) | O(1) |
 
 ```typescript
-const unordered = new UnorderedCollectable(stream);
-// OU
-const fastest = semanticStream.toUnordered();
+// Exemples d'analyse statistique
+const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .toNumericStatistics();
+
+console.log("Moyenne:", numbers.mean()); // 5.5
+console.log("Médiane:", numbers.median()); // 5.5
+console.log("Écart-type:", numbers.standardDeviation()); // ~2.87
+console.log("Somme:", numbers.summate()); // 55
+
+// Analyse statistique avec mapper
+const objects = from([
+    { value: 10 },
+    { value: 20 }, 
+    { value: 30 }
+]).toNumericStatistics();
+
+console.log("Moyenne mappée:", objects.mean(obj => obj.value)); // 20
 ```
 
-✅ **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
+## Guide de Sélection des Performances
 
+### Sélectionner Collecteur Non Ordonné (Priorité Performance)
 ```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());
+// Quand aucune garantie d'ordre n'est nécessaire
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // Meilleure performance
 ```
 
----
-
-## 🛠️ 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 :
-
+### Sélectionner Collecteur Ordonné (Nécessite un Ordre)
 ```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);
+// Quand l'ordre des éléments doit être préservé
+const ordered = data
+    .sorted(comparator) // Le tri écrase les effets de redirection
+    .toOrdered(); // Maintient l'ordre
 ```
 
-Ou utiliser des **fenêtres glissantes** :
-
+### Sélectionner Collecteur de Fenêtre (Opérations de Fenêtre)
 ```typescript
-const windowed = ordered.slide(3n, 2n); // fenêtres de taille 3, pas de 2
+// Quand des opérations de fenêtre sont nécessaires
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // Fenêtre glissante
 ```
 
----
-
-## 📄 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
+### Sélectionner Analyse Statistique (Calculs Numériques)
+```typescript
+// Quand une analyse statistique est nécessaire
+const stats = data
+    .toNumericStatistics(); // Statistiques numériques
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 Documentation : voir le code source / définitions de type
+const bigIntStats = data
+    .toBigintStatistics(); // Statistiques BigInt
+```
 
----
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-**Profitez d’un traitement de données fonctionnel, typé et composable en TypeScript.** 🚀
+## Considérations Importantes
 
---- 
+1. **Impact des opérations de tri**: Dans les collecteurs ordonnés, `sorted()` écrase les effets de `redirect`, `translate`, `shuffle`, `reverse`
+2. **Considérations de performance**: Si aucune garantie d'ordre n'est nécessaire, prioriser `toUnoredered()` pour de meilleures performances
+3. **Utilisation de la mémoire**: Les opérations de tri nécessitent un espace supplémentaire O(n)
+4. **Données en temps réel**: Les flux Semantic sont idéaux pour les données en temps réel et prennent en charge les sources de données asynchrones
 
-✅ **À retenir :**  
-- `toUnordered()` → **Pas de tri, le plus rapide**  
-- Les autres (`sorted()`, `toOrdered()`, etc.) → **Tri des données**
+Cette bibliothèque offre aux développeurs TypeScript des capacités puissantes et flexibles de traitement de flux, combinant les avantages de la programmation fonctionnelle avec la sécurité de type.