ts-prorm-orm 1.1.0 → 1.2.0

package/dist/query-optimizers/query-optimizer.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Query Optimizer - Main entry point that combines all optimization features
+ */
+import { Dialect } from '../dialects/dialect';
+import { QueryHintManager, QueryHint } from './query-hints';
+import { ExplainPlanGenerator, ExplainOptions } from './explain-plans';
+import { SlowQueryLogger, SlowQueryOptions } from './slow-query-logger';
+import { BatchQueryOptimizer, BatchOptions, BatchResult } from './batch-optimizer';
+import { PreparedStatementCache, PreparedStatementCacheOptions, QueryResultCache } from './prepared-statement-cache';
+/**
+ * Query optimization options
+ */
+export interface QueryOptimizationOptions {
+    /** Enable query hints */
+    enableHints?: boolean;
+    /** Enable explain plans */
+    enableExplain?: boolean;
+    /** Enable slow query logging */
+    enableSlowQueryLog?: boolean;
+    /** Enable prepared statement caching */
+    enablePreparedStatementCache?: boolean;
+    /** Enable query result caching */
+    enableQueryResultCache?: boolean;
+    /** Enable batch optimization */
+    enableBatchOptimization?: boolean;
+    /** Slow query logging options */
+    slowQueryOptions?: Partial<SlowQueryOptions>;
+    /** Prepared statement cache options */
+    preparedStatementCacheOptions?: Partial<PreparedStatementCacheOptions>;
+    /** Query result cache options */
+    queryResultCacheOptions?: {
+        maxSize?: number;
+        ttl?: number;
+        logging?: boolean;
+    };
+    /** Batch optimization options */
+    batchOptions?: Partial<BatchOptions>;
+    /** Default explain options */
+    explainOptions?: Partial<ExplainOptions>;
+    /** Logging function */
+    logging?: (message: string, level?: 'info' | 'warn' | 'error') => void;
+}
+/**
+ * Main query optimizer class that combines all optimization features
+ */
+export declare class QueryOptimizer {
+    private dialect;
+    private options;
+    private queryHintManager?;
+    private explainPlanGenerator?;
+    private slowQueryLogger?;
+    private preparedStatementCache?;
+    private queryResultCache?;
+    private batchOptimizer?;
+    constructor(dialect: Dialect, options?: QueryOptimizationOptions);
+    /**
+     * Initialize all optimization components
+     */
+    private initializeComponents;
+    /**
+     * Get the query hint manager
+     */
+    getHintManager(): QueryHintManager | undefined;
+    /**
+     * Get the explain plan generator
+     */
+    getExplainGenerator(): ExplainPlanGenerator | undefined;
+    /**
+     * Get the slow query logger
+     */
+    getSlowQueryLogger(): SlowQueryLogger | undefined;
+    /**
+     * Get the prepared statement cache
+     */
+    getPreparedStatementCache(): PreparedStatementCache | undefined;
+    /**
+     * Get the query result cache
+     */
+    getQueryResultCache(): QueryResultCache | undefined;
+    /**
+     * Get the batch optimizer
+     */
+    getBatchOptimizer(): BatchQueryOptimizer | undefined;
+    /**
+     * Apply query hints to a SQL statement
+     */
+    applyHints(sql: string, hints: QueryHint[]): string;
+    /**
+     * Execute an optimized query with caching support
+     */
+    executeQuery(sql: string, options?: {
+        params?: any[];
+        useCache?: boolean;
+        usePreparedStatement?: boolean;
+        hint?: QueryHint[];
+        skipSlowLog?: boolean;
+    }): Promise<{
+        result: any;
+        fromCache: boolean;
+        duration: number;
+    }>;
+    /**
+     * Explain a query
+     */
+    explainQuery(sql: string, options?: ExplainOptions): Promise<import("./explain-plans").ExplainPlan>;
+    /**
+     * Analyze a query for optimization opportunities
+     */
+    analyzeQuery(sql: string, options?: ExplainOptions): Promise<{
+        plan: import("./explain-plans").ExplainPlan;
+        recommendations: import("./explain-plans").QueryRecommendation[];
+    }>;
+    /**
+     * Perform batch insert with optimization
+     */
+    batchInsert(tableName: string, records: Record<string, any>[], options?: Partial<BatchOptions>): Promise<BatchResult>;
+    /**
+     * Perform batch update with optimization
+     */
+    batchUpdate(tableName: string, records: Record<string, any>[], identifierColumn?: string, options?: Partial<BatchOptions>): Promise<BatchResult>;
+    /**
+     * Perform batch delete with optimization
+     */
+    batchDelete(tableName: string, identifiers: any[], identifierColumn?: string, options?: Partial<BatchOptions>): Promise<BatchResult>;
+    /**
+     * Get optimization statistics
+     */
+    getStats(): {
+        slowQuery: import("./slow-query-logger").QueryStatistics | undefined;
+        preparedStatementCache: import("./prepared-statement-cache").CacheStats | undefined;
+        queryResultCache: {
+            size: number;
+            maxSize: number;
+            hitCount: number;
+        } | undefined;
+    };
+    /**
+     * Clear all caches
+     */
+    clearCaches(): void;
+    /**
+     * Prune expired cache entries
+     */
+    pruneCaches(): void;
+    /**
+     * Invalidate query result cache for a specific table
+     */
+    invalidateTableCache(tableName: string): number;
+    /**
+     * Log a message
+     */
+    private log;
+}
+/**
+ * Create a query optimizer instance
+ */
+export declare function createQueryOptimizer(dialect: Dialect, options?: QueryOptimizationOptions): QueryOptimizer;
+declare const _default: {
+    QueryOptimizer: typeof QueryOptimizer;
+    createQueryOptimizer: typeof createQueryOptimizer;
+};
+export default _default;

