v2.2.0 - AsyncCollection and Documentation Improvements

English

🎉 What's New

This release introduces AsyncCollection, a powerful Query Builder pattern for deferred execution over async data sources, and significantly improves the Collection documentation.

✨ AsyncCollection Class

A new class that implements the Query Builder pattern with deferred execution:

• Deferred Execution: Operations are registered in an array and executed only when the promise is resolved (await or .then())
• Thenable Implementation: Full Promise-like API with then(), catch(), finally()
• Custom Validators: Extensible operator system for advanced queries ($between, $isPast, etc.)
• ORM Integration: Ready-to-use examples for Prisma, TypeORM, Sequelize, Mongoose, Redis
• 40+ Chainable Methods: Complete API matching Collection plus specific async operations

Example:
```typescript
const users = new AsyncCollection(async ({ operations }) => {
const query = convertToORM(operations);
return await ORM.findAll(query);
});

const result = await users
.where('age', '>=', 18)
.where('status', 'active')
.not({ deleted: true })
.first();
```

📚 Documentation Improvements

New Documentation (9 files in EN/ES/DE):

• Complete API reference (814 lines each)
• User-friendly guides (483 lines each)
• Real-world usage examples (1149 lines)

README Expansion (+968 lines):

• AsyncCollection fundamentals and usage
• Internal workings explanation (101 lines)
• Operations array visualization (70 lines)
• Performance considerations (195 lines)

Collection Documentation Fixes:

• Fixed 4 critical errors (invalid operators, incorrect signatures)
• Added mutation warnings for 6 methods (delete, update, forget, shuffle, sort)
• Added mutability matrix showing which methods modify the collection
• Added complete operators reference ($eq, $gt, $gte, $lt, $lte, $in, $includes, $not)
• Documented return types explicitly for all methods

📦 Package Updates

• Version: 2.1.2 → 2.2.0
• New Exports: AsyncCollection now available from package root

🧪 Testing

All existing tests pass (12/12). AsyncCollection has been tested with real Redis integration.

🔗 Links

• Pull Request: #9
• Issue: #8
• Documentation: https://github.com/arcaelas/collection#readme

---

Español

🎉 Novedades

Esta versión introduce AsyncCollection, un potente patrón Query Builder para ejecución diferida sobre fuentes de datos asíncronas, y mejora significativamente la documentación de Collection.

✨ Clase AsyncCollection

Una nueva clase que implementa el patrón Query Builder con ejecución diferida:

• Ejecución Diferida: Las operaciones se registran en un array y se ejecutan solo cuando se resuelve la promesa (await o .then())
• Implementación Thenable: API completa tipo Promise con then(), catch(), finally()
• Validadores Personalizados: Sistema extensible de operadores para consultas avanzadas ($between, $isPast, etc.)
• Integración con ORMs: Ejemplos listos para usar con Prisma, TypeORM, Sequelize, Mongoose, Redis
• Más de 40 Métodos Encadenables: API completa equivalente a Collection más operaciones async específicas

Ejemplo:
```typescript
const users = new AsyncCollection(async ({ operations }) => {
const query = convertToORM(operations);
return await ORM.findAll(query);
});

const result = await users
.where('age', '>=', 18)
.where('status', 'active')
.not({ deleted: true })
.first();
```

📚 Mejoras en Documentación

Nueva Documentación (9 archivos en EN/ES/DE):

• Referencia completa de API (814 líneas cada uno)
• Guías amigables para usuarios (483 líneas cada uno)
• Ejemplos de uso del mundo real (1149 líneas)

Expansión del README (+968 líneas):

• Fundamentos y uso de AsyncCollection
• Explicación del funcionamiento interno (101 líneas)
• Visualización del array de operaciones (70 líneas)
• Consideraciones de rendimiento (195 líneas)

Correcciones en Documentación de Collection:

• Corregidos 4 errores críticos (operadores inválidos, firmas incorrectas)
• Añadidas advertencias de mutación para 6 métodos (delete, update, forget, shuffle, sort)
• Añadida matriz de mutabilidad mostrando qué métodos modifican la colección
• Añadida referencia completa de operadores ($eq, $gt, $gte, $lt, $lte, $in, $includes, $not)
• Documentados tipos de retorno explícitamente para todos los métodos

📦 Actualizaciones del Paquete

• Versión: 2.1.2 → 2.2.0
• Nuevas Exportaciones: AsyncCollection ahora disponible desde la raíz del paquete

🧪 Testing

Todas las pruebas existentes pasan (12/12). AsyncCollection ha sido probado con integración real de Redis.

🔗 Enlaces

• Pull Request: #9
• Issue: #8
• Documentación: https://github.com/arcaelas/collection#readme