semantic-typescript 0.0.8 → 0.1.4

package/readme.fr.md

@@ -1,529 +1,428 @@
-# Cadre de Traitement de Flux Semantic-TypeScript
+# Bibliothèque de Traitement de Flux Semantic-TypeScript
 
 ## Introduction
 
-Semantic-TypeScript est une bibliothèque moderne de traitement de flux inspirée par GeneratorFunction de JavaScript, Java Stream et MySQL Index. La philosophie de conception centrale repose sur la construction de pipelines efficaces de traitement de données grâce à l'indexation des données, offrant une expérience d'opération de flux de type fonctionnel et sécurisée par les types pour le développement frontend.
+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 utilise un modèle de traitement asynchrone. Lors de la création de flux de données, le moment de la réception des données terminales dépend entièrement du moment où l'amont appelle les fonctions de rappel `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.
+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 Principales
+## Installation
 
-| Caractéristique | Description | Avantage |
-|------|------|------|
-| **Génériques Type-Safe** | Support complet des types TypeScript | Détection d'erreurs à la compilation, meilleure expérience de développement |
-| **Programmation Fonctionnelle** | Structures de données immuables et fonctions pures | Code plus prévisible, tests et maintenance plus faciles |
-| **Évaluation Paresseuse** | Calcul à la demande, optimisation des performances | Haute efficacité mémoire lors du traitement de grands ensembles de données |
-| **Traitement de Flux Asynchrone** | Flux de données asynchrones basés sur les générateurs | Adapté aux données en temps réel et scénarios pilotés par événements |
-| **Collecteurs Multi-Paradigmes** | Stratégies de collecte ordonnées, non ordonnées, statistiques | Sélection de stratégie optimale basée sur différents scénarios |
-| **Analyse Statistique** | Fonctions de calcul statistique complètes intégrées | Génération intégrée d'analyse de données et de rapports |
-
-## Considérations de Performance
-
-**Note Importante**: Les méthodes suivantes sacrifient les performances pour collecter et trier les données, entraînant des collections de données ordonnées:
-- `toOrdered()`
-- `toWindow()`
-- `toNumericStatistics()`
-- `toBigIntStatistics()`
-- `sorted()`
-- `sorted(comparator)`
-
-Particulièrement important à noter: `sorted()` et `sorted(comparator)` écraseront les résultats des méthodes suivantes:
-- `redirect(redirector)`
-- `translate(translator)` 
-- `shuffle(mapper)`
-
-## Méthodes d'Usine
-
-### Usines de Création de Flux
+```bash
+npm install semantic-typescript
+```
 
-| Méthode | Signature | Description | Exemple |
-|------|------|------|------|
-| `blob` | `(blob: Blob, chunk?: bigint) => Semantic<Uint8Array>` | Convertir Blob en flux d'octets | `blob(fileBlob, 1024n)` |
-| `empty` | `<E>() => Semantic<E>` | Créer un flux vide | `empty<number>()` |
-| `fill` | `<E>(element: E, count: bigint) => Semantic<E>` | Remplir avec un nombre spécifié d'éléments | `fill("hello", 5n)` |
-| `from` | `<E>(iterable: Iterable<E>) => Semantic<E>` | Créer un flux à partir d'un objet itérable | `from([1, 2, 3])` |
-| `range` | `<N extends number\|bigint>(start: N, end: N, step?: N) => Semantic<N>` | Créer un flux de plage numérique | `range(1, 10, 2)` |
-| `iterate` | `<E>(generator: Generator<E>) => Semantic<E>` | Créer un flux à partir d'une fonction génératrice | `iterate(myGenerator)` |
-| `websocket` | `(websocket: WebSocket) => Semantic<MessageEvent>` | Créer un flux d'événements à partir de WebSocket | `websocket(socket)` |
+## 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 |
 
-**Supplément d'Exemple de Code:**
 ```typescript
-import { from, range, fill, empty } from 'semantic-typescript';
-
-// Créer un flux à partir d'un tableau
-const numberStream = from([1, 2, 3, 4, 5]);
-
-// Créer un flux de plage numérique
-const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
-
-// Remplir avec des éléments répétés
-const filledStream = fill("hello", 3n); // "hello", "hello", "hello"
-
-// Créer un flux vide
-const emptyStream = empty<number>();
+// 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;
 ```
 
-### Usines de Fonctions Utilitaires
+## 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) |
 
