arckode-framework 1.3.1 → 1.4.0

package/kernel/cache.ts

@@ -0,0 +1,37 @@
+export interface CacheAdapter {
+  get<T>(key: string): Promise<T | null>
+  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>
+  delete(key: string): Promise<void>
+  flush(): Promise<void>
+}
+
+export class MemoryCache implements CacheAdapter {
+  private store = new Map<string, { value: unknown; expiresAt: number }>()
+  private hits = 0
+  private misses = 0
+
+  async get<T>(key: string): Promise<T | null> {
+    const entry = this.store.get(key)
+    if (!entry) { this.misses++; return null }
+    if (Date.now() > entry.expiresAt) { this.store.delete(key); this.misses++; return null }
+    this.hits++
+    return entry.value as T
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds = 3600): Promise<void> {
+    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 })
+  }
+
+  async delete(key: string): Promise<void> { this.store.delete(key) }
+  async flush(): Promise<void> { this.store.clear() }
+
+  get stats() {
+    const total = this.hits + this.misses
+    return {
+      size: this.store.size,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? `${((this.hits / total) * 100).toFixed(1)}%` : '0%',
+    }
+  }
+}

package/kernel/config.ts

@@ -0,0 +1,129 @@
+import { InternalError } from './errors'
+
+export async function loadEnv(opts: { cwd?: string } = {}): Promise<Record<string, string | undefined>> {
+  const { readFile } = await import('node:fs/promises')
+  const { join } = await import('node:path')
+
+  const cwd = opts.cwd ?? process.cwd()
+  const stage = (process.env.NODE_ENV ?? 'development').toLowerCase()
+
+  const parseEnvFile = (content: string): Record<string, string> => {
+    const result: Record<string, string> = {}
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const eq = trimmed.indexOf('=')
+      if (eq === -1) continue
+      const key = trimmed.slice(0, eq).trim()
+      let val = trimmed.slice(eq + 1).trim()
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1)
+      }
+      result[key] = val
+    }
+    return result
+  }
+
+  const tryRead = async (path: string): Promise<Record<string, string>> => {
+    try { return parseEnvFile(await readFile(path, 'utf-8')) } catch { return {} }
+  }
+
+  const base   = await tryRead(join(cwd, '.env'))
+  const staged = await tryRead(join(cwd, `.env.${stage}`))
+
+  return { ...base, ...staged, ...process.env }
+}
+
+export type ConfigType = 'string' | 'number' | 'boolean' | 'url' | 'email'
+
+export interface ConfigDefinition {
+  type: ConfigType
+  required?: boolean
+  default?: string | number | boolean
+  description?: string
+  secret?: boolean
+}
+
+export class ConfigStore {
+  private definitions = new Map<string, ConfigDefinition>()
+  private values = new Map<string, unknown>()
+  private isLoaded = false
+
+  define(schema: Record<string, ConfigDefinition>): this {
+    for (const [key, def] of Object.entries(schema)) {
+      this.definitions.set(key, def)
+    }
+    return this
+  }
+
+  load(source: Record<string, string | undefined>): this {
+    const errors: string[] = []
+
+    for (const [key, def] of this.definitions) {
+      const raw = source[key] ?? def.default
+
+      if (raw == null || raw === '') {
+        if (def.required) errors.push(`CONFIG: ${key} es requerido`)
+        continue
+      }
+
+      let parsed: unknown
+
+      switch (def.type) {
+        case 'string':
+          parsed = String(raw)
+          break
+        case 'number': {
+          const n = Number(raw)
+          if (isNaN(n)) { errors.push(`CONFIG: ${key} must be a number`); continue }
+          parsed = n
+          break
+        }
+        case 'boolean':
+          parsed = raw === 'true' || raw === '1'
+          break
+        case 'url':
+          try { new URL(String(raw)); parsed = String(raw) }
+          catch { errors.push(`CONFIG: ${key} is not a valid URL`); continue }
+          break
+        case 'email':
+          if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(raw))) {
+            errors.push(`CONFIG: ${key} is not a valid email`); continue
+          }
+          parsed = String(raw)
+          break
+      }
+
+      this.values.set(key, parsed)
+    }
+
+    if (errors.length > 0) {
+      throw new InternalError(`Invalid configuration:\n${errors.join('\n')}`)
+    }
+
+    this.isLoaded = true
+    return this
+  }
+
+  get<T = string>(key: string): T {
+    if (!this.isLoaded) throw new InternalError('Config no cargada — llamar load()')
+    if (!this.values.has(key)) throw new InternalError(`Config "${key}" no definida`)
+    return this.values.get(key) as T
+  }
+
+  /** @deprecated Usar get<T>(key) — hace exactamente lo mismo */
+  getOrThrow<T = string>(key: string): T {
+    return this.get<T>(key)
+  }
+
+  toJSON(): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+    for (const [key] of this.definitions) {
+      if (this.values.has(key)) {
+        const def = this.definitions.get(key)!
+        result[key] = def.secret ? '••••••' : this.values.get(key)
+      }
+    }
+    return result
+  }
+}

