semantic-typescript 0.6.0 → 0.7.1

package/readme.fr.md

@@ -1,204 +1,267 @@
-# Semantic-TypeScript : Une bibliothèque de traitement de flux qui change de paradigme
+# **Semantic‑TypeScript**
+**Flux, indexés.** Vos données, sous contrôle précis.
 
-## Introduction
-Semantic-TypeScript représente une avancée significative dans la technologie de traitement de flux, synthétisant les concepts les plus efficaces des JavaScript GeneratorFunctions, des Java Streams et des paradigmes d'indexation de bases de données. Son principe de conception fondamental est centré sur la construction de pipelines de traitement de données exceptionnellement efficaces grâce à une évaluation paresseuse sophistiquée et une indexation intelligente. La bibliothèque offre une expérience d'opération de streaming rigoureusement type-safe et fonctionnellement pure, spécialement conçue pour le développement TypeScript et JavaScript contemporain.
+---
 
-Contrairement aux architectures de traitement synchrone conventionnelles, Semantic-TypeScript implémente un modèle unifié qui gère avec grâce à la fois les sources de données synchrones (Iterable) et asynchrones (AsyncIterable). Pendant la génération du flux, le flux et la terminaison des données sont précisément contrôlés par des mécanismes de rappel (callback), permettant à la bibliothèque de gérer avec une grâce exceptionnelle :
-- Les flux de données en temps réel (événements DOM, WebSockets, intervalles) avec un contrôle déterministe
-- Les jeux de données à grande échelle grâce à des pipelines paresseux et économes en mémoire
-- Les transformations de données complexes avec une API fluide et déclarative
+### Vue d'ensemble
 
-L'approche innovante de la bibliothèque réinvente fondamentalement la façon dont les développeurs interagissent avec les séquences de données, offrant à la fois des caractéristiques de performance sans précédent et une ergonomie pour le développeur dans un ensemble unique et cohérent.
+Semantic‑TypeScript représente une avancée significative dans le traitement des flux, **synthétisant** avec élégance les paradigmes les plus efficaces des générateurs JavaScript, des Streams Java et de l'indexation de style MySQL. Son postulat fondamental est à la fois puissant et délibéré : construire des pipelines de traitement de données exceptionnellement efficaces grâce à une indexation intelligente, plutôt que par une itération conventionnelle en force brute.
 
-## Philosophie de base : Séparation de la Définition et de l'Exécution
-Une idée architecturale clé de Semantic-TypeScript est la séparation claire entre la définition d'un flux et son exécution :
-- **`Semantic<E>`** : Un modèle immuable et paresseux d'un pipeline de transformation de données. Il définit quelles opérations (filter, map, etc.) seront effectuées.
-- **`Collectable<E>`** : Une vue exécutable et matérialisée du flux. Elle est obtenue à partir d'un Semantic et fournit toutes les opérations terminales (collect, forEach, etc.) pour exécuter le pipeline et produire un résultat.
+Là où les bibliothèques typiques imposent des boucles synchrones ou des chaînes de promesses (*Promises*) maladroites, Semantic‑TypeScript fournit une expérience **entièrement asynchrone**, fonctionnellement pure et rigoureusement sûre au niveau des types, conçue expressément pour les exigences du développement d'applications modernes.
 
-Cette séparation impose un modèle mental clair et débloque des optimisations puissantes, comme le choix d'un `UnorderedCollectable` pour ignorer les tris inutiles et obtenir une vitesse maximale.
+Ce modèle incarne une forme raffinée de flux de contrôle : les données ne sont transmises au consommateur en aval que lorsque le pipeline en amont invoque explicitement le rappel (*callback*) `accept`. Vous conservez un contrôle complet et granulaire sur le moment du traitement – celui‑ci se produit précisément quand, et seulement quand, c'est nécessaire.
 
-## Pourquoi choisir Semantic-TypeScript ?
-Choisir la bonne bibliothèque pour le traitement de flux de données implique d'équilibrer performance, sûreté des types (type safety) et expressivité. Semantic-TypeScript est conçu pour exceller dans toutes ces dimensions.
+---
 