package/dist/query-optimizers/slow-query-logger.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Slow Query Logging
+ * Provides functionality to log and analyze slow database queries
+ */
+import { EventEmitter } from 'events';
+/**
+ * Slow query log entry
+ */
+export interface SlowQueryLogEntry {
+    /** Unique identifier for the log entry */
+    id: string;
+    /** The SQL query that was executed */
+    sql: string;
+    /** Query parameters (if any) */
+    params?: any[];
+    /** Duration of query execution in milliseconds */
+    duration: number;
+    /** Timestamp when query was executed */
+    timestamp: Date;
+    /** Database dialect used */
+    dialect: string;
+    /** Whether the query was from a transaction */
+    inTransaction: boolean;
+    /** Connection info (without sensitive data) */
+    connection?: {
+        database?: string;
+        host?: string;
+    };
+    /** Error message if query failed */
+    error?: string;
+    /** Query type (SELECT, INSERT, UPDATE, DELETE) */
+    queryType?: string;
+    /** Number of rows affected/returned */
+    rowCount?: number;
+}
+/**
+ * Options for slow query logging
+ */
+export interface SlowQueryOptions {
+    /** Threshold in milliseconds to consider a query as slow */
+    threshold: number;
+    /** Minimum number of slow queries to trigger an alert */
+    alertThreshold?: number;
+    /** Time window in milliseconds for alert calculation */
+    alertWindow?: number;
+    /** Log all queries, not just slow ones */
+    logAllQueries?: boolean;
+    /** Log query parameters */
+    logParams?: boolean;
+    /** Maximum number of log entries to keep in memory */
+    maxEntries?: number;
+    /** Callback for when a slow query is logged */
+    onSlowQuery?: (entry: SlowQueryLogEntry) => void;
+    /** Callback for when alert threshold is exceeded */
+    onAlert?: (entries: SlowQueryLogEntry[]) => void;
+    /** Include stack trace for queries */
+    includeStackTrace?: boolean;
+    /** Custom logger function */
+    logger?: (message: string, meta?: Record<string, any>) => void;
+}
+/**
+ * Slow query logger
+ */
+export declare class SlowQueryLogger extends EventEmitter {
+    private threshold;
+    private logAllQueries;
+    private logParams;
+    private maxEntries;
+    private onSlowQuery?;
+    private onAlert?;
+    private includeStackTrace;
+    private logger?;
+    private logs;
+    private alertThreshold;
+    private alertWindow;
+    private queryTimestamps;
+    private static readonly DEFAULT_THRESHOLD;
+    constructor(options: SlowQueryOptions);
+    /**
+     * Set the slow query threshold
+     */
+    setThreshold(threshold: number): void;
+    /**
+     * Get the current threshold
+     */
+    getThreshold(): number;
+    /**
+     * Enable logging of all queries (not just slow ones)
+     */
+    setLogAllQueries(logAll: boolean): void;
+    /**
+     * Log a query execution
+     */
+    logQuery(options: {
+        sql: string;
+        params?: any[];
+        duration: number;
+        dialect: string;
+        inTransaction?: boolean;
+        connection?: {
+            database?: string;
+            host?: string;
+        };
+        error?: string;
+        queryType?: string;
+        rowCount?: number;
+    }): SlowQueryLogEntry | null;
+    /**
+     * Add a log entry to the internal log storage
+     */
+    private addLogEntry;
+    /**
+     * Log the entry using the configured logger
+     */
+    private logEntry;
+    /**
+     * Check if alert threshold has been exceeded
+     */
+    private checkAlertThreshold;
+    /**
+     * Get all log entries
+     */
+    getLogs(): SlowQueryLogEntry[];
+    /**
+     * Get slow query entries only
+     */
+    getSlowQueries(): SlowQueryLogEntry[];
+    /**
+     * Get query statistics
+     */
+    getStatistics(): QueryStatistics;
+    /**
+     * Calculate percentile from sorted array
+     */
+    private percentile;
+    /**
+     * Clear all log entries
+     */
+    clear(): void;
+    /**
+     * Generate a unique ID for log entries
+     */
+    private generateId;
+    /**
+     * Export logs to a file-compatible format
+     */
+    exportLogs(): string;
+    /**
+     * Get queries by type
+     */
+    getQueriesByType(type: string): SlowQueryLogEntry[];
+    /**
+     * Get queries on a specific table
+     */
+    getQueriesOnTable(tableName: string): SlowQueryLogEntry[];
+    /**
+     * Find similar queries (group by SQL pattern)
+     */
+    findSimilarQueries(sql: string): SlowQueryLogEntry[];
+    /**
+     * Normalize SQL for comparison
+     */
+    private normalizeSql;
+}
+/**
+ * Query statistics
+ */
+export interface QueryStatistics {
+    totalQueries: number;
+    slowQueries: number;
+    averageDuration: number;
+    maxDuration: number;
+    minDuration: number;
+    p50Duration: number;
+    p95Duration: number;
+    p99Duration: number;
+}
+/**
+ * Create a slow query logger instance
+ */
+export declare function createSlowQueryLogger(options: SlowQueryOptions): SlowQueryLogger;
+declare const _default: {
+    SlowQueryLogger: typeof SlowQueryLogger;
+    createSlowQueryLogger: typeof createSlowQueryLogger;
+};
+export default _default;

