semantic-typescript 0.0.8 → 0.1.4

package/readme.es.md

@@ -1,529 +1,428 @@
-# Framework de Procesamiento de Flujos Semantic-TypeScript
+# Biblioteca de Procesamiento de Flujos Semantic-TypeScript
 
 ## Introducción
 
-Semantic-TypeScript es una librería moderna de procesamiento de flujos inspirada en GeneratorFunction de JavaScript, Java Stream e Índices de MySQL. La filosofía de diseño central se basa en construir pipelines eficientes de procesamiento de datos mediante indexación de datos, proporcionando una experiencia de operación de streaming en estilo funcional y type-safe para el desarrollo frontend.
+Semantic-TypeScript es una biblioteca moderna de procesamiento de flujos inspirada en JavaScript GeneratorFunction, Java Stream y MySQL Index. El diseño central de la biblioteca se basa en la construcción de pipelines eficientes de procesamiento de datos utilizando índices de datos, proporcionando a los desarrolladores frontend una experiencia de operación de flujos con seguridad de tipos y estilo funcional.
 
-A diferencia del procesamiento sincrónico tradicional, Semantic emplea un modelo de procesamiento asíncrono. Al crear flujos de datos, el momento de recepción de datos terminales depende completamente de cuándo la corriente superior llama a las funciones callback `accept` e `interrupt`. Este diseño permite que la librería maneje elegantemente flujos de datos en tiempo real, grandes conjuntos de datos y fuentes de datos asíncronas.
+A diferencia del procesamiento sincrónico tradicional, Semantic adopta un modo de procesamiento asincrónico. Al crear flujos de datos, el momento en que el terminal recibe los datos depende completamente de cuándo la fuente ascendente llama a las funciones de callback `accept` e `interrupt`. Este diseño permite que la biblioteca maneje elegantemente flujos de datos en tiempo real, conjuntos de datos grandes y fuentes de datos asincrónicas.
 
-## Características Principales
+## Instalación
 
-| Característica | Descripción | Ventaja |
-|------|------|------|
-| **Genéricos Type-Safe** | Soporte completo de tipos TypeScript | Detección de errores en tiempo de compilación, mejor experiencia de desarrollo |
-| **Programación Funcional** | Estructuras de datos inmutables y funciones puras | Código más predecible, más fácil de probar y mantener |
-| **Evaluación Perezosa** | Cálculo bajo demanda, optimización de rendimiento | Alta eficiencia de memoria al procesar grandes conjuntos de datos |
-| **Procesamiento Asíncrono de Flujos** | Flujos de datos asíncronos basados en generadores | Adecuado para datos en tiempo real y escenarios orientados a eventos |
-| **Colectores Multi-Paradigma** | Estrategias de recolección ordenadas, desordenadas y estadísticas | Selección de estrategia óptima basada en diferentes escenarios |
-| **Análisis Estadístico** | Funciones completas integradas de cálculo estadístico | Generación integrada de análisis de datos e informes |
-
-## Consideraciones de Rendimiento
-
-**Nota Importante**: Los siguientes métodos sacrifican rendimiento para recolectar y ordenar datos, resultando en colecciones de datos ordenadas:
-- `toOrdered()`
-- `toWindow()`
-- `toNumericStatistics()`
-- `toBigIntStatistics()`
-- `sorted()`
-- `sorted(comparator)`
-
-Especialmente importante notar: `sorted()` y `sorted(comparator)` anularán los resultados de los siguientes métodos:
-- `redirect(redirector)`
-- `translate(translator)` 
-- `shuffle(mapper)`
-
-## Métodos de Fábrica
-
-### Fábricas de Creación de Flujos
+```bash
+npm install semantic-typescript
+```
 
-| Método | Firma | Descripción | Ejemplo |
-|------|------|------|------|
-| `blob` | `(blob: Blob, chunk?: bigint) => Semantic<Uint8Array>` | Convertir Blob a flujo de bytes | `blob(fileBlob, 1024n)` |
-| `empty` | `<E>() => Semantic<E>` | Crear flujo vacío | `empty<number>()` |
-| `fill` | `<E>(element: E, count: bigint) => Semantic<E>` | Llenar con número especificado de elementos | `fill("hello", 5n)` |
-| `from` | `<E>(iterable: Iterable<E>) => Semantic<E>` | Crear flujo desde objeto iterable | `from([1, 2, 3])` |
-| `range` | `<N extends number\|bigint>(start: N, end: N, step?: N) => Semantic<N>` | Crear flujo de rango numérico | `range(1, 10, 2)` |
-| `iterate` | `<E>(generator: Generator<E>) => Semantic<E>` | Crear flujo desde función generadora | `iterate(myGenerator)` |
-| `websocket` | `(websocket: WebSocket) => Semantic<MessageEvent>` | Crear flujo de eventos desde WebSocket | `websocket(socket)` |
+## 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 primitivo |
+| `OptionalSymbol` | Identificador simbólico para la clase Optional |
+| `SemanticSymbol` | Identificador simbólico para la clase Semantic |
+| `CollectorsSymbol` | Identificador simbólico para la clase Collector |
+| `CollectableSymbol` | Identificador simbólico para la clase Collectable |
+| `OrderedCollectableSymbol` | Identificador simbólico para la clase OrderedCollectable |
+| `WindowCollectableSymbol` | Identificador simbólico para la clase WindowCollectable |
+| `StatisticsSymbol` | Identificador simbólico para la clase Statistics |
+| `NumericStatisticsSymbol` | Identificador simbólico para la clase NumericStatistics |
+| `BigIntStatisticsSymbol` | Identificador simbólico para la clase BigIntStatistics |
+| `UnorderedCollectableSymbol` | Identificador simbólico para la clase UnorderedCollectable |
+| `Runnable` | Función sin parámetros ni valor de retorno |
+| `Supplier<R>` | Función sin parámetros que retorna R |
+| `Functional<T, R>` | Función de transformación de un parámetro |
+| `Predicate<T>` | Función de predicado de un parámetro |
+| `BiFunctional<T, U, R>` | Función de transformación de dos parámetros |
+| `BiPredicate<T, U>` | Función de predicado de dos parámetros |
+| `Comparator<T>` | Función de comparación |
+| `TriFunctional<T, U, V, R>` | Función de transformación de tres parámetros |
+| `Consumer<T>` | Función consumidora de un parámetro |
+| `BiConsumer<T, U>` | Función consumidora de dos parámetros |
+| `TriConsumer<T, U, V>` | Función consumidora de tres parámetros |
+| `Generator<T>` | Función generadora |
 
