@zintrust/core 0.1.28 → 0.1.29

package/src/orm/Database.ts

@@ -1,521 +0,0 @@
-/**
- * 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

@@ -1,169 +0,0 @@
-/**
- * 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 };
-  },
-});