semantic-typescript 0.6.0 → 0.7.1

package/readme.es.md

@@ -1,208 +1,267 @@
-# Semantic-TypeScript: Una biblioteca de procesamiento de flujo que cambia paradigmas
+# **Semantic‑TypeScript**
+**Flujos, indexados.** Tus datos, bajo control preciso.
 
-## Introducción
-Semantic-TypeScript representa un avance significativo en la tecnología de procesamiento de flujos, sintetizando los conceptos más efectivos de JavaScript GeneratorFunctions, Java Streams y los paradigmas de indexación de bases de datos. Su principio de diseño fundamental se centra en la construcción de pipelines de procesamiento de datos excepcionalmente eficientes mediante evaluación diferida (lazy) sofisticada e indexación inteligente. La biblioteca ofrece una experiencia de operación de flujos rigurosamente segura en tipos y funcionalmente pura, específicamente diseñada para el desarrollo moderno en TypeScript y JavaScript.
+---
 
-En contraste con las arquitecturas de procesamiento sincrónico convencionales, Semantic-TypeScript implementa un modelo unificado que maneja con gracia tanto fuentes de datos sincrónicas (Iterable) como asincrónicas (AsyncIterable). Durante la generación del flujo, el flujo y la terminación de los datos se controlan con precisión mediante mecanismos de callback, lo que permite a la biblioteca manejar con excepcional gracia:
-- Flujos de datos en tiempo real (eventos DOM, WebSockets, intervalos) con control determinista
-- Conjuntos de datos a gran escala mediante pipelines diferidos y eficientes en memoria
-- Transformaciones de datos complejas con una API fluida y declarativa
+### Descripción general
 
-El enfoque innovador de la biblioteca reinterpreta fundamentalmente cómo los desarrolladores interactúan con secuencias de datos, ofreciendo tanto características de rendimiento sin precedentes como ergonomía para el desarrollador en un paquete único y cohesivo.
+Semantic‑TypeScript representa un avance significativo en el procesamiento de flujos, **fusionando** elegantemente los paradigmas más efectivos de los generadores de JavaScript, los Streams de Java y la indexación al estilo MySQL. Su premisa fundamental es poderosa y deliberada: construir canalizaciones de procesamiento de datos excepcionalmente eficientes mediante indexación inteligente, en lugar de mediante iteración por fuerza bruta convencional.
 
-## Filosofía Central: Separación de Definición y Ejecución
-Una idea arquitectónica clave de Semantic-TypeScript es la clara separación entre la definición de un flujo y su ejecución:
-- **Semantic<E>**: Un plano inmutable y diferido de un pipeline de transformación de datos. Define qué operaciones (filter, map, etc.) se realizarán
-- **Collectable<E>**: Una vista materializada y ejecutable del flujo. Se obtiene a partir de un Semantic y proporciona todas las operaciones terminales (collect, forEach, etc.) para ejecutar el pipeline y producir un resultado
+Donde las bibliotecas típicas imponen bucles sincrónicos o cadenas de promesas engorrosas, Semantic‑TypeScript proporciona una experiencia **completamente asíncrona**, funcionalmente pura y rigurosamente segura en cuanto a tipos, diseñada expresamente para las exigencias del desarrollo moderno de aplicaciones.
 
-Esta separación impone un modelo mental limpio y desbloquea optimizaciones potentes, como elegir un UnorderedCollectable para omitir ordenaciones innecesarias y obtener la máxima velocidad.
+Este modelo encarna una forma refinada de flujo de control: los datos solo avanzan hacia el consumidor aguas abajo cuando la canalización aguas arriba invoca explícitamente la función de retorno `accept`. Conservas un control completo y granular sobre el momento del procesamiento: este ocurre precisamente cuando, y solo cuando, es necesario.
 
-## ¿Por qué elegir Semantic-TypeScript?
-Seleccionar la biblioteca adecuada para el procesamiento de flujos de datos implica equilibrar rendimiento, seguridad de tipos y expresividad. Semantic-TypeScript está diseñada para sobresalir en todas estas dimensiones.
+---
 
