@zintrust/core 0.1.27 → 0.1.28

package/src/orm/Database.ts

@@ -0,0 +1,521 @@
+/**
+ * Database Manager
+ * Central database connection management and query execution
+ */
+
+import Logger from '@/config/logger';
+import { OpenTelemetry } from '@/observability/OpenTelemetry';
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { SupportedDriver } from '@migrations/enum';
+import { EventEmitter } from '@node-singletons/events';
+import { D1Adapter } from '@orm/adapters/D1Adapter';
+import { D1RemoteAdapter } from '@orm/adapters/D1RemoteAdapter';
+import { MySQLAdapter } from '@orm/adapters/MySQLAdapter';
+import { PostgreSQLAdapter } from '@orm/adapters/PostgreSQLAdapter';
+import { SQLiteAdapter } from '@orm/adapters/SQLiteAdapter';
+import { SQLServerAdapter } from '@orm/adapters/SQLServerAdapter';
+import type { DatabaseConfig, IDatabaseAdapter, QueryResult } from '@orm/DatabaseAdapter';
+import { DatabaseAdapterRegistry } from '@orm/DatabaseAdapterRegistry';
+import type { IQueryBuilder } from '@orm/QueryBuilder';
+import { QueryBuilder } from '@orm/QueryBuilder';
+
+export interface IDatabase {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  query(sql: string, parameters?: unknown[], isRead?: boolean): Promise<unknown[]>;
+  queryOne(sql: string, parameters?: unknown[], isRead?: boolean): Promise<unknown>;
+  execute(sql: string, parameters?: unknown[], isRead?: boolean): Promise<QueryResult>;
+  transaction<T>(callback: (db: IDatabase) => Promise<T>): Promise<T>;
+  table(name: string): IQueryBuilder;
+  onBeforeQuery(handler: (query: string, params: unknown[]) => void): void;
+  onAfterQuery(handler: (query: string, params: unknown[], duration: number) => void): void;
+  offBeforeQuery(handler: (query: string, params: unknown[]) => void): void;
+  offAfterQuery(handler: (query: string, params: unknown[], duration: number) => void): void;
+  getAdapterInstance(isRead?: boolean): IDatabaseAdapter;
+  getType(): SupportedDriver;
+  getConfig(): DatabaseConfig;
+  dispose(): void;
+}
+
+/**
+ * Database Manager
+ * Refactored to Functional Object pattern
+ */
+/**
+ * Create appropriate adapter based on driver
+ */
+const createAdapter = (cfg: DatabaseConfig): IDatabaseAdapter => {
+  const registered = DatabaseAdapterRegistry.get(cfg.driver);
+  if (registered !== undefined) {
+    return registered(cfg);
+  }
+
+  switch (cfg.driver) {
+    case 'postgresql':
+      return PostgreSQLAdapter.create(cfg);
+    case 'mysql':
+      return MySQLAdapter.create(cfg);
+    case 'sqlserver':
+      return SQLServerAdapter.create(cfg);
+    case 'd1':
+      return D1Adapter.create(cfg);
+    case 'd1-remote':
+      return D1RemoteAdapter.create(cfg);
+    case 'sqlite':
+    default:
+      return SQLiteAdapter.create(cfg);
+  }
+};
+
+/**
+ * Initialize write and read adapters
+ */
+const initializeAdapters = (
+  dbConfig: DatabaseConfig
+): { writeAdapter: IDatabaseAdapter; readAdapters: IDatabaseAdapter[] } => {
+  const writeAdapter = createAdapter(dbConfig);
+  const readAdapters: IDatabaseAdapter[] = [];
+
+  if (dbConfig.readHosts !== undefined && dbConfig.readHosts.length > 0) {
+    for (const host of dbConfig.readHosts) {
+      readAdapters.push(createAdapter({ ...dbConfig, host }));
+    }
+  } else {
+    readAdapters.push(writeAdapter);
+  }
+
+  return { writeAdapter, readAdapters };
+};
+
+/**
+ * Execute a query with events and timing
+ */
+const executeQuery = async (
+  adapter: IDatabaseAdapter,
+  eventEmitter: EventEmitter,
+  sql: string,
+  parameters: unknown[],
+  method: 'query'
+): Promise<unknown[]> => {
+  eventEmitter.emit('before-query', sql, parameters);
+  const startTime = Date.now();
+  const result = await adapter[method](sql, parameters);
+  const duration = Date.now() - startTime;
+  eventEmitter.emit('after-query', sql, parameters, duration);
+  return result.rows;
+};
+
+const executeFullQuery = async (
+  adapter: IDatabaseAdapter,
+  eventEmitter: EventEmitter,
+  sql: string,
+  parameters: unknown[]
+): Promise<QueryResult> => {
+  eventEmitter.emit('before-query', sql, parameters);
+  const startTime = Date.now();
+  const result = await adapter.query(sql, parameters);
+  const duration = Date.now() - startTime;
+  eventEmitter.emit('after-query', sql, parameters, duration);
+  return result;
+};
+
+const executeQueryOne = async (
+  adapter: IDatabaseAdapter,
+  eventEmitter: EventEmitter,
+  sql: string,
+  parameters: unknown[]
+): Promise<unknown> => {
+  eventEmitter.emit('before-query', sql, parameters);
+  const startTime = Date.now();
+  const result = await adapter.queryOne(sql, parameters);
+  const duration = Date.now() - startTime;
+  eventEmitter.emit('after-query', sql, parameters, duration);
+  return result;
+};
+
+const installDbMetricsIfEnabled = (
+  dbConfig: DatabaseConfig,
+  eventEmitter: EventEmitter
+): (() => void) | null => {
+  if (Env.getBool('METRICS_ENABLED', false) === false) return null;
+
+  let observeDbQueryPromise: Promise<
+    ((input: { driver: string; durationMs: number }) => Promise<void>) | null
+  > | null = null;
+
+  const ensureObserveDbQuery = async (): Promise<
+    ((input: { driver: string; durationMs: number }) => Promise<void>) | null
+  > => {
+    if (observeDbQueryPromise !== null) return observeDbQueryPromise;
+
+    observeDbQueryPromise = import('@/observability/PrometheusMetrics')
+      .then((m) => m.PrometheusMetrics.observeDbQuery)
+      .catch(() => null);
+
+    return observeDbQueryPromise;
+  };
+
+  const handler = (_sql: string, _params: unknown[], durationMs: number): void => {
+    void ensureObserveDbQuery().then((observe) => {
+      if (observe === null) return;
+      void observe({ driver: dbConfig.driver, durationMs });
+    });
+  };
+
+  eventEmitter.on('after-query', handler);
+
+  // Return cleanup function
+  return (): void => {
+    eventEmitter.off('after-query', handler);
+  };
+};
+
+const installDbTracingIfEnabled = (
+  dbConfig: DatabaseConfig,
+  eventEmitter: EventEmitter
+): (() => void) | null => {
+  if (Env.getBool('OTEL_ENABLED', false) === false) return null;
+
+  const handler = (_sql: string, _params: unknown[], durationMs: number): void => {
+    OpenTelemetry.recordDbQuerySpan({ driver: dbConfig.driver, durationMs });
+  };
+
+  eventEmitter.on('after-query', handler);
+
+  // Return cleanup function
+  return (): void => {
+    eventEmitter.off('after-query', handler);
+  };
+};
+
+/**
+ * Create connect/disconnect handlers
+ */
+const createConnectionHandlers = (
+  writeAdapter: IDatabaseAdapter,
+  readAdapters: IDatabaseAdapter[],
+  connected: { value: boolean },
+  connectInFlight: { value: Promise<void> | undefined }
+): {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+} => {
+  return {
+    async connect() {
+      if (connected.value) return;
+
+      const inFlight = connectInFlight.value;
+      if (inFlight !== undefined) {
+        await inFlight;
+        return;
+      }
+
+      connectInFlight.value = (async () => {
+        await writeAdapter.connect();
+        await Promise.all(
+          readAdapters
+            .filter((adapter) => adapter !== writeAdapter)
+            .map(async (adapter) => adapter.connect())
+        );
+        connected.value = true;
+      })();
+
+      try {
+        await connectInFlight.value;
+      } finally {
+        connectInFlight.value = undefined;
+      }
+    },
+    async disconnect() {
+      if (connectInFlight.value !== undefined) {
+        await connectInFlight.value.catch(() => {
+          // ignore
+        });
+      }
+      await writeAdapter.disconnect();
+      await Promise.all(
+        readAdapters
+          .filter((adapter) => adapter !== writeAdapter)
+          .map(async (adapter) => adapter.disconnect())
+      );
+      connected.value = false;
+    },
+  };
+};
+
+/**
+ * Create query handlers
+ */
+const createQueryHandlers = (
+  writeAdapter: IDatabaseAdapter,
+  _readAdapters: IDatabaseAdapter[],
+  eventEmitter: EventEmitter,
+  connected: { value: boolean },
+  db: IDatabase,
+  getAdapter: (isRead?: boolean) => IDatabaseAdapter
+): {
+  query(sql: string, parameters?: unknown[], isRead?: boolean): Promise<unknown[]>;
+  queryOne(sql: string, parameters?: unknown[], isRead?: boolean): Promise<unknown>;
+  execute(sql: string, parameters?: unknown[], isRead?: boolean): Promise<QueryResult>;
+  transaction<T>(callback: (db: IDatabase) => Promise<T>): Promise<T>;
+} => {
+  return {
+    async query(sql: string, parameters: unknown[] = [], isRead = false) {
+      if (connected.value === false) await db.connect();
+      const adapter = getAdapter(isRead);
+      const registry = DatabaseAdapterRegistry.list();
+
+      // Validate that database adapters are registered
+      if (registry.length === 0) {
+        throw ErrorFactory.createConfigError(
+          'No database adapters are registered. Call DatabaseAdapterRegistry.register() during startup to register database adapters.'
+        );
+      }
+
+      Logger.debug('Using DB adapter', {
+        type: adapter?.getType?.(),
+        hasRegistry: registry,
+      });
+      return executeQuery(adapter, eventEmitter, sql, parameters, 'query');
+    },
+    async queryOne(sql: string, parameters: unknown[] = [], isRead = false) {
+      if (connected.value === false) await db.connect();
+      const adapter = getAdapter(isRead);
+
+      // Validate that database adapters are registered
+      if (DatabaseAdapterRegistry.list().length === 0) {
+        throw ErrorFactory.createConfigError(
+          'No database adapters are registered. Call DatabaseAdapterRegistry.register() during startup to register database adapters.'
+        );
+      }
+
+      return executeQueryOne(adapter, eventEmitter, sql, parameters);
+    },
+    async execute(sql: string, parameters: unknown[] = [], isRead = false) {
+      if (connected.value === false) await db.connect();
+      const adapter = getAdapter(isRead);
+
+      // Validate that database adapters are registered
+      if (DatabaseAdapterRegistry.list().length === 0) {
+        throw ErrorFactory.createConfigError(
+          'No database adapters are registered. Call DatabaseAdapterRegistry.register() during startup to register database adapters.'
+        );
+      }
+
+      return executeFullQuery(adapter, eventEmitter, sql, parameters);
+    },
+    async transaction<T>(callback: (db: IDatabase) => Promise<T>) {
+      if (connected.value === false) await db.connect();
+
+      // Validate that database adapters are registered
+      if (DatabaseAdapterRegistry.list().length === 0) {
+        throw ErrorFactory.createConfigError(
+          'No database adapters are registered. Call DatabaseAdapterRegistry.register() during startup to register database adapters.'
+        );
+      }
+
+      return writeAdapter.transaction(async () => callback(db));
+    },
+  };
+};
+
+const setupDbInstrumentation = (
+  dbConfig: DatabaseConfig,
+  eventEmitter: EventEmitter
+): Array<() => void> => {
+  const cleanupFunctions: Array<() => void> = [];
+
+  const metricsCleanup = installDbMetricsIfEnabled(dbConfig, eventEmitter);
+  const tracingCleanup = installDbTracingIfEnabled(dbConfig, eventEmitter);
+
+  if (metricsCleanup) cleanupFunctions.push(metricsCleanup);
+  if (tracingCleanup) cleanupFunctions.push(tracingCleanup);
+
+  return cleanupFunctions;
+};
+
+const applyQueryHandlers = (
+  db: IDatabase,
+  queryHandlers: ReturnType<typeof createQueryHandlers>
+): void => {
+  db.query = queryHandlers.query;
+  db.queryOne = queryHandlers.queryOne;
+  db.execute = queryHandlers.execute;
+  db.transaction = queryHandlers.transaction;
+};
+
+const createDbFacade = (input: {
+  dbConfig: DatabaseConfig;
+  writeAdapter: IDatabaseAdapter;
+  eventEmitter: EventEmitter;
+  connected: { value: boolean };
+  getAdapter: (isRead?: boolean) => IDatabaseAdapter;
+  connectionHandlers: ReturnType<typeof createConnectionHandlers>;
+  queryHandlers: ReturnType<typeof createQueryHandlers>;
+  cleanupFunctions: Array<() => void>;
+}): IDatabase => {
+  const {
+    dbConfig,
+    writeAdapter,
+    eventEmitter,
+    connected,
+    getAdapter,
+    connectionHandlers,
+    queryHandlers,
+    cleanupFunctions,
+  } = input;
+
+  const db: IDatabase = {
+    connect: connectionHandlers.connect,
+    disconnect: connectionHandlers.disconnect,
+    isConnected() {
+      return connected.value;
+    },
+    query: queryHandlers.query,
+    queryOne: queryHandlers.queryOne,
+    execute: queryHandlers.execute,
+    transaction: queryHandlers.transaction,
+    table(name) {
+      return QueryBuilder.create(name, db);
+    },
+    onBeforeQuery: (h) => eventEmitter.on('before-query', h),
+    onAfterQuery: (h) => eventEmitter.on('after-query', h),
+    offBeforeQuery: (h) => eventEmitter.off('before-query', h),
+    offAfterQuery: (h) => eventEmitter.off('after-query', h),
+    getAdapterInstance(isRead = false) {
+      return getAdapter(isRead);
+    },
+    getType() {
+      return writeAdapter.getType();
+    },
+    getConfig() {
+      return { ...dbConfig };
+    },
+    dispose() {
+      // Clean up event listeners to prevent memory leaks
+      for (const cleanup of cleanupFunctions) {
+        cleanup();
+      }
+      cleanupFunctions.length = 0;
+    },
+  };
+
+  return db;
+};
+
+const createDatabaseInstance = (dbConfig: DatabaseConfig): IDatabase => {
+  const eventEmitter = new EventEmitter();
+  const connected = { value: false };
+  const connectInFlight = { value: undefined as Promise<void> | undefined };
+  let readIndex = 0;
+
+  const { writeAdapter, readAdapters } = initializeAdapters(dbConfig);
+  const cleanupFunctions = setupDbInstrumentation(dbConfig, eventEmitter);
+
+  const getAdapter = (isRead = false): IDatabaseAdapter => {
+    if (isRead === false || readAdapters.length === 0) {
+      return writeAdapter;
+    }
+    const adapter = readAdapters[readIndex];
+    if (adapter === undefined) return writeAdapter;
+    readIndex = (readIndex + 1) % readAdapters.length;
+    return adapter;
+  };
+
+  const connectionHandlers = createConnectionHandlers(
+    writeAdapter,
+    readAdapters,
+    connected,
+    connectInFlight
+  );
+
+  // Create temporary handlers with db as undefined, then update after db is created
+  let queryHandlers = createQueryHandlers(
+    writeAdapter,
+    readAdapters,
+    eventEmitter,
+    connected,
+    {} as IDatabase,
+    getAdapter
+  );
+
+  const db = createDbFacade({
+    dbConfig,
+    writeAdapter,
+    eventEmitter,
+    connected,
+    getAdapter,
+    connectionHandlers,
+    queryHandlers,
+    cleanupFunctions,
+  });
+
+  // Update handlers with actual db reference for circular dependency
+  queryHandlers = createQueryHandlers(
+    writeAdapter,
+    readAdapters,
+    eventEmitter,
+    connected,
+    db,
+    getAdapter
+  );
+  applyQueryHandlers(db, queryHandlers);
+
+  return db;
+};
+
+export const Database = Object.freeze({
+  /**
+   * Create a new database instance
+   */
+  create(config?: DatabaseConfig): IDatabase {
+    const dbConfig = config ?? { driver: 'sqlite', database: ':memory:' };
+    return createDatabaseInstance(dbConfig);
+  },
+});
+
+const databaseInstances: Map<string, IDatabase> = new Map();
+
+export const useEnsureDbConnected = async (
+  config: DatabaseConfig | undefined = undefined,
+  connectionName = 'default'
+): Promise<ReturnType<typeof useDatabase>> => {
+  const db = useDatabase(config, connectionName);
+  if (!db.isConnected()) {
+    await db.connect();
+  }
+  return db;
+};
+
+export function useDatabase(config?: DatabaseConfig, connection = 'default'): IDatabase {
+  if (databaseInstances.has(connection) === false) {
+    if (config === undefined) {
+      throw ErrorFactory.createConfigError(
+        `Database connection '${connection}' is not registered. ` +
+          `Call useDatabase(config, '${connection}') during startup to register it.`
+      );
+    }
+
+    databaseInstances.set(connection, Database.create(config));
+  }
+  const instance = databaseInstances.get(connection);
+  if (instance === undefined) {
+    throw ErrorFactory.createConfigError(`Failed to initialize database instance: ${connection}`);
+  }
+  return instance;
+}
+
+export async function resetDatabase(): Promise<void> {
+  const promises = Array.from(databaseInstances.values()).map(async (instance) => {
+    try {
+      await instance.disconnect();
+      instance.dispose();
+    } catch {
+      // Ignore errors during disconnect
+    }
+  });
+  await Promise.all(promises);
+  databaseInstances.clear();
+}