-| Méthode | Signature | Description | Exemple |
-|------|------|------|------|
-| `validate` | `<T>(t: MaybeInvalid<T>) => t is T` | Valider si la valeur est valide | `validate(null)` → `false` |
-| `invalidate` | `<T>(t: MaybeInvalid<T>) => t is null\|undefined` | Valider si la valeur est invalide | `invalidate(0)` → `false` |
-| `useCompare` | `<T>(t1: T, t2: T) => number` | Fonction de comparaison générique | `useCompare("a", "b")` → `-1` |
-| `useRandom` | `<T = number\|bigint>(index: T) => T` | Générateur de nombres pseudo-aléatoires | `useRandom(5)` → nombre aléatoire |
-
-**Supplément d'Exemple de Code:**
 ```typescript
-import { validate, invalidate, useCompare, useRandom } from 'semantic-typescript';
+// Exemples d'utilisation des gardes de type
+const value: unknown = "hello";
 
-// Valider la validité des données
-const data: string | null = "hello";
-if (validate(data)) {
-    console.log(data.toUpperCase()); // Appel sécurisé car validate garantit que data n'est pas null
+if (isString(value)) {
+    console.log(value.length); // Sécurité de type, value est inféré comme string
 }
 
-const nullData: string | null = null;
-if (invalidate(nullData)) {
-    console.log("Données invalides"); // S'exécutera car invalidate a détecté null
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
 }
-
-// Comparer des valeurs
-const comparison = useCompare("apple", "banana"); // -1
-
-// Générer un nombre aléatoire
-const randomNum = useRandom(42); // Nombre aléatoire basé sur la graine 42
 ```
 
-## Détails de la Classe Principale
-
-### Optional<T> - Gestion Sécurisée des Valeurs Nulles
+## Fonctions Utilitaires
 
-La classe Optional fournit une approche fonctionnelle pour gérer en toute sécurité les valeurs pouvant être nulles ou non définies.
+| 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) |
 
-| Méthode | Type de Retour | Description | Complexité Temporelle |
-|------|----------|------|------------|
-| `filter(predicate: Predicate<T>)` | `Optional<T>` | Filtrer les valeurs satisfaisant la condition | O(1) |
-| `get()` | `T` | Obtenir la valeur, lance une erreur si vide | O(1) |
-| `getOrDefault(defaultValue: T)` | `T` | Obtenir la valeur ou la valeur par défaut | O(1) |
-| `ifPresent(action: Consumer<T>)` | `void` | Exécuter l'action si la valeur existe | O(1) |
-| `isEmpty()` | `boolean` | Vérifier si vide | O(1) |
-| `isPresent()` | `boolean` | Vérifier si la valeur existe | O(1) |
-| `map<R>(mapper: Functional<T, R>)` | `Optional<R>` | Mapper et transformer la valeur | O(1) |
-| `static of<T>(value: MaybeInvalid<T>)` | `Optional<T>` | Créer une instance Optional | O(1) |
-| `static ofNullable<T>(value?)` | `Optional<T>` | Créer une Optional nullable | O(1) |
-| `static ofNonNull<T>(value: T)` | `Optional<T>` | Créer une Optional non nulle | O(1) |
-
-**Supplément d'Exemple de Code:**
 ```typescript
-import { Optional } from 'semantic-typescript';
+// Exemples d'utilisation des fonctions utilitaires
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-// Créer une instance Optional
-const optionalValue = Optional.ofNullable<string>(Math.random() > 0.5 ? "hello" : null);
+const randomNum = useRandom(42); // Nombre aléatoire basé sur seed
+const randomBigInt = useRandom(1000n); // Nombre BigInt aléatoire
+```
 
-// Opérations en chaîne
-const result = optionalValue
-    .filter(val => val.length > 3) // Filtrer les valeurs plus longues que 3
-    .map(val => val.toUpperCase()) // Convertir en majuscules
-    .getOrDefault("default"); // Obtenir la valeur ou la valeur par défaut
+## Méthodes d'Usine
 
-console.log(result); // "HELLO" ou "default"
+### Méthodes d'Usine d'Optional
 
-// Opérations sécurisées
-optionalValue.ifPresent(val => {
-    console.log(`La valeur existe: ${val}`);
-});
+| 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) |
 