-### 1. Un paradigma unificado y seguro en tipos para todas las secuencias de datos
-Proporciona una API declarativa y consistente para procesar cualquier secuencia de datos, ya sean arreglos estáticos, eventos en tiempo real o fragmentos asincrónicos, al tiempo que aprovecha todo el poder de TypeScript para garantizar seguridad de tipos de extremo a extremo. Esto elimina toda una clase de errores en tiempo de ejecución y transforma la manipulación de flujos en una actividad predecible y verificada por el compilador.
+### ¿Por qué los desarrolladores eligen Semantic‑TypeScript?
 
-### 2. Rendimiento sin concesiones con evaluación diferida inteligente
-En su núcleo, la biblioteca está construida sobre evaluación diferida. Operaciones como filter, map y flatMap simplemente componen un pipeline de procesamiento; no se realiza ningún trabajo hasta que se invoca una operación terminal. Esto se combina con capacidades de cortocircuito (a través de limit, anyMatch o callbacks de interrupción personalizados), que permiten detener el procesamiento anticipadamente, mejorando drásticamente la eficiencia para flujos grandes o infinitos.
+-   **Indexación sin código repetitivo** – Cada elemento posee inherentemente su índice natural o personalizado, eliminando el seguimiento manual.
+-   **Puramente funcional y seguro en tipos** – Disfruta de inferencia de tipos TypeScript completa e idiomática junto con operaciones inmutables.
+-   **Flujos de eventos a prueba de fugas** – El patrón `useSubscription` se diseña teniendo la seguridad de recursos como primer principio. Defines el límite lógico (usando `limit(n)`, `sub(start, end)` o `takeWhile(predicate)`) y la biblioteca gestiona completamente el ciclo de vida de la suscripción. Esto garantiza que no haya oyentes residuales ni fugas de memoria.
+-   **Suite estadística integrada** – Accede a análisis exhaustivos para flujos tanto de `number` como de `bigint`, incluyendo promedios, medianas, modas, varianza, asimetría y curtosis, sin dependencias externas.
+-   **Rendimiento predecible y ajustable** – Elige entre colectores ordenados o desordenados para adaptarte exactamente a tus requisitos de rendimiento y orden.
+-   **Inherentemente eficiente en memoria** – Los flujos se evalúan de forma diferida, procesando elementos bajo demanda para aliviar la presión sobre la memoria.
+-   **Sin comportamiento indefinido** – TypeScript garantiza seguridad de tipos completa y nulabilidad. Tus datos de origen permanecen inmutables a menos que se modifiquen explícitamente dentro de tus funciones de retorno.
 
-### 3. El poder del patrón `Collector<E, A, R>`
-Inspirado en Java, el patrón Collector es el motor de la flexibilidad. Desacopla la especificación de cómo acumular elementos del flujo de la ejecución del flujo en sí. La biblioteca proporciona un rico conjunto de coleccionadores integrados (toArray, groupBy, summate, etc.) para tareas cotidianas, al tiempo que hace que sea trivial implementar tu propia lógica de reducción compleja y reutilizable. Esto es mucho más potente y componible que un conjunto fijo de métodos terminales.
+---
 
-### 4. Soporte de primera clase para datos web modernos y asincrónicos
-Semantic-TypeScript está diseñada para el desarrollo contemporáneo. Ofrece métodos de fábrica nativos para fuentes web modernas:
-- `useFrom(iterable)`, `useRange()` para datos estáticos
-- `useInterval()`, `useAnimationFrame()` para flujos basados en tiempo
-- `useBlob()` para procesamiento de datos binarios fragmentados
-- `useWebSocket()`, `useDocument()`, `useWindow()` para flujos de eventos en tiempo real
+### Instalación
 
-### 5. Más allá de la agregación básica: análisis estadístico integrado
-Ve más allá de simples sumas y promedios. La biblioteca proporciona interfaces dedicadas NumericStatistics y BigIntStatistics, ofreciendo acceso inmediato a medidas estadísticas avanzadas directamente desde tus flujos: varianza, desviación estándar, mediana, asimetría y curtosis. Esto convierte el análisis de datos complejos en una sola línea de código.
+Integra Semantic‑TypeScript en tu proyecto usando tu gestor de paquetes preferido:
 
