arckode-framework 1.3.1 → 1.4.0

package/skills/orm/SKILL.md

@@ -1,396 +1,89 @@
-# SKILL: Arckode ORM — Modelos, Queries y Migraciones
+# ORM — Modelos, Queries, Migraciones
 
-> Activar cuando: definir un modelo, escribir queries, crear migración, agregar campo, cambiar schema.
-
----
-
-## 0. NAMING FIJO (no negociable)
-
-```
-Métodos de service:  list() | getById() | create() | update() | delete()
-Controller actions:  index | show | store | update | destroy
-Tablas DB:           snake_case plural → pedidos, lineas_pedido
-Campos del modelo:   camelCase → usuarioId, fechaEntrega
-```
-
----
-
-## 1. DEFINIR UN MODELO — vive en `model.ts` (no en types.ts)
+## Modelo (`model.ts`, no `types.ts`)
 
 ```ts
-// modules/pedidos/model.ts
-import type { ModelDefinition, ORM } from 'arckode-framework'
-
 export const PedidoModel: ModelDefinition = {
-  table: 'pedidos',
+  table: 'pedidos', // snake_case plural
   fields: {
-    // Tipos: 'string' | 'number' | 'boolean' | 'date' | 'text' | 'json'
-    usuarioId:   { type: 'string',  required: true },
-    productoId:  { type: 'string',  required: true },
-    cantidad:    { type: 'number',  required: true },
-    total:       { type: 'number',  required: true },
-    estado:      { type: 'string',  default: 'pendiente' },
-    notas:       { type: 'text',    required: false },
-    metadata:    { type: 'json',    required: false },
+    usuarioId: { type: 'string', required: true },
+    total:     { type: 'number', required: true },
+    estado:    { type: 'string', default: 'pendiente' },
+    metadata:  { type: 'json' },
   },
-  timestamps: true,    // agrega createdAt, updatedAt (RECOMENDADO)
-  softDelete: false,   // true → agrega deletedAt, delete() solo marca, no borra
+  timestamps: true,  // createdAt, updatedAt
+  softDelete: false,  // deletedAt
 }
-
-// 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:**
-- Tabla: snake_case plural (`pedidos`, `lineas_pedido`)
-- Campos: camelCase (`usuarioId`, `fechaEntrega`)
-- 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 — 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.
+## Registrar (en `index.ts` del módulo, NO composition-root)
 
 ```ts
-// 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')
-      // ...
-    }
-  })
+create({ orm }) {
+  registerPedidosModels(orm)
+  const repo = new OrmRepository<PedidoDTO>(orm, 'Pedido')
 }
 ```
 
-**Composition-root solo coordina** — no toca `orm.define()` por módulo:
+## RepositoryAdapter<T> (interface genérica CRUD)
 
 ```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:** `system.init()` (corre todos los `create()`) → `orm.migrate()` → `system.start()`
-
----
-
-## 3. REPOSITORYADAPTER<T> (la interfaz genérica)
-
-El service recibe `RepositoryAdapter<T>`, nunca `ORM` directo:
-
-```ts
-import type { RepositoryAdapter } from 'arckode-framework'
-import { OrmRepository } from 'arckode-framework'
-
-// En el módulo (index.ts):
-const repo = new OrmRepository<PedidoDTO>(orm, 'Pedido')
-const service = new PedidosService(repo)
-
-// En el service:
 class PedidosService {
   constructor(private repo: RepositoryAdapter<PedidoDTO>) {}
 }
 ```
 
-`RepositoryAdapter<T>` te da CRUD básico: `findById`, `findOne`, `findMany`,
-`create`, `update`, `delete`, `count`, `paginate`. Para CRUD simple, esto basta.
+| Método | Retorno |
+|--------|---------|
+| `findMany(filters?, options?)` | `T[]` |
+| `findById(id, select?)` | `T \| null` |
+| `findOne(filters)` | `T \| null` |
+| `create(data)` | `T` |
+| `update(id, data)` | `T \| null` |
+| `delete(id)` | `boolean` |
+| `count(filters?)` | `number` |
+| `paginate(filters?, options)` | `PageResult<T>` |
 
