semantic-typescript 0.0.7 → 0.0.8

package/readme.es.md

@@ -1,335 +1,529 @@
-# 📘 semantic-typescript
+# Framework de Procesamiento de Flujos Semantic-TypeScript
 
-Una poderosa biblioteca de utilidades para **procesamiento semántico de datos** en TypeScript, completamente **segura y tipada**.  
-Proporciona construcciones funcionales compuestas para trabajar con colecciones, flujos y secuencias — con soporte para ordenar, filtrar, agrupar, realizar análisis estadísticos y más.
+## Introducción
 
-Ya sea que estés procesando **datos ordenados o no ordenados**, realizando **análisis estadísticos**, o simplemente **encadenando operaciones de forma fluida**, esta biblioteca está diseñada para cubrir todas tus necesidades.
+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.
 
----
+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.
 
-## 🧩 Características
+## Características Principales
 
-- ✅ **Genéricos tipados de forma segura** en toda la biblioteca
-- ✅ Estilo **funcional** (map, filter, reduce, etc.)
-- ✅ **Flujos de datos semánticos** (`Semantic<E>`) para evaluación diferida (lazy)
-- ✅ **Coleccionadores (Collectors)** para transformar flujos en estructuras concretas
-- ✅ **Collectables ordenados y no ordenados** — `toUnordered()` es **el más rápido (sin ordenar)**
-- ✅ **Soporte para ordenar** mediante `sorted()`, `toOrdered()`, y comparadores personalizados
-- ✅ **Análisis estadístico** (`Statistics`, `NumericStatistics`, `BigIntStatistics`)
-- ✅ **Optional<T>** — monada para manejar valores nulos de forma segura
-- ✅ Diseño basado en **iteradores y generadores** — ideal para grandes volúmenes o datos asíncronos
+| 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
 
-## 📦 Instalación
+**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)`
 
-```bash
-npm install semantic-typescript
-```
-
----
-
-## 🧠 Conceptos clave
-
-### 1. `Optional<T>` — Manejo seguro de valores nulos
-
-Un contenedor monádico para valores que pueden ser `null` o `undefined`.
+Especialmente importante notar: `sorted()` y `sorted(comparator)` anularán los resultados de los siguientes métodos:
+- `redirect(redirector)`
+- `translate(translator)` 
+- `shuffle(mapper)`
 
-#### Métodos:
+## Métodos de Fábrica
 
-| Método | Descripción | Ejemplo |
-|--------|-------------|---------|
-| `of(value)` | Envolver un valor (puede ser nulo) | `Optional.of(null)` |
-| `ofNullable(v)` | Envolver, permite valores nulos | `Optional.ofNullable(someVar)` |
-| `ofNonNull(v)` | Envolver, lanza excepción si es nulo/undefined | `Optional.ofNonNull(5)` |
-| `get()` | Obtener el valor (o lanzar excepción si está vacío) | `opt.get()` |
-| `getOrDefault(d)` | Obtener el valor o un valor por defecto | `opt.getOrDefault(0)` |
-| `ifPresent(fn)` | Ejecutar un efecto secundario si hay valor | `opt.ifPresent(x => console.log(x))` |
-| `map(fn)` | Transformar el valor si existe | `opt.map(x => x + 1)` |
-| `filter(fn)` | Conservar el valor solo si cumple el predicado | `opt.filter(x => x > 0)` |
-| `isEmpty()` | Verificar si está vacío | `opt.isEmpty()` |
-| `isPresent()` | Verificar si tiene un valor | `opt.isPresent()` |
+### Fábricas de Creación de Flujos
 
-#### Ejemplo:
+| 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)` |
 