-**Suplemento de Ejemplo de Código:**
 ```typescript
-import { from, range, fill, empty } from 'semantic-typescript';
-
-// Crear flujo desde array
-const numberStream = from([1, 2, 3, 4, 5]);
-
-// Crear flujo de rango numérico
-const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
-
-// Llenar con elementos repetidos
-const filledStream = fill("hello", 3n); // "hello", "hello", "hello"
-
-// Crear flujo vacío
-const emptyStream = empty<number>();
+// Ejemplos de uso de tipos
+const predicate: Predicate<number> = (n) => n > 0;
+const mapper: Functional<string, number> = (str) => str.length;
+const comparator: Comparator<number> = (a, b) => a - b;
 ```
 
-### Fábricas de Funciones de Utilidad
+## 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 o 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` | Verifica si es booleano | O(1) | O(1) |
+| `isString(t: unknown): t is string` | Verifica si es string | O(1) | O(1) |
+| `isNumber(t: unknown): t is number` | Verifica si es número | O(1) | O(1) |
+| `isFunction(t: unknown): t is Function` | Verifica si es función | O(1) | O(1) |
+| `isObject(t: unknown): t is object` | Verifica si es objeto | O(1) | O(1) |
+| `isSymbol(t: unknown): t is symbol` | Verifica si es símbolo | O(1) | O(1) |
+| `isBigint(t: unknown): t is bigint` | Verifica si es BigInt | O(1) | O(1) |
+| `isPrimitive(t: unknown): t is Primitive` | Verifica si es tipo primitivo | O(1) | O(1) |
+| `isIterable(t: unknown): t is Iterable<unknown>` | Verifica si es iterable | O(1) | O(1) |
+| `isOptional(t: unknown): t is Optional<unknown>` | Verifica si es instancia de Optional | O(1) | O(1) |
+| `isSemantic(t: unknown): t is Semantic<unknown>` | Verifica si es instancia de Semantic | O(1) | O(1) |
+| `isCollector(t: unknown): t is Collector<unknown, unknown, unknown>` | Verifica si es instancia de Collector | O(1) | O(1) |
+| `isCollectable(t: unknown): t is Collectable<unknown>` | Verifica si es instancia de Collectable | O(1) | O(1) |
+| `isOrderedCollectable(t: unknown): t is OrderedCollectable<unknown>` | Verifica si es instancia de OrderedCollectable | O(1) | O(1) |
+| `isWindowCollectable(t: unknown): t is WindowCollectable<unknown>` | Verifica si es instancia de WindowCollectable | O(1) | O(1) |
+| `isUnorderedCollectable(t: unknown): t is UnorderedCollectable<unknown>` | Verifica si es instancia de UnorderedCollectable | O(1) | O(1) |
+| `isStatistics(t: unknown): t is Statistics<unknown, number \| bigint>` | Verifica si es instancia de Statistics | O(1) | O(1) |
+| `isNumericStatistics(t: unknown): t is NumericStatistics<unknown>` | Verifica si es instancia de NumericStatistics | O(1) | O(1) |
+| `isBigIntStatistics(t: unknown): t is BigIntStatistics<unknown>` | Verifica si es instancia de BigIntStatistics | O(1) | O(1) |
 
-| Método | Firma | Descripción | Ejemplo |
-|------|------|------|------|
-| `validate` | `<T>(t: MaybeInvalid<T>) => t is T` | Validar si el valor es válido | `validate(null)` → `false` |
-| `invalidate` | `<T>(t: MaybeInvalid<T>) => t is null\|undefined` | Validar si el valor es inválido | `invalidate(0)` → `false` |
-| `useCompare` | `<T>(t1: T, t2: T) => number` | Función de comparación genérica | `useCompare("a", "b")` → `-1` |
-| `useRandom` | `<T = number\|bigint>(index: T) => T` | Generador de números pseudoaleatorios | `useRandom(5)` → número aleatorio |
-
-**Suplemento de Ejemplo de Código:**
 ```typescript
-import { validate, invalidate, useCompare, useRandom } from 'semantic-typescript';
+// Ejemplos de uso de guardias de tipo
+const value: unknown = "hello";
 
-// Validar validez de datos
-const data: string | null = "hello";
-if (validate(data)) {
-    console.log(data.toUpperCase()); // Llamada segura porque validate asegura que data no es null
+if (isString(value)) {
+    console.log(value.length); // Seguro de tipos, value se infiere como string
 }
 
-const nullData: string | null = null;
-if (invalidate(nullData)) {
-    console.log("Datos inválidos"); // Se ejecutará porque invalidate detectó null
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
 }
-
-// Comparar valores
-const comparison = useCompare("apple", "banana"); // -1
-
-// Generar número aleatorio
-const randomNum = useRandom(42); // Número aleatorio basado en semilla 42
 ```
 