-### 1. Un paradigme unifié et type-safe pour toutes les séquences de données
-Il fournit une API déclarative cohérente pour traiter n'importe quelle séquence de données – qu'il s'agisse de tableaux statiques, d'événements en temps réel ou de morceaux de données asynchrones – tout en exploitant toute la puissance de TypeScript pour garantir une sûreté des types de bout en bout. Cela élimine toute une classe d'erreurs d'exécution et transforme la manipulation de flux en une activité prévisible et vérifiée par le compilateur.
+### Pourquoi les développeurs choisissent Semantic‑TypeScript
 
-### 2. Performance sans compromis avec une "paresse" intelligente
-À sa base, la bibliothèque est construite sur l'évaluation paresseuse (lazy evaluation). Des opérations comme `filter`, `map`, et `flatMap` se contentent de composer un pipeline de traitement ; aucun travail n'est effectué tant qu'une opération terminale n'est invoquée. Ceci est couplé à des capacités de court-circuit (via `limit`, `anyMatch` ou des rappels `interrupt` personnalisés), ce qui permet d'arrêter le traitement prématurément, améliorant considérablement l'efficacité pour les flux grands ou infinis.
+-   **Indexation sans répétition** – Chaque élément possède intrinsèquement son index naturel ou sur mesure, éliminant le suivi manuel.
+-   **Purement fonctionnel et sûr pour les types** – Bénéficiez d'une inférence de types TypeScript complète et idiomatique avec des opérations immuables.
+-   **Flux d'événements étanches aux fuites** – Le modèle `useSubscription` est conçu avec la sécurité des ressources comme premier principe. Vous définissez la limite logique – en utilisant `limit(n)`, `sub(start, end)` ou `takeWhile(predicate)` – et la bibliothèque gère entièrement le cycle de vie de l'abonnement. Cela garantit l'absence d'écouteurs (*listeners*) résiduels et de fuites de mémoire.
+-   **Suite statistique intégrée** – Accédez à des analyses exhaustives pour les flux de type `number` et `bigint`, incluant moyennes, médianes, modes, variance, asymétrie (*skewness*) et aplatissement (*kurtosis*), sans dépendances externes.
+-   **Performances prévisibles et ajustables** – Choisissez entre des collecteurs ordonnés ou non ordonnés pour correspondre exactement à vos besoins en matière de performances et d'ordre.
+-   **Inhéremment économe en mémoire** – Les flux sont évalués de manière paresseuse (*lazy*), traitant les éléments à la demande pour soulager la pression sur la mémoire.
+-   **Aucun comportement indéfini** – TypeScript garantit une sécurité des types et une nullabilité complètes. Vos données sources restent immuables, sauf si elles sont modifiées explicitement dans vos fonctions de rappel.
 
-### 3. La puissance du motif `Collector<E, A, R>`
-Inspiré de Java, le motif Collector est le moteur de la flexibilité. Il découple la spécification de la manière d'accumuler les éléments du flux de l'exécution du flux lui-même. La bibliothèque fournit un riche ensemble de collecteurs intégrés (`toArray`, `groupBy`, `summate`, etc.) pour les tâches courantes, tout en facilitant l'implémentation de votre propre logique de réduction complexe et réutilisable. C'est bien plus puissant et composable qu'un ensemble fixe de méthodes terminales.
+---
 
-### 4. Support de première classe pour les données Web modernes et asynchrones
-Semantic-TypeScript est conçu pour le développement contemporain. Il offre des méthodes d'usine natives pour les sources web modernes :
-- `useFrom(iterable)`, `useRange()` pour les données statiques
-- `useInterval()`, `useAnimationFrame()` pour les flux basés sur le temps
-- `useBlob()` pour le traitement de données binaires par morceaux (chunked)
-- `useWebSocket()`, `useDocument()`, `useWindow()` pour les flux d'événements en temps réel
+### Installation
 