package/dist/replica-manager.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Replica Manager for handling read replicas with lag detection
+ * Supports multiple database dialects with dialect-specific lag detection queries
+ */
+import { EventEmitter } from 'events';
+import { QueryOptions } from './types';
+/**
+ * Routing strategy for selecting a replica.
+ *
+ * Companion enum to the `RoutingStrategy` string-literal union below.
+ * Use either `ReplicaRoutingStrategy.RoundRobin` or the raw string
+ * `'round-robin'` (and so on) — both are accepted wherever a
+ * `RoutingStrategy` is expected.
+ */
+export declare enum ReplicaRoutingStrategy {
+    RoundRobin = "round-robin",
+    LeastConnections = "least-connections",
+    LowestLag = "lowest-lag"
+}
+/**
+ * Routing strategy for selecting a replica
+ *
+ * Accepts either the string-literal union values directly, or the
+ * equivalent `ReplicaRoutingStrategy` enum member. Widened to include
+ * the enum in a non-breaking way: existing string-literal usage
+ * continues to work unchanged.
+ */
+export type RoutingStrategy = 'round-robin' | 'least-connections' | 'lowest-lag' | ReplicaRoutingStrategy;
+/**
+ * Replica status
+ */
+export interface ReplicaStatus {
+    /** Replica name */
+    name: string;
+    /** Whether the replica is healthy */
+    healthy: boolean;
+    /** Replication lag in milliseconds */
+    lag: number | null;
+    /** Number of active connections */
+    activeConnections: number;
+    /** Last check timestamp */
+    lastCheck: Date;
+    /** Error message if unhealthy */
+    error?: string;
+}
+/**
+ * Configuration for connecting to a replica
+ */
+export interface ReplicaConnectionConfig {
+    /** Unique name for this replica */
+    name: string;
+    /** Connection host */
+    host: string;
+    /** Connection port */
+    port: number;
+    /** Database name */
+    database: string;
+    /** Username */
+    username: string;
+    /** Password */
+    password: string;
+    /** Connection dialect (mysql, mariadb, postgres, mssql, sqlite, oracle) */
+    dialect: string;
+    /** Additional dialect-specific options */
+    dialectOptions?: Record<string, any>;
+    /** Pool options for this replica */
+    pool?: {
+        max?: number;
+        min?: number;
+        idle?: number;
+        acquire?: number;
+    };
+}
+/**
+ * Configuration for lag detection
+ */
+export interface LagDetectionConfig {
+    /** Enable lag detection */
+    enabled: boolean;
+    /** Interval in milliseconds between lag checks */
+    interval: number;
+    /** Query timeout in milliseconds */
+    timeout: number;
+    /** Maximum acceptable lag in milliseconds */
+    maxAcceptableLag: number;
+    /** Number of consecutive failures before marking replica as unhealthy */
+    maxFailures: number;
+}
+/**
+ * Options for configuring replication
+ */
+export interface ReplicationOptions {
+    /** Enable replication support */
+    enabled: boolean;
+    /** The master connection configuration */
+    master: ReplicaConnectionConfig;
+    /** Array of replica configurations */
+    replicas: ReplicaConnectionConfig[];
+    /** Default lag detection configuration */
+    lagDetection?: Partial<LagDetectionConfig>;
+    /** Default routing strategy */
+    defaultRoutingStrategy?: RoutingStrategy;
+    /** Whether to automatically fail over to master on all replicas unhealthy */
+    autoFailover?: boolean;
+}
+/**
+ * Replica connection pool wrapper
+ */
+declare class ReplicaPool {
+    private pool;
+    private dialect;
+    private name;
+    private config;
+    private dialectModule;
+    constructor(config: ReplicaConnectionConfig);
+    initialize(dialectModule: any): Promise<void>;
+    getPool(): any;
+    getName(): string;
+    getDialect(): string;
+    getConnection(): Promise<any>;
+    releaseConnection(connection: any): Promise<void>;
+    close(): Promise<void>;
+    query(sql: string, options?: QueryOptions): Promise<any>;
+}
+/**
+ * Replica Manager Events
+ */
+export interface ReplicaManagerEvents {
+    'replica:added': (name: string) => void;
+    'replica:removed': (name: string) => void;
+    'replica:healthy': (name: string, status: ReplicaStatus) => void;
+    'replica:unhealthy': (name: string, status: ReplicaStatus) => void;
+    'replica:lag-detected': (name: string, lag: number) => void;
+    'replica:selected': (name: string) => void;
+    'all-replicas-unhealthy': () => void;
+    'monitor:started': () => void;
+    'monitor:stopped': () => void;
+}
+/**
+ * ReplicaManager class for managing read replicas with lag detection
+ */
+export declare class ReplicaManager extends EventEmitter {
+    private replicas;
+    private replicaStats;
+    private lagDetectionConfig;
+    private routingStrategy;
+    private roundRobinIndex;
+    private monitorInterval;
+    private masterConfig;
+    /**
+     * Create a new ReplicaManager
+     */
+    constructor(options?: Partial<ReplicationOptions>);
+    /**
+     * Add a replica to the manager
+     */
+    addReplica(config: ReplicaConnectionConfig): Promise<void>;
+    /**
+     * Remove a replica from the manager
+     */
+    removeReplica(name: string): Promise<void>;
+    /**
+     * Get a replica by name
+     */
+    getReplica(name: string): ReplicaPool | undefined;
+    /**
+     * Get all replica names
+     */
+    getReplicaNames(): string[];
+    /**
+     * Check replication lag for a specific replica
+     * Uses dialect-specific queries for lag detection
+     */
+    checkLag(name: string): Promise<number | null>;
+    /**
+     * Start the lag monitoring loop
+     */
+    startLagMonitor(): void;
+    /**
+     * Stop the lag monitoring loop
+     */
+    stopLagMonitor(): void;
+    /**
+     * Get statistics for all replicas
+     */
+    getReplicaStats(): Map<string, ReplicaStatus>;
+    /**
+     * Get statistics for a specific replica
+     */
+    getReplicaStat(name: string): ReplicaStatus | undefined;
+    /**
+     * Set the routing strategy
+     */
+    setRoutingStrategy(strategy: RoutingStrategy): void;
+    /**
+     * Get the current routing strategy
+     */
+    getRoutingStrategy(): RoutingStrategy;
+    /**
+     * Select a replica based on the current routing strategy
+     */
+    selectReplica(): Promise<{
+        name: string;
+        pool: ReplicaPool;
+    }>;
+    /**
+     * Execute a query on a replica (auto-selects replica based on routing strategy)
+     */
+    queryReplica(sql: string, options?: QueryOptions): Promise<any>;
+    /**
+     * Get healthy replicas
+     */
+    getHealthyReplicas(): string[];
+    /**
+     * Get replica count
+     */
+    getReplicaCount(): number;
+    /**
+     * Check if replication is enabled
+     */
+    isReplicationEnabled(): boolean;
+    /**
+     * Set lag detection configuration
+     */
+    setLagDetectionConfig(config: Partial<LagDetectionConfig>): void;
+    /**
+     * Get lag detection configuration
+     */
+    getLagDetectionConfig(): LagDetectionConfig;
+    /**
+     * Close all replica connections
+     */
+    close(): Promise<void>;
+}
+export default ReplicaManager;

