<< All versions
Estructura de
Construcción — siempre
Paginación con
Skill v1.0.0
currentLLM-judged scan90/100abrahamvilchesdelacruz/ididntcatchthat/api-criteria
──Details
PublishedOctober 24, 2026 at 01:32 PM
Content Hashsha256:c06214588d714c69...
Git SHA6a16263a45ba
──Files
Files (1 file, 4.4 KB)
SKILL.md4.4 KBactive
SKILL.md · 140 lines · 4.4 KB
version: "1.0.0" name: api-criteria description: "Convenciones del patrón Criteria en la API: construcción desde query params, uso en use cases y repositorios. Trigger: Al construir queries con filtros, orden o paginación en apps/api/." license: Apache-2.0 metadata: author: AbrahamVilchesDeLaCruz version: "2.0"
When to Use
- Al implementar un endpoint con filtros, orden o paginación
- Al pasar criterios de búsqueda desde controller a use case a repositorio
- Al implementar
match(criteria)en un repositorio TypeORM
Leereferences/docs.mdpara skills relacionadas, ADRs y documentación externa.
Leereferences/repository-criteria.mdpara la implementación completa delmatch(), el flujo Controller → UseCase → Repository y la tabla de operadores.
Estructura de Criteria
Criteria vive en shared/domain/ — es transversal a todos los bounded contexts:
typescript
// shared/domain/criteria.tsexport class Criteria {constructor(readonly filters: Filter[] = [],readonly order: Order | null = null,readonly limit: number | null = null,readonly offset: number | null = null,) {}}export enum FilterOperator {EQ = '=', NEQ = '!=',GT = '>', LT = '<', GTE = '>=', LTE = '<=',LIKE = 'LIKE', IN = 'IN',}export enum OrderDirection { ASC = 'ASC', DESC = 'DESC' }export type Filter = { field: string; operator: FilterOperator; value: unknown; };export type Order = { field: string; direction: OrderDirection; };
Construcción — siempre new Criteria([...])
typescript
// Criteria con filtros, orden y paginaciónconst criteria = new Criteria([{ field: 'userId', operator: FilterOperator.EQ, value: userId },{ field: 'status', operator: FilterOperator.EQ, value: 'active' },{ field: 'startedAt', operator: FilterOperator.GTE, value: today },],{ field: 'startedAt', direction: OrderDirection.DESC },20, // limit0, // offset);// value: null → IS NULL / IS NOT NULL (el repositorio lo traduce)const criteria = new Criteria([{ field: 'finishedAt', operator: FilterOperator.EQ, value: null }, // IS NULL]);
Filtros opcionales — construcción condicional
Cuando no todos los filtros son obligatorios, construir el array dinámicamente:
typescript
const filters: Filter[] = [];if (request.category)filters.push({ field: 'category', operator: FilterOperator.EQ, value: request.category });if (request.subcategory)filters.push({ field: 'subcategory', operator: FilterOperator.EQ, value: request.subcategory });const criteria = new Criteria(filters, null, pageSize, (page - 1) * pageSize);
Paginación con page/pageSize y count()
El cliente envía page + pageSize (más natural que offset). El use case convierte y ejecuta match y count en paralelo:
typescript
// request: { page?: number; pageSize?: number }const page = request.page ?? 1;const pageSize = request.pageSize ?? 20;const criteria = new Criteria(filters, null, pageSize, (page - 1) * pageSize);const [items, total] = await Promise.all([this.repository.match(criteria),this.repository.count(criteria), // mismo Criteria — sin duplicar filtros]);return { data: items.map(i => i.toPrimitives()), total, page, pageSize };
El repositorio debe exponer count(criteria: Criteria): Promise<number> junto a match().
Reglas
Criterialo construyen el use case o domain services — nunca el controller ni el repositorio- El controller pasa primitivos como parte del
Request*— nunca pasa un objetoCriteria - El repositorio solo consume
Criteria— nunca recibe filtros sueltos por parámetro value: nullconEQ/NEQ→IS NULL/IS NOT NULL(nunca= nullen SQL)- Usar
OrderDirectionenum — no strings literales'ASC'/'DESC' - No existe
Criteria.fromPrimitives()— usar el constructor directamente
Anti-patterns
typescript
// ❌ Criteria construido en el controllerconst criteria = new Criteria([...]);await this.searcher.execute(criteria); // el use case recibe Request*, no Criteria// ❌ Repositorio recibe filtros sueltosasync findByUserId(userId: string): Promise<Game[]> {}// ❌ QueryBuilder directo sin Criteriathis.repo.find({ where: { userId } });// ❌ match() que ignora criteriaasync match(criteria: Criteria): Promise<Game[]> {return this.repo.find(); // criteria ignorado}