package/kernel/container.ts

@@ -0,0 +1,64 @@
+import { InternalError } from './errors'
+
+interface ServiceEntry<T> {
+  name: string
+  factory: () => T
+  instance?: T
+  destructor?: () => Promise<void>
+  singleton: boolean
+}
+
+export class Container {
+  private services = new Map<string, ServiceEntry<unknown>>()
+  private initialized = false
+
+  register<T>(name: string, factory: () => T, destructor?: () => Promise<void>): this {
+    if (this.initialized) throw new InternalError(`Container: "${name}" registered after init`)
+    this.services.set(name, { name, factory, destructor, singleton: true })
+    return this
+  }
+
+  registerTransient<T>(name: string, factory: () => T): this {
+    if (this.initialized) throw new InternalError(`Container: "${name}" registered after init`)
+    this.services.set(name, { name, factory, singleton: false })
+    return this
+  }
+
+  resolve<T>(name: string): T {
+    const entry = this.services.get(name) as ServiceEntry<T> | undefined
+    if (!entry) throw new InternalError(`Container: "${name}" no registrado`)
+    if (!entry.singleton) return entry.factory() as T
+    if (entry.instance !== undefined) return entry.instance
+    entry.instance = entry.factory()
+    return entry.instance as T
+  }
+
+  /** @deprecated Usar resolve<T>(name) — hace exactamente lo mismo */
+  get<T>(name: string): T {
+    return this.resolve<T>(name)
+  }
+
+  init(): void {
+    this.initialized = true
+    for (const [name] of this.services) {
+      this.resolve(name)
+    }
+  }
+
+  async destroy(): Promise<void> {
+    const entries = [...this.services.values()].reverse()
+    for (const entry of entries) {
+      if (entry.destructor) {
+        try { await entry.destructor() } catch (e) {
+          console.error(`[Container] Error al destruir "${entry.name}":`, e)
+        }
+      }
+    }
+    this.services.clear()
+    this.initialized = false
+  }
+
+  get registered(): string[] {
+    return [...this.services.keys()]
+  }
+}

package/kernel/db/orm-migrate.ts

