arckode-framework 1.3.2 → 1.4.0

package/kernel/db/orm.ts

@@ -0,0 +1,254 @@
+import { InternalError, NotFoundError, ValidationError } from '../errors'
+import type { DbAdapter, FindOptions, ModelDefinition, ModelResult, PageResult } from './types'
+import {
+  assertSafeIdentifier,
+  serializeForDb,
+  deserializeFromDb,
+  getAllowedFields,
+  buildSelect,
+  buildWhere,
+} from './orm-utils'
+import { ormMigrate } from './orm-migrate'
+
+export class ORM {
+  private models = new Map<string, ModelDefinition>()
+
+  static readonly SCHEMA_TABLE = '_arckode_schema'
+
+  constructor(private db: DbAdapter) {}
+
+  define(name: string, def: ModelDefinition): this {
+    assertSafeIdentifier(def.table, `modelo "${name}" → table`)
+    for (const fieldName of Object.keys(def.fields)) {
+      assertSafeIdentifier(fieldName, `modelo "${name}" → campo`)
+    }
+    this.models.set(name, def)
+    return this
+  }
+
+  getDefinition(name: string): ModelDefinition {
+    const def = this.models.get(name)
+    if (!def) throw new NotFoundError(`Modelo "${name}" no definido`)
+    return def
+  }
+
+  async transaction<T>(fn: (tx: ORM) => Promise<T>): Promise<T> {
+    if (this.db.transaction) {
+      return this.db.transaction(async (txAdapter) => {
+        const txOrm = new ORM(txAdapter)
+        for (const [name, def] of this.models) txOrm.define(name, def)
+        return fn(txOrm)
+      })
+    }
+    throw new InternalError('El adaptador de base de datos no soporta transacciones. Usá SqliteAdapter, MySQLAdapter o PostgresAdapter.')
+  }
+
+  // ── CRUD ──
+
+  async findMany<T extends object = ModelResult>(name: string, filters?: Record<string, unknown>, options?: FindOptions): Promise<T[]> {
+    const def = this.getDefinition(name)
+    const { clause, params } = buildWhere(def, filters)
+    const selectClause = buildSelect(def, options?.select)
+    let sql = `SELECT ${selectClause} FROM ${def.table}${clause}`
+
+    if (options?.orderBy) {
+      const allowed = getAllowedFields(def)
+      const clauses = Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy]
+      const parts = clauses.map(({ field, dir = 'ASC' }) => {
+        if (!allowed.has(field)) throw new ValidationError(`Invalid sort field: "${field}"`)
+        return `${field} ${dir === 'DESC' ? 'DESC' : 'ASC'}`
+      })
+      sql += ` ORDER BY ${parts.join(', ')}`
+    }
+
+    if (options?.limit !== undefined) {
+      sql += ` LIMIT ${Math.max(1, Math.floor(options.limit))}`
+      if (options.offset !== undefined) {
+        sql += ` OFFSET ${Math.max(0, Math.floor(options.offset))}`
+      }
+    }
+
+    const rows = (await this.db.query(sql, params)) as T[]
+    return rows.map(r => deserializeFromDb(def, r as ModelResult) as T)
+  }
+
+  async findById<T extends object = ModelResult>(name: string, id: string, select?: string[]): Promise<T | null> {
+    const def = this.getDefinition(name)
+    const selectClause = buildSelect(def, select)
+    let sql = `SELECT ${selectClause} FROM ${def.table} WHERE id = ?`
+    if (def.softDelete) sql += ' AND deletedAt IS NULL'
+    const rows = await this.db.query(sql, [id])
+    const row = (rows as ModelResult[])[0] ?? null
+    return row ? deserializeFromDb(def, row) as T : null
+  }
+
+  async findOne<T extends object = ModelResult>(name: string, filters: Record<string, unknown>): Promise<T | null> {
+    const results = await this.findMany<T>(name, filters, { limit: 1 })
+    return results[0] ?? null
+  }
+
+  async count(name: string, filters?: Record<string, unknown>): Promise<number> {
+    const def = this.getDefinition(name)
+    const { clause, params } = buildWhere(def, filters)
+    const rows = await this.db.query(`SELECT COUNT(*) as n FROM ${def.table}${clause}`, params)
+    return Number((rows as Array<{ n: number | string }>)[0]?.n ?? 0)
+  }
+
+  async paginate<T extends object = ModelResult>(
+    name: string,
+    filters?: Record<string, unknown>,
+    options: FindOptions & { limit: number } = { limit: 20 },
+  ): Promise<PageResult<T>> {
+    const limit = Math.max(1, Math.floor(options.limit))
+    const offset = Math.max(0, Math.floor(options.offset ?? 0))
+
+    const [data, total] = await Promise.all([
+      this.findMany<T>(name, filters, { ...options, limit, offset }),
+      this.count(name, filters),
+    ])
+
+    return { data, total, limit, offset, pages: Math.ceil(total / limit) }
+  }
+
+  async create<T extends object = ModelResult>(name: string, data: Record<string, unknown>): Promise<T> {
+    const def = this.getDefinition(name)
+    const allowedFields = new Set(Object.keys(def.fields))
+    const id = crypto.randomUUID()
+    const now = new Date().toISOString()
+
+    const record: Record<string, unknown> = { id }
+    for (const [k, v] of Object.entries(data)) {
+      if (allowedFields.has(k)) record[k] = v
+    }
+    if (def.timestamps) {
+      record.createdAt = now
+      record.updatedAt = now
+    }
+
+    const dbRecord = serializeForDb(def, record)
+    const keys = Object.keys(dbRecord)
+    const values = Object.values(dbRecord)
+    const placeholders = keys.map(() => '?').join(', ')
+
+    await this.db.run(
+      `INSERT INTO ${def.table} (${keys.join(', ')}) VALUES (${placeholders})`,
+      values,
+    )
+
+    return record as T
+  }
+
+  async update<T extends object = ModelResult>(name: string, id: string, data: Record<string, unknown>): Promise<T | null> {
+    const def = this.getDefinition(name)
+    const allowedFields = new Set(Object.keys(def.fields))
+    const now = new Date().toISOString()
+
+    const record: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(data)) {
+      if (allowedFields.has(k)) record[k] = v
+    }
+    if (def.timestamps) record.updatedAt = now
+
+    const dbRecord = serializeForDb(def, record)
+    const keys = Object.keys(dbRecord)
+    if (keys.length === 0) return this.findById<T>(name, id)
+    const values = Object.values(dbRecord)
+    const setClause = keys.map(k => `${k} = ?`).join(', ')
+
+    await this.db.run(`UPDATE ${def.table} SET ${setClause} WHERE id = ?`, [...values, id])
+    return this.findById<T>(name, id)
+  }
+
+  async delete(name: string, id: string): Promise<boolean> {
+    const def = this.getDefinition(name)
+
+    if (def.softDelete) {
+      const result = await this.db.run(`UPDATE ${def.table} SET deletedAt = ? WHERE id = ?`, [new Date().toISOString(), id])
+      return result.changes > 0
+    }
+
+    const result = await this.db.run(`DELETE FROM ${def.table} WHERE id = ?`, [id])
+    return result.changes > 0
+  }
+
+  // ── Bulk operations ──
+
+  async createMany(name: string, records: Record<string, unknown>[]): Promise<ModelResult[]> {
+    if (records.length === 0) return []
+    const def = this.getDefinition(name)
+    const allowedFields = new Set(Object.keys(def.fields))
+    const now = new Date().toISOString()
+
+    const prepared = records.map(data => {
+      const record: Record<string, unknown> = { id: crypto.randomUUID() }
+      for (const [k, v] of Object.entries(data)) {
+        if (allowedFields.has(k)) record[k] = v
+      }
+      if (def.timestamps) { record.createdAt = now; record.updatedAt = now }
+      return record
+    })
+
+    const dbPrepared = prepared.map(r => serializeForDb(def, r))
+    const keys = Object.keys(dbPrepared[0] ?? {})
+    const rowPlaceholders = `(${keys.map(() => '?').join(', ')})`
+    const allPlaceholders = dbPrepared.map(() => rowPlaceholders).join(', ')
+    const allValues = dbPrepared.flatMap(r => Object.values(r))
+
+    await this.db.run(
+      `INSERT INTO ${def.table} (${keys.join(', ')}) VALUES ${allPlaceholders}`,
+      allValues,
+    )
+
+    return prepared as ModelResult[]
+  }
+
+  async updateMany(
+    name: string,
+    filters: Record<string, unknown>,
+    changes: Record<string, unknown>,
+  ): Promise<number> {
+    const def = this.getDefinition(name)
+    const allowedFields = new Set(Object.keys(def.fields))
+    const { clause, params: whereParams } = buildWhere(def, filters)
+    const now = new Date().toISOString()
+
+    const data: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(changes)) {
+      if (allowedFields.has(k)) data[k] = v
+    }
+    if (def.timestamps) data.updatedAt = now
+
+    const dbData = serializeForDb(def, data)
+    const setClause = Object.keys(dbData).map(k => `${k} = ?`).join(', ')
+    const result = await this.db.run(
+      `UPDATE ${def.table} SET ${setClause}${clause}`,
+      [...Object.values(dbData), ...whereParams],
+    )
+    return result.changes
+  }
+
+  async deleteMany(name: string, filters: Record<string, unknown>): Promise<number> {
+    if (Object.keys(filters).length === 0) {
+      throw new ValidationError('deleteMany requires at least one filter to avoid deleting the entire table')
+    }
+    const def = this.getDefinition(name)
+    const { clause, params } = buildWhere(def, filters)
+
+    if (def.softDelete) {
+      const result = await this.db.run(
+        `UPDATE ${def.table} SET deletedAt = ?${clause}`,
+        [new Date().toISOString(), ...params],
+      )
+      return result.changes
+    }
+
+    const result = await this.db.run(`DELETE FROM ${def.table}${clause}`, params)
+    return result.changes
+  }
+
+  // ── Migraciones ──
+
+  async migrate(opts: { allowDrop?: boolean } = {}): Promise<void> {
+    return ormMigrate(this.db, this.models, opts)
+  }
+}

