ts-prorm-orm 1.1.0 → 1.2.1

package/dist/connection-pool.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Connection Pool Management
+ * Manages a pool of database connections for efficient resource usage
+ * Includes health checks, connection validation, and comprehensive metrics
+ */
+import { EventEmitter } from 'events';
+import { PoolOptions } from './types';
+export { PoolOptions } from './types';
+/**
+ * Pool event types
+ */
+export type PoolEventType = 'acquire' | 'release' | 'destroy' | 'create' | 'remove' | 'error' | 'enqueue' | 'dequeue' | 'timeout' | 'health-check' | 'connection-invalid' | 'reconnect';
+/**
+ * Pool events interface
+ */
+export interface PoolEvents {
+    acquire: (connection: any) => void;
+    release: (connection: any) => void;
+    destroy: (connection: any) => void;
+    create: (connection: any) => void;
+    remove: (connection: any) => void;
+    error: (error: Error) => void;
+    enqueue: () => void;
+    dequeue: () => void;
+    timeout: (connection: any) => void;
+    'health-check': (connection: any, healthy: boolean) => void;
+    'connection-invalid': (connection: any) => void;
+    reconnect: (connection: any, success: boolean) => void;
+}
+export interface PoolConnectionOptions {
+    id?: string;
+    timestamp?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Health check configuration for connections
+ */
+export interface HealthCheckConfig {
+    /** Enable health checks */
+    enabled: boolean;
+    /** Interval in milliseconds between health checks */
+    interval: number;
+    /** Timeout for health check query in milliseconds */
+    timeout: number;
+    /** SQL query to use for health check */
+    query: string;
+    /** Number of consecutive failures before removing connection */
+    maxFailures: number;
+}
+/**
+ * Pool metrics for monitoring
+ */
+export interface PoolMetrics {
+    /** Total connections in pool */
+    size: number;
+    /** Available (idle) connections */
+    available: number;
+    /** Connections currently in use */
+    inUse: number;
+    /** Total connections acquired since pool creation */
+    acquired: number;
+    /** Total connections released since pool creation */
+    released: number;
+    /** Total connections destroyed */
+    destroyed: number;
+    /** Requests waiting for a connection */
+    pending: number;
+    /** Connection acquire success rate (0-1) */
+    hitRate: number;
+    /** Average wait time in milliseconds */
+    avgWaitTime: number;
+    /** Maximum wait time observed in milliseconds */
+    maxWaitTime: number;
+    /** Total number of health checks performed */
+    healthChecks: number;
+    /** Number of failed health checks */
+    failedHealthChecks: number;
+    /** Number of connection validations performed */
+    validations: number;
+    /** Number of failed validations */
+    failedValidations: number;
+    /** Number of successful reconnection attempts */
+    reconnects: number;
+    /** Uptime in milliseconds */
+    uptime: number;
+}
+export interface PoolConfig extends PoolOptions {
+    /**
+     * Time in milliseconds to evict idle connections
+     */
+    evict?: number;
+    /**
+     * Callback when a connection is acquired
+     */
+    onAcquire?: (connection: any) => void;
+    /**
+     * Callback when a connection is released
+     */
+    onRelease?: (connection: any) => void;
+    /**
+     * Callback when a connection is destroyed
+     */
+    onDestroy?: (connection: any) => void;
+    /**
+     * Callback on pool error
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Health check configuration
+     */
+    healthCheck?: Partial<HealthCheckConfig>;
+    /**
+     * Enable connection validation on borrow
+     */
+    validateOnBorrow?: boolean;
+    /**
+     * Timeout for connection validation in milliseconds
+     */
+    validationTimeout?: number;
+    /**
+     * Custom validation query (overrides healthCheck.query)
+     */
+    validationQuery?: string;
+    /**
+     * Enable reconnection for failed connections
+     */
+    enableReconnection?: boolean;
+    /**
+     * Maximum number of reconnection attempts
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Interval between reconnection attempts in milliseconds
+     */
+    reconnectInterval?: number;
+}
+/**
+ * Pooled connection wrapper with health tracking
+ */
+export declare class PooledConnection {
+    id: string;
+    connection: any;
+    inUse: boolean;
+    timestamp: number;
+    metadata: Record<string, any>;
+    healthCheckFailures: number;
+    lastHealthCheck: number;
+    lastValidation: number;
+    isHealthy: boolean;
+    connectTimestamp: number;
+    constructor(connection: any, id?: string);
+    /**
+     * Mark the connection as in use
+     */
+    markInUse(): void;
+    /**
+     * Release the connection back to the pool
+     */
+    release(): void;
+    /**
+     * Check if the connection is idle for too long
+     */
+    isIdle(timeout: number): boolean;
+    /**
+     * Check if the connection has been idle longer than the given timeout
+     */
+    isIdleExceeding(timeout: number): boolean;
+    /**
+     * Increment health check failure counter
+     */
+    recordHealthCheckFailure(): void;
+    /**
+     * Reset health check failures on successful check
+     */
+    resetHealthCheckFailures(): void;
+    /**
+     * Get connection age in milliseconds
+     */
+    getAge(): number;
+}
+/**
+ * Connection Pool class
+ * Manages a pool of database connections with configurable limits
+ */
+export declare class ConnectionPool extends EventEmitter {
+    private config;
+    protected connections: Map<string, PooledConnection>;
+    private waitingQueue;
+    private evictTimer?;
+    private _isDestroyed;
+    protected _size: number;
+    protected _available: number;
+    protected _inUse: number;
+    protected _acquired: number;
+    protected _released: number;
+    protected _destroyed: number;
+    protected _pending: number;
+    /**
+     * Maximum number of connections in the pool
+     */
+    get max(): number;
+    /**
+     * Minimum number of idle connections
+     */
+    get min(): number;
+    /**
+     * Get the pending requests count
+     */
+    get pending(): number;
+    /**
+     * Constructor
+     */
+    constructor(config: PoolConfig);
+    /**
+     * Initialize the pool with a factory function to create connections
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get a connection from the pool
+     */
+    getConnection(): Promise<PooledConnection>;
+    /**
+     * Release a connection back to the pool
+     */
+    releaseConnection(pooledConnection: PooledConnection): void;
+    /**
+     * Destroy a connection
+     */
+    destroyConnection(pooledConnection: PooledConnection): Promise<void>;
+    /**
+     * Destroy a specific connection or the entire pool
+     * @param connection - Optional connection to destroy. If not provided, destroys the entire pool
+     */
+    destroy(connection?: any): Promise<void>;
+    /**
+     * Get pool statistics
+     */
+    get stats(): {
+        size: number;
+        available: number;
+        inUse: number;
+        acquired: number;
+        released: number;
+        destroyed: number;
+        pending: number;
+    };
+    /**
+     * Get the current pool size
+     */
+    get size(): number;
+    /**
+     * Get the number of available connections
+     */
+    get available(): number;
+    /**
+     * Get the number of connections in use
+     */
+    get inUse(): number;
+    /**
+     * Check if the pool is destroyed
+     */
+    get isDestroyed(): boolean;
+    /**
+     * Get the number of connections in use (alias for inUse)
+     */
+    get used(): number;
+    /**
+     * Get an available connection from the pool
+     */
+    private getAvailableConnection;
+    /**
+     * Create a new connection
+     */
+    protected createConnection(): Promise<PooledConnection>;
+    /**
+     * Process the waiting queue
+     */
+    private processWaitingQueue;
+    /**
+     * Start the evictor to clean up idle connections
+     */
+    private startEvictor;
+}
+/**
+ * Database-specific connection pool implementation
+ */
+export declare class DatabaseConnectionPool extends ConnectionPool {
+    private connectionFactory;
+    constructor(config: PoolConfig & {
+        factory: () => Promise<any>;
+    });
+    /**
+     * Create a new database connection
+     */
+    protected createConnection(): Promise<PooledConnection>;
+    /**
+     * Get a connection using async/await
+     */
+    acquire(): Promise<any>;
+    /**
+     * Release a connection
+     */
+    release(connection: any): void;
+}
+/**
+ * Create a new connection pool
+ */
+export declare function createPool(config: PoolConfig & {
+    factory: () => Promise<any>;
+}): DatabaseConnectionPool;
+export default ConnectionPool;

package/dist/decorators/audit.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @Audit class decorator — automatically record model lifecycle events to an
+ * in-memory audit log.
+ *
+ * When applied to a model class the decorator registers beforeCreate,
+ * beforeUpdate, and beforeDestroy hooks (via ModelClass.addHook) that append
+ * structured entries to a per-class log.
+ *
+ * Example:
+ *
+ *   @Audit({ tableName: 'audit_log', trackFields: ['name', 'email'] })
+ *   class User extends Model { ... }
+ *
+ *   // After create/update/destroy hooks fire:
+ *   const log = getAuditLog(User);
+ *   clearAuditLog(User);
+ */
+export interface AuditOptions {
+    /** Name of the conceptual audit table (used as label in entries). Default: 'audit_log'. */
+    tableName?: string;
+    /** If provided, only these fields are captured in newValues/oldValues. */
+    trackFields?: string[];
+    /** Field name on the model that holds the current user identifier. */
+    userField?: string;
+}
+export interface AuditEntry {
+    action: 'CREATE' | 'UPDATE' | 'DELETE';
+    model: string;
+    newValues?: Record<string, any>;
+    oldValues?: Record<string, any>;
+    user?: any;
+    timestamp: Date;
+}
+/** Return all audit log entries accumulated for a model class. */
+export declare function getAuditLog(target: any): AuditEntry[];
+/** Clear all audit log entries for a model class. */
+export declare function clearAuditLog(target: any): void;
+/**
+ * Mark a model class for automatic audit logging.
+ *
+ * Hooks are registered via `ModelClass.addHook` if the method exists, so this
+ * decorator is compatible with both Prorm-style models and plain mock classes
+ * that expose addHook manually in tests.
+ */
+export declare function Audit(options?: AuditOptions): ClassDecorator;
+/** Read the AuditOptions stored on a decorated class. */
+export declare function getAuditOptions(target: any): (AuditOptions & {
+    tableName: string;
+}) | undefined;

package/dist/decorators/check.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @Check decorator for the ORM — generates CHECK constraints without writing raw SQL.
+ *
+ * Supports ORM-native operator syntax that gets converted to SQL CHECK expressions.
+ *
+ * Usage Examples:
+ *
+ * // Column-level check with ORM operators
+ * @Check({ age: { $gte: 18 } })
+ * age: number;
+ *
+ * // Multiple column checks
+ * @Check({
+ *   status: { $in: ['active', 'pending', 'draft'] },
+ *   email: { $regex: '^[^@]+@[^@]+$' }
+ * })
+ * email: string;
+ *
+ * // Custom condition with message
+ * @Check({
+ *   condition: (row) => row.startDate < row.endDate,
+ *   message: 'Start date must be before end date'
+ * })
+ * startDate: Date;
+ *
+ * // Column-level check (explicit column)
+ * @CheckColumn('price', { $gte: 0 }, 'Price must be positive')
+ * @CheckColumn('quantity', { $gt: 0 }, 'Quantity must be greater than zero')
+ *
+ * // Table-level check (multiple columns)
+ * @CheckTable({
+ *   condition: (row) => row.quantity * row.price >= row.minimumOrder,
+ *   message: 'Total must meet minimum order amount'
+ * })
+ */
+/**
+ * ORM operator types for CHECK constraints
+ * Maps to SQL operators for CHECK constraint generation
+ */
+export type CheckOperator = {
+    $eq: any;
+} | {
+    $ne: any;
+} | {
+    $gt: number | string;
+} | {
+    $gte: number | string;
+} | {
+    $lt: number | string;
+} | {
+    $lte: number | string;
+} | {
+    $in: any[];
+} | {
+    $notIn: any[];
+} | {
+    $between: [any, any];
+} | {
+    $notBetween: [any, any];
+} | {
+    $like: string;
+} | {
+    $notLike: string;
+} | {
+    $iLike: string;
+} | {
+    $notILike: string;
+} | {
+    $regex: string;
+} | {
+    $notRegexp: string;
+} | {
+    $iRegexp: string;
+} | {
+    $notIRegexp: string;
+} | {
+    $isNull: null;
+} | {
+    $isNotNull: null;
+} | {
+    $contains: any;
+} | {
+    $containedBy: any;
+} | {
+    $overlap: any[];
+};
+/**
+ * Field-level check constraint definition
+ */
+export interface FieldCheckConstraint {
+    field: string;
+    operator: CheckOperator;
+    message?: string;
+}
+/**
+ * Row-level check constraint for table-level checks
+ * Uses a function to express cross-column conditions
+ */
+export interface RowCheckConstraint {
+    condition: (row: Record<string, any>) => boolean;
+    message?: string;
+}
+/**
+ * Check constraint options for @Check decorator
+ * Can specify field-level checks or row-level checks
+ */
+export interface CheckConstraintOptions {
+    /** Single field check with operator */
+    [field: string]: CheckOperator | RowCheckConstraint;
+}
+/**
+ * Options for @CheckColumn decorator
+ */
+export interface CheckColumnOptions {
+    /** Column name to check */
+    column: string;
+    /** Operator and value */
+    operator: CheckOperator;
+    /** Optional custom error message */
+    message?: string;
+}
+/**
+ * Options for @CheckTable decorator
+ */
+export interface CheckTableOptions {
+    /** Row-level condition function */
+    condition: (row: Record<string, any>) => boolean;
+    /** Custom error message */
+    message?: string;
+    /** Constraint name */
+    name?: string;
+}
+/**
+ * Internal storage for check constraints
+ */
+export interface StoredCheckConstraint {
+    type: 'column' | 'table';
+    name: string;
+    field?: string;
+    operator?: CheckOperator;
+    condition?: (row: Record<string, any>) => boolean;
+    message?: string;
+    sql?: string;
+}
+/**
+ * Supported SQL dialect identifiers used throughout the ORM
+ */
+export type CheckDialect = 'mysql' | 'mariadb' | 'postgres' | 'mssql' | 'oracle' | 'sqlite';
+/**
+ * Convert ORM operator to SQL CHECK expression
+ * @param fieldName - The column name
+ * @param operator - The ORM operator object
+ * @param dialect - The target SQL dialect (defaults to 'postgres' for backwards compatibility)
+ * @returns SQL expression string
+ */
+export declare function operatorToSQL(fieldName: string, operator: CheckOperator, dialect?: CheckDialect): string;
+/**
+ * @Check decorator — attach CHECK constraints to a column or multiple columns.
+ *
+ * For column-level use (on class property):
+ * @Check({ age: { $gte: 18 } })
+ * age: number;
+ *
+ * For multiple checks:
+ * @Check({
+ *   status: { $in: ['active', 'pending'] },
+ *   email: { $regex: '^[^@]+@[^@]+$' }
+ * })
+ * email: string;
+ *
+ * For row-level condition:
+ * @Check({
+ *   condition: (row) => row.startDate < row.endDate,
+ *   message: 'Start date must be before end date'
+ * })
+ * startDate: Date;
+ */
+export declare function Check(options: CheckConstraintOptions): PropertyDecorator;
+/**
+ * @CheckColumn decorator — explicit column-level CHECK constraint.
+ *
+ * @CheckColumn('price', { $gte: 0 }, 'Price must be positive')
+ * price: number;
+ */
+export declare function CheckColumn(column: string, operator: CheckOperator, message?: string): PropertyDecorator;
+/**
+ * @CheckTable decorator — table-level CHECK constraint with multi-column conditions.
+ *
+ * @CheckTable({
+ *   condition: (row) => row.quantity * row.price >= row.minimumOrder,
+ *   message: 'Total must meet minimum order amount'
+ * })
+ */
+export declare function CheckTable(options: CheckTableOptions): ClassDecorator;
+/**
+ * Get all CHECK constraints from a model class or instance
+ */
+export declare function getCheckConstraints(target: any): StoredCheckConstraint[];
+/**
+ * Get all table-level CHECK constraints from a model class
+ */
+export declare function getTableCheckConstraints(target: any): StoredCheckConstraint[];
+/**
+ * Get all CHECK constraints (both column and table level)
+ */
+export declare function getAllCheckConstraints(target: any): StoredCheckConstraint[];
+/**
+ * Build CREATE TABLE CHECK constraint SQL
+ */
+export declare function buildCheckConstraintSQL(tableName: string, constraint: StoredCheckConstraint, dialect?: CheckDialect): string;
+/**
+ * Build all CHECK constraints for a table
+ */
+export declare function buildAllCheckConstraints(tableName: string, constraints: StoredCheckConstraint[], dialect?: CheckDialect): string[];
+/**
+ * Clear CHECK constraints (useful for testing)
+ */
+export declare function clearCheckConstraints(target: any): void;