-// Vérifier le statut
-if (optionalValue.isPresent()) {
-    console.log("A une valeur");
-} else if (optionalValue.isEmpty()) {
-    console.log("Est vide");
-}
+```typescript
+// 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
 ```
 
-### Semantic<E> - Flux de Données Paresseux
-
-Semantic est la classe principale de traitement de flux, offrant de riches opérateurs de flux.
-
-#### Opérations de Transformation de Flux
-
-| Méthode | Type de Retour | Description | Impact sur les Performances |
-|------|----------|------|----------|
-| `concat(other: Semantic<E>)` | `Semantic<E>` | Concaténer deux flux | O(n+m) |
-| `distinct()` | `Semantic<E>` | Supprimer les doublons (en utilisant Set) | O(n) |
-| `distinct(comparator)` | `Semantic<E>` | Déduplication avec comparateur personnalisé | O(n²) |
-| `dropWhile(predicate)` | `Semantic<E>` | Supprimer les éléments de début satisfaisant la condition | O(n) |
-| `filter(predicate)` | `Semantic<E>` | Filtrer les éléments | O(n) |
-| `flat(mapper)` | `Semantic<E>` | Aplatir les flux imbriqués | O(n×m) |
-| `flatMap(mapper)` | `Semantic<R>` | Mapper et aplatir | O(n×m) |
-| `limit(n)` | `Semantic<E>` | Limiter le nombre d'éléments | O(n) |
-| `map(mapper)` | `Semantic<R>` | Mapper et transformer les éléments | O(n) |
-| `peek(consumer)` | `Semantic<E>` | Voir les éléments sans modification | O(n) |
-| `redirect(redirector)` | `Semantic<E>` | Rediriger les indices | O(n) |
-| `reverse()` | `Semantic<E>` | Inverser l'ordre du flux | O(n) |
-| `shuffle()` | `Semantic<E>` | Mélanger aléatoirement l'ordre | O(n) |
-| `shuffle(mapper)` | `Semantic<E>` | Logique de mélange personnalisée | O(n) |
-| `skip(n)` | `Semantic<E>` | Sauter les n premiers éléments | O(n) |
-| `sub(start, end)` | `Semantic<E>` | Obtenir un sous-flux | O(n) |
-| `takeWhile(predicate)` | `Semantic<E>` | Obtenir les éléments de début satisfaisant la condition | O(n) |
-| `translate(offset)` | `Semantic<E>` | Traduire les indices | O(n) |
-| `translate(translator)` | `Semantic<E>` | Transformation d'indice personnalisée | O(n) |
-
-**Supplément d'Exemple de Code:**
-```typescript
-import { from } from 'semantic-typescript';
+### Méthodes d'Usine de Collector
 
-const stream = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+| 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) |
 
-// Exemples d'opérations de transformation de flux
-const processedStream = stream
-    .filter(x => x % 2 === 0) // Filtrer les nombres pairs
-    .map(x => x * 2) // Multiplier chaque élément par 2
-    .distinct() // Supprimer les doublons
-    .limit(3) // Limiter aux 3 premiers éléments
-    .peek((val, index) => console.log(`Élément ${val} à l'indice ${index}`)); // Voir les éléments
+```typescript
+// Exemples d'utilisation de Collector
+const sumCollector = Collector.full(
+    () => 0,
+    (sum, num) => sum + num,
+    result => result
+);
 
-// Note: Le flux ne s'est pas encore exécuté, doit être converti en Collectable pour les opérations terminales
+const numbers = from([1, 2, 3, 4, 5]);
+const total = numbers.toUnoredered().collect(sumCollector); // 15
 ```
 
-#### Opérations Terminales de Flux
+### Méthodes d'usine de Semantic
 
-| Méthode | Type de Retour | Description | Caractéristiques de Performance |
-|------|----------|------|----------|
-| `toOrdered()` | `OrderedCollectable<E>` | Convertir en collection ordonnée | Opération de tri, performance inférieure |
-| `toUnordered()` | `UnorderedCollectable<E>` | Convertir en collection non ordonnée | Plus rapide, pas de tri |
-| `toWindow()` | `WindowCollectable<E>` | Convertir en collection de fenêtre | Opération de tri, performance inférieure |
-| `toNumericStatistics()` | `Statistics<E, number>` | Analyse statistique numérique | Opération de tri, performance inférieure |
-| `toBigintStatistics()` | `Statistics<E, bigint>` | Analyse statistique en grand entier | Opération de tri, performance inférieure |
-| `sorted()` | `OrderedCollectable<E>` | Tri naturel | Écrase les résultats de redirection |
-| `sorted(comparator)` | `OrderedCollectable<E>` | Tri personnalisé | Écrase les résultats de redirection |
+| 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) |
 