package/kernel/db/transactor.ts

@@ -0,0 +1,17 @@
+import type { RepositoryAdapter, Transactor, TransactionalRepos } from './types'
+import { ORM } from './orm'
+import { OrmRepository } from './orm-repository'
+
+export class OrmTransactor implements Transactor {
+  constructor(private readonly orm: ORM) {}
+
+  run<R>(fn: (repos: TransactionalRepos) => Promise<R>): Promise<R> {
+    return this.orm.transaction(async (txOrm) => {
+      const repos: TransactionalRepos = {
+        for: <T extends object = Record<string, unknown>>(modelName: string): RepositoryAdapter<T> =>
+          new OrmRepository<T>(txOrm, modelName),
+      }
+      return fn(repos)
+    })
+  }
+}

package/kernel/db/types.ts

@@ -0,0 +1,72 @@
+export interface DbAdapter {
+  query(sql: string, params?: unknown[]): Promise<unknown[]>
+  run(sql: string, params?: unknown[]): Promise<{ changes: number; lastId?: string }>
+  close(): Promise<void>
+  /** Opcional: soporte de transacciones. Si no lo implementa, ORM.transaction() lanza InternalError. */
+  transaction?<T>(fn: (adapter: DbAdapter) => Promise<T>): Promise<T>
+}
+
+export interface FieldDefinition {
+  type: 'string' | 'text' | 'number' | 'boolean' | 'json' | 'date'
+  required?: boolean
+  nullable?: boolean
+  default?: unknown
+  unique?: boolean
+  indexed?: boolean
+  maxLength?: number
+}
+
+export interface ModelDefinition {
+  table: string
+  fields: Record<string, FieldDefinition>
+  timestamps?: boolean
+  softDelete?: boolean
+}
+
+export interface ModelResult {
+  id: string
+  [key: string]: unknown
+}
+
+export interface OrderByClause {
+  field: string
+  dir?: 'ASC' | 'DESC'
+}
+
+export interface FindOptions {
+  limit?: number
+  offset?: number
+  orderBy?: OrderByClause | OrderByClause[]
+  /** Campos a seleccionar. Si se omite: SELECT *. Los nombres se validan contra el modelo. */
+  select?: string[]
+}
+
+export interface PageResult<T = ModelResult> {
+  data: T[]
+  total: number
+  limit: number
+  offset: number
+  pages: number
+}
+
+export interface RepositoryAdapter<T extends object = Record<string, unknown>> {
+  findMany(filters?: Record<string, unknown>, options?: FindOptions): Promise<T[]>
+  findById(id: string, select?: string[]): Promise<T | null>
+  findOne(filters: Record<string, unknown>): Promise<T | null>
+  create(data: Omit<T, 'id'>): Promise<T>
+  update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>
+  delete(id: string): Promise<boolean>
+  count(filters?: Record<string, unknown>): Promise<number>
+  paginate(
+    filters?: Record<string, unknown>,
+    options?: FindOptions & { limit: number },
+  ): Promise<PageResult<T>>
+}
+
+export interface TransactionalRepos {
+  for<T extends object = Record<string, unknown>>(modelName: string): RepositoryAdapter<T>
+}
+
+export interface Transactor {
+  run<R>(fn: (repos: TransactionalRepos) => Promise<R>): Promise<R>
+}