package/dist/schema/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Schema Module - Automated schema diffing and migration generation
+ * Exports classes and functions for comparing model definitions against database schema
+ */
+export type { ChangeType, ColumnChange, IndexChange, ConstraintChange, ForeignKeyChange, TableChange, SchemaDiff, ColumnDefinition, IndexDefinition, ConstraintDefinition, ForeignKeyDefinition, DatabaseColumnInfo, DatabaseIndexInfo, DatabaseConstraintInfo, DatabaseForeignKeyInfo, MigrationScript, MigrationGeneratorOptions, SchemaDifferOptions, } from './types';
+export { SchemaDiffer, createSchemaDiffer } from './schema-differ';
+export { MigrationGenerator, createMigrationGenerator } from './migration-generator';

package/dist/schema/migration-generator.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Migration Generator
+ * Generates migration scripts from schema diffs
+ */
+import type { Dialect } from '../dialects/dialect';
+import type { SchemaDiff, MigrationScript, MigrationGeneratorOptions } from './types';
+/**
+ * MigrationGenerator generates SQL migration scripts from schema diffs
+ */
+export declare class MigrationGenerator {
+    private dialect;
+    private options;
+    constructor(dialect: Dialect, options?: MigrationGeneratorOptions);
+    /**
+     * Generate a migration script from a schema diff
+     */
+    generateMigration(diff: SchemaDiff, options?: MigrationGeneratorOptions): MigrationScript;
+    /**
+     * Generate migration scripts for all schema diffs
+     */
+    generateAllMigrations(diffs: SchemaDiff[], options?: MigrationGeneratorOptions): MigrationScript[];
+    /**
+     * Generate column migration statements
+     */
+    private generateColumnMigration;
+    /**
+     * Generate index migration statements
+     */
+    private generateIndexMigration;
+    /**
+     * Generate constraint migration statements
+     */
+    private generateConstraintMigration;
+    /**
+     * Generate foreign key migration statements
+     */
+    private generateForeignKeyMigration;
+    /**
+     * Generate ADD COLUMN SQL
+     */
+    private generateAddColumnSql;
+    /**
+     * Generate MODIFY COLUMN SQL
+     */
+    private generateModifyColumnSql;
+    /**
+     * Generate CREATE INDEX SQL
+     */
+    private generateCreateIndexSql;
+    /**
+     * Generate ADD CONSTRAINT SQL
+     */
+    private generateAddConstraintSql;
+    /**
+     * Generate ADD FOREIGN KEY SQL
+     */
+    private generateAddForeignKeySql;
+    /**
+     * Quote table name based on dialect
+     */
+    private quoteTableName;
+    /**
+     * Quote identifier based on dialect
+     */
+    private quoteIdentifier;
+    /**
+     * Format default value for SQL
+     */
+    private formatDefaultValue;
+}
+/**
+ * Create a MigrationGenerator instance
+ */
+export declare function createMigrationGenerator(dialect: Dialect, options?: MigrationGeneratorOptions): MigrationGenerator;