arckode-framework 1.0.7 → 1.1.0

package/skills/orm/SKILL.md

@@ -15,11 +15,11 @@ Campos del modelo:   camelCase → usuarioId, fechaEntrega
 
 ---
 
-## 1. DEFINIR UN MODELO
+## 1. DEFINIR UN MODELO — vive en `model.ts` (no en types.ts)
 
 ```ts
-// En types.ts del módulo
-import type { ModelDefinition } from 'arckode-framework'
+// modules/pedidos/model.ts
+import type { ModelDefinition, ORM } from 'arckode-framework'
 
 export const PedidoModel: ModelDefinition = {
   table: 'pedidos',
@@ -36,6 +36,13 @@ export const PedidoModel: ModelDefinition = {
   timestamps: true,    // agrega createdAt, updatedAt (RECOMENDADO)
   softDelete: false,   // true → agrega deletedAt, delete() solo marca, no borra
 }
+
+// Helper para registrar TODOS los modelos del módulo desde index.ts
+// Si tu módulo tiene 3+ tablas (ej: wallets tiene Wallet, Transaction, Ledger...),
+// definí todos los modelos arriba y registralos todos acá.
+export function registerPedidosModels(orm: ORM): void {
+  orm.define('Pedido', PedidoModel)
+}
 ```
 
 **Reglas de naming:**
