semantic-typescript 0.5.3 → 0.7.0

package/readme.es.md

@@ -1,478 +1,213 @@
-# Biblioteca de Procesamiento de Secuencias Semantic-TypeScript
+# **Semantic-TypeScript**
+**Flujos, Indexados.** Sus datos, bajo control preciso.
 
-## Introducción
+---
 
-Semantic-TypeScript es una biblioteca moderna de procesamiento de secuencias inspirada en la función generadora de JavaScript, Java Stream y el índice de MySQL. Su filosofía de diseño central se basa en construir pipelines eficientes de procesamiento de datos utilizando la indexación de datos, proporcionando una experiencia de operación de secuencia funcional con seguridad de tipos para el desarrollo del frontend.
+### Descripción general
 
-A diferencia del procesamiento sincrónico tradicional, Semantic emplea un modelo de procesamiento asíncrono. Al crear un flujo de datos, el tiempo en que el terminal recibe los datos depende completamente de cuándo el upstream llama a las funciones de devolución de llamada `accept` y `interrupt`. Este diseño permite que la biblioteca maneje elegantemente flujos de datos en tiempo real, grandes conjuntos de datos y fuentes de datos asíncronas.
+Semantic-TypeScript marca un avance significativo en la tecnología de procesamiento de flujos, **sintetizando** los conceptos más efectivos de `GeneratorFunction` de JavaScript, Java Streams e indexación de estilo MySQL. Su filosofía central es a la vez simple y poderosa: construir pipelines de procesamiento de datos excepcionalmente eficientes mediante indexación inteligente, no a través de iteración de fuerza bruta.
 
-## Instalación
+Donde las librerías convencionales imponen bucles síncronos o cadenas de promesas incómodas, Semantic-TypeScript ofrece una experiencia **completamente asíncrona**, funcionalmente pura y rigurosamente segura en tipos, diseñada para las demandas del desarrollo front-end moderno.
 
-```bash
-npm install semantic-typescript
-```
+En su modelo elegante, los datos solo llegan al consumidor cuando el pipeline ascendente invoca explícitamente las devoluciones de llamada `accept` (y, opcionalmente, `interrupt`). Usted tiene control total sobre el momento exacto en que se necesita.
 
-## Tipos Básicos
-
-| Tipo | Descripción |
-|------|-------------|
-| `Invalid<T>` | Tipo que extiende `null` o `undefined` |
-| `Valid<T>` | Tipo que excluye `null` y `undefined` |
-| `MaybeInvalid<T>` | Tipo que puede ser `null` o `undefined` |
-| `Primitive` | Colección de tipos primitivos |
-| `MaybePrimitive<T>` | Tipo que puede ser un tipo primitivo |
-| `OptionalSymbol` | Identificador de símbolo de la clase `Optional` |
-| `SemanticSymbol` | Identificador de símbolo de la clase `Semantic` |
-| `CollectorsSymbol` | Identificador de símbolo de la clase `Collector` |
-| `CollectableSymbol` | Identificador de símbolo de la clase `Collectable` |
-| `OrderedCollectableSymbol` | Identificador de símbolo de la clase `OrderedCollectable` |
-| `WindowCollectableSymbol` | Identificador de símbolo de la clase `WindowCollectable` |
-| `StatisticsSymbol` | Identificador de símbolo de la clase `Statistics` |
-| `NumericStatisticsSymbol` | Identificador de símbolo de la clase `NumericStatistics` |
-| `BigIntStatisticsSymbol` | Identificador de símbolo de la clase `BigIntStatistics` |
-| `UnorderedCollectableSymbol` | Identificador de símbolo de la clase `UnorderedCollectable` |
-
-## Interfaces Funcionales
-
-| Interfaz | Descripción |
-|-----------|-------------|
-| `Runnable` | Función sin parámetros y sin valor de retorno |  
-| `Supplier<R>` | Función sin parámetros que devuelve `R` |  
-| `Functional<T, R>` | Función de transformación de un solo parámetro |
-| `BiFunctional<T, U, R>` | Función de transformación de dos parámetros |
-| `TriFunctional<T, U, V, R>` | Función de transformación de tres parámetros |
-| `Predicate<T>` | Función de predicado de un solo parámetro |
-| `BiPredicate<T, U>` | Función de predicado de dos parámetros |
-| `TriPredicate<T, U, V>` | Función de predicado de tres parámetros |
-| `Consumer<T>` | Función de consumidor de un solo parámetro |
-| `BiConsumer<T, U>` | Función de consumidor de dos parámetros |
-| `TriConsumer<T, U, V>` | Función de consumidor de tres parámetros |
-| `Comparator<T>` | Función de comparación de dos parámetros |
-| `Generator<T>` | Función generadora (núcleo y base) |
+---
 