-**Supplément d'Exemple de Code:**
 ```typescript
-import { from } from 'semantic-typescript';
+// Exemple d'utilisation des méthodes d'usine de Semantic
 
-const semanticStream = from([5, 2, 8, 1, 9, 3, 7, 4, 6]);
+// 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
 
-// Convertir en collection ordonnée (performance inférieure)
-const ordered = semanticStream.toOrdered();
+// Créer un flux vide qui ne s'exécutera qu'après concaténation avec d'autres flux
+empty<string>()
+  .toUnordered()
+  .join(); //[]
 
-// Convertir en collection non ordonnée (plus rapide)
-const unordered = semanticStream.toUnordered();
+// Créer un flux rempli
+const filledStream = fill("hello", 3); // "hello", "hello", "hello"
 
-// Tri naturel
-const sortedNatural = semanticStream.sorted();
+// 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);
 
-// Tri personnalisé
-const sortedCustom = semanticStream.sorted((a, b) => b - a); // Tri décroissant
+// Créer un flux depuis un objet itérable
+const numberStream = from([1, 2, 3, 4, 5]);
+const stringStream = from(new Set(["Alex", "Bob"]));
 
-// Convertir en objet statistique
-const stats = semanticStream.toNumericStatistics();
+// Créer un flux de plage
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
 
-// Note: Doit appeler les méthodes ci-dessus via une instance Semantic pour obtenir Collectable avant d'utiliser les méthodes terminales
+// 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
 ```
 
-### Collector<E, A, R> - Collecteur de Données
+## 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) |
 
-Les collecteurs sont utilisés pour agréger les données de flux dans des structures spécifiques.
-
-| Méthode | Description | Scénario d'Utilisation |
-|------|------|----------|
-| `collect(generator)` | Exécuter la collecte de données | Opération terminale de flux |
-| `static full(identity, accumulator, finisher)` | Créer un collecteur complet | Nécessite un traitement complet |
-| `static shortable(identity, interruptor, accumulator, finisher)` | Créer un collecteur interruptible | Peut se terminer prématurément |
-
-**Supplément d'Exemple de Code:**
 ```typescript
-import { Collector } from 'semantic-typescript';
-
-// Créer un collecteur personnalisé
-const sumCollector = Collector.full(
-    () => 0, // Valeur initiale
-    (acc, value) => acc + value, // Accumulateur
-    result => result // Fonction de finition
-);
-
-// Utiliser le collecteur (nécessite une conversion de Semantic en Collectable d'abord)
-const numbers = from([1, 2, 3, 4, 5]);
-const sum = numbers.toUnordered().collect(sumCollector); // 15
+// 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
 ```
 
-### Collectable<E> - Classe Abstraite de Données Collectables
-
-Fournit des méthodes riches d'agrégation et de transformation de données. **Note: Doit d'abord obtenir une instance Collectable en appelant sorted(), toOrdered() etc. via une instance Semantic avant d'utiliser les méthodes suivantes.**
-
-#### Opérations de Requête de Données
+## Méthodes de Transformation de Collecteurs
 
-| Méthode | Type de Retour | Description | Exemple |
-|------|----------|------|------|
-| `anyMatch(predicate)` | `boolean` | Si un élément correspond | `anyMatch(x => x > 0)` |
-| `allMatch(predicate)` | `boolean` | Si tous les éléments correspondent | `allMatch(x => x > 0)` |
-| `count()` | `bigint` | Statistiques de nombre d'éléments | `count()` → `5n` |
-| `isEmpty()` | `boolean` | Si le flux est vide | `isEmpty()` |
-| `findAny()` | `Optional<E>` | Trouver n'importe quel élément | `findAny()` |
-| `findFirst()` | `Optional<E>` | Trouver le premier élément | `findFirst()` |
-| `findLast()` | `Optional<E>` | Trouver le dernier élément | `findLast()` |
+| 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) |
 