+**Suplemento de Ejemplo de Código:**
 ```typescript
-import { Optional } from 'semantic-typescript';
+import { from, range, fill, empty } from 'semantic-typescript';
 
-const value: number | null = Math.random() > 0.5 ? 10 : null;
+// Crear flujo desde array
+const numberStream = from([1, 2, 3, 4, 5]);
 
-const opt = Optional.ofNullable(value);
+// Crear flujo de rango numérico
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
 
-const result = opt
-  .filter(v => v > 5)
-  .map(v => v * 2)
-  .getOrDefault(0);
+// Llenar con elementos repetidos
+const filledStream = fill("hello", 3n); // "hello", "hello", "hello"
 
-console.log(result); // 20 o 0
+// Crear flujo vacío
+const emptyStream = empty<number>();
 ```
 
----
+### Fábricas de Funciones de Utilidad
 
-### 2. `Semantic<E>` — Flujo de datos diferido
+| 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 |
 
-Un **flujo secuencial diferido y compuesto**. Similar a Java Streams o Kotlin Sequences.
+**Suplemento de Ejemplo de Código:**
+```typescript
+import { validate, invalidate, useCompare, useRandom } from 'semantic-typescript';
 
-Puedes crear un `Semantic` usando funciones como `from()`, `range()`, `iterate()` o `fill()`.
+// 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
+}
 
-#### Creadores:
+const nullData: string | null = null;
+if (invalidate(nullData)) {
+    console.log("Datos inválidos"); // Se ejecutará porque invalidate detectó null
+}
 
-| Función | Descripción | Ejemplo |
-|--------|-------------|---------|
-| `from(iterable)` | Crear desde un Array, Set, Iterable | `from([1, 2, 3])` |
-| `range(start, end, step?)` | Generar una secuencia de números | `range(0, 5)` → 0,1,2,3,4 |
-| `fill(element, count)` | Repetir un elemento N veces | `fill('a', 3n)` |
-| `iterate(gen)` | Usar una función generadora personalizada | `iterate(genFn)` |
+// Comparar valores
+const comparison = useCompare("apple", "banana"); // -1
 
-#### Operadores comunes:
+// Generar número aleatorio
+const randomNum = useRandom(42); // Número aleatorio basado en semilla 42
+```
 
-| Método | Descripción | Ejemplo |
-|--------|-------------|---------|
-| `map(fn)` | Transformar cada elemento | `.map(x => x * 2)` |
-| `filter(fn)` | Conservar elementos que cumplen el predicado | `.filter(x => x > 10)` |
-| `limit(n)` | Limitar a los primeros N elementos | `.limit(5)` |
-| `skip(n)` | Saltar los primeros N elementos | `.skip(2)` |
-| `distinct()` | Eliminar duplicados (usa Set por defecto) | `.distinct()` |
-| `sorted()` | Ordenar elementos (orden natural) | `.sorted()` |
-| `sorted(comparator)` | Ordenar con un comparador personalizado | `.sorted((a, b) => a - b)` |
-| `toOrdered()` | Ordenar y devolver un `OrderedCollectable` | `.toOrdered()` |
-| `toUnordered()` | **Sin ordenar** — el más rápido | `.toUnordered()` ✅ |
-| `collect(collector)` | Agregar usando un `Collector` | `.collect(Collector.full(...))` |
-| `toArray()` | Convertir a Array | `.toArray()` |
-| `toSet()` | Convertir a Set | `.toSet()` |
-| `toMap(keyFn, valFn)` | Convertir a Map | `.toMap(x => x.id, x => x)` |
+## Detalles de la Clase Principal
 
----
+### Optional<T> - Manejo Seguro de Valores Nulos
 
-### 3. `toUnordered()` — 🚀 El más rápido, sin ordenar
+La clase Optional proporciona un enfoque funcional para manejar seguramente valores que pueden ser null o undefined.
 