-### 6. Diseñada para la ergonomía del desarrollador
-- **API fluida y encadenable**: Escribe pipelines de datos complejos como cadenas secuenciales y legibles
-- **Suite integral de utilidades**: Protecciones esenciales (isFunction, isIterable), utilidades (useCompare, useTraverse) e interfaces funcionales incluidas
-- **Integración Optional<T>**: Modela de forma segura la ausencia de un valor, eliminando preocupaciones de punteros nulos
-- **Guía de rendimiento**: Orientación clara sobre cuándo usar recolección no ordenada (unordered) para velocidad versus ordenada (ordered) para secuencia
-
-## Instalación
 ```bash
 npm install semantic-typescript
 ```
+o
+```bash
+yarn add semantic-typescript
+```
+
+---
+
+### Introducción práctica
 
-## Conceptos centrales en la práctica
+Los siguientes ejemplos demuestran conceptos clave, desde transformaciones básicas hasta manejo de eventos del mundo real.
 
-### 1. Creación de flujos (Semantic)
-Los flujos se pueden crear desde varias fuentes usando funciones de fábrica.
 ```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
+import { useOf, useFrom, useRange, useSubscription, useText, useStringify } from "semantic-typescript";
+
+// ====================================================================
+// EJEMPLO 1: Operaciones básicas y estadísticas numéricas
+// ====================================================================
+// Demuestra operaciones de mapeo y estadísticas terminales. Después de la transformación, la canalización debe convertirse en un colector de estadísticas antes de poder llamar a métodos terminales como `.summate()`.
+
+const numericSum: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)        // Duplica cada elemento: [20, 40, 60, 80]
+  .toNumericStatistics()                    // Convierte a un colector de estadísticas
+  .summate();                               // Operación terminal: 200
+
+// Otros métodos estadísticos (disponibles después de `.toNumericStatistics()`):
+// .average(), .median(), .mode(), .variance(), .skewness(), .kurtosis()
+
+// ====================================================================
+// EJEMPLO 2: Estadísticas de BigInt
+// ====================================================================
+// Funciona de manera idéntica a las estadísticas numéricas pero está optimizado para datos BigInt.
+
+const bigintSum: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2n)       // Aritmética BigInt
+  .toBigIntStatistics()                       // Convierte a un colector de estadísticas BigInt
+  .summate();                                // Operación terminal: 200n
+
+// ====================================================================
+// EJEMPLO 3: Manipulación de índices para invertir un flujo
+// ====================================================================
+// Ilustra cómo reordenar elementos reasignando estratégicamente sus índices utilizando el método `.redirect()`, permitiendo patrones personalizados como la inversión.
+
+const reversedArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .redirect((_element: number, index: bigint): bigint => -index) // Mapea a índices negativos
+  .toOrdered()  // Esencial: recoge elementos ordenados por sus nuevos índices
+  .toArray();   // Resultado: [5, 4, 3, 2, 1]
+
+// Para una inversión simple, también está disponible `.reverse()`.
+
+// ====================================================================
+// EJEMPLO 4: Mezcla (Shuffle) de un flujo
+// ====================================================================
+// Permuta aleatoriamente los índices de los elementos usando un algoritmo de mezcla in situ.
+
+const shuffledArray: number[] = useFrom([1, 2, 3, 4, 5])
+  .shuffle()      // Reasigna índices aleatoriamente
+  .toOrdered()    // Ordena según los nuevos índices aleatorios
+  .toArray();     // Ejemplo: [2, 5, 1, 4, 3] (varía en cada ejecución)
+
+// ====================================================================
+// EJEMPLO 5: Rotación circular de un flujo
+// ====================================================================
+// Desplaza elementos cíclicamente. Los valores positivos rotan a la derecha; los negativos a la izquierda.
+
+// Rotación a la derecha 2 posiciones
+const rightRotated: number[] = useFrom([1, 2, 3, 4, 5])
+  .translate(2)   // Desplaza índices 2 posiciones a la derecha
+  .toOrdered()
+  .toArray();     // Resultado: [4, 5, 1, 2, 3]
+
+// ====================================================================
+// EJEMPLO 6: Evaluación diferida con rangos infinitos
+// ====================================================================
+// Procesa flujos teóricamente infinitos de forma diferida, calculando elementos solo cuando se necesitan.
+
+const firstTenMultiples: bigint[] = useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)  // Conserva múltiplos de 17
+  .limit(10n)                    // Crítico: se detiene después de la décima coincidencia
+  .toUnordered()                 // No se requiere ordenación
+  .toArray();                    // Resultado: [0, 17, 34, 51, 68, 85, 102, 119, 136, 153]
+
+// Sin `.limit(10n)`, la canalización procesaría el millón de elementos.
+
+// ====================================================================
+// EJEMPLO 7: Composición de una canalización compleja
+// ====================================================================
+// Demuestra la composición secuencial de múltiples operaciones.
+
+const complexResult: number[] = useRange(1n, 100n)
+  .map(n => Number(n) * 2)
+  .filter(n => n > 50)
+  .shuffle()
+  .limit(5n)
+  .translate(2)
+  .toOrdered()
+  .toArray();
 
-// Desde un arreglo estático
-const staticStream = useFrom([1, 2, 3, 4, 5]);
+// ====================================================================
+// EJEMPLO 8: Suscripción gestionada a eventos del DOM
+// ====================================================================
+// Escucha eventos del navegador con limpieza automática y a prueba de fugas.
+// La llamada `.limit(n)` define el límite para la eliminación automática del oyente.
+
+// Define un suscriptor para un objetivo Window
+const windowSubscriber = {
+    mount: (target: Window): void => { /* Lógica de configuración */ },
+    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 => { /* Lógica de limpieza */ }
+};
+
+useSubscription(window, windowSubscriber, "resize")
+  .limit(5n) // Se da de baja automáticamente después de 5 eventos
+  .toUnordered()
+  .forEach((ev: Event, idx) =>
+    console.log(`Redimensión #${idx}: ${(ev.target as Window).innerWidth}x${(ev.target as Window).innerHeight}`)
+  );
 
