@archi-code/ddd 0.0.0-stage → 3.0.0-alpha.2

package/ddd-skills/ddd-value-objects-entidades/references/persistencia-valores.md

@@ -0,0 +1,88 @@
+# Persistir value objects sin deformar el modelo
+
+## Principio
+
+El modelo de datos se subordina al de dominio. Claves, integridad referencial e índices no deben dictar cómo se modelan los objetos [IDDD cap. 6]. El informe y la analítica, mejor sobre un modelo de datos propio y no sobre las tablas de producción [IDDD cap. 6].
+
+Antes de convertir un valor en entidad "porque tiene tabla", responde [IDDD cap. 6]:
+1. ¿Es una cosa del dominio o mide, cuantifica o describe una cosa?
+2. ¿Tiene la mayoría de las características de valor?
+3. ¿Lo hago entidad solo porque el modelo de datos lo guarda como entidad?
+4. ¿El dominio exige identidad única, me importan los ejemplares y su continuidad de cambio?
+
+"Describe, sí, sí, no" → value object.
+
+## Opciones
+
+| Opción | Cuándo | Notas |
+|---|---|---|
+| Columnas en la fila del padre | Un único value object (`total_amount`, `total_currency`) | La opción por defecto y la más limpia [IDDD cap. 6] |
+| Varios valores serializados en una columna (JSON) | Colecciones pequeñas que no se consultan por dentro | Cuidado con el tamaño de columna y la consulta [IDDD cap. 6]. En PostgreSQL, `jsonb` |
+| Tabla propia para una colección | Colecciones grandes o que se consultan | La fila tiene clave técnica, pero en el modelo sigue siendo valor [IDDD cap. 6] |
+| Tabla de unión | Colecciones referenciadas | Variante de la anterior [IDDD cap. 6] |
+| Estado como enum | Tipos estándar | Guarda el código, no un objeto [IDDD cap. 6] |
+
+*DDD in PHP* resume las mismas alternativas (valor embebido, serialización como LOB y mapeo ad hoc con el ORM) [PHP: Value Objects].
+
+## En TypeScript
+
+`[Fuera de los libros: convención de @archi-code/ddd]`
+* Nada de mappers escritos a mano ni decoradores de ORM en las clases de dominio. El agregado da sus datos planos con `toPrimitives()` y se rehace con `static fromPrimitives()`; el repositorio solo llama a `order.toPrimitives()` y `Order.fromPrimitives(...)`, y la versión de concurrencia la recuerda él mismo en un `WeakMap<Order, number>`, nunca el agregado. Nada comprueba en ejecución que no se pierda ningún campo privado: lo prueba el spec del agregado con el viaje de ida y vuelta (`Order.fromPrimitives(order.toPrimitives()).toPrimitives()` igual a `order.toPrimitives()`).
+* Los primitivos ya dan la forma de cada opción de la tabla: un value object simple es su valor, un `Composite` es un objeto (`shippingAddress: { street, city, country }`), una lista de composites es una lista de objetos (`lines: { items: [...] }`) y un `EnumType` es la opción del enum (`status: 'pending'`).
+* Con un almacén de documentos (MongoDB), los primitivos se guardan tal cual. Con tablas, el repositorio decide cómo se reparten en columnas: el formato de la fila sigue en infraestructura y no deforma el modelo.
+
+```ts
+import type { PrimitiveTypes } from '@archi-code/ddd/domain';
+
+type OrderPrimitives = PrimitiveTypes<Order>;
+
+interface OrderRow {
+  id: string;
+  customer_id: string;
+  ship_street: string;
+  ship_city: string;
+  ship_country: string;
+  lines: OrderPrimitives['lines']['items'];
+  status: string;
+  stock_reservation: string | null;
+  payment_authorization: OrderPrimitives['paymentAuthorization'];
+  version: number;
+}
+
+function rowOf(order: Order, version: number): OrderRow {
+  const primitives = order.toPrimitives();
+  return {
+    id: primitives.id,
+    customer_id: primitives.customerId,
+    ship_street: primitives.shippingAddress.street,
+    ship_city: primitives.shippingAddress.city,
+    ship_country: primitives.shippingAddress.country,
+    lines: primitives.lines.items,
+    status: primitives.status,
+    stock_reservation: primitives.stockReservation,
+    payment_authorization: primitives.paymentAuthorization,
+    version: version + 1,
+  };
+}
+
+function orderOf(row: OrderRow): Order {
+  return Order.fromPrimitives({
+    id: row.id,
+    customerId: row.customer_id,
+    lines: { items: row.lines },
+    shippingAddress: {
+      street: row.ship_street,
+      city: row.ship_city,
+      country: row.ship_country,
+    },
+    status: row.status as Status,
+    stockReservation: row.stock_reservation,
+    paymentAuthorization: row.payment_authorization,
+  });
+}
+```
+
+`Order`, `ShippingAddress` y `Status` son los de `ddd-skills/ddd-agregados/references/implementacion-ts.md`. La dirección va en columnas de la fila del padre, las líneas y la autorización de pago en columnas JSON (`jsonb` en PostgreSQL) y el estado como su código. Con el driver `pg`, una columna `jsonb` se lee ya como objeto (la fecha de caducidad de la autorización llega como texto ISO, que `ExpiresAt` convierte), y al escribir el parámetro se pasa como `JSON.stringify(row.lines)` (un array sin convertir lo enviaría como array de PostgreSQL). La `version` se guarda junto a los primitivos, nunca dentro: `rowOf` recibe la que el repositorio recuerda para ese agregado en su `WeakMap` (`0` si es nuevo) y, tras cargar con `orderOf`, el repositorio anota `row.version` en ese `WeakMap`; la consulta con la condición de versión y cuándo se actualiza el `WeakMap` están en `ddd-skills/ddd-repositorios-persistencia/GUIA.md`.
+
+* Al cargar, `fromPrimitives` rehace cada value object con su constructor, que valida: un dato corrupto falla al cargar (`ValidationException`) en vez de propagarse. No se repiten reglas de creación ni se registran eventos.
+* Con Prisma o Drizzle, el esquema es de infraestructura y el repositorio sigue pasando por `order.toPrimitives()` y `Order.fromPrimitives()`.

