@plyaz/types 1.13.0 → 1.13.2

package/dist/db/DatabaseAdapter.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @fileoverview DatabaseAdapter interface - Core adapter contract
+ *
+ * Defines the standardized interface that all database adapters must implement
+ * to ensure consistent behavior across different database systems. This interface
+ * serves as the foundation for the adapter pattern implementation, enabling
+ * seamless switching between different database technologies.
+ *
+ * **Application Flow Context:**
+ * ```
+ * Extension Chain → DatabaseAdapterType → Concrete Adapter → Database
+ *       ↓              ↓                  ↓               ↓
+ * AuditAdapter   → Interface Contract → DrizzleAdapter  → PostgreSQL
+ * SoftDelete     → Method Signatures → SupabaseAdapter → Supabase
+ * Encryption     → Type Safety      → SQLAdapter     → Raw SQL
+ * ```
+ *
+ * **Interface Responsibilities:**
+ * - **Connection Management**: Initialize, connect, disconnect operations
+ * - **CRUD Operations**: Create, read, update, delete with type safety
+ * - **Query Operations**: Complex queries with filtering and pagination
+ * - **Transaction Support**: Atomic operations with rollback capabilities
+ * - **Health Monitoring**: Connection status and performance metrics
+ * - **Table Management**: Dynamic table registration and schema handling
+ *
+ * **Implementation Requirements:**
+ * All adapters must implement every method in this interface to ensure
+ * compatibility with the extension system and service layer. The interface
+ * uses generic types to maintain type safety across different data models.
+ *
+ * @example
+ * ```typescript
+ * // Adapter implementation example
+ * class CustomAdapter implements DatabaseAdapterType {
+ *   async initialize(): Promise<DatabaseResult<void>> {
+ *     // Initialize connection and validate configuration
+ *   }
+ *
+ *   async findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>> {
+ *     // Implement type-safe record retrieval
+ *   }
+ *
+ *   // ... implement all other interface methods
+ * }
+ * ```
+ *
+ */
+import type { DatabaseResult, PaginatedResult, QueryOptions, Filter, HealthStatus } from './database.types';
+import type { Transaction } from './Transaction';
+/**
+ * @interface DatabaseAdapterType
+ * @description
+ * Core interface defining the contract that all database adapters must implement.
+ *
+ * This interface ensures consistent behavior across different database implementations
+ * by defining a standardized set of methods for database operations. All adapters
+ * (Drizzle, Supabase, SQL, etc.) must implement this interface to be compatible
+ * with the database service and extension system.
+ *
+ * **Method Categories:**
+ * - **Lifecycle**: initialize, connect, disconnect
+ * - **CRUD**: create, findById, findMany, update, delete
+ * - **Queries**: count, exists, query (raw SQL)
+ * - **Transactions**: transaction with rollback support
+ * - **Management**: registerTable, healthCheck
+ *
+ * **Type Safety:**
+ * The interface uses generic types extensively to maintain compile-time type
+ * safety while allowing flexibility for different data models and database schemas.
+ *
+ * @example
+ * ```typescript
+ * // Using the adapter interface
+ * const adapter: DatabaseAdapterType = new DrizzleAdapter(config);
+ *
+ * // All operations are type-safe
+ * await adapter.initialize();
+ * adapter.registerTable('users', usersTable, usersTable.id);
+ *
+ * const user = await adapter.findById<User>('users', '123');
+ * const users = await adapter.findMany<User>('users', {
+ *   filter: { field: 'status', operator: 'eq', value: 'active' }
+ * });
+ * ```
+ */
+export interface DatabaseAdapterType {
+    /**
+     * Initialize the database adapter with configuration
+     * @returns Promise resolving to DatabaseResult indicating success or failure
+     */
+    initialize(): Promise<DatabaseResult<void>>;
+    /**
+     * Connect to the database
+     * @returns Promise that resolves when connected
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the database
+     * @returns Promise that resolves when disconnected
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get the underlying database client
+     * @returns The underlying database client
+     */
+    getClient(): object;
+    /**
+     * Execute a raw SQL query
+     * @param sql - SQL query string
+     * @param params - Query parameters
+     * @returns Promise resolving to query results
+     */
+    query<T>(sql: string, params?: T[]): Promise<T[]>;
+    /**
+     * Register a table with the adapter
+     * @param name - Logical name for the table
+     * @param table - Table object or name
+     * @param idColumn - Optional ID column name
+     */
+    registerTable<TTable, TIdColumn>(name: string, table: TTable, idColumn?: TIdColumn): void;
+    /**
+     * Find a single record by ID
+     * @param table - Table name
+     * @param id - Record ID
+     * @returns Promise resolving to DatabaseResult containing the record or null
+     */
+    findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>>;
+    /**
+     * Find multiple records with filtering and pagination
+     * @param table - Table name
+     * @param options - Query options including filters, sorting, and pagination
+     * @returns Promise resolving to DatabaseResult containing paginated data
+     */
+    findMany<T>(table: string, options?: QueryOptions): Promise<DatabaseResult<PaginatedResult<T>>>;
+    /**
+     * Create a new record
+     * @param table - Table name
+     * @param data - Record data to create
+     * @returns Promise resolving to DatabaseResult containing the created record
+     */
+    create<T>(table: string, data: T): Promise<DatabaseResult<T>>;
+    /**
+     * Update an existing record
+     * @param table - Table name
+     * @param id - Record ID
+     * @param data - Partial record data to update
+     * @returns Promise resolving to DatabaseResult containing the updated record
+     */
+    update<T>(table: string, id: string, data: Partial<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Delete a record
+     * @param table - Table name
+     * @param id - Record ID
+     * @returns Promise resolving to DatabaseResult indicating success or failure
+     */
+    delete(table: string, id: string): Promise<DatabaseResult<void>>;
+    /**
+     * Execute a transaction with multiple operations
+     * @param callback - Function containing transaction operations
+     * @returns Promise resolving to DatabaseResult containing the transaction result
+     */
+    transaction<T>(callback: (trx: Transaction) => Promise<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Check if a record exists
+     * @param table - Table name
+     * @param id - Record ID
+     * @returns Promise resolving to DatabaseResult containing boolean indicating existence
+     */
+    exists(table: string, id: string): Promise<DatabaseResult<boolean>>;
+    /**
+     * Count records matching a filter
+     * @param table - Table name
+     * @param filter - Filter conditions
+     * @returns Promise resolving to DatabaseResult containing the count
+     */
+    count(table: string, filter?: Filter): Promise<DatabaseResult<number>>;
+    /**
+     * Perform health check on the database connection
+     * @returns Promise resolving to DatabaseResult containing health status
+     */
+    healthCheck(): Promise<DatabaseResult<HealthStatus>>;
+}

package/dist/db/DatabaseService.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Public interface for DatabaseService
+ * This is what consumers interact with - matches the documentation exactly
+ */
+import type { DatabaseResult, PaginatedResult, QueryOptions, HealthStatus, Filter, CreateInput, UpdateInput, BatchUpdate } from './database.types';
+import type { TransactionFn, TransactionOptions } from './Transaction';
+import type { OperationConfig } from './enhanced-config.types';
+import type { DatabaseEvent } from './event.types';
+/**
+ * Table name type - centralized table constants
+ */
+export type TableName = string;
+/**
+ * Audit context for tracking user actions
+ */
+export interface AuditContext {
+    userId?: string;
+    requestId?: string;
+    ipAddress?: string;
+    userAgent?: string;
+}
+/**
+ * Service status information
+ */
+export interface ServiceStatus {
+    isHealthy: boolean;
+    adapter: string;
+    uptime: number;
+    lastHealthCheck: Date;
+}
+/**
+ *  MAIN DATABASE SERVICE INTERFACE - Public API Surface
+ *
+ * This is the ONLY interface that applications interact with.
+ * Provides all database operations with type safety and configuration overrides.
+ *
+ * **Application Flow Position:**
+ * Repository Layer → **DatabaseService** → DatabaseService → Adapter Chain
+ *
+ * **What this interface provides:**
+ * - Type-safe CRUD operations with per-operation configuration
+ * - Batch operations for high-performance scenarios
+ * - Transaction support with ACID guarantees
+ * - Event system for monitoring and side effects
+ * - Audit context management for compliance
+ * - Health monitoring and status reporting
+ *
+ * **Used by:** Repository layer (BaseRepository, UserRepository, etc.)
+ * **Implemented by:** DatabaseService (internal)
+ * **Created by:** createDatabaseService() factory
+ *
+ * **Key Features:**
+ * - Per-operation config overrides (skipAudit, includeSoftDeleted, etc.)
+ * - Automatic extension handling (encryption, soft delete, audit)
+ * - Event hooks for application integration
+ * - Type-safe operations with proper error handling
+ *
+ * @example
+ * ### Basic Usage in Repository
+ * ```typescript
+ * class UserRepository extends BaseRepository<User> {
+ *   constructor(private db: DatabaseService) {
+ *     super(db, Tables.USERS);
+ *   }
+ *
+ *   async findByEmail(email: string) {
+ *     return this.db.query(Tables.USERS, {
+ *       filter: { field: 'email', operator: 'eq', value: email }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ### Per-Operation Configuration
+ * ```typescript
+ * // Admin view - include soft-deleted records
+ * const allUsers = await db.list(Tables.USERS, {}, {
+ *   includeSoftDeleted: true,
+ *   forceAdapter: 'primary',
+ *   cache: { enabled: false }
+ * });
+ *
+ * // Bulk import - skip audit and caching
+ * const result = await db.batchCreate(Tables.USERS, users, {
+ *   skipAudit: true,
+ *   timestamps: { enabled: false },
+ *   cache: { enabled: false }
+ * });
+ * ```
+ */
+export interface DatabaseService {
+    /**
+     * Get a single record by ID
+     * @param table - Table name
+     * @param id - Record ID
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to the record or null
+     */
+    get<T>(table: TableName, id: string, config?: OperationConfig): Promise<DatabaseResult<T | null>>;
+    /**
+     * List records with optional filtering, sorting, and pagination
+     * @param table - Table name
+     * @param options - Query options
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to paginated results
+     */
+    list<T>(table: TableName, options?: QueryOptions, config?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
+    /**
+     * Create a new record
+     * @param table - Table name
+     * @param input - Record data to create
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to the created record
+     */
+    create<T>(table: TableName, input: CreateInput<T>, config?: OperationConfig): Promise<DatabaseResult<T>>;
+    /**
+     * Update an existing record
+     * @param table - Table name
+     * @param id - Record ID
+     * @param input - Updated fields
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to the updated record
+     */
+    update<T>(table: TableName, id: string, input: UpdateInput<T>, config?: OperationConfig): Promise<DatabaseResult<T>>;
+    /**
+     * Delete a record
+     * @param table - Table name
+     * @param id - Record ID
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to void on success
+     */
+    delete(table: TableName, id: string, config?: OperationConfig): Promise<DatabaseResult<void>>;
+    /**
+     * Create multiple records in a batch
+     * @param table - Table name
+     * @param inputs - Array of records to create
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to array of created records
+     */
+    batchCreate<T>(table: TableName, inputs: CreateInput<T>[], config?: OperationConfig): Promise<DatabaseResult<T[]>>;
+    /**
+     * Update multiple records in a batch
+     * @param table - Table name
+     * @param updates - Array of update operations
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to array of updated records
+     */
+    batchUpdate<T>(table: TableName, updates: BatchUpdate<T>[], config?: OperationConfig): Promise<DatabaseResult<T[]>>;
+    /**
+     * Delete multiple records in a batch
+     * @param table - Table name
+     * @param ids - Array of record IDs to delete
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to void on success
+     */
+    batchDelete(table: TableName, ids: string[], config?: OperationConfig): Promise<DatabaseResult<void>>;
+    /**
+     * Execute a complex query with filters, sorting, and pagination
+     * @param table - Table name
+     * @param query - Query configuration
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to paginated results
+     */
+    query<T>(table: TableName, query: QueryOptions, config?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
+    /**
+     * Count records matching a filter
+     * @param table - Table name
+     * @param filter - Optional filter conditions
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to the count
+     */
+    count(table: TableName, filter?: Filter, config?: OperationConfig): Promise<DatabaseResult<number>>;
+    /**
+     * Find a single record by filter conditions
+     * @param table - Table name
+     * @param filter - Filter conditions
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to the first matching record or null
+     */
+    findOne<T>(table: TableName, filter: Filter, config?: OperationConfig): Promise<DatabaseResult<T | null>>;
+    /**
+     * Soft delete a record (logical deletion)
+     * @param table - Table name
+     * @param id - Record ID
+     * @param config - Optional per-operation configuration overrides
+     * @returns Promise resolving to void on success
+     */
+    softDelete(table: TableName, id: string, config?: OperationConfig): Promise<DatabaseResult<void>>;
+    /**
+     * Execute operations within a transaction
+     * @param fn - Function containing transactional operations
+     * @param options - Optional transaction configuration
+     * @returns Promise resolving to the transaction result
+     */
+    transaction<T>(fn: TransactionFn<T>, options?: TransactionOptions): Promise<DatabaseResult<T>>;
+    /**
+     * Set audit context for tracking user actions
+     * @param context - Audit context information
+     * @returns Promise resolving to void on success
+     */
+    setAuditContext(context: AuditContext): Promise<DatabaseResult<void>>;
+    /**
+     * Subscribe to database events
+     * @param event - Event type to listen for
+     * @param handler - Event handler function
+     */
+    on<T extends DatabaseEvent['type']>(event: T, handler: (event: Extract<DatabaseEvent, {
+        type: T;
+    }>) => void | Promise<void>): void;
+    /**
+     * Unsubscribe from database events
+     * @param event - Event type to stop listening for
+     * @param handler - Event handler function to remove
+     */
+    off<T extends DatabaseEvent['type']>(event: T, handler: (event: Extract<DatabaseEvent, {
+        type: T;
+    }>) => void | Promise<void>): void;
+    /**
+     * Perform health check on the database connection
+     * @returns Promise resolving to health status
+     */
+    healthCheck(): Promise<DatabaseResult<HealthStatus>>;
+    /**
+     * Get current service status
+     * @returns Current service status information
+     */
+    getStatus(): ServiceStatus;
+}
+/**
+ * Legacy interface for backward compatibility
+ * @deprecated Use DatabaseService instead
+ */
+export interface DatabaseServiceType extends DatabaseService {
+    /**
+     * @deprecated Use get() instead
+     */
+    findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>>;
+    /**
+     * @deprecated Use list() instead
+     */
+    findMany<T>(table: string, options?: QueryOptions): Promise<DatabaseResult<PaginatedResult<T>>>;
+    /**
+     * Initialize the database service
+     * @deprecated Initialization is handled by factory
+     */
+    initialize(): Promise<DatabaseResult<void>>;
+    /**
+     * Register a table with the adapter
+     * @deprecated Tables are registered automatically
+     */
+    registerTable<T>(name: string, table: T, idColumn?: keyof T): void;
+    /**
+     * Check if a record exists
+     * @deprecated Use count() with filter instead
+     */
+    exists(table: string, id: string): Promise<DatabaseResult<boolean>>;
+    /**
+     * Find a single record by filter conditions
+     * @deprecated Use findOne() from main interface instead
+     */
+    findOne<T>(table: string, filter: Filter): Promise<DatabaseResult<T | null>>;
+    /**
+     * Soft delete a record (logical deletion)
+     * @deprecated Use softDelete() from main interface instead
+     */
+    softDelete(table: string, id: string): Promise<DatabaseResult<void>>;
+}

package/dist/db/EventEmitter.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Event emitter interface
+ * Defines the contract for database event emission
+ */
+import type { DatabaseEvent, DBEventHandler, DatabaseOperationType } from './event.types';
+import type { ContextType } from '@nestjs/common';
+/**
+ * Emit a query error event
+ */
+interface EmitQueryErrorOptions {
+    table: string;
+    operation: DatabaseOperationType;
+    error: Error;
+    params?: Record<string, object>;
+    context?: ContextType;
+}
+export interface DatabaseError extends Error {
+    code?: string;
+    status?: number;
+    cause?: Error;
+}
+/**
+ * Interface for database event emission
+ */
+export interface DatabaseEventEmitterType {
+    /**
+     * 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<T extends DatabaseEvent>(event: T): void;
+    /**
+     * Emit a before query event
+     */
+    emitBeforeQuery<T extends object = object>(table: string, operation: DatabaseOperationType, params?: Partial<T>, context?: Record<string, string | number | boolean | null>): void;
+    /**
+     * Emit an after query event
+     */
+    emitAfterQuery(table: string, operation: DatabaseOperationType, duration: number, affectedRows?: number): void;
+    /**
+     * Emit a query error event
+     */
+    emitQueryError<T extends object = object>(table: string, operation: DatabaseOperationType, error: DatabaseError, params?: Partial<T>, context?: Record<string, string | number | boolean | null>): void;
+    /**
+     * Emit a before transaction event
+     */
+    emitBeforeTransaction(transactionId: string, context?: Record<string, string | number | boolean | null>): void;
+    /**
+     * Emit an after transaction event
+     */
+    emitAfterTransaction(transactionId: string, duration: number): void;
+    /**
+     * Emit a transaction rollback event
+     */
+    emitTransactionRollback(transactionId: string, error?: DatabaseError): void;
+    /**
+     * Emit a health change event
+     */
+    emitHealthChange<TDetails extends object = object>(previousStatus: boolean, currentStatus: boolean, details?: TDetails): void;
+    emitQueryError(options: EmitQueryErrorOptions): void;
+}
+export {};

package/dist/db/Transaction.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Transaction interface
+ * Defines the contract for database transactions
+ */
+import type { DatabaseResult } from './database.types';
+/**
+ * Interface for database transaction operations
+ */
+export interface Transaction {
+    /**
+     * Find a single record within the transaction
+     */
+    findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>>;
+    /**
+     * Create a record within the transaction
+     */
+    create<T>(table: string, data: T): Promise<DatabaseResult<T>>;
+    /**
+     * Update a record within the transaction
+     */
+    update<T>(table: string, id: string, data: Partial<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Delete a record within the transaction
+     */
+    delete(table: string, id: string): Promise<DatabaseResult<void>>;
+    /**
+     * Commit the transaction
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the transaction
+     */
+    rollback(): Promise<void>;
+}
+/**
+ * Transaction function type
+ */
+export type TransactionFn<T> = (trx: Transaction) => Promise<T>;
+/**
+ * Transaction options
+ */
+export interface TransactionOptions {
+    /** Transaction isolation level */
+    isolationLevel?: 'READ_UNCOMMITTED' | 'READ_COMMITTED' | 'REPEATABLE_READ' | 'SERIALIZABLE';
+    /** Transaction timeout in milliseconds */
+    timeout?: number;
+    /** Whether to use savepoints for nested transactions */
+    useSavepoints?: boolean;
+}

package/dist/db/adapter.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Database adapter type definitions
+ *
+ * Defines the enumeration of supported database adapter types used throughout
+ * the database package. This enum provides type-safe identification of different
+ * database integrations and is used in configuration, factory methods, and
+ * adapter selection logic.
+ *
+ * **Application Flow Context:**
+ * ```
+ * Configuration → ADAPTERS Enum → AdapterFactory → Concrete Adapter
+ *      ↓             ↓              ↓               ↓
+ * User Config  → Type Safety   → Adapter Creation → Database Connection
+ * ```
+ *
+ * **Adapter Types:**
+ * - **DRIZZLE**: Type-safe ORM with excellent TypeScript support
+ * - **SUPABASE**: Hosted PostgreSQL with real-time capabilities
+ * - **SQL**: Raw SQL execution for maximum control
+ * - **DATABASE**: Generic fallback adapter
+ *
+ * @example
+ * ```typescript
+ * // Adapter selection in configuration
+ * const config = {
+ *   adapter: ADAPTERS.DRIZZLE,
+ *   connectionString: process.env.DATABASE_URL
+ * };
+ *
+ * // Type-safe adapter factory usage
+ * const adapter = AdapterFactory.create(ADAPTERS.SUPABASE, supabaseConfig);
+ *
+ * // Switch statement with exhaustive checking
+ * switch (config.adapter) {
+ *   case ADAPTERS.DRIZZLE:
+ *     // Handle Drizzle-specific logic
+ *     break;
+ *   case ADAPTERS.SUPABASE:
+ *     // Handle Supabase-specific logic
+ *     break;
+ *   case ADAPTERS.SQL:
+ *     // Handle SQL-specific logic
+ *     break;
+ *   default:
+ *     // TypeScript ensures all cases are handled
+ *     throw new Error(`Unsupported adapter: ${config.adapter}`);
+ * }
+ * ```
+ *
+ */
+/**
+ * @enum ADAPTERS
+ * @description
+ * Enumeration of supported database adapter types.
+ *
+ * This enum provides type-safe identification of different database integrations
+ * and is used throughout the package for configuration, factory methods, and
+ * adapter selection. Each adapter type represents a different approach to
+ * database connectivity and operations.
+ *
+ * **Adapter Characteristics:**
+ * - **DATABASE**: Generic fallback, minimal functionality
+ * - **DRIZZLE**: Full ORM with type safety and query building
+ * - **SUPABASE**: Hosted solution with real-time and auth features
+ * - **SQL**: Raw SQL for performance-critical applications
+ *
+ * @example
+ * ```typescript
+ * // Configuration with adapter selection
+ * const configs = {
+ *   development: { adapter: ADAPTERS.DRIZZLE },
+ *   production: { adapter: ADAPTERS.SUPABASE },
+ *   performance: { adapter: ADAPTERS.SQL }
+ * };
+ *
+ * // Type-safe adapter validation
+ * function validateAdapter(adapter: ADAPTERS): boolean {
+ *   return Object.values(ADAPTERS).includes(adapter);
+ * }
+ * ```
+ */
+export declare enum ADAPTERS {
+    /** Generic database adapter (default when no specific integration is set) */
+    DATABASE = "database",
+    /** Drizzle ORM adapter (PostgreSQL, MySQL, SQLite, etc.) */
+    DRIZZLE = "drizzle",
+    /** Supabase adapter (PostgreSQL backend with REST + Realtime APIs) */
+    SUPABASE = "supabase",
+    /** Raw SQL adapter (direct database queries without ORM) */
+    SQL = "sql"
+}