-```typescript
-// Ejemplos de uso de tipos
-let predicate: Predicate<number> = (n: number): boolean => n > 0;
-let mapper: Functional<string, number> = (text: string): number => text.length;
-let comparator: Comparator<number> = (a: number, b: number): number => a - b;
-```
-
-## Guardias de Tipo
-
-| Función | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------|------|------------|------------|
-| `validate<T>(t: MaybeInvalid<T>): t is T` | Valida que el valor no sea null ni undefined | O(1) | O(1) |
-| `invalidate<T>(t: MaybeInvalid<T>): t is null \| undefined` | Valida que el valor sea null o undefined | O(1) | O(1) |
-| `isBoolean(t: unknown): t is boolean` | Comprueba si es un booleano | O(1) | O(1) |
-| `isString(t: unknown): t is string` | Comprueba si es una cadena | O(1) | O(1) |
-| `isNumber(t: unknown): t is number` | Comprueba si es un número | O(1) | O(1) |
-| `isFunction(t: unknown): t is Function` | Comprueba si es una función | O(1) | O(1) |
-| `isObject(t: unknown): t is object` | Comprueba si es un objeto | O(1) | O(1) |
-| `isSymbol(t: unknown): t is symbol` | Comprueba si es un símbolo | O(1) | O(1) |
-| `isBigint(t: unknown): t is bigint` | Comprueba si es un BigInt | O(1) | O(1) |
-| `isPrimitive(t: unknown): t is Primitive` | Comprueba si es un tipo primitivo | O(1) | O(1) |
-| `isIterable(t: unknown): t is Iterable<unknown>` | Comprueba si es un objeto iterable | O(1) | O(1) |
-| `isOptional(t: unknown): t is Optional<unknown>` | Comprueba si es una instancia de Optional | O(1) | O(1) |
-| `isSemantic(t: unknown): t is Semantic<unknown>` | Comprueba si es una instancia de Semantic | O(1) | O(1) |
-| `isCollector(t: unknown): t is Collector<unknown, unknown, unknown>` | Comprueba si es una instancia de Collector | O(1) | O(1) |
-| `isCollectable(t: unknown): t is Collectable<unknown>` | Comprueba si es una instancia de Collectable | O(1) | O(1) |
-| `isOrderedCollectable(t: unknown): t is OrderedCollectable<unknown>` | Comprueba si es una instancia de OrderedCollectable | O(1) | O(1) |
-| `isWindowCollectable(t: unknown): t is WindowCollectable<unknown>` | Comprueba si es una instancia de WindowCollectable | O(1) | O(1) |
-| `isUnorderedCollectable(t: unknown): t is UnorderedCollectable<unknown>` | Comprueba si es una instancia de UnorderedCollectable | O(1) | O(1) |
-| `isStatistics(t: unknown): t is Statistics<unknown, number \| bigint>` | Comprueba si es una instancia de Statistics | O(1) | O(1) |
-| `isNumericStatistics(t: unknown): t is NumericStatistics<unknown>` | Comprueba si es una instancia de NumericStatistics | O(1) | O(1) |
-| `isBigIntStatistics(t: unknown): t is BigIntStatistics<unknown>` | Comprueba si es una instancia de BigIntStatistics | O(1) | O(1) |
-| `isPromise(t: unknown): t is Promise<unknown>` | Comprueba si es un objeto Promise | O(1) | O(1) |
-| `isAsync(t: unknown): t is AsyncFunction` | Comprueba si es una AsyncFunction | O(1) | O(1) |
-
-```typescript
-// Ejemplos de uso de guardias de tipo
-let value: unknown = "hello";
-
-if (isString(value)) {
-    console.log(value.length); // Seguro para tipos, value inferido como string
-}
-
-if (isOptional(someValue)) {
-    someValue.ifPresent((value): void => console.log(val));
-}
-
-if(isIterable(value)){
-    // Seguro para tipos, ahora es un objeto iterable.
-    for(let item of value){
-        console.log(item);
-    }
-}
-```
+### Por qué los desarrolladores lo prefieren
 
-## Funciones Utilitarias
+-   **Indexación Cero-Boilerplate** — cada elemento lleva su índice natural o personalizado.
+-   **Estilo Puramente Funcional** — con inferencia completa de TypeScript.
+-   **Flujos de Eventos a Prueba de Fugas** — `useWindow`, `useDocument`, `useHTMLElement` y `useWebSocket` están construidos con la seguridad en mente. Usted define el límite (usando `limit(n)`, `sub(start, end)` o `takeWhile(predicate)`) y la librería gestiona la limpieza. Sin oyentes persistentes, sin fugas de memoria.
+-   **Estadísticas Integradas** — análisis numérico y de bigint integral que incluye promedios, medianas, modas, varianza, asimetría y curtosis.
+-   **Rendimiento Predecible** — elija entre recolectores ordenados o desordenados según sus requisitos.
+-   **Eficiencia de Memoria** — los flujos se evalúan de forma perezosa, aliviando las preocupaciones de memoria.
+-   **Sin Comportamiento Indefinido** — TypeScript garantiza seguridad de tipos y nulabilidad. Los datos de entrada permanecen sin modificar a menos que se alteren explícitamente dentro de sus funciones de devolución de llamada.
 