-### 5. Au-delà de l'agrégation basique : Analyse statistique intégrée
-Allez au-delà des simples sommes et moyennes. La bibliothèque fournit les interfaces dédiées `NumericStatistics` et `BigIntStatistics`, offrant un accès immédiat à des mesures statistiques avancées directement depuis vos flux – variance, écart-type, médiane, asymétrie (skewness) et aplatissement (kurtosis). Cela transforme l'analyse de données complexes en une simple ligne de code.
+Intégrez Semantic‑TypeScript à votre projet en utilisant votre gestionnaire de paquets préféré :
 
-### 6. Conçu pour l'ergonomie du développeur
-- **API fluide et chaînable** : Écrivez des pipelines de données complexes sous forme de chaînes séquentielles lisibles.
-- **Suite utilitaire complète** : Gardes essentiels (`isFunction`, `isIterable`), utilitaires (`useCompare`, `useTraverse`) et interfaces fonctionnelles inclus.
-- **Intégration `Optional<T>`** : Modélise en toute sécurité l'absence d'une valeur, éliminant les problèmes de pointeur nul.
-- **Conseils de performance** : Guide clair sur quand utiliser la collection non ordonnée (`unordered`) pour la vitesse contre la collection ordonnée (`ordered`) pour la séquence.
-
-## Installation
 ```bash
 npm install semantic-typescript
 ```
+ou
+```bash
+yarn add semantic-typescript
+```
 
-## Concepts de base en pratique
+---
+
+### Introduction pratique
+
+Les exemples suivants démontrent des concepts clés, des transformations fondamentales à la gestion d'événements réels.
 