-// Desde un generador asincrónico
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
+// ====================================================================
+// EJEMPLO 9: Procesamiento de cadenas por puntos de código Unicode
+// ====================================================================
+// Itera correctamente sobre una cadena, manejando caracteres Unicode de múltiples bytes.
 
-// Un flujo basado en tiempo
-const tickStream = useInterval(1000); // emite cada segundo
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // Registra cada carácter (incluyendo emojis) en una nueva línea.
 
-// Un flujo de eventos DOM (ver nota crucial a continuación)
-const clickStream = useDocument('click');
-```
+// ====================================================================
+// EJEMPLO 10: Transformación a cadena segura de referencias circulares
+// ====================================================================
+// Serializa de forma segura objetos que contienen referencias circulares.
 
-### 2. Transformación de flujos (Operaciones intermedias)
-Las operaciones se encadenan de forma diferida para definir el pipeline.
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0) // Mantener solo números pares
-  .map(x => x * 10) // Multiplicar por 10
-  .flatMap(x => [x, x + 1]) // Transformar cada elemento en dos
-  .distinct(); // Eliminar duplicados
+const obj = {
+  a: 1,
+  b: "texto"
+};
+(obj as any).c = [obj.a, obj.b, (obj as any).c]; // Introduce una referencia circular
 
-// Nada se ha ejecutado todavía
+// const text: string = JSON.stringify(obj); // Lanza un error
+const text: string = useStringify(obj); // Produce de forma segura `{a: 1, b: "texto", c: []}`
 ```
 
-### 3. Ejecución de flujos (Operaciones terminales)
-Para obtener un resultado, debes obtener un Collectable e invocar una operación terminal.
-```typescript
-// Obtener un collectable no ordenado para rendimiento
-const resultArray = await processedStream.toUnordered().toArray();
-console.log(resultArray); // ej., [20, 21, 40, 41]
-
-// Usar un coleccionador incorporado
-const sum = await processedStream.toUnordered().collect(useSummate());
-console.log(sum);
-
-// O usar el método collect genérico
-const customResult = await processedStream.toOrdered().collect(
-  () => new Map<number, number>(),
-  (map, element, index) => map.set(index, element),
-  map => map
-);
-```
+---
 