-| Función | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------|------|------------|------------|
-| `useCompare<T>(t1: T, t2: T): number` | Función de comparación genérica | O(1) | O(1) |
-| `useRandom<T = number \| bigint>(index: T): T` | Generador de números pseudoaleatorios | O(log n) | O(1) |
+---
 
-```typescript
-// Ejemplos de uso de funciones utilitarias
-let numbers: Array<number> = [3, 1, 4, 1, 5];
-numbers.sort(useCompare); // [1, 1, 3, 4, 5]
+### Instalación
 
-let randomNum = useRandom(42); // Número aleatorio basado en semilla
+```bash
+npm install semantic-typescript
+```
+o
+```bash
+yarn add semantic-typescript
 ```
 
-## Métodos de Fábrica
-
-### Métodos de Fábrica de Optional
+---
 
-| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------|------|------------|------------|
-| `Optional.empty<T>()` | Crea un Optional vacío | O(1) | O(1) |
-| `Optional.of<T>(value)` | Crea un Optional que contiene un valor | O(1) | O(1) |
-| `Optional.ofNullable<T>(value)` | Crea un Optional que podría estar vacío | O(1) | O(1) |
-| `Optional.ofNonNull<T>(value)` | Crea un Optional que no está vacío | O(1) | O(1) |
+### Comienzo rápido
 
 ```typescript