-Si **no necesitas orden** y quieres el **máximo rendimiento**, utiliza:
+| 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
-const fastest = semanticStream.toUnordered();
-```
+import { Optional } from 'semantic-typescript';
 
-🔥 **No se aplica ningún algoritmo de ordenamiento.**  
-Ideal cuando el orden no importa y la velocidad es prioritaria.
+// Crear instancia Optional
+const optionalValue = Optional.ofNullable<string>(Math.random() > 0.5 ? "hello" : null);
 
----
+// 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
 
-### 4. `toOrdered()` y `sorted()` — Resultados ordenados
+console.log(result); // "HELLO" o "default"
 
-Si necesitas un **resultado ordenado**, puedes usar:
+// Operaciones seguras
+optionalValue.ifPresent(val => {
+    console.log(`Valor existe: ${val}`);
+});
 
-```typescript
-const ordered = semanticStream.sorted(); // Orden natural
-const customSorted = semanticStream.sorted((a, b) => a - b); // Comparador personalizado
-const orderedCollectable = semanticStream.toOrdered(); // También ordenado
+// Verificar estado
+if (optionalValue.isPresent()) {
+    console.log("Tiene valor");
+} else if (optionalValue.isEmpty()) {
+    console.log("Está vacío");
+}
 ```
 
-⚠️ Estos métodos **ordenarán los elementos**, usando orden natural o el comparador dado.
-
----
-
-### 5. `Collector<E, A, R>` — Agregación de datos
+### 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';
 
-Los **colectores** te permiten **reducir un flujo a una estructura única o compleja**.
+const stream = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
 
-Existen fábricas estáticas como:
+// 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
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// Nota: El flujo aún no se ha ejecutado, necesita conversión a Collectable para operaciones terminales
 ```
 
-Pero normalmente los usarás a través de métodos de alto nivel en las clases `Collectable`.
-
----
+#### Operaciones Terminales de Flujos
 
-### 6. `Collectable<E>` (clase abstracta)
+| 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 |
 
-Clase base para:
-
-- `OrderedCollectable<E>` — Resultados ordenados
-- `UnorderedCollectable<E>` — Sin ordenar, el más rápido
-- `WindowCollectable<E>` — Ventanas deslizantes
-- `Statistics<E, D>` — Estadísticas agregadas
+**Suplemento de Ejemplo de Código:**
+```typescript
+import { from } from 'semantic-typescript';
 
-#### Métodos comunes (heredados):
+const semanticStream = from([5, 2, 8, 1, 9, 3, 7, 4, 6]);
 
-| Método | Descripción | Ejemplo |
-|--------|-------------|---------|
-| `count()` | Contar elementos | `.count()` |
-| `toArray()` | Convertir a Array | `.toArray()` |
-| `toSet()` | Convertir a Set | `.toSet()` |
-| `toMap(k, v)` | Convertir a Map | `.toMap(x => x.id, x => x)` |
-| `group(k)` | Agrupar por clave | `.group(x => x.category)` |
-| `findAny()` | Encontrar cualquier elemento (Optional) | `.findAny()` |
-| `findFirst()` | Encontrar el primer elemento (Optional) | `.findFirst()` |
-| `reduce(...)` | Reducción personalizada | `.reduce((a,b) => a + b, 0)` |
+// Convertir a colección ordenada (menor rendimiento)
+const ordered = semanticStream.toOrdered();
 
----
+// Convertir a colección desordenada (más rápido)
+const unordered = semanticStream.toUnordered();
 
-### 7. `OrderedCollectable<E>` — Datos ordenados
+// Ordenación natural
+const sortedNatural = semanticStream.sorted();
 
-Si deseas que los elementos estén **ordenados automáticamente**, usa esta clase.
+// Ordenación personalizada
+const sortedCustom = semanticStream.sorted((a, b) => b - a); // Orden descendente
 
-Acepta un **comparador personalizado** o el orden natural.
+// Convertir a objeto estadístico
+const stats = semanticStream.toNumericStatistics();
 
-```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// Nota: Debe llamar a los métodos anteriores a través de la instancia Semantic para obtener Collectable antes de usar métodos terminales
 ```
 
-🔒 **El orden está garantizado.**
-
----
+### Collector<E, A, R> - Colector de Datos
 
-### 8. `UnorderedCollectable<E>` — Sin ordenar (🚀 Más rápido)
+Los colectores se utilizan para agregar datos de flujos en estructuras específicas.
 
-Si **no te importa el orden** y buscas el **mejor rendimiento**, usa:
+| 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
-const unordered = new UnorderedCollectable(stream);
-// O
-const fastest = semanticStream.toUnordered();
+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
 ```
 