package/src/orm/DatabaseAdapter.ts

@@ -0,0 +1,169 @@
+/**
+ * Database Adapter Interface
+ * Defines contract for different database implementations
+ */
+
+import type { SupportedDriver } from '@migrations/enum';
+
+/**
+ * Minimal D1 Database interface for type safety
+ */
+export interface ID1Database {
+  prepare(sql: string): {
+    bind(...values: unknown[]): {
+      all<T = unknown>(): Promise<{ results?: T[]; success: boolean; error?: string }>;
+      first<T = unknown>(): Promise<T | null>;
+      run(): Promise<{ success: boolean; error?: string }>;
+    };
+  };
+}
+
+export interface DatabaseConfig {
+  d1?: ID1Database;
+  driver: SupportedDriver;
+  database?: string;
+  host?: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  synchronize?: boolean;
+  logging?: boolean;
+  readHosts?: string[];
+}
+
+export interface QueryResult {
+  rows: Record<string, unknown>[];
+  rowCount: number;
+  lastInsertId?: string | number | bigint;
+}
+
+export interface IDatabaseAdapter {
+  /**
+   * Connect to database
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect from database
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Execute a query
+   */
+  query(sql: string, parameters: unknown[]): Promise<QueryResult>;
+
+  /**
+   * Execute a query and return first result
+   */
+  queryOne(sql: string, parameters: unknown[]): Promise<Record<string, unknown> | null>;
+
+  /**
+   * Lightweight connection probe.
+   *
+   * This should be safe to call from health/readiness endpoints.
+   */
+  ping(): Promise<void>;
+
+  /**
+   * Execute multiple queries in transaction
+   */
+  transaction<T>(callback: (adapter: IDatabaseAdapter) => Promise<T>): Promise<T>;
+
+  /**
+   * Execute raw SQL query (only available when USE_RAW_QRY=true)
+   * WARNING: Bypasses QueryBuilder safety. Use parameterized queries.
+   */
+  rawQuery<T = unknown>(sql: string, parameters?: unknown[]): Promise<T[]>;
+
+  /**
+   * Ensure the migrations tracking table exists.
+   *
+   * This intentionally lives on the adapter so higher-level framework code
+   * doesn't embed DDL SQL.
+   */
+  ensureMigrationsTable?(): Promise<void>;
+
+  /**
+   * Best-effort schema reset for development workflows.
+   *
+   * For SQL databases, this typically means dropping user tables.
+   */
+  resetSchema?(): Promise<void>;
+
+  /**
+   * Get database type
+   */
+  getType(): SupportedDriver;
+
+  /**
+   * Check connection status
+   */
+  isConnected(): boolean;
+
+  /**
+   * Get placeholder for parameterized query
+   */
+  getPlaceholder(index: number): string;
+}
+
+/**
+ * Base Adapter Utilities
+ * Refactored to Functional Object pattern
+ */
+export const BaseAdapter = Object.freeze({
+  /**
+   * Sanitize parameter value
+   */
+  sanitize(value: unknown): string {
+    if (value === null || value === undefined) {
+      return 'NULL';
+    }
+    if (typeof value === 'string') {
+      return `'${value.replaceAll("'", "''")}'`;
+    }
+    if (typeof value === 'boolean') {
+      return value ? '1' : '0';
+    }
+    // Support BigInt explicitly to avoid JSON.stringify errors and driver issues
+    if (typeof value === 'bigint') {
+      return String(value);
+    }
+    // Dates should be passed as ISO strings
+    if (value instanceof Date) {
+      return `'${value.toISOString()}'`;
+    }
+    if (typeof value === 'number') {
+      return String(value);
+    }
+    // Buffer / Uint8Array -> base64 string
+    // Some DB adapters expect binary types; returning base64-encoded string is a safe default
+    // and prevents JSON.stringify(BigInt) errors when objects include BigInt.
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
+      return `'${value.toString('base64')}'`;
+    }
+    if (value instanceof Uint8Array) {
+      return `'${Buffer.from(value).toString('base64')}'`;
+    }
+
+    // For objects, convert to JSON string representation
+    return `'${JSON.stringify(value).replaceAll("'", "''")}'`;
+  },
+
+  /**
+   * Build parameterized query (for adapters that need it)
+   */
+  buildParameterizedQuery(
+    sql: string,
+    parameters: unknown[],
+    getPlaceholder: (index: number) => string = () => '?'
+  ): { sql: string; parameters: unknown[] } {
+    let paramIndex = 0;
+    const processedSql = sql.replaceAll('?', () => {
+      paramIndex++;
+      return getPlaceholder(paramIndex);
+    });
+
+    return { sql: processedSql, parameters };
+  },
+});