-### 4. Crucial: Trabajar con flujos de eventos
-Los flujos de eventos (useDocument, useWindow, useHTMLElement, useWebSocket) son infinitos por naturaleza. Debes usar operaciones como sub, takeWhile o limit para definir cuándo dejar de recolectar eventos y completar el flujo. De lo contrario, la operación terminal esperará indefinidamente.
-```typescript
-import { useDocument } from 'semantic-typescript';
+### Conceptos principales
 
-// Recolectar solo los primeros 5 clics
-const first5Clicks = await useDocument('click')
-  .limit(5) // <- Esencial: limita el flujo a 5 eventos
-  .toUnordered()
-  .toArray();
+| Concepto | Propósito | Caso de uso principal |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | El constructor principal para flujos asíncronos, eventos y canalizaciones diferidas basadas en *push*. | Eventos en tiempo real, WebSockets, oyentes del DOM o cualquier flujo de larga duración/infinito. |
+| `SynchronousSemantic` | El constructor para flujos síncronos, en memoria o basados en *pull* inmediatos (*eager*). | Datos estáticos, rangos finitos o tareas de iteración inmediata. |
+| `toUnordered()` | El colector terminal más rápido, utiliza un Map para almacenar índices. | Rutas críticas de rendimiento donde el orden estable no es requerido (tiempo y espacio O(n)). |
+| `toOrdered()` | Un colector terminal ordenado, estable en índices. | Cuando se debe preservar el orden de los elementos o se necesita acceso indexado. |
+| `toNumericStatistics()` | Un colector que habilita análisis estadísticos completos en flujos de `number`. | Análisis de datos, métricas y cálculos estadísticos. |
+| `toBigIntStatistics()` | Un colector que habilita análisis estadísticos completos en flujos de `bigint`. | Análisis y estadísticas para conjuntos de datos de enteros grandes. |
+| `toWindow()` | Proporciona operaciones de ventana deslizante (*sliding*) y fija (*tumbling*) sobre un flujo. | Análisis de series temporales, procesamiento por lotes y agregaciones por ventanas. |
 
-// Recolectar clics durante una ventana de 10 segundos
-const clicksIn10s = await useDocument('click')
-  .takeWhile((_, index, startTime = Date.now()) => Date.now() - startTime < 10000)
-  .toUnordered()
-  .toArray();
+---
 
-// Recolectar clics desde el índice 2 al 5 (base 0)
-const specificClicks = await useDocument('click')
-  .sub(2n, 6n) // <- Toma elementos con índice 2, 3, 4, 5
-  .toUnordered()
-  .toArray();
-```
+**Reglas de uso esenciales**
 
-**Perspicacia clave**: El evento (por ejemplo, un MouseEvent) y su índice de disparo secuencial (como un bigint) se pasan juntos a través del pipeline mediante el callback `accept(event, index)`.
+1.  **Los flujos de eventos** (creados a través de fábricas como `useSubscription`) devuelven un `AsynchronousSemantic`.
+    → Debes llamar a un método que defina un límite, como `.limit(n)`, `.sub(start, end)` o `.takeWhile(predicate)` para terminar el oyente. De lo contrario, la suscripción permanecerá activa.
 
-### 5. Aprovechando las estadísticas
-```typescript
-const numericStream = useFrom([10, 20, 30, 40, 50]).toNumeric();
+2.  **Las operaciones terminales** (`.toArray()`, `.count()`, `.forEach()`, `.findFirst()`, etc.) solo están disponibles después de convertir la canalización en un colector:
+    ```typescript
+    .toUnordered()   // Para máxima velocidad, sin garantía de orden.
+    // o
+    .toOrdered()     // Para salida estable y ordenada.
+    // o
+    .toNumericStatistics() // Para métodos estadísticos.
+    ```
 
-const average = await numericStream.average();
-const median = await numericStream.median();
-const standardDeviation = await numericStream.standardDeviation();
-const skewness = await numericStream.skewness();
+---
 
-console.log(`Promedio: ${average}, Mediana: ${median}, DesvEst: ${standardDeviation}`);
-```
+### Características de rendimiento
 