-✅ **No se ejecuta ningún algoritmo de ordenamiento**  
-✅ **Mejor rendimiento cuando el orden no importa**
-
----
+### Collectable<E> - Clase Abstracta de Datos Colectables
 
-### 9. `Statistics<E, D>` — Análisis estadístico
+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.**
 
-Clase abstracta para analizar datos numéricos.
+#### Operaciones de Consulta de Datos
 
-#### Subclases:
+| 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()` |
 
-- `NumericStatistics<E>` — Para valores `number`
-- `BigIntStatistics<E>` — Para valores `bigint`
-
-##### Métodos estadísticos comunes:
+**Suplemento de Ejemplo de Código:**
+```typescript
+import { from } from 'semantic-typescript';
 
-| Método | Descripción | Ejemplo |
-|--------|-------------|---------|
-| `mean()` | Media | `.mean()` |
-| `median()` | Mediana | `.median()` |
-| `mode()` | Moda (valor más frecuente) | `.mode()` |
-| `minimum()` | Mínimo | `.minimum()` |
-| `maximum()` | Máximo | `.maximum()` |
-| `range()` | Rango (máximo - mínimo) | `.range()` |
-| `variance()` | Varianza | `.variance()` |
-| `standardDeviation()` | Desviación estándar | `.standardDeviation()` |
-| `summate()` | Suma total | `.summate()` |
-| `quantile(q)` | Valor en el percentil q (0–1) | `.quantile(0.5)` → mediana |
-| `frequency()` | Frecuencia como Map | `.frequency()` |
+const numbers = from([1, 2, 3, 4, 5]);
 
----
+// Debe convertir a Collectable antes de usar métodos terminales
+const collectable = numbers.toUnordered();
 
-## 🧪 Ejemplo completo
+// 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
+```
 
+#### 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:**
 ```typescript
-import { from, toUnordered, toOrdered, sorted, NumericStatistics } from 'semantic-typescript';
-
-// Datos de ejemplo
-const numbers = from([10, 2, 8, 4, 5, 6]);
-
-// 🚀 Más rápido: sin ordenar
-const fastest = numbers.toUnordered();
-console.log(fastest.toArray()); // Ej: [10, 2, 8, 4, 5, 6] (orden original)
-
-// 🔢 Orden natural
-const ordered = numbers.sorted();
-console.log(ordered.toArray()); // [2, 4, 5, 6, 8, 10]
-
-// 📊 Estadísticas
-const stats = new NumericStatistics(numbers);
-console.log('Media:', stats.mean());
-console.log('Mediana:', stats.median());
-console.log('Moda:', stats.mode());
-console.log('Rango:', stats.range());
-console.log('Desviación estándar:', stats.standardDeviation());
+import { from } from 'semantic-typescript';
+
+const people = from([
+    { name: "Alice", age: 25, city: "New York" },
+    { name: "Bob", age: 30, city: "London" },
+    { name: "Charlie", age: 25, city: "New York" }
+]);
+
+// Debe convertir a Collectable antes de usar operaciones de agregación
+const collectable = people.toUnordered();
+
+// 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
+);
+// 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 }
+
+// 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
 
-## 🛠️ Funciones útiles
+#### 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
 
-La librería también exporta varias **guardas de tipo (type guards)** y **herramientas de comparación**:
+#### 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
 
-| Función | Propósito |
-|--------|-----------|
-| `isString(x)` | Guarda de tipo para `string` |
-| `isNumber(x)` | Guarda de tipo para `number` |
-| `isBoolean(x)` | Guarda de tipo para `boolean` |
-| `isIterable(x)` | Comprueba si un objeto es iterable |
-| `useCompare(a, b)` | Función de comparación universal |
-| `useRandom(x)` | Generador de números aleatorios (divertido) |
+#### 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
 