----
+## Repository del dominio (`repository.ts` — opcional)
 
-## 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:
+Crear cuando: filtros repetidos 3+ veces || JOIN/IN/LIKE || nombres del dominio.
 
 ```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) ───
+  findById(id: string) { return this.base.findById(id) }
   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
-
-```ts
-// Buscar muchos con filtros
-await repo.findMany(
-  { estado: 'pendiente', usuarioId: userId },  // filtros (AND implícito)
-  { limit: 20, offset: 0, orderBy: 'createdAt', orderDir: 'desc' }
-)
-
-// Buscar por ID
-const pedido = await repo.findById(id)  // null si no existe
-
-// Buscar uno con filtro
-const pedido = await repo.findOne({ usuarioId, estado: 'activo' })
-
-// Crear
-const nuevo = await repo.create({
-  usuarioId: 'u123',
-  productoId: 'p456',
-  cantidad: 2,
-  total: 200,
-})
-
-// Actualizar (solo los campos pasados)
-const actualizado = await repo.update(id, { estado: 'confirmado' })
-
-// Eliminar
-const ok = await repo.delete(id)
-
-// Contar
-const total = await repo.count({ estado: 'pendiente' })
-
-// Paginación
-const resultado = await repo.paginate(
-  { estado: 'pendiente' },
-  { page: 1, limit: 10 }
-)
-// → { data: PedidoDTO[], total: number, page: 1, limit: 10, totalPages: number }
-```
-
-### Filtros disponibles
-Los filtros son **igualdad exacta** (AND implícito). Para queries complejas (LIKE, IN, JOIN) → implementar `RepositoryAdapter<T>` custom con el driver directo.
-
-```ts
-// ✅ Soportado
-{ estado: 'activo', usuarioId: 'u123' }
-
-// ❌ No soportado directamente — necesita adapter custom
-{ total: { gte: 1000 } }
-{ nombre: { like: '%zapato%' } }
-```
-
----
-
-## 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.
+## Transactor (solo multi-tabla atómica)
 
 ```ts