-## Características principales
-- **Tipos de flujo dual**: Soporte completo para ambos SynchronousSemantic (para Iterable) y AsynchronousSemantic (para AsyncIterable y eventos)
-- **Conjunto de operaciones rico**: filter, map, flatMap, concat, distinct, sorted, limit, skip, peek, reverse, shuffle
-- **Operaciones terminales flexibles**: collect (con coleccionadores personalizados), toArray, toSet, toMap, forEach, reduce, findFirst, anyMatch, allMatch, count
-- **Coleccionadores avanzados**: Coleccionadores integrados para joining, groupingBy, partitioningBy, summing, averaging, maxBy, minBy
-- **Módulo estadístico**: Métodos listos para usar para media, mediana, moda, varianza, desviaciónEstándar, rango, cuantiles, asimetría, curtosis en flujos numéricos/de bigint
-- **Funciones de utilidad**: Protecciones de tipo (isPromise, isAsyncIterable), comparadores (useCompare), recorrido (useTraverse) y ganchos de conversión
-- **Optional<T>**: Un contenedor monádico para valores anulables, integrado con operaciones de búsqueda
-
-## Resumen de la API
-
-### Clases e interfaces centrales
-- `Semantic<E>` / `AsynchronousSemantic<E>`: La definición abstracta del flujo
-- `Collectable<E>` / `AsynchronousCollectable<E>`: El flujo ejecutable con operaciones terminales
-- `OrderedCollectable<E>` / `UnorderedCollectable<E>`: Versiones materializadas optimizadas para operaciones sensibles o no sensibles al orden
-- `Collector<E, A, R>`: La abstracción para operaciones de reducción mutables
-
-### Funciones de fábrica (use*)
-- **Desde fuentes**: useFrom, useRange, useFill, useEmpty
-- **Desde tiempo**: useInterval, useAnimationFrame
-- **Desde APIs web**: useBlob, useDocument, useWindow, useHTMLElement, useWebSocket
-- **Coleccionadores**: useToArray, useGroupBy, useSummate, useJoin, etc.
-
-## Notas de rendimiento
-- **Evaluación diferida**: Los pipelines se componen sin ejecución hasta que se llama a una operación terminal
-- **Cortocircuito**: Operaciones como limit, anyMatch y findFirst detendrán el procesamiento de elementos tan pronto como se determine el resultado
-- **Ordenado vs No ordenado**:
-  - Usa `.toUnordered()` para operaciones terminales cuando el orden de los elementos fuente no importa para tu resultado (por ejemplo, para suma, máximo o toSet). Esto puede permitir optimizaciones internas que omiten costosos pasos de ordenación
-  - Usa `.toOrdered()` cuando la secuencia es importante (por ejemplo, para toArray donde se debe preservar el orden)
-
-## Ejemplo de inicio
-```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' },
-];
-
-// Calcular el monto total por categoría
-const totalsByCategory = await useFrom(transactions)
-  .toUnordered()
-  .collect(
-    useGroupBy(
-      t => t.category,
-      t => t.amount,
-      useSummate() // Coleccionador para los valores
-    )
-  );
+| Colector | Complejidad temporal | Complejidad espacial | ¿Orden garantizado? | Escenario ideal |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | No | El rendimiento bruto es clave; el orden final es irrelevante. |
+| `toOrdered()` | O(n log n) | O(n) | Sí (ordenado) | Orden estable, acceso indexado o pre-ordenación para estadísticas. |
+| `toNumericStatistics()` | O(n log n) | O(n) | Sí (orden interno) | Realizar operaciones estadísticas que requieren datos ordenados. |
+| `toBigIntStatistics()` | O(n log n) | O(n) | Sí (orden interno) | Operaciones estadísticas en datos BigInt. |
+| `toWindow()` | O(n log n) | O(n) | Sí (orden interno) | Operaciones de ventana que se benefician de índices ordenados. |
 
-console.log(totalsByCategory); // Map { 'Food' => 150, 'Electronics' => 500 }
-```
+Elige `toUnordered()` cuando la velocidad absoluta es primordial. Opta por `toOrdered()` o un colector de estadísticas solo cuando tu lógica dependa del orden de los elementos.
+
+---
+
+**Análisis comparativo con bibliotecas modernas de flujos**
+
+| Característica | Semantic‑TypeScript | RxJS | Async Iterators / Generators nativos | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **Integración TypeScript** | De primera clase, fuertemente tipado con conciencia de índice inherente. | Excelente, pero a menudo implica cadenas genéricas complejas. | Buena, pero requiere anotaciones de tipo manuales. | Fuerte, con un estilo de tipado funcional-*first*. |
+| **Análisis estadístico integrado** | Soporte nativo completo para `number` y `bigint`. | No disponible de forma nativa (requiere operadores personalizados u otras bibliotecas). | Ninguno. | Ninguno. |
+| **Indexación y conciencia de posición** | Indexación BigInt nativa y poderosa en cada elemento. | Requiere operadores personalizados (ej. `scan`, `withLatestFrom`). | Se requiere gestión manual de contadores. | Básica, sin propiedad de índice incorporada. |
+| **Gestión de flujos de eventos** | Fábricas dedicadas, seguras en tipos, con control de ciclo de vida explícito y declarativo. | Poderosa pero requiere una gestión manual cuidadosa de las suscripciones para evitar fugas. | Adjuntar oyentes de eventos manualmente y gestionar tokens de cancelación. | Buen `fromEvent`, generalmente liviano. |
+| **Rendimiento y memoria** | Excepcional: ofrece colectores optimizados `toUnordered()` y `toOrdered()`. | Muy buena, aunque las cadenas profundas de operadores pueden introducir sobrecarga. | Excelente (sobrecarga nativa mínima). | Excelente. |
+| **Tamaño del paquete** | Muy liviano. | Sustancial (incluso con *tree-shaking*). | Cero (característica nativa del lenguaje). | Pequeño. |
+| **Filosofía de diseño de API** | Patrón de colector funcional con semántica de índice explícita. | Patrón Observable reactivo. | Patrón Iterator imperativo / Generator declarativo. | Funcional, composición *point-free*. |
+| **Control de flujo** | Explícito (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Bueno (`take`, `takeUntil`, `first`). | Manual (`break` en bucles). | Bueno (`take`, `until`). |
+| **Soporte síncrono y asíncrono** | API unificada: soporte de primera clase para ambos paradigmas. | Principalmente asíncrono. | Ambos soportados, pero con puente manual. | Principalmente asíncrono. |
+| **Curva de aprendizaje** | Suave para desarrolladores familiarizados con canalizaciones de colecciones funcionales e indexadas. | Más pronunciada (amplio léxico de operadores, conceptos de Observable *hot/cold*). | Baja a media. | Media. |
+
+**La ventaja de Semantic‑TypeScript**
+
+*   **Capacidades únicas:** Las características de estadística e indexación integradas eliminan la necesidad de operaciones manuales de `reduce` o bibliotecas de análisis de datos suplementarias.
+*   **Gestión de recursos predecible:** El control explícito sobre los flujos de eventos previene las fugas de memoria que pueden ser sutiles en las aplicaciones RxJS.
+*   **Diseño unificado:** Una API consistente para flujos de trabajo tanto síncronos como asíncronos reduce la carga cognitiva y la duplicación de código.
+
+Esta comparación destaca por qué Semantic‑TypeScript es especialmente adecuado para aplicaciones TypeScript modernas que exigen alto rendimiento, solidez en la seguridad de tipos y amplias funciones de procesamiento de datos sin la complejidad de los marcos reactivos tradicionales.
+
+---
+
+### Comienza tu exploración
+
+Semantic‑TypeScript transforma flujos de datos complejos en canalizaciones legibles, componibles y de alto rendimiento. Ya sea que estés manejando eventos de UI en tiempo real, procesando grandes conjuntos de datos o construyendo paneles de análisis, ofrece el poder de la indexación a nivel de base de datos con la elegancia de la programación funcional.
+
+**Tus próximos pasos:**
+
+*   Explora la API completamente tipificada directamente en tu IDE (todas las exportaciones están disponibles desde el punto de entrada principal del paquete).
+*   Únete a la creciente comunidad de desarrolladores que han reemplazado iteradores asíncronos complejos y cadenas reactivas con canalizaciones Semantic claras e intencionales.
+
+**Semantic‑TypeScript** – donde los flujos se encuentran con la estructura.
+
+Comienza a construir hoy y experimenta la diferencia tangible que aporta un diseño de indexación reflexivo.
 
-Semantic-TypeScript está construida para desarrolladores que buscan una biblioteca de procesamiento de flujos rigurosamente diseñada, segura en tipos y de alto rendimiento. Lleva el poder de los patrones de transformación de datos a nivel empresarial al ecosistema TypeScript, perfectamente adecuada para aplicaciones front-end intensivas en datos, procesamiento de datos en Node.js y cualquier escenario donde se requiera un manejo elegante y eficiente de secuencias.
+**Construye con claridad, avanza con confianza y transforma datos con intención.**
 
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript) 
+MIT © Eloy Kim