----
+**Suplemento de Ejemplo de Código:**
+```typescript
+import { from } from 'semantic-typescript';
 
-## 🧩 Avanzado: Generadores personalizados y ventanas
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
 
-Puedes crear **generadores personalizados** para flujos controlados o infinitos:
+// Colector desordenado (más rápido)
+const unordered = data.toUnordered();
+const unorderedArray = unordered.toArray(); // Puede mantener orden original [1, 2, 3, ...]
 
-```typescript
-const gen = (accept: BiConsumer<number, bigint>, interrupt: Predicate<number>) => {
-  for (let i = 0; i < 10; i++) {
-    accept(i, BigInt(i));
-    if (i === 5) interrupt(i);
-  }
-};
-
-const s = new Semantic(gen);
-```
+// Colector ordenado
+const ordered = data.toOrdered();
+const orderedArray = ordered.toArray(); // Orden garantizado [1, 2, 3, ...]
 
-O usar **ventanas deslizantes (sliding windows)**:
+// 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], ...
 
-```typescript
-const windowed = ordered.slide(3n, 2n); // Ventanas de tamaño 3, salto de 2
+const tumblingWindows = windowed.tumble(4n); // Ventana de tumble tamaño 4
+// Ventana 1: [1, 2, 3, 4], Ventana 2: [5, 6, 7, 8], ...
 ```
 
----
-
-## 📄 Licencia
-
-Este proyecto está bajo la licencia **MIT** — libre para uso comercial y personal.
+### 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:**
+```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, ...}
+```
 
----
+#### Clases Específicas de Implementación Estadística
 
-## 🙌 Contribuir
+**NumericStatistics<E>**
+- Maneja análisis estadístico de tipo number
+- Todos los cálculos estadísticos retornan tipo number
 
-¡Pull requests, issues y sugerencias son bienvenidos!
+**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:**
+```typescript
+import { from } from 'semantic-typescript';
 
-## 🚀 Resumen rápido
+// Estadísticas numéricas
+const numberData = from([10, 20, 30, 40, 50]);
+const numericStats = numberData.toNumericStatistics();
 
-| Tarea | Método |
-|-------|--------|
-| Manejar nulos con seguridad | `Optional<T>` |
-| Crear un flujo | `from([...])`, `range()`, `fill()` |
-| Transformar datos | `map()`, `filter()` |
-| Ordenar datos | `sorted()`, `toOrdered()` |
-| Sin ordenar (más rápido) | `toUnordered()` ✅ |
-| Agrupar / Agregar | `toMap()`, `group()`, `Collector` |
-| Estadísticas | `NumericStatistics`, `mean()`, `median()`, etc. |
+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();
 
-## 🔗 Enlaces
+console.log(bigintStats.mean()); // 300n
+console.log(bigintStats.summate()); // 1500n
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 Documentación: Ver código fuente / definiciones de tipo
+// Estadísticas usando funciones mapeadoras
+const objectData = from([
+    { value: 15 },
+    { value: 25 }, 
+    { value: 35 },
+    { value: 45 }
+]);
 
----
+const objectStats = objectData.toNumericStatistics();
+const meanWithMapper = objectStats.mean(obj => obj.value); // 30
+const sumWithMapper = objectStats.summate(obj => obj.value); // 120
+```
 
-**Disfruta del procesamiento de datos funcional, seguro y compuesto en TypeScript.** 🚀
+## Ejemplo Completo de Uso
 
---- 
+```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
+}
+
+// 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]
+```
 
-✅ **Recuerda:**  
-- `toUnordered()` → **Sin ordenar, más rápido**  
-- Los demás (`sorted()`, `toOrdered()`, etc.) → **Ordenan los datos**
+## 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.