-## Detalles de la Clase Principal
-
-### Optional<T> - Manejo Seguro de Valores Nulos
+## Funciones de Utilidad
 
-La clase Optional proporciona un enfoque funcional para manejar seguramente valores que pueden ser null o undefined.
+| Función | Descripción | Complejidad Temporal | Complejidad Espacial |
+|---------|-------------|---------------------|---------------------|
+| `useCompare<T>(t1: T, t2: T): number` | Función de comparación universal | O(1) | O(1) |
+| `useRandom<T = number \| bigint>(index: T): T` | Generador de números pseudoaleatorios | O(log n) | O(1) |
 
-| Método | Tipo de Retorno | Descripción | Complejidad Temporal |
-|------|----------|------|------------|
-| `filter(predicate: Predicate<T>)` | `Optional<T>` | Filtrar valores que satisfacen condición | O(1) |
-| `get()` | `T` | Obtener valor, lanza error si está vacío | O(1) |
-| `getOrDefault(defaultValue: T)` | `T` | Obtener valor o valor por defecto | O(1) |
-| `ifPresent(action: Consumer<T>)` | `void` | Ejecutar acción si existe valor | O(1) |
-| `isEmpty()` | `boolean` | Verificar si está vacío | O(1) |
-| `isPresent()` | `boolean` | Verificar si existe valor | O(1) |
-| `map<R>(mapper: Functional<T, R>)` | `Optional<R>` | Mapear y transformar valor | O(1) |
-| `static of<T>(value: MaybeInvalid<T>)` | `Optional<T>` | Crear instancia Optional | O(1) |
-| `static ofNullable<T>(value?)` | `Optional<T>` | Crear Optional nullable | O(1) |
-| `static ofNonNull<T>(value: T)` | `Optional<T>` | Crear Optional no nulo | O(1) |
-
-**Suplemento de Ejemplo de Código:**
 ```typescript
-import { Optional } from 'semantic-typescript';
+// Ejemplos de uso de funciones de utilidad
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-// Crear instancia Optional
-const optionalValue = Optional.ofNullable<string>(Math.random() > 0.5 ? "hello" : null);
+const randomNum = useRandom(42); // Número aleatorio basado en semilla
+const randomBigInt = useRandom(1000n); // Número BigInt aleatorio
+```
 
-// Operaciones en cadena
-const result = optionalValue
-    .filter(val => val.length > 3) // Filtrar valores más largos que 3
-    .map(val => val.toUpperCase()) // Convertir a mayúsculas
-    .getOrDefault("default"); // Obtener valor o por defecto
+## Métodos de Fábrica
 
-console.log(result); // "HELLO" o "default"
+### Métodos de Fábrica de Optional
 
-// Operaciones seguras
-optionalValue.ifPresent(val => {
-    console.log(`Valor existe: ${val}`);
-});
+| 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 con valor | O(1) | O(1) |
+| `Optional.ofNullable<T>(value)` | Crea un Optional que puede ser nulo | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value)` | Crea un Optional no nulo | O(1) | O(1) |
 
-// Verificar estado
-if (optionalValue.isPresent()) {
-    console.log("Tiene valor");
-} else if (optionalValue.isEmpty()) {
-    console.log("Está vacío");
-}
+```typescript
+// Ejemplos de uso de Optional
+const emptyOpt = Optional.empty<number>();
+const presentOpt = Optional.of(42);
+const nullableOpt = Optional.ofNullable<string>(null);
+const nonNullOpt = Optional.ofNonNull("hello");
+
+presentOpt.ifPresent(val => console.log(val)); // Output 42
+console.log(emptyOpt.orElse(100)); // Output 100
 ```
 
-### Semantic<E> - Flujo de Datos Perezoso
-
-Semantic es la clase principal de procesamiento de flujos, que proporciona operadores ricos de flujos.
-
-#### Operaciones de Transformación de Flujos
-
-| Método | Tipo de Retorno | Descripción | Impacto en Rendimiento |
-|------|----------|------|----------|
-| `concat(other: Semantic<E>)` | `Semantic<E>` | Concatenar dos flujos | O(n+m) |
-| `distinct()` | `Semantic<E>` | Eliminar duplicados (usando Set) | O(n) |
-| `distinct(comparator)` | `Semantic<E>` | Eliminación de duplicados con comparador personalizado | O(n²) |
-| `dropWhile(predicate)` | `Semantic<E>` | Descartar elementos iniciales que satisfacen condición | O(n) |
-| `filter(predicate)` | `Semantic<E>` | Filtrar elementos | O(n) |
-| `flat(mapper)` | `Semantic<E>` | Aplanar flujos anidados | O(n×m) |
-| `flatMap(mapper)` | `Semantic<R>` | Mapear y aplanar | O(n×m) |
-| `limit(n)` | `Semantic<E>` | Limitar número de elementos | O(n) |
-| `map(mapper)` | `Semantic<R>` | Mapear y transformar elementos | O(n) |
-| `peek(consumer)` | `Semantic<E>` | Ver elementos sin modificación | O(n) |
-| `redirect(redirector)` | `Semantic<E>` | Redirigir índices | O(n) |
-| `reverse()` | `Semantic<E>` | Invertir orden del flujo | O(n) |
-| `shuffle()` | `Semantic<E>` | Barajar orden aleatoriamente | O(n) |
-| `shuffle(mapper)` | `Semantic<E>` | Lógica de barajado personalizada | O(n) |
-| `skip(n)` | `Semantic<E>` | Saltar primeros n elementos | O(n) |
-| `sub(start, end)` | `Semantic<E>` | Obtener subflujo | O(n) |
-| `takeWhile(predicate)` | `Semantic<E>` | Obtener elementos iniciales que satisfacen condición | O(n) |
-| `translate(offset)` | `Semantic<E>` | Traducir índices | O(n) |
-| `translate(translator)` | `Semantic<E>` | Transformación de índices personalizada | O(n) |
-
-**Suplemento de Ejemplo de Código:**
-```typescript
-import { from } from 'semantic-typescript';
+### Métodos de Fábrica de Collector
 
