@plyaz/db 0.0.0

package/dist/service/DatabaseService.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Internal Database Service Implementation for @plyaz/db package
+ *
+ * This module provides the internal DatabaseService class that orchestrates all database
+ * operations. It is NOT exported and is created internally by the createDatabaseService() factory.
+ *
+ * Part of the @plyaz/db package - a TypeScript database abstraction layer with
+ * support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
+ * soft delete), and advanced features (caching, read replicas, multi-tenancy).
+ *
+ */
+import { DatabaseEventEmitter } from "./EventEmitter";
+import type { AuditContext, BatchUpdate, CreateInput, DatabaseAdapterType, DatabaseEvent, DatabaseEvents, DatabaseHealthStatus, DatabaseResult, DatabaseServiceConfig, DatabaseServiceInterface, Filter, OperationConfig, PaginatedResult, QueryOptions, ServiceStatus, TableName, TransactionFn, UpdateInput } from "@plyaz/types/db";
+/**
+ * 🛠️ DATABASE SERVICE - Internal Service Layer
+ *
+ * Core service implementation that orchestrates all database operations.
+ * NOT EXPORTED - created internally by createDatabaseService() factory.
+ *
+ * **Application Flow Position:**
+ * createDatabaseService() → **DatabaseService** → Adapter Chain → Database
+ *
+ * **What this class does:**
+ * 1. Stores global configuration from createDatabaseService()
+ * 2. Receives calls from repositories via IDatabaseService interface
+ * 3. Merges per-operation config with global config using ConfigMerger
+ * 4. Fires before/after events (onBeforeWrite, onAfterWrite, etc.)
+ * 5. Delegates to adapter chain with resolved configuration
+ * 6. Returns results back to repositories
+ *
+ * **Called by:** Repository layer (BaseRepository, UserRepository, etc.)
+ * **Calls:** ConfigMerger.mergeConfigs(), adapter chain methods, event handlers
+ * **Delegates to:** Final wrapped adapter (ReadReplicaAdapter → AuditAdapter → ... → BaseAdapter)
+ *
+ * **Key Responsibilities:**
+ * - Configuration merging and resolution
+ * - Event system orchestration
+ * - Audit context management
+ * - Error handling and propagation
+ * - Service status tracking
+ *
+ * @internal This class is not part of the public API
+ */
+export declare class DatabaseService implements DatabaseServiceInterface {
+    private readonly globalConfig;
+    private readonly adapter;
+    private readonly eventHandlers;
+    private readonly eventEmitter;
+    private readonly healthManager;
+    private readonly startTime;
+    private auditContext;
+    constructor(config: {
+        adapter: DatabaseAdapterType;
+        globalConfig: DatabaseServiceConfig;
+        eventHandlers?: DatabaseEvents;
+    });
+    /**
+     * 🔍 Get a single record by ID
+     *
+     * **Flow:** Repository.findById() → **DatabaseService.get()** → ConfigMerger → Adapter Chain → Database
+     *
+     * **What happens:**
+     * 1. Merges operation config with global config using ConfigMerger
+     * 2. Fires onBeforeRead event (if configured)
+     * 3. Delegates to adapter chain: ReadReplica → Audit → Cache → SoftDelete → Encryption → Base
+     * 4. Fires onAfterRead event on success
+     * 5. Returns result to repository
+     *
+     * **Called by:** BaseRepository.findById(), custom repository methods
+     * **Calls:** ConfigMerger.mergeConfigs(), this.adapter.findById(), event handlers
+     *
+     * @param table Table name (from Tables enum)
+     * @param id Record ID to retrieve
+     * @param operationConfig Optional per-operation configuration overrides
+     * @returns Promise resolving to the record or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Called by UserRepository.findById()
+     * const user = await this.db.get(Tables.USERS, 'user-123');
+     *
+     * // With operation config override
+     * const user = await this.db.get(Tables.USERS, 'user-123', {
+     *   forceAdapter: 'primary',  // Force primary DB
+     *   cache: { enabled: false } // Skip cache
+     * });
+     * ```
+     */
+    get<T>(table: TableName, id: string, operationConfig?: OperationConfig): Promise<DatabaseResult<T | null>>;
+    /**
+     * List records with optional filtering, sorting, and pagination
+     * Merges operation config with global config before delegating
+     */
+    list<T>(table: TableName, options?: QueryOptions, operationConfig?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
+    /**
+     * Create a new record
+     * Merges operation config with global config before delegating
+     */
+    create<T>(table: TableName, input: CreateInput<T>, operationConfig?: OperationConfig): Promise<DatabaseResult<T>>;
+    /**
+     * Update an existing record
+     * Merges operation config with global config before delegating
+     */
+    update<T>(table: TableName, id: string, input: UpdateInput<T>, operationConfig?: OperationConfig): Promise<DatabaseResult<T>>;
+    /**
+     * Delete a record
+     * Merges operation config with global config before delegating
+     */
+    delete(table: TableName, id: string, operationConfig?: OperationConfig): Promise<DatabaseResult<void>>;
+    batchCreate<T>(table: TableName, inputs: CreateInput<T>[], operationConfig?: OperationConfig): Promise<DatabaseResult<T[]>>;
+    batchUpdate<T>(table: TableName, updates: BatchUpdate<T>[], operationConfig?: OperationConfig): Promise<DatabaseResult<T[]>>;
+    batchDelete(table: TableName, ids: string[], operationConfig?: OperationConfig): Promise<DatabaseResult<void>>;
+    query<T>(table: TableName, query: QueryOptions, operationConfig?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
+    count(table: TableName, filter?: Filter, operationConfig?: OperationConfig): Promise<DatabaseResult<number>>;
+    transaction<T>(fn: TransactionFn<T>): Promise<DatabaseResult<T>>;
+    setAuditContext(context: AuditContext): Promise<DatabaseResult<void>>;
+    on<T extends DatabaseEvent["type"]>(event: T, handler: (event: Extract<DatabaseEvent, {
+        type: T;
+    }>) => void | Promise<void>): void;
+    off<T extends DatabaseEvent["type"]>(event: T, handler: (event: Extract<DatabaseEvent, {
+        type: T;
+    }>) => void | Promise<void>): void;
+    healthCheck(): Promise<DatabaseResult<DatabaseHealthStatus>>;
+    getStatus(): ServiceStatus;
+    findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>>;
+    findMany<T>(table: string, options?: QueryOptions): Promise<DatabaseResult<PaginatedResult<T>>>;
+    initialize(): Promise<DatabaseResult<void>>;
+    registerTable(): void;
+    exists(table: string, id: string): Promise<DatabaseResult<boolean>>;
+    private fireBeforeReadEvent;
+    private fireAfterReadEvent;
+    findOne<T>(table: TableName, filter: Filter, operationConfig?: OperationConfig): Promise<DatabaseResult<T | null>>;
+    softDelete(table: TableName, id: string, operationConfig?: OperationConfig): Promise<DatabaseResult<void>>;
+    get events(): DatabaseEventEmitter;
+}
+//# sourceMappingURL=DatabaseService.d.ts.map

package/dist/service/DatabaseService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseService.d.ts","sourceRoot":"","sources":["../../src/service/DatabaseService.ts"],"names":[],"mappings":"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"}

package/dist/service/EventEmitter.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview DatabaseEventEmitter - Event management for database operations
+ *
+ * Provides a comprehensive event system for monitoring and reacting to database
+ * operations. The DatabaseEventEmitter implements the Observer pattern to enable
+ * decoupled monitoring of database activities, allowing multiple components to
+ * subscribe to and react to various database events.
+ *
+ * **Application Flow Context:**
+ * ```
+ * Database Operations → DatabaseEventEmitter → Event Handlers
+ *         ↓                    ↓                  ↓
+ * Query Execution   → Event Emission     → Logging
+ * Transaction       → Handler Dispatch   → Monitoring
+ * Health Changes    → Error Handling     → Alerting
+ * ```
+ *
+ * **Supported Events:**
+ * - **BeforeQuery**: Emitted before database queries
+ * - **AfterQuery**: Emitted after successful queries
+ * - **QueryError**: Emitted when queries fail
+ * - **BeforeTransaction**: Emitted before transactions start
+ * - **AfterTransaction**: Emitted after transactions complete
+ * - **TransactionRollback**: Emitted when transactions rollback
+ * - **HealthChange**: Emitted when database health status changes
+ *
+ * @example
+ * ```typescript
+ * // Event emitter setup
+ * const eventEmitter = new DatabaseEventEmitter('drizzle');
+ *
+ * // Subscribe to query events
+ * eventEmitter.on('BeforeQuery', (event) => {
+ *   console.log(`Executing ${event.operation} on ${event.table}`);
+ * });
+ *
+ * eventEmitter.on('QueryError', (event) => {
+ *   console.error(`Query failed: ${event.error.message}`);
+ * });
+ *
+ * // Emit events during database operations
+ * eventEmitter.emitBeforeQuery('users', 'SELECT', { id: '123' });
+ * ```
+ *
+ */
+import type { ContextType } from "@nestjs/common";
+import type { DatabaseEvent, DatabaseOperationType, DBEventHandler } from "@plyaz/types";
+import type { ADAPTERS } from "@plyaz/types";
+/**
+ * Emit a query error event
+ */
+interface EmitQueryErrorOptions {
+    table: string;
+    operation: DatabaseOperationType;
+    error: Error;
+    params?: Record<string, object>;
+    context?: ContextType;
+}
+/**
+ * Event emitter for database events that implements the observer pattern.
+ * This class manages event subscriptions and emissions for various database operations,
+ * allowing decoupled monitoring of database activities.
+ *
+ * @class
+ * @implements {DatabaseEventEmitter}
+ */
+export declare class DatabaseEventEmitter implements DatabaseEventEmitter {
+    private readonly adapter;
+    private readonly eventHandlers;
+    constructor(adapter: ADAPTERS);
+    /**
+     * Register an event handler for a specific event type
+     */
+    on<T extends DatabaseEvent>(eventType: T["type"], handler: DBEventHandler<T>): void;
+    /**
+     * Remove an event handler for a specific event type
+     */
+    off<T extends DatabaseEvent>(eventType: T["type"], handler: DBEventHandler<T>): void;
+    /**
+     * Emit an event to all registered handlers
+     */
+    emit(event: DatabaseEvent): void;
+    /**
+     * Emit a before query event
+     */
+    emitBeforeQuery(table: string, operation: DatabaseOperationType, params?: Record<string, object>, context?: ContextType): void;
+    /**
+     * Emit an after query event
+     */
+    emitAfterQuery(table: string, operation: DatabaseOperationType, duration: number, affectedRows?: number): void;
+    emitQueryError(options: EmitQueryErrorOptions): void;
+    /**
+     * Emit a before transaction event
+     */
+    emitBeforeTransaction(transactionId: string, context?: ContextType): void;
+    /**
+     * Emit an after transaction event
+     */
+    emitAfterTransaction(transactionId: string, duration: number): void;
+    /**
+     * Emit a transaction rollback event
+     */
+    emitTransactionRollback(transactionId: string, error?: Error): void;
+    /**
+     * Emit a health change event
+     */
+    emitHealthChange(previousStatus: boolean, currentStatus: boolean, details?: Record<string, string | number | boolean>): void;
+}
+export {};
+//# sourceMappingURL=EventEmitter.d.ts.map

package/dist/service/EventEmitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventEmitter.d.ts","sourceRoot":"","sources":["../../src/service/EventEmitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAKV,aAAa,EACb,qBAAqB,EACrB,cAAc,EAIf,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAM7C;;GAEG;AACH,UAAU,qBAAqB;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,qBAAqB,CAAC;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,oBAAoB;IAInD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAClB;gBAEiB,OAAO,EAAE,QAAQ;IAa9C;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,aAAa,EACxB,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,EACpB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,IAAI;IAuCP;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,aAAa,EACzB,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,EACpB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,IAAI;IAQP;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IA6BhC;;OAEG;IACH,eAAe,CACb,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,qBAAqB,EAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,OAAO,CAAC,EAAE,WAAW,GACpB,IAAI;IAaP;;OAEG;IACH,cAAc,CACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,qBAAqB,EAChC,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI;IAaP,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAiCpD;;OAEG;IACH,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAWzE;;OAEG;IACH,oBAAoB,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAWnE;;OAEG;IACH,uBAAuB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI;IAWnE;;OAEG;IACH,gBAAgB,CACd,cAAc,EAAE,OAAO,EACvB,aAAa,EAAE,OAAO,EACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAClD,IAAI;CAWR"}

package/dist/service/HealthManager.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview Health Manager for @plyaz/db package
+ *
+ * This module provides the HealthManager class responsible for monitoring database
+ * connection health, performing periodic health checks, and managing the lifecycle
+ * of database connections. It provides a centralized way to track database status.
+ *
+ * Part of the @plyaz/db package - a TypeScript database abstraction layer with
+ * support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
+ * soft delete), and advanced features (caching, read replicas, multi-tenancy).
+ *
+ */
+import type { DatabaseAdapterType, DatabaseHealthStatus, DatabaseResult } from "@plyaz/types/db";
+/**
+ * 🌡️ HEALTH MANAGER - Database Health Monitoring
+ *
+ * Manages database health checks and monitoring functionality for all database adapters.
+ * This class is responsible for performing health checks on the database connection,
+ * storing the last known health status, and providing methods to quickly check
+ * the current health state of the database.
+ *
+ * **Application Flow Position:**
+ * DatabaseService → **HealthManager** → Adapter.healthCheck() → Database
+ *
+ * **What this class does:**
+ * 1. Initializes database connections on startup
+ * 2. Performs periodic health checks via adapter.healthCheck()
+ * 3. Caches last known health status for quick access
+ * 4. Normalizes health details across different adapters
+ * 5. Manages connection lifecycle (connect/disconnect)
+ *
+ * **Called by:** DatabaseService.healthCheck(), application health endpoints
+ * **Calls:** DatabaseAdapter.healthCheck(), DatabaseAdapter.connect/disconnect
+ * **Used for:** Application health monitoring, load balancer health checks
+ *
+ * @example
+ * ```typescript
+ * // Create health manager with adapter
+ * const healthManager = new HealthManager(drizzleAdapter);
+ *
+ * // Initialize connection and perform initial health check
+ * await healthManager.init();
+ *
+ * // Perform health check
+ * const healthResult = await healthManager.checkHealth();
+ * if (healthResult.success) {
+ *   console.log('Database is healthy:', healthResult.value);
+ * }
+ *
+ * // Quick health status check (uses cached result)
+ * const isHealthy = healthManager.isHealthy();
+ *
+ * // Get last known status without new check
+ * const lastStatus = healthManager.getLastHealthStatus();
+ *
+ * // Cleanup on shutdown
+ * await healthManager.shutdown();
+ * ```
+ *
+ */
+export declare class HealthManager {
+    private readonly adapter;
+    private lastHealthStatus;
+    private initialized;
+    constructor(adapter: DatabaseAdapterType);
+    /**
+     * Initializes the health manager by establishing database connection and performing initial health check
+     *
+     * Sets up the database connection and performs an initial health check to establish
+     * baseline health status. This method should be called during application startup
+     * to ensure the database is ready for operations.
+     *
+     * **Initialization Process:**
+     * 1. Checks if already initialized (prevents double initialization)
+     * 2. Calls adapter.connect() if available (establishes connection)
+     * 3. Performs initial health check via checkHealth()
+     * 4. Sets initialized flag to prevent re-initialization
+     *
+     * @returns {Promise<void>} Promise that resolves when initialization is complete
+     *
+     * @example
+     * ```typescript
+     * const healthManager = new HealthManager(adapter);
+     *
+     * // Initialize during application startup
+     * await healthManager.init();
+     * console.log('Health manager initialized');
+     *
+     * // Subsequent calls are no-ops
+     * await healthManager.init(); // Does nothing, already initialized
+     * ```
+     *
+     */
+    init(): Promise<void>;
+    /**
+     * Performs a comprehensive health check on the database connection
+     *
+     * Executes a health check via the database adapter and normalizes the results
+     * into a standardized health status format. Measures response time and handles
+     * both successful and failed health checks gracefully.
+     *
+     * **Health Check Process:**
+     * 1. Records start time for response time measurement
+     * 2. Calls adapter.healthCheck() to test database connectivity
+     * 3. Normalizes adapter-specific response into standard format
+     * 4. Caches result as lastHealthStatus for quick access
+     * 5. Returns standardized DatabaseResult with health information
+     *
+     * **Health Status Fields:**
+     * - isHealthy: Boolean indicating if database is operational
+     * - responseTime: Time in milliseconds for health check to complete
+     * - details: Normalized adapter-specific details (connection info, errors, etc.)
+     *
+     * @returns {Promise<DatabaseResult<DatabaseHealthStatus>>} Promise resolving to health status result
+     *
+     * @example
+     * ```typescript
+     * // Perform health check
+     * const healthResult = await healthManager.checkHealth();
+     *
+     * if (healthResult.success) {
+     *   const status = healthResult.value;
+     *   console.log(`Database healthy: ${status.isHealthy}`);
+     *   console.log(`Response time: ${status.responseTime}ms`);
+     *   console.log('Details:', status.details);
+     * } else {
+     *   console.error('Health check failed:', healthResult.error.message);
+     * }
+     *
+     * // Example healthy response:
+     * // {
+     * //   success: true,
+     * //   value: {
+     * //     isHealthy: true,
+     * //     responseTime: 45,
+     * //     details: { adapter: "drizzle", connections: "5" }
+     * //   }
+     * // }
+     *
+     * // Example unhealthy response:
+     * // {
+     * //   success: true,
+     * //   value: {
+     * //     isHealthy: false,
+     * //     responseTime: 5000,
+     * //     details: { error: "Connection timeout" }
+     * //   }
+     * // }
+     * ```
+     *
+     */
+    checkHealth(): Promise<DatabaseResult<DatabaseHealthStatus>>;
+    /**
+     * Get the last known health status
+     */
+    getLastHealthStatus(): DatabaseHealthStatus | null;
+    /**
+     * Check if the database is currently healthy
+     */
+    isHealthy(): boolean;
+    /**
+     * Gracefully shut down the health manager
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=HealthManager.d.ts.map

package/dist/service/HealthManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HealthManager.d.ts","sourceRoot":"","sources":["../../src/service/HealthManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACf,MAAM,iBAAiB,CAAC;AAMzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,aAAa;IAIZ,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,gBAAgB,CAAqC;IAC7D,OAAO,CAAC,WAAW,CAAS;gBAEC,OAAO,EAAE,mBAAmB;IAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACG,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAsClE;;OAEG;IACH,mBAAmB,IAAI,oBAAoB,GAAG,IAAI;IAIlD;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAQhC"}

package/dist/utils/ConfigMerger.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @fileoverview Configuration Merger for @plyaz/db package
+ *
+ * This module provides the ConfigMerger utility class responsible for deep merging
+ * database configurations. It handles merging global database service configuration
+ * with per-operation overrides to create resolved configurations for the adapter chain.
+ *
+ * Part of the @plyaz/db package - a TypeScript database abstraction layer with
+ * support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
+ * soft delete), and advanced features (caching, read replicas, multi-tenancy).
+ */
+import type { DatabaseServiceConfig, OperationConfig, ResolvedOperationConfig } from "@plyaz/types/db";
+/**
+ *  CONFIG MERGER - Configuration Resolution Engine
+ *
+ * Utility class for deep merging database configurations.
+ * Handles merging global database service configuration with per-operation overrides
+ *
+ * Application Flow Position:**
+ * DatabaseService → **ConfigMerger** → Resolved Config → Adapter Chain
+ *
+ * **What this class does:**
+ * 1. Receives global config (from createDatabaseService) and operation config (from method calls)
+ * 2. Deep merges nested objects (encryption, softDelete, cache, etc.)
+ * 3. Operation config takes precedence over global config
+ * 4. Returns resolved configuration for adapter chain
+ *
+ * **Called by:** DatabaseService methods (get, create, update, delete, etc.)
+ * **Calls:** Internal merge methods for each config section
+ * **Returns to:** DatabaseService for delegation to adapter chain
+ *
+ * **Merge Strategy:**
+ * - Operation config overrides global config
+ * - Nested objects are deep merged (not replaced)
+ * - Arrays use replace strategy for fields, concat for others
+ * - Undefined values in operation config fall back to global defaults
+ *
+ * @example
+ * ### Configuration Merging Flow
+ * ```typescript
+ * // Global config (from createDatabaseService)
+ * const globalConfig = {
+ *   softDelete: { enabled: true, field: 'deletedAt' },
+ *   cache: { enabled: true, ttl: 300 }
+ * };
+ *
+ * // Operation config (from method call)
+ * const operationConfig = {
+ *   cache: { enabled: false },
+ *   includeSoftDeleted: true
+ * };
+ *
+ * // ConfigMerger.mergeConfigs() produces:
+ * const resolved = {
+ *   softDelete: { enabled: true, field: 'deletedAt' }, // From global
+ *   cache: { enabled: false, ttl: 300 },               // Merged
+ *   includeSoftDeleted: true,                          // From operation
+ *   skipAudit: false                                   // Default
+ * };
+ * ```
+ */
+export declare class ConfigMerger {
+    /**
+     * Merges global database configuration with operation-specific overrides
+     *
+     * This is the main entry point for configuration resolution in the DatabaseService.
+     * It performs deep merging of nested configuration objects while preserving type safety
+     * and applying proper precedence rules.
+     *
+     * **Merge Precedence (highest to lowest):**
+     * 1. Operation-specific config (method-level overrides)
+     * 2. Global service config (from createDatabaseService)
+     * 3. Default values (built-in fallbacks)
+     *
+     * **Configuration Sections Merged:**
+     * - softDelete: Logical deletion settings
+     * - encryption: Field-level encryption settings
+     * - cache: Caching behavior and TTL
+     * - timestamps: Automatic timestamp management
+     * - Operation flags: skipAudit, includeSoftDeleted, etc.
+     *
+     * @param {DatabaseServiceConfig} global - Global database service configuration from createDatabaseService()
+     * @param {OperationConfig} [operation] - Optional operation-specific configuration overrides
+     * @returns {ResolvedOperationConfig} Fully resolved configuration with all defaults applied
+     *
+     * @example
+     * ```typescript
+     * // In DatabaseService.get() method
+     * const resolvedConfig = ConfigMerger.mergeConfigs(
+     *   this.globalConfig,  // From createDatabaseService
+     *   operationConfig     // From method parameter
+     * );
+     *
+     * // Example global config
+     * const globalConfig = {
+     *   softDelete: { enabled: true, field: 'deletedAt' },
+     *   encryption: { enabled: true, fields: { users: ['ssn'] } },
+     *   cache: { enabled: true, ttl: 300 }
+     * };
+     *
+     * // Example operation config (disable cache for this operation)
+     * const operationConfig = {
+     *   cache: { enabled: false },
+     *   skipAudit: true
+     * };
+     *
+     * // Resulting merged config
+     * const result = {
+     *   softDelete: { enabled: true, field: 'deletedAt' },     // From global
+     *   encryption: { enabled: true, fields: { users: ['ssn'] } }, // From global
+     *   cache: { enabled: false, ttl: 300 },                   // Merged (enabled overridden)
+     *   timestamps: undefined,                                  // Not specified
+     *   skipAudit: true,                                        // From operation
+     *   includeSoftDeleted: false,                             // Default
+     *   forceAdapter: undefined,                               // Not specified
+     *   timeout: 30000                                         // Default
+     * };
+     * ```
+     *
+     */
+    static mergeConfigs(global: DatabaseServiceConfig, operation?: OperationConfig): ResolvedOperationConfig;
+    /**
+     * Merges soft delete configuration with operation-specific overrides
+     *
+     * Handles deep merging of soft delete settings, allowing operation-level
+     * overrides while preserving base configuration values.
+     *
+     * @private
+     * @param {SoftDeleteConfig} [base] - Base soft delete configuration from global config
+     * @param {Partial<SoftDeleteConfig>} [override] - Operation-specific soft delete overrides
+     * @returns {SoftDeleteConfig | undefined} Merged soft delete configuration or undefined if neither provided
+     *
+     * @example
+     * ```typescript
+     * // Base config: { enabled: true, field: 'deletedAt', excludeTables: ['logs'] }
+     * // Override: { enabled: false }
+     * // Result: { enabled: false, field: 'deletedAt', excludeTables: ['logs'] }
+     * ```
+     *
+     */
+    private static mergeSoftDeleteConfig;
+    /**
+     * Merges encryption configuration with operation-specific overrides
+     *
+     * Handles deep merging of field-level encryption settings, allowing operation-level
+     * overrides for encryption behavior while preserving base configuration.
+     *
+     * @private
+     * @param {DBEncryptionConfig} [base] - Base encryption configuration from global config
+     * @param {Partial<DBEncryptionConfig>} [override] - Operation-specific encryption overrides
+     * @returns {DBEncryptionConfig | undefined} Merged encryption configuration or undefined if neither provided
+     *
+     * @example
+     * ```typescript
+     * // Base config: { enabled: true, key: 'base64key', fields: { users: ['ssn'] } }
+     * // Override: { enabled: false }
+     * // Result: { enabled: false, key: 'base64key', fields: { users: ['ssn'] } }
+     * ```
+     *
+     */
+    private static mergeEncryptionConfig;
+    /**
+     * Merges cache configuration with operation-specific overrides
+     *
+     * Handles deep merging of caching settings, allowing operation-level
+     * overrides for cache behavior (enable/disable, TTL changes, etc.).
+     *
+     * @private
+     * @param {DBCacheConfig} [base] - Base cache configuration from global config
+     * @param {Partial<DBCacheConfig>} [override] - Operation-specific cache overrides
+     * @returns {DBCacheConfig | undefined} Merged cache configuration or undefined if neither provided
+     *
+     * @example
+     * ```typescript
+     * // Base config: { enabled: true, ttl: 300, provider: 'redis' }
+     * // Override: { enabled: false }
+     * // Result: { enabled: false, ttl: 300, provider: 'redis' }
+     * ```
+     *
+  
+     */
+    private static mergeCacheConfig;
+    /**
+     * Merges timestamps configuration with operation-specific overrides
+     *
+     * Handles deep merging of automatic timestamp settings, allowing operation-level
+     * overrides for timestamp field names and auto-update behavior.
+     *
+     * @private
+     * @param {TimestampsConfig} [base] - Base timestamps configuration from global config
+     * @param {Partial<TimestampsConfig>} [override] - Operation-specific timestamp overrides
+     * @returns {TimestampsConfig | undefined} Merged timestamps configuration or undefined if neither provided
+     *
+     * @example
+     * ```typescript
+     * // Base config: { enabled: true, createdAtField: 'createdAt', updatedAtField: 'updatedAt' }
+     * // Override: { autoUpdate: false }
+     * // Result: { enabled: true, createdAtField: 'createdAt', updatedAtField: 'updatedAt', autoUpdate: false }
+     * ```
+     */
+    private static mergeTimestampsConfig;
+    /**
+     * Converts global database service configuration to resolved operation configuration
+     *
+     * Used when no operation-specific overrides are provided. Applies default values
+     * for operation-specific flags while preserving global configuration settings.
+     *
+     * @private
+     * @param {DatabaseServiceConfig} global - Global database service configuration
+     * @returns {ResolvedOperationConfig} Resolved configuration with defaults applied
+     *
+     * @example
+     * ```typescript
+     * // Global config: { softDelete: { enabled: true }, cache: { enabled: true, ttl: 300 } }
+     * // Result: {
+     * //   softDelete: { enabled: true },
+     * //   cache: { enabled: true, ttl: 300 },
+     * //   skipAudit: false,           // Default
+     * //   includeSoftDeleted: false, // Default
+     * //   timeout: 30000            // Default
+     * // }
+     * ```
+     *
+     */
+    private static convertGlobalToResolved;
+}
+//# sourceMappingURL=ConfigMerger.d.ts.map

package/dist/utils/ConfigMerger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigMerger.d.ts","sourceRoot":"","sources":["../../src/utils/ConfigMerger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EACV,qBAAqB,EAGrB,eAAe,EACf,uBAAuB,EAGxB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,YAAY;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyDG;IACH,MAAM,CAAC,YAAY,CACjB,MAAM,EAAE,qBAAqB,EAC7B,SAAS,CAAC,EAAE,eAAe,GAC1B,uBAAuB;IA0B1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAmBpC;;;;;;;;;;;;;;;;;;OAkBG;IAEH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAqBpC;;;;;;;;;;;;;;;;;;;OAmBG;IAEH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAoB/B;;;;;;;;;;;;;;;;;OAiBG;IAEH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAoBpC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;CAevC"}