-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> {
+class WalletsService {
+  constructor(private transactor: Transactor) {}
+  async credit(userId: string, amount: number) {
     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
-  }
-}
-```
-
-**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)
+      const txs     = repos.for<TransactionDTO>('Transaction')
     })
   }
 }
 ```
 
-**Importante:** Si el adapter no soporta transacciones (RecordingDb en tests), el `Transactor`
-ejecuta sin atomicidad — los tests siguen funcionando, solo no son atómicos.
-
----
-
-## 6. MIGRACIONES MANUALES (SQL explícito)
-
-Para cambios que el auto-migrate no puede hacer (renombrar columna, cambiar tipo, agregar índice):
-
-```ts
-// Generar archivo de migración
-// arckode make:migration add_index_to_pedidos
-
-// src/migrations/1716000000_add_index_to_pedidos.ts
-export async function up(adapter: DbAdapter): Promise<void> {
-  await adapter.run('CREATE INDEX IF NOT EXISTS idx_pedidos_usuario ON pedidos(usuario_id)')
-}
-
-export async function down(adapter: DbAdapter): Promise<void> {
-  await adapter.run('DROP INDEX IF EXISTS idx_pedidos_usuario')
-}
-```
-
-```bash
-arckode db:migrate         # corre up() de migraciones pendientes
-arckode db:migrate --rollback  # corre down() de la última migración
-```
-
-**Tabla de control:** `_arckode_migrations` (no tocar manualmente)
-**Tabla de schema drift:** `_arckode_schema` (usada por `orm.migrate()`, separada)
-
----
-
-## 7. DRIFT DETECTION (automático)
-
-`orm.migrate()` detecta:
-- **Columnas nuevas en el modelo** → ejecuta `ALTER TABLE ADD COLUMN` automáticamente
-- **Columnas que dejaron de existir en el modelo** → emite WARNING, NO las elimina (datos en producción)
-
-Si necesitás eliminar una columna → hacerlo con una migración manual explícita.
-
----
-
-## 8. ADAPTERS DE BASE DE DATOS
-
-```ts
-// SQLite (desarrollo)
-import { SqliteAdapter } from 'arckode-framework/adapters/sqlite'
-const db = new SqliteAdapter({ path: './data/db.sqlite' })
-await db.connect()
-
-// MySQL (producción)
-import { MySqlAdapter } from 'arckode-framework/adapters/mysql'
-const db = new MySqlAdapter({
-  host: config.get('DB_HOST'),
-  port: config.get<number>('DB_PORT'),
-  user: config.get('DB_USER'),
-  password: config.get('DB_PASSWORD'),
-  database: config.get('DB_NAME'),
-})
-await db.connect()
-
-// PostgreSQL (producción)
-import { PostgresAdapter } from 'arckode-framework/adapters/postgres'
-const db = new PostgresAdapter({ connectionString: config.get('DATABASE_URL') })
-await db.connect()
-```
-
-**El ORM y todos los services son iguales independientemente del adapter.** Solo cambia el adapter en composition-root.
-
----
-
-## 9. ANTI-PATRONES DE ORM
-
-```ts
-// ❌ ORM directo en controller
-router.get('/pedidos', async (req) => {
-  return orm.findMany('Pedido')  // NO — viola REGLA #12
-})
-
-// ❌ ORM directo en service (debe ser RepositoryAdapter)
-class PedidosService {
-  constructor(private orm: ORM) {}  // NO — viola REGLA #18
-}
-
-// ❌ N+1: ORM dentro de un loop (viola REGLA #17)
-const pedidos = await repo.findMany()
-for (const p of pedidos) {
-  const user = await orm.findById('Usuario', p.usuarioId)  // N queries
-}
-
-// ❌ Dos módulos escribiendo en la misma tabla (viola REGLA #4)
-// módulo-pedidos: orm.update('Inventario', ...)  → NO
-// módulo-inventario es el dueño de la tabla inventario
-
-// ✅ Para queries complejas: adapter custom o dos queries separadas
-const pedidos = await repo.findMany()
-const userIds = [...new Set(pedidos.map(p => p.usuarioId))]
-// luego pasar userIds al módulo de usuarios por acción pública
-```
-
----
+Composition root: `const transactor = new OrmTransactor(orm)`
 
-## 10. CHECKLIST ORM
+## Errores silenciosos
 
-- [ ] El modelo tiene `table` en snake_case plural
-- [ ] Los campos usan camelCase y tipos válidos
-- [ ] `orm.define()` en composition-root, NO en el módulo
-- [ ] `orm.migrate()` después de todos los `define()`
-- [ ] Service recibe `RepositoryAdapter<T>`, no `ORM`
-- [ ] No hay ORM dentro de loops
-- [ ] Migraciones manuales en `src/migrations/` para cambios de schema complejos
+| Error | Señal | Fix |
+|-------|-------|-----|
+| Transactor sin atomicidad | Adapter sin `transaction?()` | No hay fix automático — el ORM ejecuta sin transacción |
+| `findMany` solo igualdad exacta | Filtrar con `{ total: { gte: 1000 } }` no funciona | Adapter custom con driver directo |
+| `model.ts` en `types.ts` | `arckode analyze` → `MODEL_IN_TYPES_FILE` | Mover a `model.ts` |
+| Service recibe ORM directo | `arckode analyze` → `SERVICE_DEPENDS_ON_ORM` | Inyectar `RepositoryAdapter<T>` |
+| N+1 en loop | `arckode analyze` → `N_PLUS_ONE_RISK` | Dos queries separadas: `findMany` + segundo query con ids |
+| Migración manual sin timestamp | Archivos no ordenados | Usar `arckode make:migration` que genera timestamp |