-const stream = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
+|--------|-------------|---------------------|---------------------|
+| `Collector.full(identity, accumulator, finisher)` | Crea un colector completo | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | Crea un colector interrumpible | O(1) | O(1) |
 
-// Ejemplos de operaciones de transformación de flujos
-const processedStream = stream
-    .filter(x => x % 2 === 0) // Filtrar números pares
-    .map(x => x * 2) // Multiplicar cada elemento por 2
-    .distinct() // Eliminar duplicados
-    .limit(3) // Limitar a primeros 3 elementos
-    .peek((val, index) => console.log(`Elemento ${val} en índice ${index}`)); // Ver elementos
+```typescript
+// Ejemplos de uso de Collector
+const sumCollector = Collector.full(
+    () => 0,
+    (sum, num) => sum + num,
+    result => result
+);
 
-// Nota: El flujo aún no se ha ejecutado, necesita conversión a Collectable para operaciones terminales
+const numbers = from([1, 2, 3, 4, 5]);
+const total = numbers.toUnoredered().collect(sumCollector); // 15
 ```
 
-#### Operaciones Terminales de Flujos
+### Métodos de fábrica de Semantic
 
-| Método | Tipo de Retorno | Descripción | Características de Rendimiento |
-|------|----------|------|----------|
-| `toOrdered()` | `OrderedCollectable<E>` | Convertir a colección ordenada | Operación de ordenación, menor rendimiento |
-| `toUnordered()` | `UnorderedCollectable<E>` | Convertir a colección desordenada | Más rápido, sin ordenación |
-| `toWindow()` | `WindowCollectable<E>` | Convertir a colección de ventana | Operación de ordenación, menor rendimiento |
-| `toNumericStatistics()` | `Statistics<E, number>` | Análisis estadístico numérico | Operación de ordenación, menor rendimiento |
-| `toBigintStatistics()` | `Statistics<E, bigint>` | Análisis estadístico de big integer | Operación de ordenación, menor rendimiento |
-| `sorted()` | `OrderedCollectable<E>` | Ordenación natural | Anula resultados de redirección |
-| `sorted(comparator)` | `OrderedCollectable<E>` | Ordenación personalizada | Anula resultados de redirección |
+| Método | Descripción | Complejidad temporal | Complejidad espacial |
+|--------|-------------|----------------------|----------------------|
+| `blob(blob, chunkSize)` | Crea flujo desde Blob | O(n) | O(chunkSize) |
+| `empty<E>()` | Crea flujo vacío | O(1) | O(1) |
+| `fill<E>(element, count)` | Crea flujo lleno | O(n) | O(1) |
+| `from<E>(iterable)` | Crea flujo desde objeto iterable | O(1) | O(1) |
+| `interval(period, delay?)` | Crea flujo de intervalo regular | O(1)* | O(1) |
+| `iterate<E>(generator)` | Crea flujo desde generador | O(1) | O(1) |
+| `range(start, end, step)` | Crea flujo de rango numérico | O(n) | O(1) |
+| `websocket(websocket)` | Crea flujo desde WebSocket | O(1) | O(1) |
 
-**Suplemento de Ejemplo de Código:**
 ```typescript
-import { from } from 'semantic-typescript';
+// Ejemplo de uso de métodos de fábrica de Semantic
 
-const semanticStream = from([5, 2, 8, 1, 9, 3, 7, 4, 6]);
+// Crear flujo desde Blob (lectura por fragmentos)
+blob(someBlob, 1024n)
+  .toUnordered()
+  .write(WritableStream)
+  .then(callback) // Escritura de flujo exitosa
+  .catch(writeFi); // Escritura de flujo fallida
 
-// Convertir a colección ordenada (menor rendimiento)
-const ordered = semanticStream.toOrdered();
+// Crear flujo vacío que no se ejecutará hasta concatenarse con otros flujos
+empty<string>()
+  .toUnordered()
+  .join(); //[]
 
-// Convertir a colección desordenada (más rápido)
-const unordered = semanticStream.toUnordered();
+// Crear flujo lleno
+const filledStream = fill("hello", 3); // "hello", "hello", "hello"
 
-// Ordenación natural
-const sortedNatural = semanticStream.sorted();
+// Crear flujo temporal con retraso inicial de 2 segundos y ciclo de 5 segundos,
+// implementado mediante mecanismo de temporizador, posibles desviaciones de tiempo 
+// debido a limitaciones de programación del sistema.
+const intervalStream = interval(5000, 2000);
 
-// Ordenación personalizada
-const sortedCustom = semanticStream.sorted((a, b) => b - a); // Orden descendente
+// Crear flujo desde objeto iterable
+const numberStream = from([1, 2, 3, 4, 5]);
+const stringStream = from(new Set(["Alex", "Bob"]));
 
-// Convertir a objeto estadístico
-const stats = semanticStream.toNumericStatistics();
+// Crear flujo de rango
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
 
-// Nota: Debe llamar a los métodos anteriores a través de la instancia Semantic para obtener Collectable antes de usar métodos terminales
+// Flujo de eventos WebSocket
+const ws = new WebSocket("ws://localhost:8080");
+websocket(ws)
+  .filter((event)=> event.type === "message") // Solo monitorear eventos de mensaje
+  .toUnordered() // Para eventos normalmente sin ordenar
+  .forEach((event)=> receive(event)); // Recibir mensajes
 ```
 