package/kernel/errors.ts

@@ -0,0 +1,102 @@
+export abstract class ErrorContract extends Error {
+  public abstract readonly httpStatus: number
+  public abstract readonly isExpected: boolean
+  public abstract readonly canRetry: boolean
+  public abstract readonly errorCode: string
+
+  constructor(
+    message: string,
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message)
+    this.name = this.constructor.name
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      error: this.message,
+      code: this.errorCode,
+      ...(this.details ? { details: this.details } : {}),
+    }
+  }
+}
+
+export class ValidationError extends ErrorContract {
+  httpStatus = 400
+  isExpected = true
+  canRetry = false
+  errorCode = 'VALIDATION_ERROR'
+  constructor(msg: string, public fields?: Record<string, string[]>) {
+    super(msg, fields ? { fields } : undefined)
+  }
+}
+
+export class AuthError extends ErrorContract {
+  httpStatus = 401
+  isExpected = true
+  canRetry = false
+  errorCode = 'AUTH_ERROR'
+  constructor(message = 'Authentication error', details?: Record<string, unknown>) {
+    super(message, details)
+  }
+}
+
+export class ForbiddenError extends ErrorContract {
+  httpStatus = 403
+  isExpected = true
+  canRetry = false
+  errorCode = 'FORBIDDEN'
+}
+
+export class NotFoundError extends ErrorContract {
+  httpStatus = 404
+  isExpected = true
+  canRetry = false
+  errorCode = 'NOT_FOUND'
+}
+
+export class ConflictError extends ErrorContract {
+  httpStatus = 409
+  isExpected = true
+  canRetry = false
+  errorCode = 'CONFLICT'
+}
+
+export class RateLimitError extends ErrorContract {
+  httpStatus = 429
+  isExpected = true
+  canRetry = true
+  errorCode = 'RATE_LIMIT'
+}
+
+export class RepositoryError extends ErrorContract {
+  httpStatus = 500
+  isExpected = true
+  canRetry = true
+  errorCode = 'REPOSITORY_ERROR'
+}
+
+export class InternalError extends ErrorContract {
+  httpStatus = 500
+  isExpected = false
+  canRetry = false
+  errorCode = 'INTERNAL_ERROR'
+}
+
+export class PayloadTooLargeError extends ErrorContract {
+  httpStatus = 413
+  isExpected = true
+  canRetry = false
+  errorCode = 'PAYLOAD_TOO_LARGE'
+  constructor() { super('Payload Too Large') }
+}
+
+export class ModuleRuleError extends ErrorContract {
+  httpStatus = 500
+  isExpected = false
+  canRetry = false
+  errorCode = 'MODULE_RULE_VIOLATION'
+  constructor(module: string, rule: string) {
+    super(`[${module}] Regla violada: ${rule}`, { module, rule })
+  }
+}