-// Ejemplos de uso de Optional
-let empty: Optional<number> = Optional.empty();
-let present: Optional<number> = Optional.of(42);
-let nullable: Optional<string> = Optional.ofNullable<string>(null);
-let nonNull: Optional<string> = Optional.ofNonNull("hello");
-
-present.ifPresent((val: number): void => console.log(val)); // Salida: 42
-console.log(emptyOpt.get(100)); // Salida: 100
+import { useOf, useFrom, useRange, useWindow, useHTMLElement, useWebSocket, useText, useStringify } from "semantic-typescript";
+
+// Estadísticas numéricas
+let summate: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)
+  .toNumericStatistics()  // Requerido antes de la operación terminal
+  .summate();             // 200
+
+// Estadísticas de BigInt
+let summate: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2)
+  .toBigIntStatistics()   // Requerido antes de la operación terminal
+  .summate();             // 200n
+
+// Invertir un flujo por índice
+useFrom([1, 2, 3, 4, 5])
+  .redirect((element: E, index: bigint): bigint => -index) // Índice negativo para inversión
+  .toOrdered() // Llamar a toOrdered() para preservar el orden del índice
+  .toArray(); // [5, 4, 3, 2, 1]
+
+// Mezclar un flujo
+useFrom([1, 2, 3, 4, 5])
+  .shuffle()
+  .toOrdered()
+  .toArray(); // ej., [2, 5, 1, 4, 3]
+
+// Trasladar elementos dentro de un flujo
+useFrom([1, 2, 3, 4, 5])
+  .translate(2)  // Desplazar elementos 2 posiciones a la derecha
+  .toOrdered()
+  .toArray(); // [4, 5, 1, 2, 3]
+
+useFrom([1, 2, 3, 4, 5])
+  .translate(-2) // Desplazar elementos 2 posiciones a la izquierda
+  .toOrdered()
+  .toArray(); // [3, 4, 5, 1, 2]
+
+// Rango infinito con terminación temprana
+useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)
+  .limit(10n)          // Detenerse después de 10 elementos
+  .toUnordered()
+  .toArray();
+
+// Redimensión de ventana en tiempo real (se detiene automáticamente tras 5 eventos)
+useWindow("resize")
+  .limit(5n)          // Crucial para flujos de eventos
+  .toUnordered()
+  .forEach((ev, idx) => console.log(`Redimensión #${idx}`));
+
+// Escuchar un elemento HTML
+// <input id="input" type="text"/>
+useHTMLElement("#input", "change")
+  .limit(1)
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
+
+// Escuchar múltiples elementos y eventos
+useHTMLElement("input", ["change", "keyup"])
+  .takeWhile((event: Event): boolean => validate(event))
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
+
+// Escuchar un WebSocket
+let webSocket = new WebSocket("ws://localhost:8080");
+webSocket.addEventListener("close", (): void => {
+  webSocket.close();  // Gestionar el ciclo de vida del WebSocket manualmente
+});
+useWebSocket(webSocket, "message")
+  .limit(1)
+  .toUnordered()
+  .forEach((message: MessageEvent) => console.log(message.data));
+
+// Iterar sobre una cadena por punto de código
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // Imprime la cadena
+
+// Convertir a cadena de forma segura un objeto con referencias circulares
+let o = {
+  a: 1,
+  b: "text",
+  c: [o.a, o.b, o.c] // Referencia circular
+};
+// let text: string = JSON.stringify(o); // Lanza un error
+let text: string = useStringify(o); // Produce de forma segura `{a: 1, b: "text", c: []}`
 ```
 
-### Métodos de Fábrica de Collector
+---
 
-| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------|------|------------|------------|
-| `Collector.full(identity, accumulator, finisher)` | Crea un Collector completo | O(1) | O(1) |
-| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Crea un Collector interrumpible | O(1) | O(1) |
+### Conceptos centrales
 
-```typescript
-// Ejemplos de conversión de Collector
-let numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
-
-// Prioridad de rendimiento: usa un Collector no ordenado para obtener el mejor rendimiento
-let unordered = numbers
-    .filter((n: number): boolean => n > 3)
-    .toUnordered(); // Mejor rendimiento
-
-// Necesita ordenación: usa un Collector ordenado
-let ordered = numbers.sorted();
-
-// Operaciones de recuento de elementos
-let count = Collector.full(
-    (): number => 0, // Valor inicial
-    (accumulator: number, element: number): number => accumulator + element, // Acumular
-    (accumulator: number): number => accumulator // Finalizar
-);
-count.collect(from([1, 2, 3, 4, 5])); // Recuento desde un flujo
-count.collect([1, 2, 3, 4, 5]); // Recuento desde un objeto iterable
-
-let find = Collector.shortable(
-    (): Optional<number> => Optional.empty(), // Valor inicial
-    (element: number, index: bigint, accumulator: Optional<number>): Optional<number> => accumulator.isPresent(), // Interrumpir
-    (accumulator: Optional<number>, element: number, index: bigint): Optional<number> => Optional.of(element), // Acumular
-    (accumulator: Optional<number>): Optional<number> => accumulator // Finalizar
-);
-find.collect(from([1, 2, 3, 4, 5])); // Encuentra el primer elemento
-find.collect([1, 2, 3, 4, 5]); // Encuentra el primer elemento
-```
+| Concepto | Propósito | Cuándo usarlo |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | Constructor central para flujos asíncronos, eventos y pipelines perezosos. | Eventos en tiempo real, WebSockets, oyentes DOM, flujos de larga duración o infinitos. |
+| `SynchronousSemantic` | Constructor para flujos síncronos, en memoria o basados en bucle. | Datos estáticos, rangos, iteración inmediata. |
+| `toUnordered()` | Recolector terminal más rápido (indexación basada en Map). | Rutas críticas de rendimiento (tiempo y espacio O(n), sin ordenación). |
+| `toOrdered()` | Recolector ordenado, estable en índices. | Cuando se requiere orden estable o acceso indexado. |
+| `toNumericStatistics()` | Análisis estadístico numérico rico (media, mediana, varianza, asimetría, curtosis, etc.). | Análisis de datos y cálculos estadísticos. |
+| `toBigIntStatistics()` | Análisis estadístico de bigint. | Análisis de datos y cálculos estadísticos para enteros grandes. |
+| `toWindow()` | Soporte para ventanas deslizantes y fijas. | Procesamiento de series temporales, procesamiento por lotes y operaciones con ventanas. |
 
-### Métodos de Fábrica de Semantic
+---
 
-| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------|------|------------|------------|
-| `animationFrame(period: number, delay: number = 0)` | Crea un flujo de fotogramas de animación basado en tiempo | O(1)* | O(1) |
-| `blob(blob, chunkSize)` | Crea un flujo a partir de un Blob | O(n) | O(chunkSize) |
-| `empty<E>()` | Crea un flujo vacío | O(1) | O(1) |
-| `fill<E>(element, count)` | Crea un flujo lleno | O(n) | O(1) |
-| `from<E>(iterable)` | Crea un flujo a partir de un objeto iterable | O(1) | O(1) |
-| `interval(period, delay?)` | Crea un flujo de intervalo de tiempo | O(1)* | O(1) |
-| `iterate<E>(generator)` | Crea un flujo a partir de un generador | O(1) | O(1) |
-| `range(start, end, step)` | Crea un flujo de rango numérico | O(n) | O(1) |
-| `websocket(websocket)` | Crea un flujo a partir de un WebSocket | O(1) | O(1) |
+**Reglas de uso importantes**
 
-```typescript
-// Ejemplos de métodos de fábrica de Semantic
-
-// Crea un flujo a partir de un Blob (lectura por partes)
-blob(someBlob, 1024n)
-    .toUnordered()
-    .write(WritableStream)
-    .then(callback) // Escritura del flujo exitosa
-    .catch(callback); // Escritura del flujo fallida
-
-// Crea un flujo vacío, no se ejecutará hasta concatenarse con otros flujos
-empty<string>()
-    .toUnordered()
-    .join(); // []
-
-// Crea un flujo lleno
-const filledStream = fill("hello", 3); // "hello", "hello", "hello"
-
-// Crea un flujo de intervalo con un retraso inicial de 2 segundos y un período de ejecución de 5 segundos, implementado sobre un mecanismo de temporizador; puede experimentar deriva temporal debido a las limitaciones de precisión de la programación del sistema.
-const intervalStream = interval(5000, 2000);
-
-// Crea un flujo a partir de un objeto iterable
-const numberStream = from([1, 2, 3, 4, 5]);
-const stringStream = from(new Set(["Alex", "Bob"]));
-
-// Crea un flujo de rango
-const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
-
-// Flujo de eventos WebSocket
-const ws = new WebSocket("ws://localhost:8080");
-websocket(ws)
-  .filter((event): boolean => event.type === "message") // Solo escucha eventos de mensaje
-  .toUnordered() // Los eventos generalmente no están ordenados
-  .forEach((event): void => receive(event)); // Recibe mensajes
-```
+1.  **Flujos de eventos** (`useWindow`, `useDocument`, `useHTMLElement`, `useWebSocket`, …) devuelven un `AsynchronousSemantic`.
+    → **Debe** llamar a `.limit(n)`, `.sub(start, end)` o `.takeWhile()` para dejar de escuchar. De lo contrario, el oyente permanece activo.
 
-## Métodos de Clase Semantic
-
-| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------|------|------------|------------|
-| `concat(other)` | Concatena dos flujos | O(n) | O(1) |
-| `distinct()` | Elimina duplicados | O(n) | O(n) |
-| `distinct(comparator)` | Elimina duplicados usando un comparador | O(n²) | O(n) |
-| `dropWhile(predicate)` | Descarta elementos que satisfacen la condición | O(n) | O(1) |
-| `filter(predicate)` | Filtra elementos | O(n) | O(1) |
-| `flat(mapper)` | Aplicación plana de mapa | O(n × m) | O(1) |
-| `flatMap(mapper)` | Aplicación plana de mapa a un nuevo tipo | O(n × m) | O(1) |
-| `limit(n)` | Limita el número de elementos | O(n) | O(1) |
-| `map(mapper)` | Transformación de asignación | O(n) | O(1) |
-| `peek(consumer)` | Mirar elementos | O(n) | O(1) |
-| `redirect(redirector)` | Redirigir índice | O(n) | O(1) |
-| `reverse()` | Invierte el flujo | O(n) | O(1) |
-| `shuffle()` | Mezcla al azar | O(n) | O(1) |
-| `shuffle(mapper)` | Mezcla usando un mapeador | O(n) | O(1) |
-| `skip(n)` | Omite los primeros n elementos | O(n) | O(1) |
-| `sorted()` | Ordena | O(n log n) | O(n) |
-| `sorted(comparator)` | Ordena usando un comparador | O(n log n) | O(n) |
-| `sub(start, end)` | Obtiene un subflujo | O(n) | O(1) |
-| `takeWhile(predicate)` | Obtiene elementos que satisfacen la condición | O(n) | O(1) |
-| `translate(offset)` | Traduce índice | O(n) | O(1) |
-| `translate(translator)` | Traduce índice usando un traductor | O(n) | O(1) |
+2.  **Operaciones terminales** (`.toArray()`, `.count()`, `.average()`, `.reduce()`, `.findFirst()`, etc.) **solo están disponibles después** de la conversión a un recolector:
+    ```typescript
+    .toUnordered()   // Tiempo y espacio O(n), sin ordenación
+    // o
+    .toOrdered()     // Ordenado, mantiene el orden
+    ```
 
-```typescript
-// Ejemplos de operaciones Semantic
-const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .filter((n: number): boolean => n % 2 === 0) // Filtra números pares
-    .map((n: number): number => n * 2) // Multiplica por 2
-    .skip(1) // Omite el primero
-    .limit(3) // Limita a 3 elementos
-    .toUnordered() // Convierte a un colector no ordenado
-    .toArray(); // Convierte a arreglo
-// Resultado: [8, 12, 20]
-
-// Ejemplo de operación compleja
-const complexResult = range(1, 100, 1)
-    .flatMap((n: number): Semantics<number> => from([n, n * 2])) // Asigna cada elemento a dos
-    .distinct() // Elimina duplicados
-    .shuffle() // Mezcla el orden
-    .takeWhile((n: number): boolean => n < 50) // Toma elementos menores que 50
-    .toOrdered() // Convierte a un colector ordenado
-    .toArray(); // Convierte a arreglo
-```
+---
 
-## Métodos de Conversión Semantic
+### Características de rendimiento
 
-| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------------|------------|------------|------------|
-| `sorted()` | Convierte a un colector ordenado | O(n log n) | O(n) |
-| `toUnordered()` | Convierte a un colector no ordenado | O(1) | O(1) |
-| `toOrdered()` | Convierte a un colector ordenado | O(1) | O(1) |
-| `toNumericStatistics()` | Convierte a estadísticas numéricas | O(n) | O(1) |
-| `toBigintStatistics()` | Convierte a estadísticas BigInt | O(n) | O(1) |
-| `toWindow()` | Convierte a un colector de ventana | O(1) | O(1) |
-| `toCollectable()` | Convierte a `UnorderdCollectable` | O(n) | O(1) |
-| `toCollectable(mapper)` | Convierte a un colector personalizado | O(n) | O(1) |
+| Recolector | Complejidad Temporal | Complejidad Espacial | ¿Ordenado? | Mejor para |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | No | Velocidad bruta, orden no requerido. |
+| `toOrdered()` | O(2n) | O(n) | Sí | Orden estable, acceso indexado, análisis. |
+| `toNumericStatistics()` | O(2n) | O(n) | Sí | Operaciones estadísticas que requieren datos ordenados. |
+| `toBigIntStatistics()` | O(2n) | O(n) | Sí | Operaciones estadísticas para bigint. |
+| `toWindow()` | O(2n) | O(n) | Sí | Operaciones de ventana basadas en tiempo. |
 
-```typescript
-// Convierte a un arreglo ordenado ascendente
-from([6, 4, 3, 5, 2]) // Crea un flujo
-    .sorted() // Ordena el flujo en orden ascendente
-    .toArray(); // [2, 3, 4, 5, 6]
-
-// Convierte a un arreglo ordenado descendente
-from([6, 4, 3, 5, 2]) // Crea un flujo
-    .soted((a: number, b: number): number => b - a) // Ordena el flujo en orden descendente
-    .toArray(); // [6, 5, 4, 3, 2]
-
-// Redirige a un arreglo invertido
-from([6, 4, 3, 5, 2])
-    .redirect((element, index): bigint => -index) // Redirige a orden inverso
-    .toOrderd() // Mantiene el orden redirigido
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// Ignora las redirecciones para invertir el arreglo
-from([6, 4, 3, 5, 2])
-    .redirect((element, index): bigint => -index) // Redirige a orden inverso
-    .toUnorderd() // Descarta el orden redirigido. Esta operación ignorará `redirect`, `reverse`, `shuffle` y `translate`
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// Invierte el flujo en un arreglo
-from([6, 4, 3, 5, 2])
-    .reverse() // Invierte el flujo
-    .toOrdered() // Garantiza el orden invertido
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// Sobrescribe el flujo mezclado en un arreglo
-from([6, 4, 3, 5, 2])
-    .shuffle() // Mezcla el flujo
-    .sorted() // Sobrescribe el orden mezclado. Esta operación sobrescribirá `redirect`, `reverse`, `shuffle` y `translate`
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// Convierte a un colector de ventana
-from([6, 4, 3, 5, 2])
-    .toWindow(); // Convierte a estadísticas numéricas
-
-from([6, 4, 3, 5, 2])
-    .toNumericStatistics(); // Convierte a estadísticas BigInt
-
-from([6n, 4n, 3n, 5n, 2n])
-    .toBigintStatistics(); // Define un colector personalizado para recopilar datos
-
-let customizedCollector = from([1, 2, 3, 4, 5])
-    .toCollectable((generator: Generator<E>) => new CustomizedCollector(generator));
-```
+Opte por `toUnordered()` cuando la velocidad sea primordial. Use `toOrdered()` solo cuando necesite un orden estable o métodos estadísticos que dependan de datos ordenados.
 
-## Métodos de Recolección Collectable
-
-| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------|------|------------|------------|
-| `anyMatch(predicate)` | Si algún elemento coincide | O(n) | O(1) |
-| `allMatch(predicate)` | Si todos los elementos coinciden | O(n) | O(1) |
-| `count()` | Recuento de elementos | O(n) | O(1) |
-| `isEmpty()` | Si está vacío | O(1) | O(1) |
-| `findAny()` | Encuentra cualquier elemento | O(n) | O(1) |
-| `findFirst()` | Encuentra el primer elemento | O(n) | O(1) |
-| `findLast()` | Encuentra el último elemento | O(n) | O(1) |
-| `forEach(action)` | Itera sobre todos los elementos | O(n) | O(1) |
-| `group(classifier)` | Agrupa por clasificador | O(n) | O(n) |
-| `groupBy(keyExtractor, valueExtractor)` | Agrupa por extracción de clave-valor | O(n) | O(n) |
-| `join()` | Únete como cadena | O(n) | O(n) |
-| `join(delimiter)` | Únete usando un delimitador | O(n) | O(n) |
-| `nonMatch(predicate)` | Si ningún elemento coincide | O(n) | O(1) |
-| `partition(count)` | Particionar por recuento | O(n) | O(n) |
-| `partitionBy(classifier)` | Particionar por clasificador | O(n) | O(n) |
-| `reduce(accumulator)` | Operación de reducción | O(n) | O(1) |
-| `reduce(identity, accumulator)` | Reducción con valor inicial | O(n) | O(1) |
-| `toArray()` | Convierte a arreglo | O(n) | O(n) |
-| `toMap(keyExtractor, valueExtractor)` | Convierte a Map | O(n) | O(n) |
-| `toSet()` | Convierte a Set | O(n) | O(n) |
-| `write(stream)` | Escribe en el flujo | O(n) | O(1) |
+---
 
-```typescript
-// Ejemplos de operaciones Collectable
-const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .filter((n: number): boolean => n % 2 === 0)
-    .toOrdered();
-
-// Comprobaciones de coincidencia
-console.log(data.anyMatch((n: number): boolean => n > 5)); // true
-console.log(data.allMatch((n: number): boolean => n < 20)); // true
-
-// Operaciones de búsqueda
-data.findFirst().ifPresent((n: number): void => console.log(n)); // 2
-data.findAny().ifPresent((n: number): void => console.log(n)); // Cualquier elemento
-
-// Operaciones de agrupación
-const grouped = data.groupBy(
-    (n: number): string => (n > 5 ? "grande" : "pequeño"),
-    (n: number): number => n * 2
-); // {pequeño: [4, 8], grande: [12, 16, 20]}
-
-// Operaciones de reducción
-const sum = data.reduce(0, (acc, n) => acc + n); // 30
-
-// Operaciones de salida
-data.join(", "); // "[2, 4, 6, 8, 10]"
-```
+**Comparación con otros procesadores de flujo para Front-End**
 
-## Métodos de Análisis Estadístico
-
-### Métodos de NumericStatistics
-
-| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
-|------|------|------------|------------|
-| `range()` | Rango | O(n) | O(1) |
-| `variance()` | Varianza | O(n) | O(1) |
-| `standardDeviation()` | Desviación estándar | O(n) | O(1) |
-| `mean()` | Media | O(n) | O(1) |
-| `median()` | Mediana | O(n log n) | O(n) |
-| `mode()` | Moda | O(n) | O(n) |
-| `frequency()` | Distribución de frecuencia | O(n) | O(n) |
-| `summate()` | Suma | O(n) | O(1) |
-| `quantile(quantile)` | Cuantil | O(n log n) | O(n) |
-| `interquartileRange()` | Rango intercuartílico | O(n log n) | O(n) |
-| `skewness()` | Sesgo | O(n) | O(1) |
-| `kurtosis()` | Curtosis | O(n) | O(1) |
+| Característica | Semantic-TypeScript | RxJS | Iteradores/Generadores Asíncronos Nativos | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **Integración con TypeScript** | De primer nivel, profundamente tipado con consciencia nativa de índices. | Excelente, pero involucra genéricos complejos. | Buena, requiere tipado manual. | Estilo funcional fuerte. |
+| **Análisis Estadístico Integrado** | Soporte nativo integral para `number` y `bigint`. | No disponible de forma nativa (requiere operadores personalizados). | Ninguno. | Ninguno. |
+| **Indexación y Conciencia de Posición** | Indexación nativa y potente de bigint en cada elemento. | Requiere operadores personalizados (`scan`, `withLatestFrom`). | Se requiere contador manual. | Básica, sin índice incorporado. |
+| **Gestión de Flujos de Eventos** | Fábricas dedicadas y seguras en tipos con control explícito de parada temprana. | Potente pero requiere gestión manual de suscripciones. | Oyente de eventos manual + cancelación. | Buena `fromEvent`, ligero. |
+| **Rendimiento y Eficiencia de Memoria** | Excepcional – recolectores optimizados `toUnordered()` y `toOrdered()`. | Muy buena, pero las cadenas de operadores añaden sobrecarga. | Excelente (sobrecarga cero). | Excelente. |
+| **Tamaño del Paquete** | Muy ligero. | Grande (incluso con tree-shaking). | Cero (nativo). | Pequeño. |
+| **Filosofía de Diseño de API** | Patrón de recolector funcional con indexación explícita. | Patrón Observable Reactivo. | Patrón Iterador / Generador. | Funcional, point-free. |
+| **Terminación Temprana y Control** | Explícito (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | Bueno (`take`, `takeUntil`, `first`). | Manual (`break` en `for await…of`). | Bueno (`take`, `until`). |
+| **Soporte Síncrono y Asíncrono** | API unificada – soporte de primer nivel para ambos. | Principalmente asíncrono. | Ambos, pero manual. | Principalmente asíncrono. |
+| **Curva de Aprendizaje** | Suave para desarrolladores familiarizados con pipelines funcionales e indexados. | Más pronunciada (muchos operadores, observables fríos/calientes). | Baja. | Moderada. |
 
-```typescript
-// Ejemplos de análisis estadístico
-const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .toNumericStatistics();
-
-console.log("Media:", numbers.mean()); // 5.5
-console.log("Mediana:", numbers.median()); // 5.5
-console.log("Desviación estándar:", numbers.standardDeviation()); // ~2.87
-console.log("Suma:", numbers.summate()); // 55
-
-// Análisis estadístico utilizando mappers
-const objects = from([
-    { value: 10 },
-    { value: 20 },
-    { value: 30 }
-]).toNumericStatistics();
-console.log("Media mapeada:", objects.mean(obj => obj.value)); // 20
-```
+**Ventajas clave de Semantic-TypeScript**
 
-## Guía de Selección de Rendimiento
+*   Capacidades únicas de estadística e indexación integradas, eliminando la necesidad de `reduce` manual o librerías externas.
+*   Control explícito sobre los flujos de eventos previene las fugas de memoria comunes en RxJS.
+*   Un diseño síncrono/asíncrono unificado proporciona una única API consistente para diversos casos de uso.
 
-### Elija un Colector No Ordenado (Rendimiento Primero)
-```typescript
-// Cuando no se necesita garantizar el orden, use un colector no ordenado para obtener el mejor rendimiento
-let highPerformance = data
-    .filter(predicate)
-    .map(mapper)
-    .toUnordered(); // Mejor rendimiento
-```
+Esta comparación ilustra por qué Semantic-TypeScript es particularmente adecuado para aplicaciones front-end modernas con TypeScript que exigen rendimiento, seguridad de tipos y análisis ricos sin la ceremonia de las librerías reactivas tradicionales.
 
-### Elija un Colector Ordenado (Se Requiere Orden)
-```typescript
-// Cuando se necesita mantener el orden de los elementos, use un colector ordenado
-let ordered = data.sorted(comparator);
-```
+---
 
-### Elija un Colector de Ventana (Operaciones de Ventana)
-```typescript
-// Cuando se necesitan operaciones de ventana
-let windowed: WindowCollectable<number> = data
-    .toWindow()
-    .slide(5n, 2n); // Ventana deslizante
-```
+### ¿Listo para explorar?
 
-### Elija un Análisis Estadístico (Cálculos Numéricos)
-```typescript
-// Cuando se necesita un análisis estadístico
-let statistics: NumericStatistics<number> = data
-    .toNumericStatistics(); // Estadísticas numéricas
+Semantic-TypeScript transforma flujos de datos complejos en pipelines legibles, componibles y de alto rendimiento. Ya sea que esté manejando eventos de UI en tiempo real, procesando grandes conjuntos de datos o construyendo paneles de análisis, proporciona el poder de la indexación a nivel de base de datos con la elegancia de la programación funcional.
 