-### Collector<E, A, R> - Colector de Datos
+## 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 con comparador | O(n²) | O(n) |
+| `dropWhile(predicate)` | Descarta elementos que cumplen condición | O(n) | O(1) |
+| `filter(predicate)` | Filtra elementos | O(n) | O(1) |
+| `flat(mapper)` | Aplanamiento de mapeo | O(n × m) | O(1) |
+| `flatMap(mapper)` | Aplanamiento a nuevo tipo | O(n × m) | O(1) |
+| `limit(n)` | Limita cantidad de elementos | O(n) | O(1) |
+| `map(mapper)` | Transformación de mapeo | O(n) | O(1) |
+| `peek(consumer)` | Inspecciona elementos | O(n) | O(1) |
+| `redirect(redirector)` | Redirección de índices | O(n) | O(1) |
+| `reverse()` | Revierte flujo | O(n) | O(1) |
+| `shuffle()` | Mezcla aleatoria | O(n) | O(1) |
+| `shuffle(mapper)` | Mezcla con mapeador | O(n) | O(1) |
+| `skip(n)` | Salta primeros n elementos | O(n) | O(1) |
+| `sorted()` | Ordena | O(n log n) | O(n) |
+| `sorted(comparator)` | Ordena con comparador | O(n log n) | O(n) |
+| `sub(start, end)` | Obtiene subflujo | O(n) | O(1) |
+| `takeWhile(predicate)` | Toma elementos que cumplen condición | O(n) | O(1) |
+| `translate(offset)` | Traslación de índices | O(n) | O(1) |
+| `translate(translator)` | Traslación con traductor | O(n) | O(1) |
 
-Los colectores se utilizan para agregar datos de flujos en estructuras específicas.
-
-| Método | Descripción | Escenario de Uso |
-|------|------|----------|
-| `collect(generator)` | Ejecutar recolección de datos | Operación terminal de flujo |
-| `static full(identity, accumulator, finisher)` | Crear colector completo | Requiere procesamiento completo |
-| `static shortable(identity, interruptor, accumulator, finisher)` | Crear colector interrumpible | Puede terminar temprano |
-
-**Suplemento de Ejemplo de Código:**
 ```typescript
-import { Collector } from 'semantic-typescript';
-
-// Crear colector personalizado
-const sumCollector = Collector.full(
-    () => 0, // Valor inicial
-    (acc, value) => acc + value, // Acumulador
-    result => result // Función finalizadora
-);
-
-// Usar colector (requiere conversión de Semantic a Collectable primero)
-const numbers = from([1, 2, 3, 4, 5]);
-const sum = numbers.toUnordered().collect(sumCollector); // 15
+// Ejemplos de operaciones Semantic
+const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)        // Filtra números pares
+    .map(n => n * 2)                 // Multiplica por 2
+    .skip(1)                         // Salta el primero
+    .limit(3)                        // Limita a 3 elementos
+    .toArray();                      // Convierte a array
+// Resultado: [8, 12, 20]
+
+// Ejemplo de operación compleja
+const complexResult = range(1, 100, 1)
+    .flatMap(n => from([n, n * 2])) // Mapea cada elemento a dos elementos
+    .distinct()                      // Elimina duplicados
+    .shuffle()                       // Mezcla aleatoriamente
+    .takeWhile(n => n < 50)         // Toma elementos < 50
+    .toOrdered()                     // Convierte a colector ordenado
+    .toArray();                      // Convierte a array
 ```
 
-### Collectable<E> - Clase Abstracta de Datos Colectables
+## Métodos de Transformación de Colectores
 
-Proporciona métodos ricos de agregación y transformación de datos. **Nota: Primero debe obtener una instancia Collectable llamando a sorted(), toOrdered(), etc. a través de la instancia Semantic antes de usar los siguientes métodos.**
+| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
+|--------|-------------|---------------------|---------------------|
+| `toUnoredered()` | Convierte a colector no ordenado (prioridad rendimiento) | O(1) | O(1) |
+| `toOrdered()` | Convierte a colector ordenado | O(1) | O(1) |
+| `sorted()` | Ordena y convierte a colector ordenado | O(n log n) | O(n) |
+| `toWindow()` | Convierte a colector de ventana | O(1) | O(1) |
+| `toNumericStatistics()` | Convierte a estadísticas numéricas | O(1) | O(1) |
+| `toBigintStatistics()` | Convierte a estadísticas BigInt | O(1) | O(1) |
 
-#### Operaciones de Consulta de Datos
+```typescript
+// Ejemplos de transformación de colectores
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
 
-| Método | Tipo de Retorno | Descripción | Ejemplo |
-|------|----------|------|------|
-| `anyMatch(predicate)` | `boolean` | Si algún elemento coincide | `anyMatch(x => x > 0)` |
-| `allMatch(predicate)` | `boolean` | Si todos los elementos coinciden | `allMatch(x => x > 0)` |
-| `count()` | `bigint` | Estadísticas de conteo de elementos | `count()` → `5n` |
-| `isEmpty()` | `boolean` | Si el flujo está vacío | `isEmpty()` |
-| `findAny()` | `Optional<E>` | Encontrar cualquier elemento | `findAny()` |
-| `findFirst()` | `Optional<E>` | Encontrar primer elemento | `findFirst()` |
-| `findLast()` | `Optional<E>` | Encontrar último elemento | `findLast()` |
+// Prioridad rendimiento: Usar colector no ordenado
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
 
-**Suplemento de Ejemplo de Código:**
-```typescript
-import { from } from 'semantic-typescript';
+// Necesita orden: Usar colector ordenado  
+const ordered = numbers.sorted();
 
