@plyaz/types 1.13.11 → 1.13.13

package/dist/db/config.types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Configuration types
+ * Types for database configuration
+ */
+import type { ADAPTERS } from './adapter';
+/**
+ * Base adapter interface with common configuration options
+ */
+export interface BaseAdapter {
+    /** Database adapter type */
+    adapter: ADAPTERS;
+    /** Database connection string */
+    connectionString?: string;
+    /** Connection pool configuration */
+    pool?: {
+        /** Minimum number of connections to maintain in the pool */
+        min?: number;
+        /** Maximum number of connections allowed in the pool */
+        max?: number;
+        /** Time in milliseconds after which idle connections are closed */
+        idleTimeoutMillis?: number;
+    };
+    /** Maximum time in milliseconds to wait for a query to complete */
+    queryTimeout?: number;
+    /** Whether to enable SSL for database connections */
+    ssl?: boolean;
+    /** Database schema name */
+    schema?: string;
+}
+/**
+ * Drizzle adapter configuration
+ */
+export interface DrizzleAdapterConfig extends BaseAdapter {
+    adapter: ADAPTERS.DRIZZLE;
+}
+/**
+ * Supabase adapter configuration
+ */
+export interface SupabaseAdapterConfig extends BaseAdapter {
+    adapter: ADAPTERS.SUPABASE;
+    /** Supabase project URL */
+    supabaseUrl: string;
+    /** Supabase anonymous key */
+    supabaseAnonKey?: string;
+    /** Supabase service role key */
+    supabaseServiceKey?: string;
+}
+/**
+ * SQL adapter configuration
+ */
+export interface SQLAdapterConfig extends BaseAdapter {
+    adapter: ADAPTERS.SQL;
+}
+/**
+ * Database configuration as a union of all adapter configurations
+ */
+export type DatabaseConfig = DrizzleAdapterConfig | SupabaseAdapterConfig | SQLAdapterConfig;

package/dist/db/databaseAdapter.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @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, QueryOptions, Filter, DatabaseHealthStatus } from './database.types';
+import type { PaginatedResult } from './databsePagination';
+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<DatabaseHealthStatus>>;
+}

package/dist/db/databaseService.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Public interface for DatabaseService
+ * This is what consumers interact with - matches the documentation exactly
+ */
+import type { DatabaseResult, QueryOptions, DatabaseHealthStatus, Filter, CreateInput, UpdateInput, BatchUpdate } from './database.types';
+import type { TransactionFn, TransactionOptions } from './Transaction';
+import type { OperationConfig } from './features-config.types';
+import type { DatabaseEvent } from './event.types';
+import type { PaginatedResult } from './databsePagination';
+import type { AuditContext } from './audit.types';
+/**
+ * Table name type - centralized table constants
+ */
+export type TableName = 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 DatabaseServiceInterface {
+    /**
+     * 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<DatabaseHealthStatus>>;
+    /**
+     * Get current service status
+     * @returns Current service status information
+     */
+    getStatus(): ServiceStatus;
+}
+/**
+ * Legacy interface for backward compatibility
+ * @deprecated Use DatabaseService instead
+ */
+export interface DatabaseServiceType extends DatabaseServiceInterface {
+    /**
+     * @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/index.d.ts

@@ -1,3 +1,7 @@
+export type * from './databaseService';
+export type * from './eventEmitter';
+export type * from './config.types';
+export type * from './databaseAdapter';
 export type * from './features-config.types';
 export type * from './database.types';
 export * from './adapter';

package/dist/db/replica.types.d.ts

@@ -1,4 +1,4 @@
-import type { AdapterConfig } from "./features-config.types";
+import type { DatabaseAdapterType } from "./databaseAdapter";
 import type { REPLICA_STRATEGY } from "./replicaStrategy";
 /**
  * Options for the @UseReplica decorator.
@@ -18,7 +18,7 @@ export interface ReadReplicaConfig {
     /** Whether read replicas are enabled */
     enabled: boolean;
     /** Replica connection configs */
-    replicas: AdapterConfig[];
+    replicas: DatabaseAdapterType[];
     /** Load balancing strategy */
     strategy?: 'round-robin' | 'random' | 'least-connections';
     /** Fallback to primary if all replicas unhealthy */

package/dist/errors/index.cjs

@@ -4410,7 +4410,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// node_modules/.pnpm/@plyaz+types@1.13.10_@types+react@19.2.2_next@15.4.7_react-dom@19.2.0_react@19.2.0/node_modules/@plyaz/types/dist/index.js
+// node_modules/.pnpm/@plyaz+types@1.13.12_@types+react@19.2.2_next@15.4.7_react-dom@19.2.0_react@19.2.0/node_modules/@plyaz/types/dist/index.js
 var __defProp2 = Object.defineProperty;
 var __name2 = /* @__PURE__ */ __name((target, value) => __defProp2(target, "name", { value, configurable: true }), "__name");
 external_exports.object({