-### 1. Création de flux (Semantic)
-Les flux peuvent être créés à partir de diverses sources en utilisant des fonctions d'usine.
 ```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
+import { useOf, useFrom, useRange, useSubscription, useText, useStringify } from "semantic-typescript";
+
+// ====================================================================
+// EXEMPLE 1 : Opérations fondamentales et statistiques numériques
+// ====================================================================
+// Démontre les opérations de mappage (*map*) et les opérations statistiques terminales. Après transformation, le pipeline doit être converti en un collecteur de statistiques avant de pouvoir appeler des méthodes terminales comme `.summate()`.
+
+const numericSum: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)        // Double chaque élément : [20, 40, 60, 80]
+  .toNumericStatistics()                    // Convertit en un collecteur de statistiques
+  .summate();                               // Opération terminale : 200
+
+// Autres méthodes statistiques (disponibles après `.toNumericStatistics()`) :
+// .average(), .median(), .mode(), .variance(), .skewness(), .kurtosis()
+
+// ====================================================================
+// EXEMPLE 2 : Statistiques BigInt
+// ====================================================================
+// Fonctionne de manière identique aux statistiques numériques mais est optimisé pour les données BigInt.
+
+const bigintSum: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2n)       // Arithmétique BigInt
+  .toBigIntStatistics()                     // Convertit en un collecteur de statistiques BigInt
+  .summate();                               // Opération terminale : 200n
+
+// ====================================================================
+// EXEMPLE 3 : Manipulation d'index pour inverser un flux
+// ====================================================================
+// Illustre le réordonnancement des éléments en réattribuant stratégiquement leurs index à l'aide de la méthode `.redirect()`, permettant des modèles personnalisés comme l'inversion.
+
+const reversedArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .redirect((_element: number, index: bigint): bigint => -index) // Mappe sur des index négatifs
+  .toOrdered()  // Essentiel : collecte les éléments triés selon leurs nouveaux index
+  .toArray();   // Résultat : [5, 4, 3, 2, 1]
+
+// Pour une inversion simple, `.reverse()` est également disponible.
+
+// ====================================================================
+// EXEMPLE 4 : Mélange (*Shuffle*) d'un flux
+// ====================================================================
+// Permute aléatoirement les index des éléments à l'aide d'un algorithme de mélange sur place (*in‑place*).
+
+const shuffledArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .shuffle()      // Réattribue aléatoirement les index
+  .toOrdered()    // Trie selon les nouveaux index aléatoires
+  .toArray();     // Par exemple : [2, 5, 1, 4, 3] (varie à chaque exécution)
+
+// ====================================================================
+// EXEMPLE 5 : Rotation circulaire d'un flux
+// ====================================================================
+// Décale les éléments de manière cyclique. Les valeurs positives tournent vers la droite ; les valeurs négatives vers la gauche.
+
+// Rotation à droite de 2 positions
+const rightRotated: number[] = useFrom([1, 2, 3, 4, 5])
+  .translate(2)   // Décale les index de 2 vers la droite
+  .toOrdered()
+  .toArray();     // Résultat : [4, 5, 1, 2, 3]
+
+// ====================================================================
+// EXEMPLE 6 : Évaluation paresseuse (*Lazy*) avec des plages infinies
+// ====================================================================
+// Traite des flux théoriquement infinis de manière paresseuse, ne calculant les éléments que lorsqu'ils sont nécessaires.
+
+const firstTenMultiples: bigint[] = useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)  // Conserve les multiples de 17
+  .limit(10n)                   // Critique : s'arrête après le 10e élément correspondant
+  .toUnordered()                // Aucun tri requis
+  .toArray();                   // Résultat : [0, 17, 34, 51, 68, 85, 102, 119, 136, 153]
+
+// Sans `.limit(10n)`, le pipeline traiterait le million d'éléments.
+
+// ====================================================================
+// EXEMPLE 7 : Composition d'un pipeline complexe
+// ====================================================================
+// Démontre la composition séquentielle de plusieurs opérations.
+
+const complexResult: number[] = useRange(1n, 100n)
+  .map(n => Number(n) * 2)
+  .filter(n => n > 50)
+  .shuffle()
+  .limit(5n)
+  .translate(2)
+  .toOrdered()
+  .toArray();
 
-// Depuis un tableau statique
-const staticStream = useFrom([1, 2, 3, 4, 5]);
+// ====================================================================
+// EXEMPLE 8 : Abonnement géré aux événements du DOM
+// ====================================================================
+// Écoute les événements du navigateur avec un nettoyage automatique et étanche aux fuites.
+// L'appel `.limit(n)` définit la limite pour la suppression automatique de l'écouteur.
+
+// Définit un abonné pour une cible Window
+const windowSubscriber = {
+    mount: (target: Window): void => { /* Logique de configuration */ },
+    subscribe: (target: Window, event: keyof WindowEventMap, handler: EventListener): void => {
+        target.addEventListener(event, handler);
+    },
+    unsubscribe: (target: Window, event: keyof WindowEventMap, handler: EventListener): void => {
+        target.removeEventListener(event, handler);
+    },
+    unmount: (): void => { /* Logique de nettoyage */ }
+};
+
+useSubscription(window, windowSubscriber, "resize")
+  .limit(5n) // Se désabonne automatiquement après 5 événements
+  .toUnordered()
+  .forEach((ev: Event, idx) =>
+    console.log(`Redimensionnement #${idx} : ${(ev.target as Window).innerWidth}x${(ev.target as Window).innerHeight}`)
+  );
 
-// Depuis un générateur asynchrone
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
+// ====================================================================
+// EXEMPLE 9 : Traitement de chaînes par points de code Unicode
+// ====================================================================
+// Parcourt correctement une chaîne, gérant les caractères Unicode multi‑octets.
 
-// Un flux basé sur le temps
-const tickStream = useInterval(1000); // émet toutes les secondes
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // Affiche chaque caractère (y compris les émojis) sur une nouvelle ligne.
 