-**Supplément d'Exemple de Code:**
 ```typescript
-import { from } from 'semantic-typescript';
+// Exemples de transformation de collecteurs
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
 
-const numbers = from([1, 2, 3, 4, 5]);
+// Priorité performance: Utiliser collecteur non ordonné
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
 
-// Doit convertir en Collectable avant d'utiliser les méthodes terminales
-const collectable = numbers.toUnordered();
+// Nécessite un tri: Utiliser collecteur ordonné  
+const ordered = numbers.sorted();
 
-// Opérations de requête de données
-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(); // N'importe quel élément
-```
+// Analyse statistique: Utiliser collecteur statistique
+const stats = numbers
+    .toNumericStatistics();
 
-#### Opérations d'Aggrégation de Données
-
-| Méthode | Type de Retour | Description | Complexité |
-|------|----------|------|--------|
-| `group(classifier)` | `Map<K, E[]>` | Grouper par classifieur | O(n) |
-| `groupBy(keyExtractor, valueExtractor)` | `Map<K, V[]>` | Grouper par extracteurs clé-valeur | O(n) |
-| `join()` | `string` | Joindre en chaîne | O(n) |
-| `join(delimiter)` | `string` | Joindre avec délimiteur | O(n) |
-| `partition(count)` | `E[][]` | Partitionner par compte | O(n) |
-| `partitionBy(classifier)` | `E[][]` | Partitionner par classifieur | O(n) |
-| `reduce(accumulator)` | `Optional<E>` | Opération de réduction | O(n) |
-| `reduce(identity, accumulator)` | `E` | Réduction avec identité | O(n) |
-| `toArray()` | `E[]` | Convertir en tableau | O(n) |
-| `toMap(keyExtractor, valueExtractor)` | `Map<K, V>` | Convertir en Map | O(n) |
-| `toSet()` | `Set<E>` | Convertir en Set | O(n) |
-
-**Supplément d'Exemple de Code:**
-```typescript
-import { from } from 'semantic-typescript';
+console.log(stats.mean());        // Moyenne
+console.log(stats.median());      // Médiane
+console.log(stats.standardDeviation()); // Écart-type
 
-const people = from([
-    { name: "Alice", age: 25, city: "New York" },
-    { name: "Bob", age: 30, city: "London" },
-    { name: "Charlie", age: 25, city: "New York" }
-]);
+// Opérations de fenêtre
+const windowed = numbers
+    .toWindow()
+    .tumble(3n); // Fenêtre de 3 éléments
 
-// Doit convertir en Collectable avant d'utiliser les opérations d'agrégation
-const collectable = people.toUnordered();
+windowed.forEach(window => {
+    console.log(window.toArray()); // Contenu de chaque fenêtre
+});
+```
 
-// Opérations de regroupement
-const byCity = collectable.group(person => person.city);
-// Map { "New York" => [{name: "Alice", ...}, {name: "Charlie", ...}], "London" => [{name: "Bob", ...}] }
+## 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) |
 