package/ddd-skills/ddd-value-objects-entidades/references/specification-y-diseno-flexible.md

@@ -0,0 +1,119 @@
+# Specification y diseño flexible (Supple Design)
+
+Contenido: 1. Diseño flexible · 2. Specification · 3. Specification para consultar · 4. Errores frecuentes
+
+## 1. Diseño flexible
+
+Conjunto de patrones de Evans para que el modelo sea fácil de usar y de cambiar. IDDD aplica varios de ellos de forma explícita; los que no aparecen en las fuentes del proyecto se marcan `[Fuera de los libros: Evans, Domain-Driven Design, 2003]`.
+
+### Intention Revealing Interfaces
+
+Los nombres de clases y métodos dicen **qué** consiguen, en el lenguaje ubicuo, no **cómo**. IDDD lo ilustra con `Tenant.activate()` y `deactivate()` en lugar de `setActive(boolean)`: varios setters para una sola petición vuelven ambigua la intención y complican publicar un único evento con significado [IDDD cap. 5, citando a Evans]. IDDD defiende también nombres fluidos (`valuePercentage()` frente a `getValuePercentage()`) [IDDD cap. 6].
+
+```ts
+order.setStatus('cancelled');
+price.amount.value * 21 / 100;
+```
+
+```ts
+order.cancel(new CancellationReason('customer request'), clock);
+price.percentage('21');
+```
+
+El primero revela cómo; el segundo, la intención (`CancellationReason` es un `Required(StringType)` con nombre y `percentage` el de `Money` en `ddd-skills/ddd-value-objects-entidades/references/value-objects-ts.md`).
+
+### Side-Effect-Free Functions
+
+Las operaciones que devuelven un resultado no cambian estado observable. En los value objects todos los métodos lo son, porque son inmutables [IDDD cap. 6]. Pasa solo valores como argumentos, no entidades: así se puede demostrar que no hay efectos secundarios [IDDD cap. 6]. Aplica también a entidades: separa consultas (devuelven algo, no cambian nada) de comandos (cambian estado, no devuelven datos de negocio).
+
+### Assertions
+
+`[Fuera de los libros: Evans 2003]`. Cuando una operación sí tiene efectos, haz explícitos sus resultados y las invariantes que mantiene: en los tests (tests de aceptación con lenguaje del negocio) y en guardas del código. IDDD trata las guardas de autoencapsulación como aserciones que protegen el estado [IDDD cap. 5].
+
+### Conceptual Contours
+
+`[Fuera de los libros: Evans 2003]`. Divide los objetos y operaciones siguiendo las líneas naturales del dominio, de modo que los cambios habituales del negocio afecten a una sola pieza. Señal práctica: si cada cambio de regla toca muchas clases a la vez, los contornos están mal trazados. Es la misma intuición que lleva a los "todos conceptuales" de los value objects [IDDD cap. 6].
+
+### Standalone Classes
+
+`[Fuera de los libros: Evans 2003]`. Reduce las dependencias de cada clase al mínimo imprescindible. Los value objects que solo dependen de su propio tipo y de sus atributos son el caso ideal, y IDDD recomienda exactamente eso [IDDD cap. 6].
+
+### Closure of Operations
+
+`[Fuera de los libros: Evans 2003]`. Cuando sea natural, una operación devuelve el mismo tipo que recibe: `Money.add(Money): Money`, `DateRange.extendTo(EndDate): DateRange`, `Specification.and(Specification): Specification`. Permite combinar operaciones sin introducir conceptos nuevos.
+
+## 2. Specification
+
+Un objeto que responde si otro objeto cumple un criterio del negocio. Evans y Fowler lo describen; IDDD lo propone como forma de implementar validadores de objetos completos [IDDD cap. 5, citando a Evans y Fowler] y *DDD in PHP* lo usa para consultar repositorios [PHP: Repositories; PHP: Factories].
+
+Tres usos clásicos `[Fuera de los libros: Evans 2003]`:
+1. **Validar:** ¿este objeto cumple la regla?
+2. **Seleccionar:** ¿qué objetos de una colección la cumplen?
+3. **Construir a la carta:** crear algo que cumpla la regla.
+
+Cuándo merece la pena: la regla tiene nombre en el lenguaje ("cliente moroso", "pedido apto para envío urgente"), se usa en varios sitios o se combina con otras. Si es una condición de una línea usada una vez, un método del agregado basta.
+
+No se escribe la base ni las combinaciones: `Specification<T>` viene de `@archi-code/ddd/domain`. Declara `isSatisfiedBy` como abstracto y da `and`, `or` y `not`, que devuelven otra `Specification<T>` (clausura de operaciones: se pueden seguir encadenando) y cortan en cuanto la respuesta está decidida. `and` y `or` aceptan cualquier `SatisfiedBy<T>` (un objeto con `isSatisfiedBy`), que es la interfaz `Specification` de los libros [IDDD cap. 5].
+
+Reglas de negocio con nombre:
+
+```ts
+import { Specification } from '@archi-code/ddd/domain';
+
+export interface StockSnapshot {
+  covers(sku: Sku, quantity: Quantity): boolean;
+}
+
+export class EligibleForExpressShipping extends Specification<Order> {
+  constructor(private readonly centralStock: StockSnapshot) {
+    super();
+  }
+
+  isSatisfiedBy(order: Order): boolean {
+    return (
+      order.shippingAddress.country.value === 'ES' &&
+      order.lines.items.every((line) => this.centralStock.covers(line.sku, line.quantity))
+    );
+  }
+}
+
+export class OrderAbove extends Specification<Order> {
+  constructor(private readonly threshold: Money) {
+    super();
+  }
+
+  isSatisfiedBy(order: Order): boolean {
+    return order.total().covers(this.threshold);
+  }
+}
+
+const freeExpress = new EligibleForExpressShipping(stock).and(
+  new OrderAbove(Money.fromPrimitives({ amount: 5000, currency: 'EUR' })),
+);
+freeExpress.isSatisfiedBy(order);
+```
+
+`Order`, `Money`, `Sku` y `Quantity` son los de `ddd-skills/ddd-agregados/references/implementacion-ts.md`. La especificación recibe datos de otros agregados ya cargados (`StockSnapshot`), no repositorios: misma regla que para los agregados [IDDD cap. 10].
+
+## 3. Specification para consultar
+
+*DDD in PHP* propone sustituir los métodos `find...` que crecen sin fin en los repositorios por un método `query(specification)` [PHP: Repositories; PHP: Factories]. Aquí no se hace: el repositorio solo obtiene y persiste, sin lógica ni consultas de negocio `[Fuera de los libros: convención de @archi-code/ddd]`. Una selección con nombre del negocio ("pedidos pendientes desde hace más de un día") es una consulta de lectura: una interfaz en `application/`, implementada en infraestructura directamente sobre la base de datos, que devuelve ids o DTOs.
+
+```ts
+export interface StaleOrders {
+  ids(pendingSince: Date, limit: number): Promise<OrderId[]>;
+}
+```
+
+La interfaz vive en `application/` y su implementación (`PgStaleOrders`, una consulta SQL; los filtros pueden escribirse con `@archi-code/criteria`) en infraestructura. Quien la usa (un programador de tareas, por ejemplo) ejecuta un caso de uso por cada id, y ese caso de uso carga el pedido con `AggregateFinder<Order>`.
+
+La Specification se queda para validar, seleccionar sobre datos ya cargados o construir.
+
+Úsalo con mesura `[Fuera de los libros]`: si acabas construyendo un lenguaje de consultas genérico, has reinventado el ORM. Para pantallas, mejor consultas de lectura (`ddd-skills/ddd-repositorios-persistencia/GUIA.md`).
+
+## 4. Errores frecuentes
+
+* Especificaciones genéricas sin nombre de negocio (`FieldEqualsSpecification`).
+* Especificaciones que cargan datos por su cuenta (inyectan repositorios).
+* Usar Specification para invariantes del agregado: la invariante se protege dentro del agregado, siempre; la especificación sirve para validar, seleccionar o construir.
+* Interfaces que revelan intención en el nombre pero no en el comportamiento: `confirm()` que en realidad también envía correos.