-const numbers = from([1, 2, 3, 4, 5]);
+// Análisis estadístico: Usar colector estadístico
+const stats = numbers
+    .toNumericStatistics();
+
+console.log(stats.mean());        // Promedio
+console.log(stats.median());      // Mediana
+console.log(stats.standardDeviation()); // Desviación estándar
 
-// Debe convertir a Collectable antes de usar métodos terminales
-const collectable = numbers.toUnordered();
+// Operaciones de ventana
+const windowed = numbers
+    .toWindow()
+    .tumble(3n); // Ventana de 3 elementos
 
-// Operaciones de consulta de datos
-const hasEven = collectable.anyMatch(x => x % 2 === 0); // true
-const allPositive = collectable.allMatch(x => x > 0); // true
-const count = collectable.count(); // 5n
-const isEmpty = collectable.isEmpty(); // false
-const firstElement = collectable.findFirst(); // Optional.of(1)
-const anyElement = collectable.findAny(); // Cualquier elemento
+windowed.forEach(window => {
+    console.log(window.toArray()); // Contenido de cada ventana
+});
 ```
 
-#### Operaciones de Agregación de Datos
-
-| Método | Tipo de Retorno | Descripción | Complejidad |
-|------|----------|------|--------|
-| `group(classifier)` | `Map<K, E[]>` | Agrupar por clasificador | O(n) |
-| `groupBy(keyExtractor, valueExtractor)` | `Map<K, V[]>` | Agrupar por extractores de clave-valor | O(n) |
-| `join()` | `string` | Unir como cadena | O(n) |
-| `join(delimiter)` | `string` | Unir con delimitador | O(n) |
-| `partition(count)` | `E[][]` | Particionar por conteo | O(n) |
-| `partitionBy(classifier)` | `E[][]` | Particionar por clasificador | O(n) |
-| `reduce(accumulator)` | `Optional<E>` | Operación de reducción | O(n) |
-| `reduce(identity, accumulator)` | `E` | Reducción con identidad | O(n) |
-| `toArray()` | `E[]` | Convertir a array | O(n) |
-| `toMap(keyExtractor, valueExtractor)` | `Map<K, V>` | Convertir a Map | O(n) |
-| `toSet()` | `Set<E>` | Convertir a Set | O(n) |
-
-**Suplemento de Ejemplo de Código:**
+## Métodos de Recolección de Collectable
+
+| Método | Descripción | Complejidad Temporal | Complejidad Espacial |
+|--------|-------------|---------------------|---------------------|
+| `anyMatch(predicate)` | Verifica si existe coincidencia | O(n) | O(1) |
+| `allMatch(predicate)` | Verifica si todos coinciden | O(n) | O(1) |
+| `count()` | Cuenta elementos | O(n) | O(1) |
+| `isEmpty()` | Verifica si está vacío | O(1) | O(1) |
+| `findAny()` | Encuentra cualquier elemento | O(n) | O(1) |
+| `findFirst()` | Encuentra primer elemento | O(n) | O(1) |
+| `findLast()` | Encuentra ú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 extractores de clave-valor | O(n) | O(n) |
+| `join()` | Concatena a string | O(n) | O(n) |
+| `join(delimiter)` | Concatena con separador | O(n) | O(n) |
+| `nonMatch(predicate)` | Verifica si no hay coincidencias | O(n) | O(1) |
+| `partition(count)` | Particiona por cantidad | O(n) | O(n) |
+| `partitionBy(classifier)` | Particiona 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 array | 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 a stream | O(n) | O(1) |
+
 ```typescript
-import { from } from 'semantic-typescript';
+// Ejemplos de operaciones Collectable
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)
+    .toOrdered();
 
-const people = from([
-    { name: "Alice", age: 25, city: "New York" },
-    { name: "Bob", age: 30, city: "London" },
-    { name: "Charlie", age: 25, city: "New York" }
-]);
+// Verificaciones de coincidencia
+console.log(data.anyMatch(n => n > 5)); // true
+console.log(data.allMatch(n => n < 20)); // true
 
-// Debe convertir a Collectable antes de usar operaciones de agregación
-const collectable = people.toUnordered();
+// Operaciones de búsqueda
+data.findFirst().ifPresent(n => console.log(n)); // 2
+data.findAny().ifPresent(n => console.log(n)); // Elemento cualquiera
 
 // Operaciones de agrupación