-// Un flux d'événements DOM (voir note cruciale ci-dessous)
-const clickStream = useDocument('click');
-```
+// ====================================================================
+// EXEMPLE 10 : Transformation sécurisée en chaîne pour références circulaires
+// ====================================================================
+// Sérialise de manière sûre des objets contenant des références circulaires.
 
-### 2. Transformation de flux (Opérations intermédiaires)
-Les opérations sont enchaînées de manière paresseuse pour définir le pipeline.
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0) // Ne garde que les nombres pairs
-  .map(x => x * 10)         // Multiplie par 10
-  .flatMap(x => [x, x + 1]) // Transforme chaque élément en deux
-  .distinct();              // Supprime les doublons
-// Rien n'a été exécuté pour l'instant
-```
+const obj = {
+  a: 1,
+  b: "texte"
+};
+(obj as any).c = [obj.a, obj.b, (obj as any).c]; // Introduit une référence circulaire
 
-### 3. Exécution de flux (Opérations terminales)
-Pour obtenir un résultat, vous devez obtenir un `Collectable` et invoquer une opération terminale.
-```typescript
-// Obtenir un collectable non ordonné pour la performance
-const resultArray = await processedStream.toUnordered().toArray();
-console.log(resultArray); // ex: [20, 21, 40, 41]
-
-// Utiliser un collecteur intégré
-const sum = await processedStream.toUnordered().collect(useSummate());
-console.log(sum);
-
-// Ou utiliser la méthode générique collect
-const customResult = await processedStream.toOrdered().collect(
-  () => new Map<number, number>(),
-  (map, element, index) => map.set(index, element),
-  map => map
-);
+// const text: string = JSON.stringify(obj); // Lance une erreur
+const text: string = useStringify(obj); // Produit de manière sûre `{a: 1, b: "texte", c: []}`
 ```
 
-### 4. Crucial : Travailler avec les flux d'événements
-Les flux d'événements (`useDocument`, `useWindow`, `useHTMLElement`, `useWebSocket`) sont par nature infinis. Vous devez utiliser des opérations comme `sub`, `takeWhile`, ou `limit` pour définir quand arrêter de collecter les événements et terminer le flux. Sinon, l'opération terminale attendra indéfiniment.
-```typescript
-import { useDocument } from 'semantic-typescript';
+---
 
-// Collecter uniquement les 5 premiers clics
-const first5Clicks = await useDocument('click')
-  .limit(5) // <- Essentiel : limite le flux à 5 événements
-  .toUnordered()
-  .toArray();
+### Concepts principaux
 
-// Collecter les clics pendant une fenêtre de 10 secondes
-const clicksIn10s = await useDocument('click')
-  .takeWhile((_, index, startTime = Date.now()) => Date.now() - startTime < 10000)
-  .toUnordered()
-  .toArray();
+| Concept | Objectif | Cas d'utilisation principal |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | Le constructeur principal pour les flux asynchrones, les événements et les pipelines paresseux basés sur une poussée (*push*). | Événements en temps réel, WebSockets, écouteurs DOM ou tout flux de longue durée/infini. |
+| `SynchronousSemantic` | Le constructeur pour les flux synchrones, en mémoire ou basés sur une traction (*pull*) immédiate (*eager*). | Données statiques, plages finies ou tâches d'itération immédiate. |
+| `toUnordered()` | Le collecteur terminal le plus rapide, utilise une Map pour stocker les index. | Chemins critiques pour les performances où l'ordre stable n'est pas requis (temps et espace O(n)). |
+| `toOrdered()` | Un collecteur terminal trié, stable en termes d'index. | Lorsque l'ordre des éléments doit être préservé ou qu'un accès indexé est nécessaire. |
+| `toNumericStatistics()` | Un collecteur permettant des analyses statistiques riches sur les flux de type `number`. | Analyse de données, métriques et calculs statistiques. |
+| `toBigIntStatistics()` | Un collecteur permettant des analyses statistiques riches sur les flux de type `bigint`. | Analyse et statistiques pour des jeux de données d'entiers de grande taille. |
+| `toWindow()` | Fournit des opérations de fenêtre glissante (*sliding*) et fixe (*tumbling*) sur un flux. | Analyse de séries temporelles, traitement par lots et agrégations par fenêtres. |
 
-// Collecter les clics de l'index 2 à 5 (base 0)
-const specificClicks = await useDocument('click')
-  .sub(2n, 6n) // <- Prend les éléments avec les index 2, 3, 4, 5
-  .toUnordered()
-  .toArray();
-```
-**Idée clé** : L'événement (par exemple, un `MouseEvent`) et son index d'émission séquentiel (sous forme de `bigint`) sont passés ensemble à travers le pipeline via le rappel `accept(event, index)`.
+---
 