package/ddd-skills/ddd-value-objects-entidades/references/validacion.md

@@ -0,0 +1,96 @@
+# Validación
+
+## Tres niveles
+
+Que todos los atributos sean válidos no implica que el objeto lo sea, y que cada objeto sea válido no implica que su composición lo sea [IDDD cap. 5]. Por eso hay tres niveles [IDDD cap. 5; PHP: Entities]:
+
+| Nivel | Qué comprueba | Dónde |
+|---|---|---|
+| Atributo | Un valor aislado: formato, rango, obligatoriedad | Constructor del value object (`Required(...)` y `@Validations`); un `Composite` con reglas `custom` para lo que combina sus campos |
+| Objeto completo | Combinaciones de atributos de una entidad | La propia entidad en sus métodos, o un validador separado en el mismo módulo (un servicio de dominio o `Specification`s) |
+| Composición | Varios objetos o agregados juntos | Servicio de dominio que recibe lo cargado o lee por `AggregateFinder` |
+
+IDDD llama a lo del primer nivel más bien **aserciones** que protegen el estado, no "validación" en el sentido de un framework [IDDD cap. 5]. Con el paquete, un value object que existe es válido: su constructor convierte, comprueba `Required` y ejecuta todas sus reglas, y si falla alguna lanza una `ValidationException` con todas `[Fuera de los libros: convención de @archi-code/ddd]`. A eso se suma la autorización, que no es validación del modelo: la comprueba el caso de uso (`NotAllowedException`).
+
+## Objeto completo: ¿dentro o fuera de la entidad?
+
+IDDD advierte que meter toda la validación en la entidad le da demasiadas responsabilidades y que la validación suele cambiar más que la entidad; propone un validador separado (Specification o Strategy) en el mismo módulo, con validación diferida [IDDD cap. 5].
+
+Criterio práctico `[Fuera de los libros]`:
+* **Invariantes** (lo que nunca puede ser falso: un pedido sin líneas) → en la entidad o el agregado, siempre. Se tratan en `ddd-skills/ddd-agregados/GUIA.md`.
+* **Reglas de completitud o calidad** que dependen del momento ("para publicar, la ficha necesita al menos tres fotos") → validador separado, invocado cuando toca.
+
+## Patrón de notificación
+
+Para devolver todos los errores en vez de parar en el primero, IDDD y *DDD in PHP* usan un manejador de notificación que recibe los fallos [IDDD cap. 5; PHP: Entities]. Con el paquete no se escribe ese manejador `[Fuera de los libros: convención de @archi-code/ddd]`:
+
+* **Entrada de un caso de uso:** `ValueObjectBuilder.build({...})` ejecuta todas las factorías y lanza una sola `ValidationException` cuyos `errors` (`ValidationIssue`: `{ field, code, message }`) llevan el campo y el código de cada problema; `ValueObjectBuilder.buildList` nombra los elementos de una lista por su posición (`lines.1.quantity`).
+
+```ts
+import { ValueObjectBuilder } from '@archi-code/ddd/application';
+
+const command = ValueObjectBuilder.build({
+  customerId: () => new CustomerId(input.customerId),
+  email: () => new Email(input.email),
+  lines: () => ValueObjectBuilder.buildList(input.lines, (line) => OrderLine.fromPrimitives(line)),
+});
+// input { customerId: 'x', email: 'ana', lines: [...] } → una ValidationException:
+// errors: [
+//   { field: 'customerId', code: 'DOM003', message: 'Validation Error: Expected a valid UUID, but received "x".' },
+//   { field: 'email', code: 'isEmail', message: 'Email: Value does not satisfy isEmail' },
+// ]
+```
+
+* **Un objeto ya construido** (la ficha de un producto que se quiere publicar, en el contexto de Catálogo): un servicio de dominio recoge los `ValidationIssue` y lanza una sola `new ValidationException(issues)`.
+
+```ts
+import { ValidationException } from '@archi-code/ddd/domain';
+import type { ValidationIssue } from '@archi-code/ddd/domain';
+
+export class ListingReadyToPublish {
+  check(listing: ProductListing): void {
+    const issues: ValidationIssue[] = [];
+    if (listing.photos.value < 3) {
+      issues.push({ field: 'photos', code: 'tooFewPhotos', message: 'At least 3 photos' });
+    }
+    if (!listing.description.isLongEnough()) {
+      issues.push({ field: 'description', code: 'tooShort', message: 'Describe the product' });
+    }
+    if (listing.price.isZero()) {
+      issues.push({ field: 'price', code: 'zeroPrice', message: 'A listing needs a price' });
+    }
+    if (issues.length > 0) {
+      throw new ValidationException(issues);
+    }
+  }
+}
+```
+
+`ProductListing` es un agregado con `photos` (`PhotoCount`), `description` (`ListingDescription`, con su método `isLongEnough()`) y `price` (`Money`). Nunca captures la `ValidationException` de un value object para quedarte con un valor inválido.
+
+## Validación diferida y estados intermedios
+
+Un agregado puede estar en un estado intermedio legítimo en el que no procede validar. Se puede modelar con un estado y publicar un evento cuando la validación ya tiene sentido [IDDD cap. 5].
+
+## Interfaz frente a dominio
+
+* La interfaz valida formato para dar buena experiencia (campo vacío, longitud). Eso no sustituye a la validación del modelo, donde vive el conocimiento profundo [IDDD cap. 4].
+* No dupliques reglas de negocio en el esquema del DTO. Si el DTO comprueba "email válido" y `new Email(...)` también, que el DTO solo compruebe que es un `string` y deje la regla al value object `[Fuera de los libros]`. La entrada de un caso de uso llega sin validar a propósito: `toCommand` construye los value objects, así que todos los adaptadores pasan por las mismas reglas.
+
+## Errores con nombre
+
+`[Fuera de los libros]`
+* Una clase de error por regla de negocio (`OrderMustHaveLines`, `CurrencyMismatch`), con un código estable para traducir a mensajes de usuario y a códigos HTTP en el adaptador. Con el paquete, una subclase de `DomainException` (de `@archi-code/ddd/domain`) con su código en el segundo argumento.
+* No uses `Error('invalid')` en el dominio.
+
+```ts
+import { DomainException } from '@archi-code/ddd/domain';
+
+export class OrderMustHaveLines extends DomainException {
+  constructor() {
+    super('An order needs at least one line', ['ORD002']);
+  }
+}
+```
+
+`error.code` es `'ORD002'`. En la entrada, `ExceptionClassifier.classify(error)` (de `@archi-code/ddd/infrastructure`) da el tipo de fallo sin tablas por excepción: `ExceptionKind.Invalid` para una `ValidationException` o cualquier `DomainException` (422 en HTTP) y `ExceptionKind.Malformed` para un error de conversión u obligatoriedad lanzado solo (400); el punto de entrada cambia el estado de un código cuando el negocio lo pide (`ORD001` → 409).