-const byCity = collectable.group(person => person.city);
-// Map { "New York" => [{name: "Alice", ...}, {name: "Charlie", ...}], "London" => [{name: "Bob", ...}] }
-
-const byAge = collectable.groupBy(
-    person => person.age,
-    person => person.name
+const grouped = data.groupBy(
+    n => n > 5 ? "large" : "small",
+    n => n * 2
 );
-// Map { 25 => ["Alice", "Charlie"], 30 => ["Bob"] }
-
-// Convertir a colecciones
-const array = collectable.toArray(); // Array original
-const set = collectable.toSet(); // Colección Set
-const map = collectable.toMap(
-    person => person.name,
-    person => person.age
-); // Map { "Alice" => 25, "Bob" => 30, "Charlie" => 25 }
+// {small: [4, 8], large: [12, 16, 20]}
 
 // Operaciones de reducción
-const totalAge = collectable.reduce(0, (acc, person) => acc + person.age); // 80
-const oldest = collectable.reduce((a, b) => a.age > b.age ? a : b); // Optional.of({name: "Bob", age: 30, ...})
-```
-
-### Implementaciones Específicas de Colectores
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
 
-#### UnorderedCollectable<E>
-- **Características**: Colector más rápido, sin ordenación
-- **Escenarios de Uso**: Orden no importante, máximo rendimiento deseado
-- **Métodos**: Hereda todos los métodos de Collectable
-
-#### OrderedCollectable<E> 
-- **Características**: Garantiza orden de elementos, menor rendimiento
-- **Escenarios de Uso**: Requieren resultados ordenados
-- **Métodos Especiales**: Hereda todos los métodos, mantiene estado de orden interno
+// Operaciones de salida
+data.join(", "); // "2, 4, 6, 8, 10"
+```
 
-#### WindowCollectable<E>
-- **Características**: Soporta operaciones de ventana deslizante
-- **Escenarios de Uso**: Análisis de datos de series temporales
-- **Métodos Especiales**:
-  - `slide(size, step)` - Ventana deslizante
-  - `tumble(size)` - Ventana de tumble
+## 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()` | Sumatoria | 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) |
 
-**Suplemento de Ejemplo de Código:**
 ```typescript
-import { from } from 'semantic-typescript';
-
-const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-// Colector desordenado (más rápido)
-const unordered = data.toUnordered();
-const unorderedArray = unordered.toArray(); // Puede mantener orden original [1, 2, 3, ...]
-
-// Colector ordenado
-const ordered = data.toOrdered();
-const orderedArray = ordered.toArray(); // Orden garantizado [1, 2, 3, ...]
+// 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 con mapeador
+const objects = from([
+    { value: 10 },
+    { value: 20 }, 
+    { value: 30 }
+]).toNumericStatistics();
+
+console.log("Media mapeada:", objects.mean(obj => obj.value)); // 20
+```
 
-// Colector de ventana
-const windowed = data.toWindow();
-const slidingWindows = windowed.slide(3n, 2n); // Tamaño de ventana 3, paso 2
-// Ventana 1: [1, 2, 3], Ventana 2: [3, 4, 5], Ventana 3: [5, 6, 7], ...
+## Guía de Selección de Rendimiento
 
-const tumblingWindows = windowed.tumble(4n); // Ventana de tumble tamaño 4
-// Ventana 1: [1, 2, 3, 4], Ventana 2: [5, 6, 7, 8], ...
+### Seleccionar Colector No Ordenado (Prioridad Rendimiento)
+```typescript
+// Cuando no se necesita garantía de orden
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // Mejor rendimiento
 ```
 
-### Statistics<E, D> - Análisis Estadístico
-
-Clase base de análisis estadístico que proporciona métodos ricos de cálculo estadístico. **Nota: Primero debe obtener una instancia Statistics llamando a toNumericStatistics() o toBigIntStatistics() a través de la instancia Semantic antes de usar los siguientes métodos.**
-
-#### Operaciones de Cálculo Estadístico
-
-| Método | Tipo de Retorno | Descripción | Complejidad de Algoritmo |
-|------|----------|------|------------|
-| `maximum()` | `Optional<E>` | Valor máximo | O(n) |
-| `minimum()` | `Optional<E>` | Valor mínimo | O(n) |
-| `range()` | `D` | Rango (max-min) | O(n) |
-| `variance()` | `D` | Varianza | O(n) |
-| `standardDeviation()` | `D` | Desviación estándar | O(n) |
-| `mean()` | `D` | Valor medio | O(n) |
-| `median()` | `D` | Valor mediano | O(n log n) |
-| `mode()` | `D` | Valor modal | O(n) |
-| `frequency()` | `Map<D, bigint>` | Distribución de frecuencia | O(n) |
-| `summate()` | `D` | Sumatoria | O(n) |
-| `quantile(quantile)` | `D` | Cuantil | O(n log n) |
-| `interquartileRange()` | `D` | Rango intercuartílico | O(n log n) |
-| `skewness()` | `D` | Asimetría | O(n) |
-| `kurtosis()` | `D` | Curtosis | O(n) |
-
-**Suplemento de Ejemplo de Código:**
+### Seleccionar Colector Ordenado (Necesita Orden)
 ```typescript
-import { from } from 'semantic-typescript';
-
-const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-// Debe convertir a objeto estadístico antes de usar métodos estadísticos
-const stats = numbers.toNumericStatistics();
-
-// Estadísticas básicas
-const count = stats.count(); // 10n
-const max = stats.maximum(); // Optional.of(10)
-const min = stats.minimum(); // Optional.of(1)
-const range = stats.range(); // 9
-const mean = stats.mean(); // 5.5
-const median = stats.median(); // 5.5
-const sum = stats.summate(); // 55
-
-// Estadísticas avanzadas
-const variance = stats.variance(); // 8.25
-const stdDev = stats.standardDeviation(); // 2.872
-const mode = stats.mode(); // Cualquier valor (ya que todos aparecen una vez)
-const q1 = stats.quantile(0.25); // 3.25
-const q3 = stats.quantile(0.75); // 7.75
-const iqr = stats.interquartileRange(); // 4.5
-
-// Distribución de frecuencia
-const freq = stats.frequency(); // Map {1 => 1n, 2 => 1n, ...}
+// Cuando se debe mantener el orden de elementos
+const ordered = data
+    .sorted(comparator) // La ordenación sobrescribe efectos de redirección
+    .toOrdered(); // Mantiene orden
 ```
 
-#### Clases Específicas de Implementación Estadística
-
-**NumericStatistics<E>**
-- Maneja análisis estadístico de tipo number
-- Todos los cálculos estadísticos retornan tipo number
-
-**BigIntStatistics<E>**  
-- Maneja análisis estadístico de tipo bigint
-- Todos los cálculos estadísticos retornan tipo bigint
-
-**Suplemento de Ejemplo de Código:**
+### Seleccionar Colector de Ventana (Operaciones de Ventana)
 ```typescript
-import { from } from 'semantic-typescript';
-
-// Estadísticas numéricas
-const numberData = from([10, 20, 30, 40, 50]);
-const numericStats = numberData.toNumericStatistics();
-
-console.log(numericStats.mean()); // 30
-console.log(numericStats.summate()); // 150
-
-// Estadísticas de big integer
-const bigintData = from([100n, 200n, 300n, 400n, 500n]);
-const bigintStats = bigintData.toBigIntStatistics();
-
-console.log(bigintStats.mean()); // 300n
-console.log(bigintStats.summate()); // 1500n
+// Cuando se necesitan operaciones de ventana
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // Ventana deslizante
+```
 
-// Estadísticas usando funciones mapeadoras
-const objectData = from([
-    { value: 15 },
-    { value: 25 }, 
-    { value: 35 },
-    { value: 45 }
-]);
+### Seleccionar Análisis Estadístico (Cálculos Numéricos)
+```typescript
+// Cuando se necesita análisis estadístico
+const stats = data
+    .toNumericStatistics(); // Estadísticas numéricas
 
-const objectStats = objectData.toNumericStatistics();
-const meanWithMapper = objectStats.mean(obj => obj.value); // 30
-const sumWithMapper = objectStats.summate(obj => obj.value); // 120
+const bigIntStats = data
+    .toBigintStatistics(); // Estadísticas BigInt
 ```
 
-## Ejemplo Completo de Uso
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-```typescript
-import { from, validate, invalidate } from 'semantic-typescript';
-
-// 1. Crear flujo de datos
-const rawData = [5, 2, 8, 1, null, 9, 3, undefined, 7, 4, 6];
-const semanticStream = from(rawData);
-
-// 2. Pipeline de procesamiento de flujo
-const processedStream = semanticStream
-    .filter(val => validate(val)) // Filtrar null y undefined
-    .map(val => val! * 2) // Multiplicar cada valor por 2 (usando ! porque validate asegura no vacío)
-    .distinct(); // Eliminar duplicados
-
-// 3. Convertir a Collectable y usar operaciones terminales
-const collectable = processedStream.toUnordered();
-
-// 4. Validación de datos y uso
-if (!collectable.isEmpty()) {
-    const results = collectable
-        .filter(x => x > 5) // Filtrar nuevamente
-        .toArray(); // Convertir a array
-    
-    console.log("Resultados del procesamiento:", results); // [16, 18, 14, 8, 12]
-    
-    // Información estadística
-    const stats = processedStream.toNumericStatistics();
-    console.log("Valor medio:", stats.mean()); // 11.2
-    console.log("Suma total:", stats.summate()); // 56
-}
+## Consideraciones Importantes
 
-// 5. Manejar datos potencialmente inválidos
-const potentiallyInvalidData: Array<number | null> = [1, null, 3, 4, null];
-const validData = potentiallyInvalidData.filter(validate);
-const invalidData = potentiallyInvalidData.filter(invalidate);
-
-console.log("Datos válidos:", validData); // [1, 3, 4]
-console.log("Datos inválidos:", invalidData); // [null, null]
-```
+1. **Impacto de operaciones de ordenación**: En colectores ordenados, `sorted()` sobrescribe los efectos de `redirect`, `translate`, `shuffle`, `reverse`
+2. **Consideraciones de rendimiento**: Si no se necesita garantía de orden, priorizar `toUnoredered()` para mejor rendimiento
+3. **Uso de memoria**: Las operaciones de ordenación requieren espacio adicional O(n)
+4. **Datos en tiempo real**: Los flujos Semantic son ideales para datos en tiempo real y admiten fuentes de datos asincrónicas
 
-## Resumen de Reglas Importantes de Uso
-
-1. **Crear Flujo**: Usar métodos de fábrica `from()`, `range()`, `fill()`, etc. para crear instancias Semantic
-2. **Transformación de Flujo**: Llamar métodos `map()`, `filter()`, `distinct()`, etc. en instancias Semantic
-3. **Convertir a Collectable**: Debe llamar a uno de los siguientes métodos a través de la instancia Semantic:
-   - `toOrdered()` - Colector ordenado
-   - `toUnordered()` - Colector desordenado (más rápido)
-   - `toWindow()` - Colector de ventana  
-   - `toNumericStatistics()` - Estadísticas numéricas
-   - `toBigIntStatistics()` - Estadísticas de big integer
-   - `sorted()` - Ordenación natural
-   - `sorted(comparator)` - Ordenación personalizada
-4. **Operaciones Terminales**: Llamar métodos terminales `toArray()`, `count()`, `summate()`, etc. en instancias Collectable
-5. **Validación de Datos**: Usar `validate()` para asegurar que los datos no son null/undefined, usar `invalidate()` para verificar datos inválidos
-
-Este diseño garantiza seguridad de tipos y optimización de rendimiento mientras proporciona funcionalidad rica de procesamiento de flujos.
+Esta biblioteca proporciona a los desarrolladores de TypeScript capacidades potentes y flexibles de procesamiento de flujos, combinando las ventajas de la programación funcional con la seguridad de tipos.