@@ -0,0 +1,136 @@
+import type { DbAdapter, ModelDefinition } from './types'
+import { assertSafeIdentifier, fieldTypeToSQL } from './orm-utils'
+
+async function getTableColumns(db: DbAdapter, table: string): Promise<string[]> {
+  try {
+    const rows = await db.query(`PRAGMA table_info(${table})`)
+    if (Array.isArray(rows) && rows.length > 0 && 'name' in (rows[0] as object)) {
+      return (rows as { name: string }[]).map(r => r.name)
+    }
+  } catch { /* not SQLite */ }
+
+  try {
+    const rows = await db.query(
+      'SELECT column_name FROM information_schema.columns WHERE table_name = ? AND table_schema = DATABASE()',
+      [table],
+    )
+    if (Array.isArray(rows) && rows.length > 0 && 'column_name' in (rows[0] as object)) {
+      return (rows as { column_name: string }[]).map(r => r.column_name)
+    }
+  } catch { /* not MySQL */ }
+
+  try {
+    const rows = await db.query(
+      "SELECT column_name FROM information_schema.columns WHERE table_name = ? AND table_schema = 'public'",
+      [table],
+    )
+    if (Array.isArray(rows) && rows.length > 0) {
+      return (rows as { column_name: string }[]).map(r => r.column_name)
+    }
+  } catch { /* adapter doesn't support introspection */ }
+
+  return []
+}
+
+export async function ormMigrate(
+  db: DbAdapter,
+  models: Map<string, ModelDefinition>,
+  opts: { allowDrop?: boolean } = {},
+): Promise<void> {
+  await db.run(
+    `CREATE TABLE IF NOT EXISTS _arckode_schema (table_name TEXT PRIMARY KEY, migratedAt TEXT)`
+  )
+
+  for (const [modelName, def] of models) {
+    assertSafeIdentifier(def.table, `modelo "${modelName}" → table`)
+    for (const fieldName of Object.keys(def.fields)) {
+      assertSafeIdentifier(fieldName, `modelo "${modelName}" → campo`)
+    }
+
+    const hasExplicitId = Object.keys(def.fields).includes('id')
+    const columns = Object.entries(def.fields).map(([name, field]) => {
+      const sqlType = fieldTypeToSQL(field.type)
+      const parts = [name, sqlType]
+
+      if (name === 'id') parts.push('PRIMARY KEY')
+      if (field.required) parts.push('NOT NULL')
+      if (field.unique) parts.push('UNIQUE')
+      if (field.default !== undefined) {
+        parts.push(`DEFAULT ${typeof field.default === 'string' ? `'${field.default.replace(/'/g, "''")}'` : field.default}`)
+      }
+
+      return parts.join(' ')
+    })
+
+    if (!hasExplicitId) columns.unshift('id TEXT PRIMARY KEY')
+
+    if (def.timestamps) {
+      columns.push('createdAt TEXT')
+      columns.push('updatedAt TEXT')
+    }
+
+    if (def.softDelete) columns.push('deletedAt TEXT')
+
+    await db.run(`CREATE TABLE IF NOT EXISTS ${def.table} (${columns.join(', ')})`)
+
+    for (const [fieldName, field] of Object.entries(def.fields)) {
+      if (field.indexed && !field.unique) {
+        const idxName = `idx_${def.table}_${fieldName}`
+        try {
+          await db.run(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${def.table}(${fieldName})`)
+        } catch { /* index already exists */ }
+      }
+    }
+
+    for (const [name, field] of Object.entries(def.fields)) {
+      const sqlType = fieldTypeToSQL(field.type)
+      try {
+        await db.run(`ALTER TABLE ${def.table} ADD COLUMN ${name} ${sqlType}`)
+      } catch { /* column already exists */ }
+
+      if (field.nullable === true) {
+        try {
+          await db.run(`ALTER TABLE ${def.table} ALTER COLUMN ${name} DROP NOT NULL`)
+        } catch { /* SQLite doesn't support this */ }
+      }
+    }
+
+    if (def.timestamps) {
+      try { await db.run(`ALTER TABLE ${def.table} ADD COLUMN createdAt TEXT`) } catch { /* already exists */ }
+      try { await db.run(`ALTER TABLE ${def.table} ADD COLUMN updatedAt TEXT`) } catch { /* already exists */ }
+    }
+    if (def.softDelete) {
+      try { await db.run(`ALTER TABLE ${def.table} ADD COLUMN deletedAt TEXT`) } catch { /* already exists */ }
+    }
+
+    const definedCols = new Set([
+      'id',
+      ...Object.keys(def.fields).map(k => k.toLowerCase()),
+      ...(def.timestamps ? ['createdat', 'updatedat'] : []),
+      ...(def.softDelete ? ['deletedat'] : []),
+    ])
+
+    const dbCols = await getTableColumns(db, def.table)
+
+    for (const col of dbCols) {
+      if (definedCols.has(col.toLowerCase())) continue
+
+      if (opts.allowDrop) {
+        try {
+          await db.run(`ALTER TABLE ${def.table} DROP COLUMN ${col}`)
+          console.warn(`[arckode/migrate] Column "${col}" dropped from "${def.table}" — no longer in model`)
+        } catch {
+          console.warn(
+            `[arckode/migrate] ⚠  Orphan column "${col}" in table "${def.table}" — ` +
+            `could not be auto-dropped. Create a manual migration: arckode make:migration drop_${col}_from_${def.table}`
+          )
+        }
+      } else {
+        console.warn(
+          `[arckode/migrate] ⚠  Orphan column "${col}" in table "${def.table}" — ` +
+          `not in model. To drop it: orm.migrate({ allowDrop: true }) or arckode make:migration drop_${col}_from_${def.table}`
+        )
+      }
+    }
+  }
+}

package/kernel/db/orm-repository.ts

@@ -0,0 +1,45 @@
+import type { FindOptions, ModelResult, PageResult, RepositoryAdapter } from './types'
+import { ORM } from './orm'
+
+export class OrmRepository<T extends object = Record<string, unknown>>
+  implements RepositoryAdapter<T> {
+  constructor(
+    private readonly orm: ORM,
+    private readonly modelName: string,
+  ) {}
+
+  findMany(filters?: Record<string, unknown>, options?: FindOptions): Promise<T[]> {
+    return this.orm.findMany<T>(this.modelName, filters, options)
+  }
+
+  findById(id: string, select?: string[]): Promise<T | null> {
+    return this.orm.findById<T>(this.modelName, id, select)
+  }
+
+  findOne(filters: Record<string, unknown>): Promise<T | null> {
+    return this.orm.findOne<T>(this.modelName, filters)
+  }
+
+  create(data: Omit<T, 'id'>): Promise<T> {
+    return this.orm.create<T>(this.modelName, data as Record<string, unknown>)
+  }
+
+  update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null> {
+    return this.orm.update<T>(this.modelName, id, data as Record<string, unknown>)
+  }
+
+  delete(id: string): Promise<boolean> {
+    return this.orm.delete(this.modelName, id)
+  }
+
+  count(filters?: Record<string, unknown>): Promise<number> {
+    return this.orm.count(this.modelName, filters)
+  }
+
+  paginate(
+    filters?: Record<string, unknown>,
+    options: FindOptions & { limit: number } = { limit: 20 },
+  ): Promise<PageResult<T>> {
+    return this.orm.paginate<T>(this.modelName, filters, options)
+  }
+}

package/kernel/db/orm-utils.ts

@@ -0,0 +1,93 @@
+import { ValidationError } from '../errors'
+import type { FieldDefinition, ModelDefinition, ModelResult } from './types'
+
+export function assertSafeIdentifier(value: string, context: string): void {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(value)) {
+    throw new ValidationError(`Invalid SQL identifier in ${context}: "${value}". Only letters, numbers and underscores.`)
+  }
+}
+
+export function fieldTypeToSQL(type: FieldDefinition['type']): string {
+  const map: Record<FieldDefinition['type'], string> = {
+    string: 'TEXT',
+    text: 'TEXT',
+    number: 'REAL',
+    boolean: 'BOOLEAN',
+    json: 'TEXT',
+    date: 'TEXT',
+  }
+  return map[type]
+}
+
+export function serializeForDb(def: ModelDefinition, record: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(record)) {
+    if (def.fields[k]?.type === 'json' && v !== null && v !== undefined && typeof v !== 'string') {
+      out[k] = JSON.stringify(v)
+    } else {
+      out[k] = v
+    }
+  }
+  return out
+}
+
+export function deserializeFromDb(def: ModelDefinition, row: ModelResult): ModelResult {
+  const result = { ...row } as Record<string, unknown>
+
+  for (const [k, field] of Object.entries(def.fields)) {
+    if (field.type === 'json' && typeof result[k] === 'string') {
+      try { result[k] = JSON.parse(result[k] as string) } catch { console.warn(`[ORM] deserialize: campo "${k}" tiene JSON inválido en DB, se mantiene como string`) }
+    }
+  }
+
+  const tsMap: Record<string, string> = {
+    createdat:  'createdAt',
+    updatedat:  'updatedAt',
+    deletedat:  'deletedAt',
+  }
+  for (const [lower, camel] of Object.entries(tsMap)) {
+    if (lower in result && !(camel in result)) {
+      result[camel] = result[lower]
+      delete result[lower]
+    }
+  }
+
+  return result as ModelResult
+}
+
+export function getAllowedFields(def: ModelDefinition): Set<string> {
+  const allowed = new Set(['id', ...Object.keys(def.fields)])
+  if (def.timestamps) { allowed.add('createdAt'); allowed.add('updatedAt') }
+  if (def.softDelete) allowed.add('deletedAt')
+  return allowed
+}
+
+export function buildSelect(def: ModelDefinition, fields?: string[]): string {
+  if (!fields || fields.length === 0) return '*'
+  const allowed = getAllowedFields(def)
+  for (const f of fields) {
+    if (!allowed.has(f)) throw new ValidationError(`Invalid select field: "${f}"`)
+  }
+  return fields.join(', ')
+}
+
+export function buildWhere(def: ModelDefinition, filters?: Record<string, unknown>): { clause: string; params: unknown[] } {
+  const parts: string[] = []
+  const params: unknown[] = []
+
+  if (filters && Object.keys(filters).length > 0) {
+    const allowed = getAllowedFields(def)
+    for (const [k, v] of Object.entries(filters)) {
+      if (!allowed.has(k)) throw new ValidationError(`Invalid filter field: "${k}"`)
+      params.push(v)
+      parts.push(`${k} = ?`)
+    }
+  }
+
+  if (def.softDelete) parts.push('deletedAt IS NULL')
+
+  return {
+    clause: parts.length > 0 ? ' WHERE ' + parts.join(' AND ') : '',
+    params,
+  }
+}