@plyaz/types 1.12.4 → 1.13.1

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/database.types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Core database types and utilities
+ *
+ * Provides fundamental type definitions and utility functions used throughout
+ * the database package. These types ensure type safety, consistent data structures,
+ * and standardized error handling across all database operations and adapters.
+ *
+ * **Type Categories:**
+ * - **Input Types**: CreateInput, UpdateInput for data manipulation
+ * - **Query Types**: QueryOptions, Filter, SortOptions for data retrieval
+ * - **Result Types**: DatabaseResult, PaginatedResult for operation results
+ * - **Utility Types**: HealthStatus for monitoring
+ * - **Error Types**: DatabaseError for standardized error handling
+ *
+ * **Application Flow Context:**
+ * ```
+ * Application Data → Input Types → Database Operations → Result Types
+ *       ↓             ↓            ↓                 ↓
+ * User Input     → Validation → Adapter Methods  → Type-Safe Results
+ * Query Params   → Type Safety → SQL Generation   → Error Handling
+ * ```
+ *
+ * **Key Features:**
+ * - **Type Safety**: Compile-time validation of data structures
+ * - **Result Pattern**: Consistent success/failure result handling
+ * - **Generic Support**: Flexible types for different data models
+ * - **Error Standardization**: Unified error handling across adapters
+ *
+ * @example
+ * ```typescript
+ * // Type-safe database operations
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ *   createdAt: Date;
+ * }
+ *
+ * // Input types automatically exclude system fields
+ * const createData: CreateInput<User> = {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ *   // id, createdAt automatically excluded
+ * };
+ *
+ * // Result pattern for consistent error handling
+ * const result = await service.create('users', createData);
+ * if (result.success) {
+ *   console.log('Created user:', result.value);
+ * } else {
+ *   console.error('Error:', result.error.message);
+ * }
+ * ```
+ *
+ * @author Plyaz Engineering Team
+ * @since 1.0.0
+ */
+/**
+ * Input type for creating records
+ */
+export type CreateInput<T> = Omit<T, 'id' | 'createdAt' | 'updatedAt' | 'deletedAt'>;
+/**
+ * Input type for updating records
+ */
+export type UpdateInput<T> = Partial<Omit<T, 'id' | 'createdAt'>>;
+/**
+ * Batch update operation
+ */
+export interface BatchUpdate<T> {
+    /** Record ID to update */
+    id: string;
+    /** Fields to update */
+    data: UpdateInput<T>;
+}
+/**
+ * Query options for findMany operations
+ */
+export interface QueryOptions<TRecord extends object = object> {
+    /** Filter conditions */
+    filter?: Filter<TRecord>;
+    /** Sorting options */
+    sort?: SortOptions<TRecord>[];
+    /** Pagination options */
+    pagination?: PaginationOptions;
+}
+/**
+ * Filter conditions for queries
+ */
+export interface Filter<TRecord extends object = object> {
+    /** Field to filter on */
+    field: keyof TRecord & string;
+    /** Filter operator */
+    operator: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'like' | 'between' | 'isNull' | 'isNotNull';
+    /** Value to compare against */
+    value: TRecord[keyof TRecord];
+    /** Logical operator to combine with other filters */
+    logical?: 'and' | 'or' | 'not';
+}
+/**
+ * Sorting options for queries
+ */
+export interface SortOptions<TRecord extends object = object> {
+    /** Field to sort by */
+    field: keyof TRecord & string;
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Pagination options for queries
+ */
+export interface PaginationOptions {
+    /** Number of items to return */
+    limit?: number;
+    /** Number of items to skip */
+    offset?: number;
+    /** Cursor for cursor-based pagination */
+    cursor?: string;
+}
+/**
+ * Paginated result type
+ */
+export interface PaginatedResult<T> {
+    /** Array of results */
+    data: T[];
+    /** Total count of items */
+    total: number;
+    /** Pagination metadata */
+    pagination: {
+        /** Current page number */
+        page?: number;
+        /** Number of items per page */
+        limit?: number;
+        /** Total number of pages */
+        totalPages?: number;
+        /** Next cursor for cursor-based pagination */
+        nextCursor?: string;
+        /** Previous cursor for cursor-based pagination */
+        prevCursor?: string;
+    };
+}
+/**
+ * Database health status
+ */
+export interface HealthStatus<TDetails extends object = object> {
+    /** Whether the database is healthy */
+    isHealthy: boolean;
+    /** Response time in milliseconds */
+    responseTime: number;
+    /** Additional health details */
+    details?: TDetails;
+}
+/**
+ * Database result type that wraps either a successful value or an error
+ */
+export interface DatabaseResult<T> {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** The result value if successful */
+    value?: T;
+    /** The error if unsuccessful */
+    error?: Error;
+}
+/**
+ * Helper function to create a successful database result
+ */
+export declare function success<T>(value: T): DatabaseResult<T>;
+/**
+ * Helper function to create a failed database result
+ */
+export declare function failure<T>(error: Error): DatabaseResult<T>;
+export declare class DatabaseError extends Error {
+    code?: string;
+    status?: number;
+    cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+export declare class BaseError extends DatabaseError {
+    code: string;
+    status: number;
+    constructor(code: string, status: number, message: string);
+}
+export declare class ValidationError extends DatabaseError {
+    code: string;
+    status: number;
+    constructor(code: string, status: number, message: string);
+}

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

@@ -0,0 +1,311 @@
+/**
+ * @fileoverview Enhanced configuration types for database service
+ *
+ * Provides comprehensive, strictly-typed configuration interfaces for all
+ * database extensions and features. These types enable type-safe configuration
+ * of the entire database system, from basic adapter settings to advanced
+ * features like encryption, audit logging, and caching.
+ *
+ * **Configuration Hierarchy:**
+ * ```
+ * DatabaseServiceConfig (Root)
+ *       ↓
+ * ├── AdapterConfig (Database Connection)
+ * ├── ExtensionConfigs (Features)
+ * │   ├── SoftDeleteConfig
+ * │   ├── DBEncryptionConfig
+ * │   ├── AuditConfig
+ * │   └── DBCacheConfig
+ * └── OperationConfig (Per-Operation Overrides)
+ * ```
+ *
+ * **Configuration Features:**
+ * - **Type Safety**: Compile-time validation of all configuration options
+ * - **Hierarchical Overrides**: Global config with per-operation overrides
+ * - **Extension Integration**: Seamless configuration for all extensions
+ * - **Event Handling**: Type-safe event handler configuration
+ * - **Adapter Flexibility**: Support for multiple database adapters
+ *
+ * **Usage Patterns:**
+ * - Global configuration for application-wide settings
+ * - Per-operation configuration for specific requirements
+ * - Extension-specific configuration for feature customization
+ * - Event handler configuration for monitoring and logging
+ *
+ * @example
+ * ```typescript
+ * // Complete database service configuration
+ * const config: DatabaseServiceConfig = {
+ *   adapter: 'drizzle',
+ *   config: {
+ *     connectionString: process.env.DATABASE_URL,
+ *     poolSize: 10
+ *   },
+ *   encryption: {
+ *     enabled: true,
+ *     key: process.env.ENCRYPTION_KEY,
+ *     fields: {
+ *       users: ['ssn', 'taxId'],
+ *       payments: ['cardNumber', 'cvv']
+ *     }
+ *   },
+ *   audit: {
+ *     enabled: true,
+ *     retentionDays: 90,
+ *     excludeTables: ['sessions', 'logs']
+ *   },
+ *   events: {
+ *     onAfterWrite: async (event) => {
+ *       console.log(`${event.operation} completed on ${event.table}`);
+ *     }
+ *   }
+ * };
+ *
+ * // Per-operation configuration override
+ * const operationConfig: OperationConfig = {
+ *   skipAudit: true,
+ *   cache: { ttl: 600 },
+ *   timeout: 30000
+ * };
+ * ```
+ */
+/**
+ * Configuration for soft delete functionality
+ */
+export interface SoftDeleteConfig {
+    /** Whether soft delete is enabled */
+    enabled: boolean;
+    /** Field name for soft delete timestamp (default: 'deletedAt') */
+    field?: string;
+    /** Tables to exclude from soft delete behavior */
+    excludeTables?: string[];
+}
+/**
+ * Configuration for field-level encryption
+ */
+export interface DBEncryptionConfig {
+    /** Whether encryption is enabled */
+    enabled: boolean;
+    /** Base64 encoded encryption key */
+    key: string;
+    /** Fields to encrypt per table */
+    fields: Record<string, string[]>;
+    /** Encryption algorithm (default: 'aes-256-gcm') */
+    algorithm?: 'aes-256-gcm' | 'aes-256-cbc';
+    /** Use database-native encryption when available */
+    useDatabaseNative?: boolean;
+}
+/**
+ * Configuration for audit logging
+ */
+export interface AuditConfig {
+    /** Whether audit logging is enabled */
+    enabled: boolean;
+    /** Number of days to retain audit logs (default: 90) */
+    retentionDays?: number;
+    /** Fields to exclude from audit logs */
+    excludeFields?: string[];
+    /** Tables to exclude from audit logging */
+    excludeTables?: string[];
+    /** Custom audit event handler */
+    onAuditAfterWrite?: (event: AuditEvent) => void | Promise<void>;
+}
+/**
+ * Configuration for automatic timestamps
+ */
+export interface TimestampsConfig {
+    /** Whether automatic timestamps are enabled */
+    enabled: boolean;
+    /** Field name for creation timestamp (default: 'createdAt') */
+    createdAtField?: string;
+    /** Field name for update timestamp (default: 'updatedAt') */
+    updatedAtField?: string;
+    /** Automatically update timestamp on record changes */
+    autoUpdate?: boolean;
+}
+/**
+ * Configuration for query result caching
+ */
+export interface DBCacheConfig {
+    /** Whether caching is enabled */
+    enabled: boolean;
+    /** Default TTL in seconds (default: 300) */
+    ttl?: number;
+    /** Cache provider ('redis' | 'memory') */
+    provider?: string;
+    /** Cache invalidation strategy */
+    invalidation?: 'write' | 'ttl' | 'manual';
+}
+/**
+ * Configuration for read replicas
+ */
+export interface ReadReplicaConfig {
+    /** Whether read replicas are enabled */
+    enabled: boolean;
+    /** Replica connection configs */
+    replicas: AdapterConfig[];
+    /** Load balancing strategy */
+    strategy?: 'round-robin' | 'random' | 'least-connections';
+    /** Fallback to primary if all replicas unhealthy */
+    fallbackToPrimary?: boolean;
+}
+/**
+ * Connection pool configuration
+ */
+export interface PoolConfig {
+    /** Minimum number of connections */
+    min?: number;
+    /** Maximum number of connections */
+    max?: number;
+    /** Idle connection timeout in milliseconds */
+    idleTimeoutMs?: number;
+    /** Connection acquisition timeout in milliseconds */
+    acquireTimeoutMs?: number;
+}
+/**
+ * Database event handlers
+ */
+export interface DatabaseEvents {
+    /** Called before any write operation */
+    onBeforeWrite?: (event: BeforeWriteEvent) => void | Promise<void>;
+    /** Called after successful write operation */
+    onAfterWrite?: (event: AfterWriteEvent) => void | Promise<void>;
+    /** Called before any read operation */
+    onBeforeRead?: (event: BeforeReadEvent) => void | Promise<void>;
+    /** Called after successful read operation */
+    onAfterRead?: (event: AfterReadEvent) => void | Promise<void>;
+}
+/**
+ * Event types for database operations
+ */
+export interface BeforeWriteEvent {
+    type: 'beforeWrite';
+    operation: 'CREATE' | 'UPDATE' | 'DELETE';
+    table: string;
+    data: Record<string, string | number | boolean | Date>;
+    timestamp: Date;
+}
+export interface AfterWriteEvent {
+    type: 'afterWrite';
+    operation: 'CREATE' | 'UPDATE' | 'DELETE';
+    table: string;
+    result: Record<string, string | number | boolean | Date>;
+    duration: number;
+    timestamp: Date;
+}
+export interface BeforeReadEvent {
+    type: 'beforeRead';
+    operation: 'READ';
+    table: string;
+    timestamp: Date;
+}
+export interface AfterReadEvent {
+    type: 'afterRead';
+    operation: 'READ';
+    table: string;
+    result: Record<string, string | number | boolean | Date>;
+    duration: number;
+    timestamp: Date;
+}
+export interface AuditEvent {
+    operation: string;
+    table: string;
+    recordId?: string;
+    userId?: string;
+    requestId?: string;
+    changes: {
+        before?: Record<string, string | number | boolean | Date>;
+        after?: Record<string, string | number | boolean | Date>;
+        fields?: string[];
+    };
+    timestamp: Date;
+    ipAddress?: string;
+    userAgent?: string;
+}
+/**
+ * Adapter-specific configuration types
+ */
+export interface DrizzleConfig {
+    connectionString?: string;
+    url?: string;
+    poolSize?: number;
+    ssl?: boolean;
+}
+export interface SupabaseConfig {
+    supabaseUrl: string;
+    supabaseAnonKey: string;
+    supabaseServiceKey?: string;
+    schema?: string;
+}
+export interface SqlConfig {
+    connectionString?: string;
+    url?: string;
+    dialect?: 'postgresql' | 'mysql' | 'sqlite';
+}
+export interface MockConfig {
+    logging?: boolean;
+    initialData?: Record<string, Record<string, string | number | boolean | Date>[]>;
+}
+/**
+ * Union type for adapter configurations
+ */
+export type AdapterConfig = DrizzleConfig | SupabaseConfig | SqlConfig | MockConfig;
+/**
+ * Per-operation configuration overrides
+ */
+export interface OperationConfig {
+    /** Override soft delete settings for this operation */
+    softDelete?: Partial<SoftDeleteConfig>;
+    /** Override encryption settings for this operation */
+    encryption?: Partial<DBEncryptionConfig>;
+    /** Skip audit logging for this operation */
+    skipAudit?: boolean;
+    /** Override cache settings for this operation */
+    cache?: Partial<DBCacheConfig>;
+    /** Force specific adapter usage */
+    forceAdapter?: 'primary' | 'replica';
+    /** Include soft-deleted records in results */
+    includeSoftDeleted?: boolean;
+    /** Override query timeout for this operation */
+    timeout?: number;
+    /** Override timestamp settings for this operation */
+    timestamps?: Partial<TimestampsConfig>;
+}
+/**
+ * Complete database service configuration
+ */
+export interface DatabaseServiceConfig {
+    /** Database adapter type */
+    adapter: 'drizzle' | 'supabase' | 'sql' | 'mock';
+    /** Adapter-specific configuration */
+    config: AdapterConfig;
+    /** Connection pool settings */
+    pool?: PoolConfig;
+    /** Encryption configuration */
+    encryption?: DBEncryptionConfig;
+    /** Soft delete configuration */
+    softDelete?: SoftDeleteConfig;
+    /** Audit logging configuration */
+    audit?: AuditConfig;
+    /** Automatic timestamps configuration */
+    timestamps?: TimestampsConfig;
+    /** Query result caching configuration */
+    cache?: DBCacheConfig;
+    /** Read replica configuration */
+    readReplica?: ReadReplicaConfig;
+    /** Database event handlers */
+    events?: DatabaseEvents;
+}
+/**
+ * Resolved configuration after merging global and operation configs
+ */
+export interface ResolvedOperationConfig {
+    softDelete?: SoftDeleteConfig;
+    encryption?: DBEncryptionConfig;
+    cache?: DBCacheConfig;
+    timestamps?: TimestampsConfig;
+    skipAudit: boolean;
+    includeSoftDeleted: boolean;
+    forceAdapter?: 'primary' | 'replica';
+    timeout: number;
+}

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

@@ -0,0 +1,158 @@
+/**
+ * Event system types for database operations
+ * Matches the documentation's event system design
+ */
+/**
+ * Database operation types
+ */
+export type DatabaseOperationType = 'CREATE' | 'READ' | 'UPDATE' | 'DELETE';
+/**
+ * Base database event interface
+ */
+export interface DatabaseEvent {
+    /** Event type */
+    type: string;
+    /** Timestamp when the event occurred */
+    timestamp: Date;
+}
+/**
+ * Event emitted before any write operation starts
+ */
+export interface DatabaseBeforeWriteEvent extends DatabaseEvent {
+    type: 'beforeWrite';
+    /** Database adapter name */
+    adapter: string;
+    /** Database operation type */
+    operation: 'CREATE' | 'UPDATE' | 'DELETE';
+    /** Table name */
+    table: string;
+    /** Data being written */
+    data: Record<string, string | number | boolean | Date>;
+}
+/**
+ * Event emitted after successful write operation
+ */
+export interface DatabaseAfterWriteEvent extends DatabaseEvent {
+    type: 'afterWrite';
+    /** Database adapter name */
+    adapter: string;
+    /** Database operation type */
+    operation: 'CREATE' | 'UPDATE' | 'DELETE';
+    /** Table name */
+    table: string;
+    /** Result data */
+    result: Record<string, string | number | boolean | Date>;
+    /** Operation duration in milliseconds */
+    duration: number;
+}
+/**
+ * Event emitted before any read operation starts
+ */
+export interface DatabaseBeforeReadEvent extends DatabaseEvent {
+    type: 'beforeRead';
+    /** Database adapter name */
+    adapter: string;
+    /** Database operation type */
+    operation: 'READ';
+    /** Table name */
+    table: string;
+}
+/**
+ * Event emitted after successful read operation
+ */
+export interface DatabaseAfterReadEvent extends DatabaseEvent {
+    type: 'afterRead';
+    /** Database adapter name */
+    adapter: string;
+    /** Database operation type */
+    operation: 'READ';
+    /** Table name */
+    table: string;
+    /** Result data */
+    result: Record<string, string | number | boolean | Date>;
+    /** Operation duration in milliseconds */
+    duration: number;
+}
+/**
+ * Event emitted when any database operation fails
+ */
+export interface DBErrorEvent extends DatabaseEvent {
+    type: 'error';
+    /** Database adapter name */
+    adapter: string;
+    /** Database operation type */
+    operation: string;
+    /** Table name */
+    table: string;
+    /** Error that occurred */
+    error: Error;
+}
+/**
+ * Event emitted when health status changes
+ */
+export interface HealthChangeEvent extends DatabaseEvent {
+    type: 'healthChange';
+    /** Database adapter name */
+    adapter: string;
+    /** Previous health status */
+    previousStatus: boolean;
+    /** Current health status */
+    currentStatus: boolean;
+    /** Health check details */
+    details?: Record<string, string | number | boolean>;
+}
+/**
+ * Event emitted on slow queries
+ */
+export interface SlowQueryEvent extends DatabaseEvent {
+    type: 'slowQuery';
+    /** Table name */
+    table: string;
+    /** Database operation type */
+    operation: 'READ';
+    /** Query configuration */
+    query: Record<string, string | number | boolean>;
+    /** Query duration in milliseconds */
+    duration: number;
+    /** Slow query threshold that was exceeded */
+    threshold: number;
+}
+/**
+ * Audit event for compliance logging
+ */
+export interface DatabaseAuditEvent extends DatabaseEvent {
+    type: 'audit';
+    /** Database operation type */
+    operation: string;
+    /** User ID who performed the action */
+    userId?: string;
+    /** System action identifier */
+    systemAction?: string;
+    /** Request ID for tracing */
+    requestId: string;
+    /** Table name */
+    table: string;
+    /** Record ID that was affected */
+    recordId?: string;
+    /** Changes made to the record */
+    changes: {
+        /** State before the change */
+        before?: Record<string, string | number | boolean | Date>;
+        /** State after the change */
+        after?: Record<string, string | number | boolean | Date>;
+        /** Fields that were changed */
+        fields?: string[];
+    };
+    /** IP address of the user */
+    ipAddress?: string;
+    /** User agent string */
+    userAgent?: string;
+}
+/**
+ * Union type for all database events
+ */
+export type DatabaseEventUnion = DatabaseBeforeWriteEvent | DatabaseAfterWriteEvent | DatabaseBeforeReadEvent | DatabaseAfterReadEvent | DBErrorEvent | DatabaseAuditEvent | HealthChangeEvent | SlowQueryEvent;
+/**
+ * Event handler function type
+ */
+export type DBEventHandler<T extends DatabaseEvent> = (event: T) => void | Promise<void>;