@@ -44,23 +51,47 @@ export const PedidoModel: ModelDefinition = {
 - Solo alfanuméricos y guión bajo — `assertSafeIdentifier()` valida esto en ORM
 - No usar palabras reservadas SQL: `order`, `table`, `select`, `where`
 
+**Por qué `model.ts` separado de `types.ts`:**
+- `model.ts` describe la persistencia (schema DB) — cambia con migraciones
+- `types.ts` describe el contrato TS (DTOs, queries) — cambia con la API
+- Conceptos distintos → archivos distintos
+
 ---
 
-## 2. REGISTRAR EL MODELO (composition-root.ts)
+## 2. REGISTRAR EL MODELO — desde `index.ts` del módulo (NO composition-root)
+
+El módulo es dueño de su modelo. Lo registra en su `create()`, no afuera.
 
 ```ts
-import { PedidoModel } from './modules/pedidos/types'
+// modules/pedidos/index.ts
+import { registerPedidosModels } from './model'
+
+export function PedidosModule() {
+  return createModule({
+    create({ orm, ... }) {
+      registerPedidosModels(orm)   // ← acá adentro
+      const repo = new OrmRepository<PedidoDTO>(orm, 'Pedido')
+      // ...
+    }
+  })
+}
+```
+
+**Composition-root solo coordina** — no toca `orm.define()` por módulo:
 
-// ANTES de llamar system.start()
-orm.define('Pedido', PedidoModel)
+```ts
+// composition-root.ts
+system.addModule(PedidosModule())   // el módulo se autorregistra
+system.init()
 await orm.migrate()    // CREATE TABLE IF NOT EXISTS + drift detection
+await system.start()
 ```
 
-**Orden importa:** `orm.define()` → `orm.migrate()` → `system.start()`
+**Orden importa:** `system.init()` (corre todos los `create()`) → `orm.migrate()` → `system.start()`
 
 ---
 
-## 3. REPOSITORYADAPTER<T> (la interfaz correcta)
+## 3. REPOSITORYADAPTER<T> (la interfaz genérica)
 
 El service recibe `RepositoryAdapter<T>`, nunca `ORM` directo:
 
@@ -78,6 +109,61 @@ class PedidosService {
 }
 ```
 
+`RepositoryAdapter<T>` te da CRUD básico: `findById`, `findOne`, `findMany`,
+`create`, `update`, `delete`, `count`, `paginate`. Para CRUD simple, esto basta.
+
+---
+
+## 3b. REPOSITORY DEL DOMINIO (`repository.ts` — OPCIONAL)
+
+`RepositoryAdapter<T>` es genérico. Cuando necesitás expresar queries con
+**nombres del dominio**, creás un `repository.ts` por módulo:
+
+```ts
+// modules/wallets/repository.ts
+import type { RepositoryAdapter } from 'arckode-framework'
+import type { WalletDTO, WalletCurrency } from './types'
+
+export class WalletsRepository {
+  constructor(private base: RepositoryAdapter<WalletDTO>) {}
+
+  // Delegamos los métodos genéricos
+  findById(id: string)   { return this.base.findById(id) }
+  create(data: Omit<WalletDTO, 'id'>) { return this.base.create(data) }
+  update(id: string, data: Partial<Omit<WalletDTO, 'id'>>) { return this.base.update(id, data) }
+
+  // ─── Métodos del dominio (lo realmente importante) ───
+  findByUserAndCurrency(userId: string, currency: WalletCurrency) {
+    return this.base.findOne({ user_id: userId, currency })
+  }
+
+  findActiveByUser(userId: string) {
+    return this.base.findMany({ user_id: userId, status: 'active' })
+  }
+}
+```
+
+**¿Por qué?** El service ahora habla en lenguaje del dominio:
+```ts
+// ❌ Service conoce nombres de columna (acoplado a la DB)
+const wallet = await this.repo.findOne({ user_id: userId, currency })
+
+// ✅ Service habla el dominio (desacoplado)
+const wallet = await this.wallets.findByUserAndCurrency(userId, currency)
+```
+
+Si mañana renombrás la columna `user_id → owner_id`, cambiás SOLO `repository.ts`.
+El service no se entera.
+
+**¿Cuándo crear repository.ts?**
+1. El service repite los mismos filtros en 3+ métodos
+2. Necesitás JOIN, IN, LIKE (el ORM builtin no los soporta)
+3. Querés nombres del dominio
+
+**¿Cuándo NO?**
+- CRUD pelado — `OrmRepository<T>` directo, sin agregar archivo
+- Cada filtro se usa una sola vez
+
 ---
 
 ## 4. QUERIES DISPONIBLES
@@ -134,20 +220,70 @@ Los filtros son **igualdad exacta** (AND implícito). Para queries complejas (LI
 
 ---
 
-## 5. TRANSACCIONES
+## 5. TRANSACCIONES MULTI-TABLA → usar `Transactor`
+
+**El service NO recibe `ORM` directamente** (viola Regla #18). Recibe `Transactor`,
+una interfaz que el framework provee para atomicidad cross-modelo.
 
 ```ts
-// En el service — si necesitás atomicidad entre operaciones
-await orm.transaction(async (tx) => {
-  const txRepo = new OrmRepository<PedidoDTO>(tx, 'Pedido')
-  const txInventarioRepo = new OrmRepository<InventarioDTO>(tx, 'Inventario')
+import type { Transactor, RepositoryAdapter } from 'arckode-framework'
+
+// service.ts (al root del módulo)
+export class WalletsService {
+  constructor(
+    private walletRepo: RepositoryAdapter<WalletDTO>,
+    private transactor: Transactor,    // ← interfaz, no ORM concreto
+  ) {}
+
+  async creditDeposit(userId: string, amount: number): Promise<TransactionDTO> {
+    return this.transactor.run(async (repos) => {
+      // Obtener repos transaccionales tipados para cualquier modelo
+      const wallets = repos.for<WalletDTO>('Wallet')
+      const txs    = repos.for<TransactionDTO>('Transaction')
+      const ledger = repos.for<LedgerEntryDTO>('LedgerEntry')
+
+      const wallet = await wallets.findOne({ user_id: userId })
+      if (!wallet) throw new NotFoundError('Wallet no encontrada')
+
+      const newBalance = Number(wallet.balance) + amount
+
+      const tx = await txs.create({ user_id: userId, type: 'deposit', amount, ... })
+      await ledger.create({ transaction_id: tx.id, entry_type: 'credit', amount, ... })
+      await wallets.update(wallet.id, { balance: newBalance })
+
+      return tx
+    })
+    // Si CUALQUIER operación dentro de run() falla → rollback automático completo
+  }
+}
+```
 
-  await txRepo.create(datosPedido)
-  await txInventarioRepo.update(inventarioId, { stock: stockNuevo })
-})
+**Composition root:**
+```ts
+import { OrmTransactor } from 'arckode-framework'
+
+const transactor = new OrmTransactor(orm)  // implementación SQL del Transactor
+const service = new WalletsService(walletRepo, transactor)
+```
+
+**Para Prisma/Drizzle/MongoDB:** implementar `Transactor` custom. El service NO cambia.
+
+```ts
+class PrismaTransactor implements Transactor {
+  constructor(private prisma: PrismaClient) {}
+  async run<R>(fn: (repos: TransactionalRepos) => Promise<R>): Promise<R> {
+    return this.prisma.$transaction(async (tx) => {
+      const repos: TransactionalRepos = {
+        for: (modelName) => new PrismaRepo(tx[modelName]),
+      }
+      return fn(repos)
+    })
+  }
+}
 ```
 
-**Importante:** Si el adapter no soporta transacciones (MemoryDb, RecordingDb), el ORM ejecuta sin transacción — no falla, solo no es atómico.
+**Importante:** Si el adapter no soporta transacciones (RecordingDb en tests), el `Transactor`
+ejecuta sin atomicidad — los tests siguen funcionando, solo no son atómicos.
 
 ---
 

package/skills/realtime/SKILL.md

@@ -220,7 +220,7 @@ create({ logger, orm, router, ws }: ModuleDependencies) {
   ...
 }
 
-// En actions/service.ts
+// En service.ts (al root del módulo)
 class PedidosService {
   constructor(
     private repo: RepositoryAdapter<PedidoDTO>,

package/skills/services/SKILL.md

@@ -82,7 +82,7 @@ create({ logger, orm, cache, router, auth, mail }: ModuleDependencies) {
   ...
 }
 
-// En actions/service.ts
+// En service.ts (al root del módulo)
 class AuthService {
   constructor(
     private repo: RepositoryAdapter<UserDTO>,

package/skills/testing/SKILL.md

@@ -12,7 +12,7 @@ import { describe, test, expect, beforeEach, mock } from 'bun:test'
 // createRecordingOrm / createSilentLogger / createNullCache NO existen — nunca usar esos nombres
 import { silentLogger, createRecordingDb } from 'arckode-framework/testing'
 import type { RepositoryAdapter, CacheAdapter } from 'arckode-framework'
-import { ProductosService } from '../actions/service'
+import { ProductosService } from '../service'
 import type { ProductoDTO } from '../types'
 
 // silentLogger es factory function — SIEMPRE llamar con ()