package/kernel/framework.default.ts

@@ -0,0 +1,41 @@
+import {
+  ErrorContract, ValidationError, AuthError, ForbiddenError,
+  NotFoundError, ConflictError, RateLimitError, RepositoryError,
+  InternalError, ModuleRuleError,
+} from './errors'
+import { Logger, ConsoleTransport } from './logger'
+import { ConfigStore, loadEnv } from './config'
+import { Container } from './container'
+import { ORM, } from './db/orm'
+import { OrmRepository } from './db/orm-repository'
+import { OrmTransactor } from './db/transactor'
+import { Router } from './http/router'
+import { NodeServer } from './http/server'
+import { validateSchema } from './validator'
+import { Auth, } from './auth'
+import { MemoryCache } from './cache'
+import { createModule, } from './modules/create-module'
+import { System } from './modules/system'
+import { SeedRunner } from './seeds'
+
+export default {
+  // Errors
+  ErrorContract, ValidationError, AuthError, ForbiddenError,
+  NotFoundError, ConflictError, RateLimitError, RepositoryError,
+  InternalError, ModuleRuleError,
+
+  // Infrastructure
+  Logger, ConsoleTransport,
+  ConfigStore, loadEnv,
+  Container,
+  ORM, OrmRepository, OrmTransactor,
+  Router, NodeServer,
+  validateSchema,
+  Auth, MemoryCache,
+
+  // Module System
+  createModule, System,
+
+  // Seeds
+  SeedRunner,
+}