@plyaz/db 0.0.0

package/dist/extensions/AuditExtension.d.ts

@@ -0,0 +1,468 @@
+import type { DatabaseAdapterType, DatabaseResult, Filter, DatabaseHealthStatus, PaginatedResult, QueryOptions, Transaction, AuditContext, AuditEvent } from "@plyaz/types/db";
+/**
+ * AUDIT ADAPTER - Compliance Logging Layer
+ *
+ * Audit extension that automatically logs all database operations for compliance.
+ * Fifth layer in the adapter chain (second from outermost).
+ *
+ * **Adapter Chain Position:**
+ * ReadReplica � **Audit** � Cache � SoftDelete � Encryption � Base Adapter
+ *
+ * **What this adapter does:**
+ * 1. Captures before-state for update/delete operations
+ * 2. Delegates to next adapter in chain
+ * 3. Captures after-state and writes audit record to daily audit tables
+ * 4. Calls onAuditAfterWrite event handler (if configured)
+ * 5. Honors skipAudit flag from operation config
+ *
+ * **Called by:** ReadReplicaAdapter (or DatabaseService if no read replicas)
+ * **Calls:** CachingAdapter (or next adapter in chain)
+ * **Writes to:** Daily audit tables (audit_YYYYMMDD)
+ *
+ * **Audit Flow:**
+ * 1. **CREATE:** Records after-state only
+ * 2. **UPDATE:** Records before-state, after-state, and changed fields
+ * 3. **DELETE:** Records before-state only
+ * 4. **SOFT_DELETE:** Records before/after state with deletedAt change
+ *
+ * **Audit Context:** Uses context from DatabaseService.setAuditContext()
+ * - userId, requestId, ipAddress, userAgent
+ *
+ * @example
+ * ### Configuration
+ * ```typescript
+ * audit: {
+ *   enabled: true,
+ *   retentionDays: 90,
+ *   excludeFields: ['password', 'token'],
+ *   excludeTables: ['temp_data'],
+ *   onAuditAfterWrite: async (event) => {
+ *     await complianceService.recordAudit(event);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ### Audit Record Structure
+ * ```typescript
+ * // Written to audit_20241201 table
+ * {
+ *   operation: 'UPDATE',
+ *   table: 'users',
+ *   recordId: 'user-123',
+ *   userId: 'admin-456',
+ *   requestId: 'req-789',
+ *   changes: {
+ *     before: { name: 'John Doe', email: 'john@old.com' },
+ *     after: { name: 'John Smith', email: 'john@new.com' },
+ *     fields: ['name', 'email']
+ *   },
+ *   timestamp: '2024-12-01T10:30:00Z',
+ *   ipAddress: '192.168.1.1',
+ *   userAgent: 'Mozilla/5.0...'
+ * }
+ * ```
+ */
+export declare class AuditAdapter implements DatabaseAdapterType {
+    private baseAdapter;
+    private config;
+    private auditContext;
+    /**
+     * Creates a new AuditAdapter instance.
+     *
+     * **RESPONSIBILITY:** Wraps base adapter with audit logging functionality
+     * **CONFIGURATION:** Sets up audit rules, retention, and event handlers
+     *
+     * @param baseAdapter - The underlying database adapter to wrap
+     * @param config - Audit configuration options
+     *
+     * @example
+     * ```typescript
+     * const auditAdapter = new AuditAdapter(baseAdapter, {
+     *   enabled: true,
+     *   retentionDays: 90,
+     *   excludeFields: ['password', 'token'],
+     *   excludeTables: ['temp_data'],
+     *   onAuditAfterWrite: async (event) => {
+     *     await complianceService.recordAudit(event);
+     *   }
+     * });
+     * ```
+     */
+    constructor(baseAdapter: DatabaseAdapterType, config: {
+        enabled: boolean;
+        retentionDays?: number;
+        excludeFields?: string[];
+        excludeTables?: string[];
+        onAuditAfterWrite?: (event: AuditEvent) => void | Promise<void>;
+    });
+    /**
+     * Initializes the audit adapter and underlying adapter.
+     *
+     * **RESPONSIBILITY:** Passes initialization to base adapter
+     * **BEHAVIOR:** No additional initialization needed for audit
+     *
+     * @returns Promise resolving to initialization result
+     *
+     * @example
+     * ```typescript
+     * const result = await auditAdapter.initialize();
+     * if (result.success) {
+     *   console.log('Audit adapter initialized');
+     * }
+     * ```
+     */
+    initialize(): Promise<DatabaseResult<void>>;
+    /**
+     * Establishes database connection through base adapter.
+     *
+     * **RESPONSIBILITY:** Delegates connection to underlying adapter
+     * **BEHAVIOR:** No additional connection logic needed
+     *
+     * @example
+     * ```typescript
+     * await auditAdapter.connect();
+     * console.log('Connected with audit support');
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Closes database connection through base adapter.
+     *
+     * **RESPONSIBILITY:** Delegates disconnection to underlying adapter
+     * **BEHAVIOR:** No additional cleanup needed for audit
+     *
+     * @example
+     * ```typescript
+     * await auditAdapter.disconnect();
+     * console.log('Disconnected gracefully');
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Gets the underlying database client.
+     *
+     * **RESPONSIBILITY:** Provides access to raw database client
+     * **USE CASE:** For operations that bypass audit logging
+     *
+     * @returns Database client object
+     *
+     * @example
+     * ```typescript
+     * const client = auditAdapter.getClient();
+     * // Use for direct database operations if needed
+     * ```
+     */
+    getClient(): object;
+    /**
+     * Executes raw SQL query through base adapter.
+     *
+     * **RESPONSIBILITY:** Passes raw SQL to base adapter without audit logging
+     * **BEHAVIOR:** Does not audit raw SQL operations
+     * **NOTE:** Use CRUD methods for automatic audit logging
+     *
+     * @param sql - SQL query string
+     * @param params - Query parameters
+     * @returns Query results
+     *
+     * @example
+     * ```typescript
+     * // Raw SQL bypasses audit logging
+     * const results = await adapter.query(
+     *   'SELECT * FROM users WHERE status = $1',
+     *   ['active']
+     * );
+     *
+     * // Use findMany for automatic audit logging
+     * const users = await adapter.findMany('users', { filter: ... });
+     * ```
+     */
+    query<T>(sql: string, params?: T[]): Promise<T[]>;
+    /**
+     * Registers a table schema with the base adapter.
+     *
+     * **RESPONSIBILITY:** Passes table registration to base adapter
+     * **BEHAVIOR:** No additional registration logic needed
+     *
+     * @param name - Table name
+     * @param table - Table schema
+     * @param idColumn - Primary key column
+     *
+     * @example
+     * ```typescript
+     * auditAdapter.registerTable('users', userSchema, 'id');
+     * // Table now supports audited operations
+     * ```
+     */
+    registerTable<T, U>(name: string, table: T, idColumn?: U): void;
+    /**
+     * Sets audit context for tracking user actions.
+     *
+     * **RESPONSIBILITY:** Stores context information for audit records
+     * **CONTEXT:** userId, requestId, ipAddress, userAgent
+     * **USAGE:** Called by DatabaseService.setAuditContext()
+     *
+     * @param context - Audit context information
+     *
+     * @example
+     * ```typescript
+     * // Usually called by middleware
+     * auditAdapter.setAuditContext({
+     *   userId: 'user-123',
+     *   requestId: 'req-456',
+     *   ipAddress: '192.168.1.1',
+     *   userAgent: 'Mozilla/5.0...'
+     * });
+     *
+     * // Subsequent operations will include this context in audit logs
+     * await adapter.create('users', userData); // Audited with context
+     * ```
+     */
+    setAuditContext(context: AuditContext): void;
+    /**
+     * Finds a record by ID without audit logging.
+     *
+     * **RESPONSIBILITY:** Retrieves single record without creating audit trail
+     * **BEHAVIOR:** Read operations are not audited by default
+     * **PERFORMANCE:** No audit overhead for read operations
+     *
+     * @param table - Table name
+     * @param id - Record ID
+     * @returns Found record or null
+     *
+     * @example
+     * ```typescript
+     * // Read operations don't create audit records
+     * const user = await adapter.findById('users', 'user-123');
+     * if (user.success && user.value) {
+     *   console.log('User found:', user.value.name);
+     * }
+     * ```
+     */
+    findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>>;
+    /**
+     * Finds multiple records without audit logging.
+     *
+     * **RESPONSIBILITY:** Retrieves multiple records without creating audit trail
+     * **BEHAVIOR:** Read operations are not audited by default
+     * **PERFORMANCE:** No audit overhead for read operations
+     *
+     * @param table - Table name
+     * @param options - Query options
+     * @returns Paginated results
+     *
+     * @example
+     * ```typescript
+     * // Read operations don't create audit records
+     * const users = await adapter.findMany('users', {
+     *   filter: { field: 'status', operator: 'eq', value: 'active' },
+     *   pagination: { page: 1, limit: 10 }
+     * });
+     *
+     * console.log('Found users:', users.value?.data.length);
+     * ```
+     */
+    findMany<T>(table: string, options?: QueryOptions): Promise<DatabaseResult<PaginatedResult<T>>>;
+    create<T>(table: string, data: T): Promise<DatabaseResult<T>>;
+    private validateCreateParams;
+    private handleCreateAudit;
+    update<T>(table: string, id: string, data: Partial<T>): Promise<DatabaseResult<T>>;
+    delete(table: string, id: string): Promise<DatabaseResult<void>>;
+    /**
+     * Executes operations within a transaction with audit logging.
+     *
+     * **RESPONSIBILITY:** Passes transaction to base adapter
+     * **BEHAVIOR:** Individual operations within transaction are audited
+     * **ATOMICITY:** Audit records are part of the transaction
+     *
+     * @param callback - Transaction callback function
+     * @returns Transaction result
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.transaction(async (trx) => {
+     *   // Each operation creates audit record within transaction
+     *   const user = await trx.create('users', { name: 'John' });
+     *   await trx.update('profiles', 'profile-1', { userId: user.id });
+     *   return user;
+     * });
+     *
+     * // If transaction fails, audit records are also rolled back
+     * ```
+     */
+    transaction<T>(callback: (trx: Transaction) => Promise<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Checks if a record exists without audit logging.
+     *
+     * **RESPONSIBILITY:** Verifies record existence without creating audit trail
+     * **BEHAVIOR:** Read operations are not audited by default
+     * **PERFORMANCE:** No audit overhead for existence checks
+     *
+     * @param table - Table name
+     * @param id - Record ID
+     * @returns True if record exists
+     *
+     * @example
+     * ```typescript
+     * // Existence checks don't create audit records
+     * const userExists = await adapter.exists('users', 'user-123');
+     * if (userExists.value) {
+     *   console.log('User exists');
+     * }
+     * ```
+     */
+    exists(table: string, id: string): Promise<DatabaseResult<boolean>>;
+    /**
+     * Counts records without audit logging.
+     *
+     * **RESPONSIBILITY:** Counts records without creating audit trail
+     * **BEHAVIOR:** Read operations are not audited by default
+     * **PERFORMANCE:** No audit overhead for counting operations
+     *
+     * @param table - Table name
+     * @param filter - Optional filter conditions
+     * @returns Count of records
+     *
+     * @example
+     * ```typescript
+     * // Count operations don't create audit records
+     * const activeUsers = await adapter.count('users', {
+     *   field: 'status',
+     *   operator: 'eq',
+     *   value: 'active'
+     * });
+     *
+     * console.log('Active users:', activeUsers.value);
+     * ```
+     */
+    count(table: string, filter?: Filter): Promise<DatabaseResult<number>>;
+    /**
+     * Performs health check through base adapter.
+     *
+     * **RESPONSIBILITY:** Delegates health check to underlying adapter
+     * **BEHAVIOR:** No additional health metrics for audit
+     *
+     * @returns Health status from base adapter
+     *
+     * @example
+     * ```typescript
+     * const health = await adapter.healthCheck();
+     * if (health.success && health.value?.isHealthy) {
+     *   console.log('Database healthy with audit support');
+     * }
+     * ```
+     */
+    healthCheck(): Promise<DatabaseResult<DatabaseHealthStatus>>;
+    /**
+     * Determines if a table should be audited.
+     *
+     * **RESPONSIBILITY:** Checks if table is enabled for audit logging
+     * **CONFIGURATION:** Based on enabled flag and excludeTables array
+     *
+     * @private
+     * @param table - Table name to check
+     * @returns True if table should be audited
+     *
+     * @example
+     * ```typescript
+     * // Configuration: { enabled: true, excludeTables: ['temp_data'] }
+     *
+     * this.shouldAudit('users');     // true - will be audited
+     * this.shouldAudit('temp_data'); // false - excluded from audit
+     * ```
+     */
+    private shouldAudit;
+    /**
+     * Logs an audit event to the audit table and executes custom handlers.
+     *
+     * **RESPONSIBILITY:** Orchestrates audit record creation and event handling
+     * **PROCESS:** Validates event → Writes to audit table → Executes custom handler
+     *
+     * @private
+     * @param event - Audit event to log
+     *
+     * @example
+     * ```typescript
+     * // Internal usage after successful operation
+     * await this.logAudit({
+     *   operation: 'CREATE',
+     *   table: 'users',
+     *   recordId: 'user-123',
+     *   changes: { after: userData },
+     *   userId: 'admin-456',
+     *   timestamp: new Date()
+     * });
+     * ```
+     */
+    private logAudit;
+    /**
+     * Validates audit event has required fields.
+     *
+     * **RESPONSIBILITY:** Ensures audit event is properly formed
+     * **VALIDATION:** Checks for required operation and table fields
+     *
+     * @private
+     * @param event - Audit event to validate
+     * @throws {DatabaseError} When event is invalid
+     *
+     * @example
+     * ```typescript
+     * // Internal validation before logging
+     * this.validateAuditEvent({
+     *   operation: 'CREATE', // Required
+     *   table: 'users',     // Required
+     *   recordId: 'user-123'
+     * });
+     * ```
+     */
+    private validateAuditEvent;
+    /**
+     * Writes audit record to daily audit table.
+     *
+     * **RESPONSIBILITY:** Persists audit event to database
+     * **TABLE NAMING:** Uses daily tables (audit_YYYYMMDD)
+     * **STRUCTURE:** Converts event to database record format
+     *
+     * @private
+     * @param event - Audit event to write
+     * @throws {DatabaseError} When write operation fails
+     *
+     * @example
+     * ```typescript
+     * // Internal usage - writes to audit_20241201 table
+     * await this.writeAuditRecord({
+     *   operation: 'UPDATE',
+     *   table: 'users',
+     *   recordId: 'user-123',
+     *   changes: { before: {...}, after: {...} },
+     *   timestamp: new Date('2024-12-01')
+     * });
+     * ```
+     */
+    private writeAuditRecord;
+    /**
+     * Executes custom audit event handler if configured.
+     *
+     * **RESPONSIBILITY:** Calls user-defined audit event handler
+     * **ERROR HANDLING:** Logs handler errors without failing the operation
+     * **USE CASE:** Integration with compliance systems, notifications
+     *
+     * @private
+     * @param event - Audit event to handle
+     *
+     * @example
+     * ```typescript
+     * // Configuration with custom handler
+     * {
+     *   onAuditAfterWrite: async (event) => {
+     *     await complianceService.recordAudit(event);
+     *     await notificationService.sendAuditAlert(event);
+     *   }
+     * }
+     *
+     * // Handler is called after successful audit record write
+     * ```
+     */
+    private executeCustomHandler;
+}
+//# sourceMappingURL=AuditExtension.d.ts.map

package/dist/extensions/AuditExtension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuditExtension.d.ts","sourceRoot":"","sources":["../../src/extensions/AuditExtension.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,MAAM,EACN,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,EACX,MAAM,iBAAiB,CAAC;AAGzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,qBAAa,YAAa,YAAW,mBAAmB;IA2BpD,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,MAAM;IA3BhB,OAAO,CAAC,YAAY,CAAoB;IAGxC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBAEO,WAAW,EAAE,mBAAmB,EAChC,MAAM,EAAE;QACd,OAAO,EAAE,OAAO,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QACzB,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACjE;IAGH;;;;;;;;;;;;;;;OAeG;IACG,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAIjD;;;;;;;;;;;OAWG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B;;;;;;;;;;;OAWG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;;;;;;;;;;;OAaG;IACH,SAAS,IAAI,MAAM;IAInB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAIvD;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI;IAI/D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAI5C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,CAAC,EACd,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,cAAc,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAIpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,QAAQ,CAAC,CAAC,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAIxC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAYnE,OAAO,CAAC,oBAAoB;YAad,iBAAiB;IAsBzB,MAAM,CAAC,CAAC,EACZ,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GACf,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAgCvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IA2BtE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,WAAW,CAAC,CAAC,EACjB,QAAQ,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAI7B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAIzE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAI5E;;;;;;;;;;;;;;;OAeG;IACG,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAIlE;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,WAAW;IAKnB;;;;;;;;;;;;;;;;;;;;;OAqBG;YACW,QAAQ;IAOtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,gBAAgB;IAuC9B;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,oBAAoB;CAWnC"}