-const byAge = collectable.groupBy(
-    person => person.age,
-    person => person.name
+```typescript
+// 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
 );
-// Map { 25 => ["Alice", "Charlie"], 30 => ["Bob"] }
-
-// Convertir en collections
-const array = collectable.toArray(); // Tableau original
-const set = collectable.toSet(); // Collection Set
-const map = collectable.toMap(
-    person => person.name,
-    person => person.age
-); // Map { "Alice" => 25, "Bob" => 30, "Charlie" => 25 }
+// {small: [4, 8], large: [12, 16, 20]}
 
 // Opérations de réduction
-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, ...})
-```
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
 
-### Implémentations Spécifiques de Collecteurs
-
-#### UnorderedCollectable<E>
-- **Caractéristiques**: Collecteur le plus rapide, pas de tri
-- **Scénarios d'Utilisation**: Ordre non important, performance maximale souhaitée
-- **Méthodes**: Hérite de toutes les méthodes Collectable
-
-#### OrderedCollectable<E> 
-- **Caractéristiques**: Garantit l'ordre des éléments, performance inférieure
-- **Scénarios d'Utilisation**: Requiert des résultats triés
-- **Méthodes Spéciales**: Hérite de toutes les méthodes, maintient l'état de tri interne
+// Opérations de sortie
+data.join(", "); // "2, 4, 6, 8, 10"
+```
 
-#### WindowCollectable<E>
-- **Caractéristiques**: Prend en charge les opérations de fenêtre glissante
-- **Scénarios d'Utilisation**: Analyse de données de séries temporelles
-- **Méthodes Spéciales**:
-  - `slide(size, step)` - Fenêtre glissante
-  - `tumble(size)` - Fenêtre tumble
+## 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) |
 
-**Supplément d'Exemple de Code:**
 ```typescript
-import { from } from 'semantic-typescript';
-
-const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-// Collecteur non ordonné (plus rapide)
-const unordered = data.toUnordered();
-const unorderedArray = unordered.toArray(); // Peut maintenir l'ordre original [1, 2, 3, ...]
-
-// Collecteur ordonné
-const ordered = data.toOrdered();
-const orderedArray = ordered.toArray(); // Tri garanti [1, 2, 3, ...]
+// 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
+```
 
-// Collecteur de fenêtre
-const windowed = data.toWindow();
-const slidingWindows = windowed.slide(3n, 2n); // Taille de fenêtre 3, pas 2
-// Fenêtre 1: [1, 2, 3], Fenêtre 2: [3, 4, 5], Fenêtre 3: [5, 6, 7], ...
+## Guide de Sélection des Performances
 
-const tumblingWindows = windowed.tumble(4n); // Taille de fenêtre tumble 4
-// Fenêtre 1: [1, 2, 3, 4], Fenêtre 2: [5, 6, 7, 8], ...
+### Sélectionner Collecteur Non Ordonné (Priorité Performance)
+```typescript
+// Quand aucune garantie d'ordre n'est nécessaire
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // Meilleure performance
 ```
 
-### Statistics<E, D> - Analyse Statistique
-
-Classe de base d'analyse statistique fournissant de riches méthodes de calcul statistique. **Note: Doit d'abord obtenir une instance Statistics en appelant toNumericStatistics() ou toBigIntStatistics() via une instance Semantic avant d'utiliser les méthodes suivantes.**
-
-#### Opérations de Calcul Statistique
-
-| Méthode | Type de Retour | Description | Complexité de l'Algorithme |
-|------|----------|------|------------|
-| `maximum()` | `Optional<E>` | Valeur maximale | O(n) |
-| `minimum()` | `Optional<E>` | Valeur minimale | O(n) |
-| `range()` | `D` | Plage (max-min) | O(n) |
-| `variance()` | `D` | Variance | O(n) |
-| `standardDeviation()` | `D` | Écart type | O(n) |
-| `mean()` | `D` | Valeur moyenne | O(n) |
-| `median()` | `D` | Valeur médiane | O(n log n) |
-| `mode()` | `D` | Valeur modale | O(n) |
-| `frequency()` | `Map<D, bigint>` | Distribution de fréquence | O(n) |
-| `summate()` | `D` | Sommation | O(n) |
-| `quantile(quantile)` | `D` | Quantile | O(n log n) |
-| `interquartileRange()` | `D` | Intervalle interquartile | O(n log n) |
-| `skewness()` | `D` | Asymétrie | O(n) |
-| `kurtosis()` | `D` | Aplatissement | O(n) |
-
-**Supplément d'Exemple de Code:**
+### Sélectionner Collecteur Ordonné (Nécessite un Ordre)
 ```typescript
-import { from } from 'semantic-typescript';
-
-const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-// Doit convertir en objet statistique avant d'utiliser les méthodes statistiques
-const stats = numbers.toNumericStatistics();
-
-// Statistiques de base
-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
-
-// Statistiques avancées
-const variance = stats.variance(); // 8.25
-const stdDev = stats.standardDeviation(); // 2.872
-const mode = stats.mode(); // N'importe quelle valeur (puisque toutes apparaissent une fois)
-const q1 = stats.quantile(0.25); // 3.25
-const q3 = stats.quantile(0.75); // 7.75
-const iqr = stats.interquartileRange(); // 4.5
-
-// Distribution de fréquence
-const freq = stats.frequency(); // Map {1 => 1n, 2 => 1n, ...}
+// 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
 ```
 
-#### Classes d'Implémentation Statistique Spécifiques
-
-**NumericStatistics<E>**
-- Gère l'analyse statistique de type nombre
-- Tous les calculs statistiques retournent le type nombre
-
-**BigIntStatistics<E>**  
-- Gère l'analyse statistique de type bigint
-- Tous les calculs statistiques retournent le type bigint
-
-**Supplément d'Exemple de Code:**
+### Sélectionner Collecteur de Fenêtre (Opérations de Fenêtre)
 ```typescript
-import { from } from 'semantic-typescript';
-
-// Statistiques numériques
-const numberData = from([10, 20, 30, 40, 50]);
-const numericStats = numberData.toNumericStatistics();
-
-console.log(numericStats.mean()); // 30
-console.log(numericStats.summate()); // 150
-
-// Statistiques en grand entier
-const bigintData = from([100n, 200n, 300n, 400n, 500n]);
-const bigintStats = bigintData.toBigIntStatistics();
-
-console.log(bigintStats.mean()); // 300n
-console.log(bigintStats.summate()); // 1500n
+// Quand des opérations de fenêtre sont nécessaires
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // Fenêtre glissante
+```
 
-// Statistiques utilisant des fonctions de mappage
-const objectData = from([
-    { value: 15 },
-    { value: 25 }, 
-    { value: 35 },
-    { value: 45 }
-]);
+### Sélectionner Analyse Statistique (Calculs Numériques)
+```typescript
+// Quand une analyse statistique est nécessaire
+const stats = data
+    .toNumericStatistics(); // Statistiques numériques
 
-const objectStats = objectData.toNumericStatistics();
-const meanWithMapper = objectStats.mean(obj => obj.value); // 30
-const sumWithMapper = objectStats.summate(obj => obj.value); // 120
+const bigIntStats = data
+    .toBigintStatistics(); // Statistiques BigInt
 ```
 
-## Exemple Complet d'Utilisation
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-```typescript
-import { from, validate, invalidate } from 'semantic-typescript';
-
-// 1. Créer un flux de données
-const rawData = [5, 2, 8, 1, null, 9, 3, undefined, 7, 4, 6];
-const semanticStream = from(rawData);
-
-// 2. Pipeline de traitement de flux
-const processedStream = semanticStream
-    .filter(val => validate(val)) // Filtrer les null et undefined
-    .map(val => val! * 2) // Multiplier chaque valeur par 2 (en utilisant ! car validate garantit non vide)
-    .distinct(); // Supprimer les doublons
-
-// 3. Convertir en Collectable et utiliser les opérations terminales
-const collectable = processedStream.toUnordered();
-
-// 4. Validation et utilisation des données
-if (!collectable.isEmpty()) {
-    const results = collectable
-        .filter(x => x > 5) // Filtrer à nouveau
-        .toArray(); // Convertir en tableau
-    
-    console.log("Résultats du traitement:", results); // [16, 18, 14, 8, 12]
-    
-    // Informations statistiques
-    const stats = processedStream.toNumericStatistics();
-    console.log("Valeur moyenne:", stats.mean()); // 11.2
-    console.log("Somme totale:", stats.summate()); // 56
-}
+## Considérations Importantes
 
-// 5. Gérer les données potentiellement invalides
-const potentiallyInvalidData: Array<number | null> = [1, null, 3, 4, null];
-const validData = potentiallyInvalidData.filter(validate);
-const invalidData = potentiallyInvalidData.filter(invalidate);
-
-console.log("Données valides:", validData); // [1, 3, 4]
-console.log("Données invalides:", invalidData); // [null, null]
-```
+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
 
-## Règles d'Utilisation Importantes Résumées
-
-1. **Créer un Flux**: Utiliser les méthodes d'usine `from()`, `range()`, `fill()` etc. pour créer des instances Semantic
-2. **Transformation de Flux**: Appeler les méthodes `map()`, `filter()`, `distinct()` etc. sur les instances Semantic
-3. **Convertir en Collectable**: Doit appeler l'une des méthodes suivantes via une instance Semantic:
-   - `toOrdered()` - Collecteur ordonné
-   - `toUnordered()` - Collecteur non ordonné (plus rapide)
-   - `toWindow()` - Collecteur de fenêtre  
-   - `toNumericStatistics()` - Statistiques numériques
-   - `toBigIntStatistics()` - Statistiques en grand entier
-   - `sorted()` - Tri naturel
-   - `sorted(comparator)` - Tri personnalisé
-4. **Opérations Terminales**: Appeler les méthodes terminales `toArray()`, `count()`, `summate()` etc. sur les instances Collectable
-5. **Validation des Données**: Utiliser `validate()` pour garantir que les données ne sont pas nulles/non définies, utiliser `invalidate()` pour vérifier les données invalides
-
-Cette conception garantit la sécurité des types et l'optimisation des performances tout en fournissant une fonctionnalité riche de traitement de flux.
+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.