arckode-framework 1.0.0

package/adapters/__tests__/mysql.test.ts

@@ -0,0 +1,283 @@
+// adapters/__tests__/mysql.test.ts
+// Testea MySQLAdapter con mocks de mysql2/promise — sin servidor real.
+// Para tests de integración real ver el bloque comentado al final.
+
+import { describe, it, expect, beforeAll, beforeEach, mock } from 'bun:test'
+import type { MySQLAdapter } from '../mysql'
+
+// ── Mocks de conexión (transacciones) ────────────────────────────────────────
+const connMock = {
+  beginTransaction: mock(async () => {}),
+  execute:          mock(async (): Promise<unknown[]> => [[], []]),
+  commit:           mock(async () => {}),
+  rollback:         mock(async () => {}),
+  release:          mock(() => {}),
+}
+
+// ── Mock del pool ─────────────────────────────────────────────────────────────
+const poolMock = {
+  getConnection: mock(async () => connMock),
+  execute:       mock(async (): Promise<unknown[]> => [[], []]),
+  end:           mock(async () => {}),
+}
+
+// Registrar el mock ANTES de que el adapter importe mysql2/promise.
+// El dynamic import en beforeAll garantiza que mysql2/promise ya está mockeado.
+mock.module('mysql2/promise', () => ({
+  default: { createPool: mock(() => poolMock) },
+}))
+
+// ── Carga diferida del adapter ────────────────────────────────────────────────
+let Adapter: typeof MySQLAdapter
+
+beforeAll(async () => {
+  const mod = await import('../mysql')
+  Adapter = mod.MySQLAdapter
+})
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function resetMocks() {
+  connMock.beginTransaction.mockClear()
+  connMock.execute.mockClear()
+  connMock.commit.mockClear()
+  connMock.rollback.mockClear()
+  connMock.release.mockClear()
+  poolMock.getConnection.mockClear()
+  poolMock.execute.mockClear()
+  poolMock.end.mockClear()
+}
+
+function makeAdapter() {
+  return new Adapter({ host: 'localhost', user: 'test', password: 'test', database: 'testdb' })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('MySQLAdapter', () => {
+  beforeEach(resetMocks)
+
+  // ── connect() ───────────────────────────────────────────────────────────────
+  describe('connect()', () => {
+    it('crea el pool y verifica la conexión con getConnection+release', async () => {
+      const adapter = makeAdapter()
+      await adapter.connect()
+
+      expect(poolMock.getConnection).toHaveBeenCalledTimes(1)
+      expect(connMock.release).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  // ── query() ─────────────────────────────────────────────────────────────────
+  describe('query()', () => {
+    let adapter: MySQLAdapter
+
+    beforeEach(async () => {
+      adapter = makeAdapter()
+      await adapter.connect()
+      resetMocks() // limpia las calls de connect()
+    })
+
+    it('retorna el array de filas', async () => {
+      const filas = [{ id: '1', nombre: 'Laptop' }, { id: '2', nombre: 'Mouse' }]
+      poolMock.execute.mockImplementation(async () => [filas, []])
+
+      const result = await adapter.query('SELECT * FROM productos')
+      expect(result).toEqual(filas)
+    })
+
+    it('pasa los params al execute del pool', async () => {
+      poolMock.execute.mockImplementation(async () => [[{ id: '1' }], []])
+
+      await adapter.query('SELECT * FROM productos WHERE id = ?', ['1'])
+      expect(poolMock.execute).toHaveBeenCalledWith(
+        'SELECT * FROM productos WHERE id = ?',
+        ['1'],
+      )
+    })
+
+    it('retorna array vacío cuando no hay resultados', async () => {
+      poolMock.execute.mockImplementation(async () => [[], []])
+
+      const result = await adapter.query('SELECT * FROM productos WHERE id = ?', ['999'])
+      expect(result).toEqual([])
+    })
+  })
+
+  // ── run() ────────────────────────────────────────────────────────────────────
+  describe('run()', () => {
+    let adapter: MySQLAdapter
+
+    beforeEach(async () => {
+      adapter = makeAdapter()
+      await adapter.connect()
+      resetMocks()
+    })
+
+    it('INSERT retorna changes y lastId como string', async () => {
+      poolMock.execute.mockImplementation(async () => [{ affectedRows: 1, insertId: 42 }, []])
+
+      const result = await adapter.run(
+        'INSERT INTO productos (nombre, precio) VALUES (?, ?)',
+        ['Laptop', 999],
+      )
+
+      expect(result.changes).toBe(1)
+      expect(result.lastId).toBe('42')
+    })
+
+    it('UPDATE retorna changes y lastId undefined (insertId === 0)', async () => {
+      poolMock.execute.mockImplementation(async () => [{ affectedRows: 3, insertId: 0 }, []])
+
+      const result = await adapter.run(
+        'UPDATE productos SET activo = ? WHERE categoria = ?',
+        [false, 'perifericos'],
+      )
+
+      expect(result.changes).toBe(3)
+      expect(result.lastId).toBeUndefined()
+    })
+
+    it('DELETE retorna changes y sin lastId', async () => {
+      poolMock.execute.mockImplementation(async () => [{ affectedRows: 1, insertId: 0 }, []])
+
+      const result = await adapter.run('DELETE FROM productos WHERE id = ?', ['1'])
+      expect(result.changes).toBe(1)
+      expect(result.lastId).toBeUndefined()
+    })
+  })
+
+  // ── transaction() ────────────────────────────────────────────────────────────
+  describe('transaction()', () => {
+    let adapter: MySQLAdapter
+
+    beforeEach(async () => {
+      adapter = makeAdapter()
+      await adapter.connect()
+      resetMocks()
+    })
+
+    it('adquiere conexión, abre transacción, ejecuta fn y hace commit', async () => {
+      const filas = [{ id: '1' }]
+      connMock.execute.mockImplementation(async () => [filas, []])
+
+      const result = await adapter.transaction(async (tx) => {
+        return tx.query('SELECT * FROM productos')
+      })
+
+      expect(poolMock.getConnection).toHaveBeenCalledTimes(1)
+      expect(connMock.beginTransaction).toHaveBeenCalledTimes(1)
+      expect(connMock.commit).toHaveBeenCalledTimes(1)
+      expect(connMock.rollback).not.toHaveBeenCalled()
+      expect(connMock.release).toHaveBeenCalledTimes(1)
+      expect(result).toEqual(filas)
+    })
+
+    it('el adapter de transacción usa la conexión, no el pool', async () => {
+      connMock.execute.mockImplementation(async () => [[{ total: 5 }], []])
+
+      await adapter.transaction(async (tx) => {
+        await tx.query('SELECT COUNT(*) as total FROM productos')
+        await tx.run('INSERT INTO auditoria (evento) VALUES (?)', ['sync'])
+      })
+
+      // Ambas llamadas van a connMock.execute, NO a poolMock.execute
+      expect(connMock.execute).toHaveBeenCalledTimes(2)
+      expect(poolMock.execute).not.toHaveBeenCalled()
+    })
+
+    it('hace rollback y lanza el error si fn falla', async () => {
+      const error = new Error('error de negocio')
+
+      await expect(
+        adapter.transaction(async () => {
+          throw error
+        }),
+      ).rejects.toThrow('error de negocio')
+
+      expect(connMock.beginTransaction).toHaveBeenCalledTimes(1)
+      expect(connMock.rollback).toHaveBeenCalledTimes(1)
+      expect(connMock.commit).not.toHaveBeenCalled()
+      expect(connMock.release).toHaveBeenCalledTimes(1)
+    })
+
+    it('libera la conexión aunque el rollback falle (finally garantizado)', async () => {
+      connMock.rollback.mockImplementation(async () => {
+        throw new Error('rollback falló')
+      })
+
+      await expect(
+        adapter.transaction(async () => {
+          throw new Error('error original')
+        }),
+      ).rejects.toBeDefined()
+
+      // release() debe ejecutarse siempre — está en finally
+      expect(connMock.release).toHaveBeenCalledTimes(1)
+
+      // Restaurar implementación para tests siguientes
+      connMock.rollback.mockImplementation(async () => {})
+    })
+  })
+
+  // ── close() ──────────────────────────────────────────────────────────────────
+  describe('close()', () => {
+    it('termina el pool', async () => {
+      const adapter = makeAdapter()
+      await adapter.connect()
+      resetMocks()
+
+      await adapter.close()
+      expect(poolMock.end).toHaveBeenCalledTimes(1)
+    })
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Test de integración real (requiere MySQL corriendo):
+//
+//   describe('MySQLAdapter — integración', () => {
+//     let adapter: MySQLAdapter
+//
+//     beforeAll(async () => {
+//       const { MySQLAdapter } = await import('../mysql')
+//       adapter = new MySQLAdapter({
+//         host: 'localhost',
+//         user: 'test',
+//         password: 'test',
+//         database: 'arckode_test',
+//       })
+//       await adapter.connect()
+//       await adapter.run('CREATE TABLE IF NOT EXISTS test_items (id INT AUTO_INCREMENT PRIMARY KEY, nombre VARCHAR(255))')
+//     })
+//
+//     afterAll(async () => {
+//       await adapter.run('DROP TABLE IF EXISTS test_items')
+//       await adapter.close()
+//     })
+//
+//     it('INSERT + SELECT funcionan con placeholders ?', async () => {
+//       await adapter.run('INSERT INTO test_items (nombre) VALUES (?)', ['Laptop'])
+//       const rows = await adapter.query('SELECT * FROM test_items WHERE nombre = ?', ['Laptop'])
+//       expect(rows).toHaveLength(1)
+//       expect((rows[0] as any).nombre).toBe('Laptop')
+//     })
+//
+//     it('transacción commit persiste los datos', async () => {
+//       await adapter.transaction(async (tx) => {
+//         await tx.run('INSERT INTO test_items (nombre) VALUES (?)', ['Mouse'])
+//       })
+//       const rows = await adapter.query('SELECT * FROM test_items WHERE nombre = ?', ['Mouse'])
+//       expect(rows).toHaveLength(1)
+//     })
+//
+//     it('transacción rollback no persiste los datos', async () => {
+//       await expect(
+//         adapter.transaction(async (tx) => {
+//           await tx.run('INSERT INTO test_items (nombre) VALUES (?)', ['Keyboard'])
+//           throw new Error('forzar rollback')
+//         })
+//       ).rejects.toThrow()
+//       const rows = await adapter.query('SELECT * FROM test_items WHERE nombre = ?', ['Keyboard'])
+//       expect(rows).toHaveLength(0)
+//     })
+//   })

package/adapters/jwt.ts

@@ -0,0 +1,18 @@
+// adapters/jwt.ts — Adapter JWT
+// Responsabilidad ÚNICA: traducir llamadas de JwtAdapter a jsonwebtoken
+// SOLID: implementa JwtAdapter, puede reemplazarse sin cambiar Auth
+
+import jwt from 'jsonwebtoken'
+import type { JwtAdapter } from '../kernel/framework'
+
+export const jwtTokenAdapter: JwtAdapter = {
+  sign(payload, secret, expiresIn) {
+    // jsonwebtoken's expiresIn accepts ms-compatible strings (e.g. "24h", "30d")
+    // We cast via unknown to satisfy its StringValue/number union
+    return jwt.sign(payload, secret, { expiresIn: expiresIn as unknown as number })
+  },
+
+  verify(token, secret) {
+    return jwt.verify(token, secret) as Record<string, unknown>
+  },
+}

package/adapters/mysql.ts

@@ -0,0 +1,98 @@
+// adapters/mysql.ts — Adapter MySQL
+// Usa mysql2/promise. Placeholders ? nativos (sin conversión, a diferencia de Postgres).
+// Instalar: bun add mysql2
+
+import mysql from 'mysql2/promise'
+import type { DbAdapter } from '../kernel/framework'
+
+export interface MySQLConfig {
+  host: string
+  port?: number
+  user: string
+  password: string
+  database: string
+  poolMin?: number
+  poolMax?: number
+  /** Timeout en ms para adquirir una conexión del pool. Default: 10000 */
+  acquireTimeout?: number
+}
+
+// ── Adapter para usar dentro de una transacción (conexión dedicada) ──
+class MySQLTransactionAdapter implements DbAdapter {
+  constructor(private conn: mysql.PoolConnection) {}
+
+  async query(sql: string, params: unknown[] = []): Promise<unknown[]> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const [rows] = await this.conn.execute(sql, params as any)
+    return rows as unknown[]
+  }
+
+  async run(sql: string, params: unknown[] = []): Promise<{ changes: number; lastId?: string }> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const [result] = await this.conn.execute(sql, params as any) as [mysql.ResultSetHeader, mysql.FieldPacket[]]
+    return {
+      changes: result.affectedRows,
+      lastId: result.insertId > 0 ? String(result.insertId) : undefined,
+    }
+  }
+
+  async close(): Promise<void> {
+    // no-op: la conexión la cierra MySQLAdapter.transaction() al finalizar
+  }
+}
+
+export class MySQLAdapter implements DbAdapter {
+  private pool!: mysql.Pool
+
+  constructor(private config: MySQLConfig) {}
+
+  async connect(): Promise<void> {
+    this.pool = mysql.createPool({
+      host: this.config.host,
+      port: this.config.port ?? 3306,
+      user: this.config.user,
+      password: this.config.password,
+      database: this.config.database,
+      connectionLimit: this.config.poolMax ?? 10,
+      waitForConnections: true,
+      queueLimit: 0,
+    })
+    // Verificar conexión al arrancar (fail fast)
+    const conn = await this.pool.getConnection()
+    conn.release()
+  }
+
+  async query(sql: string, params: unknown[] = []): Promise<unknown[]> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const [rows] = await this.pool.execute(sql, params as any)
+    return rows as unknown[]
+  }
+
+  async run(sql: string, params: unknown[] = []): Promise<{ changes: number; lastId?: string }> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const [result] = await this.pool.execute(sql, params as any) as [mysql.ResultSetHeader, mysql.FieldPacket[]]
+    return {
+      changes: result.affectedRows,
+      lastId: result.insertId > 0 ? String(result.insertId) : undefined,
+    }
+  }
+
+  async transaction<T>(fn: (adapter: DbAdapter) => Promise<T>): Promise<T> {
+    const conn = await this.pool.getConnection()
+    await conn.beginTransaction()
+    try {
+      const result = await fn(new MySQLTransactionAdapter(conn))
+      await conn.commit()
+      return result
+    } catch (err) {
+      await conn.rollback()
+      throw err
+    } finally {
+      conn.release()
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.pool.end()
+  }
+}

package/adapters/postgres.ts

@@ -0,0 +1,52 @@
+// adapters/postgres.ts — Adapter Postgres
+// Convierte ? placeholders (propios del ORM) a $1, $2, $3 (formato PostgreSQL)
+
+import pg, { type Pool as PgPool } from 'pg'
+import type { DbAdapter } from '../kernel/framework'
+
+export interface PostgresConfig {
+  connectionString: string
+  poolMin?: number
+  poolMax?: number
+}
+
+export class PostgresAdapter implements DbAdapter {
+  private pool!: PgPool
+
+  constructor(private config: PostgresConfig) {}
+
+  async connect(): Promise<void> {
+    this.pool = new pg.Pool({
+      connectionString: this.config.connectionString,
+      min: this.config.poolMin ?? 2,
+      max: this.config.poolMax ?? 10,
+    })
+    const client = await this.pool.connect()
+    client.release()
+  }
+
+  // Convierte ? a $1, $2, $3... para compatibilidad con PostgreSQL
+  private convertPlaceholders(sql: string): string {
+    let index = 0
+    return sql.replace(/\?/g, () => `$${++index}`)
+  }
+
+  async query(sql: string, params: unknown[] = []): Promise<unknown[]> {
+    const pgSql = this.convertPlaceholders(sql)
+    const result = await this.pool.query(pgSql, params)
+    return result.rows
+  }
+
+  async run(sql: string, params: unknown[] = []): Promise<{ changes: number; lastId?: string }> {
+    const pgSql = this.convertPlaceholders(sql)
+    const result = await this.pool.query(pgSql, params)
+    return {
+      changes: result.rowCount ?? 0,
+      lastId: result.rows[0]?.id ? String(result.rows[0].id) : undefined,
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.pool.end()
+  }
+}

package/adapters/redis-cache.ts

@@ -0,0 +1,64 @@
+// adapters/redis-cache.ts — Adapter Redis para cache
+// SOLID: implementa CacheAdapter, reemplaza MemoryCache sin cambiar los módulos
+
+import { createClient, type RedisClientType } from 'redis'
+import type { CacheAdapter } from '../kernel/framework'
+
+export interface RedisCacheConfig {
+  url: string
+  keyPrefix?: string
+  defaultTTL?: number
+}
+
+export class RedisCacheAdapter implements CacheAdapter {
+  private client!: RedisClientType
+  private connected = false
+
+  constructor(private config: RedisCacheConfig) {}
+
+  async connect(): Promise<void> {
+    this.client = createClient({ url: this.config.url })
+    await this.client.connect()
+    this.connected = true
+  }
+
+  private prefix(key: string): string {
+    return this.config.keyPrefix ? `${this.config.keyPrefix}:${key}` : key
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    if (!this.connected) return null
+    const val = await this.client.get(this.prefix(key))
+    if (!val) return null
+    try { return JSON.parse(val) as T } catch { return val as unknown as T }
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+    if (!this.connected) return
+    const serialized = typeof value === 'string' ? value : JSON.stringify(value)
+    const ttl = ttlSeconds ?? this.config.defaultTTL ?? 3600
+    await this.client.setEx(this.prefix(key), ttl, serialized)
+  }
+
+  async delete(key: string): Promise<void> {
+    if (!this.connected) return
+    await this.client.del(this.prefix(key))
+  }
+
+  async flush(): Promise<void> {
+    if (!this.connected) return
+    if (this.config.keyPrefix) {
+      const keys = await this.client.keys(`${this.config.keyPrefix}:*`)
+      if (keys.length) await this.client.del(keys)
+    } else {
+      await this.client.flushAll()
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.connected) {
+      await this.client.quit()
+      this.connected = false
+    }
+  }
+}

package/adapters/sqlite.ts

@@ -0,0 +1,73 @@
+// adapters/sqlite.ts — Adapter SQLite
+// Responsabilidad ÚNICA: traducir llamadas de DbAdapter a better-sqlite3
+// SOLID: implementa DbAdapter, puede reemplazarse por PostgresAdapter sin cambiar el ORM
+
+import Database from 'better-sqlite3'
+import type { DbAdapter } from '../kernel/framework'
+
+interface SqliteConfig {
+  path: string
+  wal?: boolean
+  foreignKeys?: boolean
+}
+
+// Configuración con valores por defecto
+const DEFAULT_CONFIG: SqliteConfig = {
+  path: './data/db.sqlite',
+  wal: true,
+  foreignKeys: true,
+}
+
+export class SqliteAdapter implements DbAdapter {
+  private db!: Database.Database
+  private config: SqliteConfig
+
+  constructor(config?: Partial<SqliteConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+  }
+
+  async connect(): Promise<void> {
+    this.db = new Database(this.config.path)
+
+    if (this.config.wal) this.db.pragma('journal_mode = WAL')
+    if (this.config.foreignKeys) this.db.pragma('foreign_keys = ON')
+  }
+
+  query(sql: string, params: unknown[] = []): Promise<unknown[]> {
+    const stmt = this.db.prepare(sql)
+    const rows = params.length > 0 ? stmt.all(...params) : stmt.all()
+    return Promise.resolve(rows)
+  }
+
+  run(sql: string, params: unknown[] = []): Promise<{ changes: number; lastId?: string }> {
+    const stmt = this.db.prepare(sql)
+    const result = params.length > 0 ? stmt.run(...params) : stmt.run()
+    return Promise.resolve({
+      changes: result.changes,
+      lastId: result.lastInsertRowid ? String(result.lastInsertRowid) : undefined,
+    })
+  }
+
+  async transaction<T>(fn: (adapter: DbAdapter) => Promise<T>): Promise<T> {
+    // better-sqlite3 usa transacciones síncronas — necesitamos un wrapper async
+    return new Promise((resolve, reject) => {
+      const txFn = this.db.transaction((args: unknown[]) => args[0])
+      // Ejecutar la función dentro de BEGIN/COMMIT de better-sqlite3
+      this.db.exec('BEGIN')
+      fn(this)
+        .then((result) => {
+          this.db.exec('COMMIT')
+          resolve(result)
+        })
+        .catch((err) => {
+          try { this.db.exec('ROLLBACK') } catch { /* ya hizo rollback */ }
+          reject(err)
+        })
+    })
+  }
+
+  close(): Promise<void> {
+    this.db.close()
+    return Promise.resolve()
+  }
+}

package/adapters/vendor.d.ts

@@ -0,0 +1,48 @@
+// adapters/vendor.d.ts — Minimal type stubs for optional peer dependencies.
+// pg and redis are optional — users install them only when using those adapters.
+// These stubs let TypeScript compile without the packages installed.
+
+declare module 'pg' {
+  export interface PoolConfig {
+    connectionString?: string
+    min?: number
+    max?: number
+    [key: string]: unknown
+  }
+
+  export interface QueryResult<R = Record<string, unknown>> {
+    rows: R[]
+    rowCount: number | null
+  }
+
+  export interface PoolClient {
+    release(): void
+  }
+
+  export class Pool {
+    constructor(config?: PoolConfig)
+    connect(): Promise<PoolClient>
+    query(sql: string, params?: unknown[]): Promise<QueryResult>
+    end(): Promise<void>
+  }
+
+  const pg: {
+    Pool: typeof Pool
+  } & typeof import('pg')
+  export default pg
+}
+
+declare module 'redis' {
+  export type RedisClientType = {
+    connect(): Promise<void>
+    get(key: string): Promise<string | null>
+    set(key: string, value: string): Promise<unknown>
+    setEx(key: string, seconds: number, value: string): Promise<unknown>
+    del(keys: string | string[]): Promise<unknown>
+    keys(pattern: string): Promise<string[]>
+    flushAll(): Promise<unknown>
+    quit(): Promise<unknown>
+  }
+
+  export function createClient(options?: { url?: string; [key: string]: unknown }): RedisClientType
+}

package/bin/arckode.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const dir = fileURLToPath(new URL('..', import.meta.url))
+process.argv[1] = resolve(dir, 'cli/index.ts')
+import(resolve(dir, 'cli/index.ts')).catch(console.error)