-let bigIntStatistics: BigintStatistics<bigint> = data
-    .toBigintStatistics(); // Estadísticas de enteros grandes
-```
+**Próximos pasos:**
 
-[GitHub](https://github.com/eloyhere/semantic-typescript)
-[NPMJS](https://www.npmjs.com/package/semantic-typescript)
+*   Explore la API completamente tipada en su IDE (todas las exportaciones son del paquete principal).
+*   Únase a la creciente comunidad de desarrolladores que han reemplazado iteradores asíncronos complejos con pipelines Semantic limpios.
 
-## Notas Importantes
+**Semantic-TypeScript** — donde los flujos se encuentran con la estructura.
 
-1. **Impacto de las Operaciones de Ordenación**: En colectores ordenados, la operación `sorted()` invalida los efectos de `redirect`, `translate`, `shuffle`, `reverse`.
-2. **Consideraciones de Rendimiento**: Si no se necesita garantizar el orden, priorice el uso de `toUnordered()` para un mejor rendimiento.
-3. **Uso de Memoria**: Las operaciones de ordenación requieren espacio adicional de O(n).
-4. **Datos en Tiempo Real**: Los flujos Semantic son adecuados para procesar datos en tiempo real y admiten fuentes de datos asíncronas.
+Comience a construir hoy y experimente la diferencia que proporciona una indexación bien pensada.
 
-Esta biblioteca proporciona a los desarrolladores de TypeScript capacidades de streaming poderosas y flexibles, combinando los beneficios de la programación funcional con garantías de seguridad de tipos.
+**Construya con claridad, proceda con confianza y transforme los datos con intención.**