-### 5. Tirer parti des statistiques
-```typescript
-const numericStream = useFrom([10, 20, 30, 40, 50]).toNumeric();
-const average = await numericStream.average();
-const median = await numericStream.median();
-const standardDeviation = await numericStream.standardDeviation();
-const skewness = await numericStream.skewness();
-console.log(`Moyenne: ${average}, Médiane: ${median}, Écart-type: ${standardDeviation}`);
-```
+**Règles d'utilisation essentielles**
 
-## Fonctionnalités principales
-- **Deux types de flux** : Support complet à la fois de `SynchronousSemantic` (pour `Iterable`) et d'`AsynchronousSemantic` (pour `AsyncIterable` et les événements)
-- **Ensemble d'opérations riche** : `filter`, `map`, `flatMap`, `concat`, `distinct`, `sorted`, `limit`, `skip`, `peek`, `reverse`, `shuffle`
-- **Opérations terminales flexibles** : `collect` (avec collecteurs personnalisés), `toArray`, `toSet`, `toMap`, `forEach`, `reduce`, `findFirst`, `anyMatch`, `allMatch`, `count`
-- **Collecteurs avancés** : Collecteurs intégrés pour `joining`, `groupingBy`, `partitioningBy`, `summing`, `averaging`, `maxBy`, `minBy`
-- **Module statistique** : Méthodes prêtes à l'emploi pour `mean`, `median`, `mode`, `variance`, `standardDeviation`, `range`, `quantiles`, `skewness`, `kurtosis` sur les flux numériques/bigint
-- **Fonctions utilitaires** : Gardes de type (`isPromise`, `isAsyncIterable`), comparateurs (`useCompare`), traversée (`useTraverse`) et crochets de conversion
-- **`Optional<T>`** : Un conteneur monadique pour les valeurs nullables, intégré aux opérations de recherche
-
-## Aperçu de l'API
-
-### Classes et Interfaces de base
-- `Semantic<E>` / `AsynchronousSemantic<E>` : La définition abstraite du flux
-- `Collectable<E>` / `AsynchronousCollectable<E>` : Le flux exécutable avec les opérations terminales
-- `OrderedCollectable<E>` / `UnorderedCollectable<E>` : Versions matérialisées optimisées pour les opérations respectant l'ordre (`order-sensitive`) ou non (`order-insensitive`)
-- `Collector<E, A, R>` : L'abstraction pour les opérations de réduction mutables
-
-### Fonctions d'usine (`use*`)
-- **Depuis des sources** : `useFrom`, `useRange`, `useFill`, `useEmpty`
-- **Depuis le temps** : `useInterval`, `useAnimationFrame`
-- **Depuis les APIs Web** : `useBlob`, `useDocument`, `useWindow`, `useHTMLElement`, `useWebSocket`
-- **Collecteurs** : `useToArray`, `useGroupBy`, `useSummate`, `useJoin`, etc.
-
-## Notes sur la performance
-- **Évaluation paresseuse (Lazy Evaluation)** : Les pipelines sont composés sans exécution jusqu'à ce qu'une opération terminale soit appelée.
-- **Court-circuit (Short-Circuiting)** : Des opérations comme `limit`, `anyMatch` et `findFirst` arrêteront de traiter les éléments dès que le résultat est déterminé.
-- **Ordonné vs Non ordonné** :
-    - Utilisez `.toUnordered()` pour les opérations terminales lorsque l'ordre des éléments source n'a pas d'importance pour votre résultat (ex: pour `sum`, `max`, ou `toSet`). Cela peut permettre des optimisations internes qui sautent des étapes de tri coûteuses.
-    - Utilisez `.toOrdered()` lorsque la séquence est importante (ex: pour `toArray` où l'ordre doit être préservé).
-
-## Exemple pour commencer
-```typescript
-import { useFrom, useSummate, useGroupBy } from 'semantic-typescript';
-
-interface Transaction {
-  id: number;
-  amount: number;
-  category: string;
-}
-
-const transactions: Transaction[] = [
-  { id: 1, amount: 100, category: 'Food' },
-  { id: 2, amount: 200, category: 'Electronics' },
-  { id: 3, amount: 50, category: 'Food' },
-  { id: 4, amount: 300, category: 'Electronics' },
-];
-
-// Calculer le montant total par catégorie
-const totalsByCategory = await useFrom(transactions)
-  .toUnordered()
-  .collect(
-    useGroupBy(
-      t => t.category,
-      t => t.amount,
-      useSummate() // Collecteur pour les valeurs
-    )
-  );
+1.  **Les flux d'événements** (créés via des fabriques comme `useSubscription`) retournent un `AsynchronousSemantic`.
+    → Vous **devez** appeler une méthode définissant une limite, comme `.limit(n)`, `.sub(start, end)` ou `.takeWhile(predicate)` pour mettre fin à l'écoute. Sinon, l'abonnement restera actif.
 
-console.log(totalsByCategory); // Map { 'Food' => 150, 'Electronics' => 500 }
-```
+2.  **Les opérations terminales** (`.toArray()`, `.count()`, `.forEach()`, `.findFirst()`, etc.) ne sont **disponibles qu'après** avoir converti le pipeline en un collecteur :
+    ```typescript
+    .toUnordered()   // Pour une vitesse maximale, sans garantie d'ordre.
+    // ou
+    .toOrdered()     // Pour une sortie stable et triée.
+    // ou
+    .toNumericStatistics() // Pour les méthodes statistiques.
+    ```
+
+---
+
+### Caractéristiques de performance
+
+| Collecteur | Complexité temporelle | Complexité spatiale | Ordre garanti ? | Scénario idéal |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | Non | Le débit brut est primordial ; l'ordre final est sans importance. |
+| `toOrdered()` | O(n log n) | O(n) | Oui (trié) | Ordre stable, accès indexé ou pré‑tri pour les statistiques. |
+| `toNumericStatistics()` | O(n log n) | O(n) | Oui (tri interne) | Exécution d'opérations statistiques nécessitant des données triées. |
+| `toBigIntStatistics()` | O(n log n) | O(n) | Oui (tri interne) | Opérations statistiques sur des données BigInt. |
+| `toWindow()` | O(n log n) | O(n) | Oui (tri interne) | Opérations de fenêtre bénéficiant d'index triés. |
+
+Choisissez `toUnordered()` lorsque la vitesse absolue est primordiale. Optez pour `toOrdered()` ou un collecteur de statistiques uniquement lorsque votre logique dépend de l'ordre des éléments.
+
+---
+
+**Analyse comparative avec les bibliothèques de flux modernes**
+
+| Caractéristique | Semantic‑TypeScript | RxJS | Async Iterators / Generators natifs | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **Intégration TypeScript** | De première classe, fortement typée avec une conscience d'index inhérente. | Excellente, mais implique souvent des chaînes génériques complexes. | Bonne, mais nécessite des annotations de type manuelles. | Solide, avec un style de typage fonctionnel‑*first*. |
+| **Analyse statistique intégrée** | Prise en charge native complète pour `number` et `bigint`. | Non disponible nativement (nécessite des opérateurs personnalisés ou d'autres bibliothèques). | Aucune. | Aucune. |
+| **Indexation et conscience de position** | Indexation BigInt native et puissante sur chaque élément. | Nécessite des opérateurs personnalisés (ex. `scan`, `withLatestFrom`). | Gestion manuelle de compteur nécessaire. | Basique, aucune propriété d'index intégrée. |
+| **Gestion des flux d'événements** | Fabriques dédiées, sûres pour les types, avec contrôle de cycle de vie explicite et déclaratif. | Puissante mais nécessite une gestion manuelle minutieuse des abonnements pour éviter les fuites. | Attachement manuel des écouteurs d'événements et gestion de jetons d'annulation. | Bon `fromEvent`, généralement léger. |
+| **Performances et mémoire** | Exceptionnel – offre des collecteurs optimisés `toUnordered()` et `toOrdered()`. | Très bonne, bien que les chaînes profondes d'opérateurs puissent introduire une surcharge. | Excellente (surcharge native minimale). | Excellente. |
+| **Taille du bundle** | Très léger. | Substantielle (même avec l'élagage d'arbre – *tree‑shaking*). | Zéro (fonctionnalité native du langage). | Petit. |
+| **Philosophie de conception d'API** | Modèle de collecteur fonctionnel avec sémantique d'index explicite. | Modèle Observable réactif. | Modèle Iterator impératif / Generator déclaratif. | Fonctionnel, composition *point‑free*. |
+| **Contrôle de flux** | Explicite (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Bon (`take`, `takeUntil`, `first`). | Manuel (`break` dans les boucles). | Bon (`take`, `until`). |
+| **Support synchrone et asynchrone** | API unifiée – support de première classe pour les deux paradigmes. | Principalement asynchrone. | Les deux pris en charge, mais avec un pont manuel. | Principalement asynchrone. |
+| **Courbe d'apprentissage** | Douce pour les développeurs familiers avec les pipelines de collections fonctionnelles et indexées. | Plus raide (lexique étendu d'opérateurs, concepts Observable chaud/froid – *hot/cold*). | Faible à moyenne. | Moyenne. |
+
+**L'avantage de Semantic‑TypeScript**
+
+*   **Capacités uniques :** Les fonctionnalités de statistique et d'indexation intégrées éliminent le besoin d'opérations manuelles de `reduce` ou de bibliothèques d'analyse de données supplémentaires.
+*   **Gestion prévisible des ressources :** Le contrôle explicite des flux d'événements prévient les fuites de mémoire qui peuvent être subtiles dans les applications RxJS.
+*   **Conception unifiée :** Une API cohérente pour les flux de travail synchrones et asynchrones réduit la charge cognitive et la duplication de code.
+
+Cette comparaison met en lumière pourquoi Semantic‑TypeScript est particulièrement adapté aux applications TypeScript modernes qui exigent des performances élevées, une robustesse en matière de sécurité des types et des fonctionnalités de traitement de données riches sans la complexité des frameworks réactifs traditionnels.
+
+---
+
+### Commencez votre exploration
+
+Semantic‑TypeScript transforme des flux de données complexes en pipelines lisibles, composables et performants. Que vous manipuliez des événements d'interface utilisateur en temps réel, traitiez de grands ensembles de données ou construisiez des tableaux de bord analytiques, il offre la puissance de l'indexation au niveau base de données avec l'élégance de la programmation fonctionnelle.
+
+**Vos prochaines étapes :**
+
+*   Explorez l'API entièrement typée directement dans votre IDE (toutes les exportations sont disponibles depuis le point d'entrée principal du paquet).
+*   Rejoignez la communauté grandissante de développeurs qui ont remplacé des itérateurs asynchrones complexes et des chaînes réactives par des pipelines Semantic clairs et intentionnels.
+
+**Semantic‑TypeScript** – où les flux rencontrent la structure.
+
+Commencez à construire dès aujourd'hui et expérimentez la différence tangible qu'apporte une conception d'indexation réfléchie.
 
-Semantic-TypeScript est conçue pour les développeurs qui recherchent une bibliothèque de traitement de flux rigoureusement conçue, type-safe et haute performance. Elle apporte la puissance des modèles de transformation de données de niveau entreprise à l'écosystème TypeScript, parfaitement adaptée aux applications front-end gourmandes en données, au traitement de données Node.js, et à tout scénario où une manipulation élégante et efficace des séquences est requise.
+**Construisez avec clarté, avancez avec confiance et transformez les données avec intention.**
 
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript)
+MIT © Eloy Kim