ts-prorm-orm 1.1.0 → 1.2.0

package/dist/query-optimizers/explain-plans.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Explain Query Plans
+ * Provides functionality to analyze and explain SQL query execution plans
+ */
+import { Dialect } from '../dialects/dialect';
+import { QueryResult } from '../types';
+/**
+ * Explain output format options
+ */
+export declare enum ExplainFormat {
+    TEXT = "text",
+    JSON = "json",
+    XML = "xml",
+    YAML = "yaml",
+    TREE = "tree"
+}
+/**
+ * Explain options
+ */
+export interface ExplainOptions {
+    /** Output format (text, json, xml, yaml) */
+    format?: ExplainFormat;
+    /** For MySQL: ANALYZE the query */
+    analyze?: boolean;
+    /** For MySQL: show format JSON */
+    verbose?: boolean;
+    /** For MySQL: show costs */
+    costs?: boolean;
+    /** For MySQL: show buffers */
+    buffers?: boolean;
+    /** For MySQL: timing information */
+    timing?: boolean;
+    /** For MySQL: show schema */
+    schema?: boolean;
+    /** For MySQL: type of statement (SELECT, INSERT, UPDATE, DELETE) */
+    type?: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
+    /** Custom options to pass to EXPLAIN */
+    [key: string]: any;
+}
+/**
+ * Generic explain plan entry (dialect-specific parsing may be needed)
+ */
+export interface ExplainPlan {
+    /** The analyzed SQL query */
+    sql: string;
+    /** Explain output (format depends on dialect) */
+    plan: any;
+    /** Raw query results from EXPLAIN */
+    rawResults: QueryResult;
+    /** Duration of the explain query in ms */
+    duration: number;
+    /** Dialect used */
+    dialect: string;
+    /** Parsed plan (if parsable) */
+    parsedPlan?: ParsedExplainStep[];
+}
+/**
+ * Parsed explain step for easier analysis
+ */
+export interface ParsedExplainStep {
+    /** Operation type (e.g., SCAN, INDEX, JOIN, etc.) */
+    operation: string;
+    /** Table involved (if applicable) */
+    table?: string;
+    /** Index used (if applicable) */
+    index?: string;
+    /** Number of rows to scan */
+    rows?: number;
+    /** Estimated cost (if available) */
+    cost?: number;
+    /** Additional details */
+    details?: Record<string, any>;
+    /** Child operations */
+    children?: ParsedExplainStep[];
+}
+/**
+ * Explain plan generator for different database dialects
+ */
+export declare class ExplainPlanGenerator {
+    private dialect;
+    private defaultOptions;
+    constructor(dialect: Dialect, defaultOptions?: ExplainOptions);
+    /**
+     * Set default options for EXPLAIN queries
+     */
+    setDefaultOptions(options: ExplainOptions): void;
+    /**
+     * Generate an explain plan for a SQL query
+     */
+    explain(sql: string, options?: ExplainOptions): Promise<ExplainPlan>;
+    /**
+     * Build the appropriate EXPLAIN SQL statement for the dialect
+     */
+    private buildExplainSql;
+    /**
+     * Build MySQL EXPLAIN statement
+     */
+    private buildMySQLExplain;
+    /**
+     * Build PostgreSQL EXPLAIN statement
+     */
+    private buildPostgresExplain;
+    /**
+     * Build SQLite EXPLAIN statement
+     */
+    private buildSQLiteExplain;
+    /**
+     * Parse EXPLAIN output into structured format
+     */
+    private parseExplainOutput;
+    /**
+     * Parse MySQL EXPLAIN output
+     */
+    private parseMySQLExplain;
+    /**
+     * Parse PostgreSQL EXPLAIN output
+     */
+    private parsePostgresExplain;
+    /**
+     * Recursively parse PostgreSQL plan nodes
+     */
+    private parsePostgresPlanNode;
+    /**
+     * Parse SQLite EXPLAIN QUERY PLAN output
+     */
+    private parseSQLiteExplain;
+    /**
+     * Extract operation type from SQLite detail
+     */
+    private extractSQLiteOperation;
+    /**
+     * Extract table name from SQLite detail
+     */
+    private extractSQLiteTable;
+    /**
+     * Extract index name from SQLite detail
+     */
+    private extractSQLiteIndex;
+    /**
+     * Generic explain output parser
+     */
+    private parseGenericExplain;
+    /**
+     * Analyze a query and provide optimization recommendations
+     */
+    analyzeQuery(sql: string, options?: ExplainOptions): Promise<{
+        plan: ExplainPlan;
+        recommendations: QueryRecommendation[];
+    }>;
+    /**
+     * Generate optimization recommendations based on explain plan
+     */
+    private generateRecommendations;
+    /**
+     * Generate MySQL-specific recommendations
+     */
+    private generateMySQLRecommendations;
+    /**
+     * Generate PostgreSQL-specific recommendations
+     */
+    private generatePostgresRecommendations;
+    /**
+     * Generate SQLite-specific recommendations
+     */
+    private generateSQLiteRecommendations;
+}
+/**
+ * Query recommendation
+ */
+export interface QueryRecommendation {
+    type: 'INDEX' | 'OPTIMIZATION' | 'REWRITE' | 'STATISTICS';
+    severity: 'HIGH' | 'MEDIUM' | 'LOW';
+    message: string;
+    table?: string;
+    column?: string;
+    suggestion?: string;
+}
+/**
+ * Create an ExplainPlanGenerator instance
+ */
+export declare function createExplainPlanGenerator(dialect: Dialect, options?: ExplainOptions): ExplainPlanGenerator;
+declare const _default: {
+    ExplainPlanGenerator: typeof ExplainPlanGenerator;
+    ExplainFormat: typeof ExplainFormat;
+    createExplainPlanGenerator: typeof createExplainPlanGenerator;
+};
+export default _default;

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

@@ -0,0 +1,27 @@
+/**
+ * Query Optimizers Module
+ * Provides various query optimization features including:
+ * - Query hint support
+ * - Explain query plans
+ * - Slow query logging
+ * - Query batch/bulk optimization
+ * - Prepared statement caching
+ */
+export { QueryHintManager, QueryHint, HintType, INDEX_HINT, FORCE_INDEX, USE_INDEX, JOIN_FIXED_ORDER, MERGE_HASH, NO_MERGE, } from './query-hints';
+export { ExplainPlanGenerator, ExplainPlan, ExplainOptions, ExplainFormat, createExplainPlanGenerator, } from './explain-plans';
+export { SlowQueryLogger, SlowQueryLogEntry, SlowQueryOptions, createSlowQueryLogger, } from './slow-query-logger';
+export { BatchQueryOptimizer, BatchOptions, BatchResult, QueryBatch, optimizeBatchInsert, optimizeBatchUpdate, optimizeBatchDelete, } from './batch-optimizer';
+export { PreparedStatementCache, PreparedStatementCacheOptions, CacheEntry, createPreparedStatementCache, } from './prepared-statement-cache';
+export { QueryOptimizer, QueryOptimizationOptions, createQueryOptimizer } from './query-optimizer';
+/**
+ * Default configuration for query optimizers
+ */
+export declare const defaultOptimizerConfig: {
+    slowQueryThreshold: number;
+    preparedStatementCacheSize: number;
+    batchInsertChunkSize: number;
+    batchUpdateChunkSize: number;
+    batchDeleteChunkSize: number;
+    enableExplainPlans: boolean;
+    enableQueryHints: boolean;
+};

package/dist/query-optimizers/prepared-statement-cache.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Prepared Statement Caching
+ * Provides functionality to cache and reuse prepared statements for better performance
+ */
+import { Dialect } from '../dialects/dialect';
+/**
+ * Options for prepared statement cache
+ */
+export interface PreparedStatementCacheOptions {
+    /** Maximum number of statements to cache */
+    maxSize: number;
+    /** Time-to-live in milliseconds for cached statements */
+    ttl?: number;
+    /** Whether to cache based on normalized SQL (with placeholders) */
+    normalizeSql?: boolean;
+    /** Callback when a statement is cached */
+    onCache?: (key: string, statement: CachedStatement) => void;
+    /** Callback when a statement is evicted */
+    onEvict?: (key: string, statement: CachedStatement) => void;
+    /** Whether to log cache operations */
+    logging?: boolean;
+}
+/**
+ * Cached prepared statement entry
+ */
+export interface CacheEntry {
+    /** Unique key for the cache entry */
+    key: string;
+    /** The SQL statement */
+    sql: string;
+    /**
+     * Caller-supplied metadata about the statement shape (e.g. parameter count,
+     * normalized SQL). This is NOT a real driver-level prepared-statement handle:
+     * `Dialect.query()` in this codebase always takes the full SQL text plus a
+     * `replacements`/`bind` array/object and does its own placeholder substitution
+     * or binds per-call - there is no separate "prepare" step whose handle could be
+     * cached and reused across calls. See the `PreparedStatementCache` class doc
+     * for details. Defaults to `{}` if the caller doesn't pass anything meaningful.
+     */
+    compiled: any;
+    /** Timestamp when the entry was created */
+    createdAt: number;
+    /** Number of times this statement was used */
+    hitCount: number;
+    /** Last time the statement was used */
+    lastUsedAt: number;
+}
+/**
+ * Extended cache entry with additional metadata
+ */
+export interface CachedStatement extends CacheEntry {
+    /** The number of times this statement has been executed */
+    executions: number;
+    /** Total time spent executing this statement */
+    totalExecutionTime: number;
+}
+/**
+ * Query cache entry for query results
+ */
+export interface QueryCacheEntry {
+    key: string;
+    sql: string;
+    params: any[];
+    result: any;
+    createdAt: number;
+    lastUsedAt: number;
+    hitCount: number;
+}
+/**
+ * Tracks SQL statement usage (hit/miss counts, execution timings, last-used
+ * time) keyed by normalized SQL + params, with TTL-based expiry.
+ *
+ * IMPORTANT — naming caveat: despite the name, this does **not** cache a real
+ * driver-level prepared-statement handle. None of the `Dialect` implementations
+ * in `src/dialects/**` expose a separate prepare/execute split - `query(sql,
+ * options)` always receives the full SQL text and applies `options.replacements`
+ * / `options.bind` per call (see e.g. `sqlite/index.ts` `query()`, which calls
+ * `connection.prepare(sql)` fresh on every invocation). So there is no reusable
+ * driver object for this class to hold onto; the `compiled` field on each entry
+ * is whatever metadata the caller passes to `set()` (by default just `{}`, or -
+ * see `QueryOptimizer.executeQuery()` - a lightweight `{ sql, paramCount }`
+ * descriptor). In practice this class behaves as a query-usage/hit-count
+ * tracker with an optional metadata slot, not a real statement cache. It is
+ * kept under this name for backwards compatibility with existing callers/tests;
+ * treat `getStats()` / `hitCount` / `topStatements` as the reliable surface,
+ * and don't rely on `compiled` holding an executable handle.
+ *
+ * Invalidation: entries expire via TTL (`options.ttl`, default 1 hour). Since
+ * that alone can serve stale-shaped results after schema changes made via raw
+ * DDL, `invalidateTable()` is provided to drop entries referencing a given
+ * table name on write (e.g. from a caller's insert/update/delete path); it is
+ * not auto-wired to every write in this codebase, but `QueryOptimizer.
+ * invalidateTableCache()` calls it alongside the query-result cache.
+ */
+export declare class PreparedStatementCache {
+    private dialect;
+    private cache;
+    private maxSize;
+    private ttl;
+    private normalizeSql;
+    private onCache?;
+    private onEvict?;
+    private logging;
+    private stats;
+    constructor(dialect: Dialect, options: PreparedStatementCacheOptions);
+    /**
+     * Get a cached prepared statement
+     */
+    get(sql: string, params?: any[]): CachedStatement | undefined;
+    /**
+     * Store a prepared statement in the cache
+     */
+    set(sql: string, compiled: any, params?: any[]): CachedStatement;
+    /**
+     * Record execution of a prepared statement
+     */
+    recordExecution(key: string, executionTime: number): void;
+    /**
+     * Check if a statement is cached
+     */
+    has(sql: string, params?: any[]): boolean;
+    /**
+     * Clear all cached statements
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get all cached statements
+     */
+    getAll(): CachedStatement[];
+    /**
+     * Generate a cache key from SQL and optional parameters
+     */
+    private generateKey;
+    /**
+     * Normalize SQL for consistent caching
+     */
+    private normalizeSQL;
+    /**
+     * Evict the oldest entry from cache
+     */
+    private evictOldest;
+    /**
+     * Evict a specific entry from cache
+     */
+    private evict;
+    /**
+     * Log a message if logging is enabled
+     */
+    private log;
+    /**
+     * Invalidate (remove) cache entries whose SQL references the given table.
+     * Intended to be called by write paths (INSERT/UPDATE/DELETE/DDL) so cached
+     * entries can't outlive schema/data changes for that table between TTL
+     * expirations. Not automatically wired into every write in this codebase -
+     * callers that write outside of `QueryOptimizer` should call this explicitly.
+     */
+    invalidateTable(tableName: string): number;
+    /**
+     * Remove expired entries
+     */
+    prune(): number;
+    /**
+     * Get cache size
+     */
+    get size(): number;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    size: number;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    totalExecutions: number;
+    evictions: number;
+    topStatements: Array<{
+        sql: string;
+        hits: number;
+        executions: number;
+        avgExecutionTime: number;
+    }>;
+}
+/**
+ * Query result cache for caching query results
+ */
+export declare class QueryResultCache {
+    private cache;
+    private maxSize;
+    private ttl;
+    private logging;
+    constructor(options?: {
+        maxSize?: number;
+        ttl?: number;
+        logging?: boolean;
+    });
+    /**
+     * Get cached query result
+     */
+    get(sql: string, params?: any[]): any | undefined;
+    /**
+     * Store a query result in cache
+     */
+    set(sql: string, params: any[], result: any): void;
+    /**
+     * Check if a query result is cached
+     */
+    has(sql: string, params?: any[]): boolean;
+    /**
+     * Invalidate cache for a specific table
+     */
+    invalidateTable(tableName: string): number;
+    /**
+     * Clear all cached results
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hitCount: number;
+    };
+    /**
+     * Generate a cache key
+     */
+    private generateKey;
+    /**
+     * Evict the oldest entry
+     */
+    private evictOldest;
+    /**
+     * Log a message
+     */
+    private log;
+}
+/**
+ * Create a prepared statement cache
+ */
+export declare function createPreparedStatementCache(dialect: Dialect, options?: PreparedStatementCacheOptions): PreparedStatementCache;
+declare const _default: {
+    PreparedStatementCache: typeof PreparedStatementCache;
+    QueryResultCache: typeof QueryResultCache;
+    createPreparedStatementCache: typeof createPreparedStatementCache;
+};
+export default _default;

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

@@ -0,0 +1,201 @@
+/**
+ * Query Hint Support
+ * Provides functionality to add database-specific query hints to optimize query execution
+ */
+import { Dialect } from '../dialects/dialect';
+/**
+ * Types of query hints supported
+ */
+export declare enum HintType {
+    /** Force use of a specific index */
+    FORCE_INDEX = "FORCE INDEX",
+    /** Suggest using a specific index */
+    USE_INDEX = "USE INDEX",
+    /** Ignore certain indexes */
+    IGNORE_INDEX = "IGNORE INDEX",
+    /** Force join order */
+    JOIN_FIXED_ORDER = "JOIN_FIXED_ORDER",
+    /** Force hash join */
+    MERGE_HASH = "MERGE_HASH",
+    /** Disable merge join */
+    NO_MERGE = "NO_MERGE",
+    /** Use nested loop join */
+    NESTED_LOOP = "NESTED_LOOP",
+    /** Maximum execution time in seconds */
+    MAX_EXECUTION_TIME = "MAX_EXECUTION_TIME",
+    /** SQL_BIG_RESULT hint */
+    SQL_BIG_RESULT = "SQL_BIG_RESULT",
+    /** SQL_SMALL_RESULT hint */
+    SQL_SMALL_RESULT = "SQL_SMALL_RESULT",
+    /** PostgreSQL: Sequential scan */
+    SEQ_SCAN = "SEQ_SCAN",
+    /** PostgreSQL: No sequential scan */
+    NO_SEQ_SCAN = "NO_SEQ_SCAN",
+    /** PostgreSQL: Index scan */
+    INDEX_SCAN = "INDEX_SCAN",
+    /** PostgreSQL: No index scan */
+    NO_INDEX_SCAN = "NO_INDEX_SCAN",
+    /** SQLite: Optimize query */
+    OPTIMIZE = "OPTIMIZE",
+    /** SQLite: Query plan */
+    QUERY_PLAN = "QUERY_PLAN",
+    /** SQL_BUFFER_RESULT hint */
+    SQL_BUFFER_RESULT = "SQL_BUFFER_RESULT",
+    /** SQL_CACHE hint (MySQL query cache) */
+    SQL_CACHE = "SQL_CACHE",
+    /** SQL_NO_CACHE hint */
+    SQL_NO_CACHE = "SQL_NO_CACHE",
+    /** Index merge hints */
+    INDEX_MERGE = "INDEX_MERGE",
+    /** Subquery optimization hints */
+    SUBQUERY = "SUBQUERY"
+}
+/**
+ * Query hint definition
+ */
+export interface QueryHint {
+    type: HintType | HintTypeExtended;
+    value?: string | string[] | number;
+    tableName?: string;
+}
+/**
+ * Standard index hint for MySQL/MariaDB
+ */
+export declare const INDEX_HINT: {
+    FORCE: (indexName: string, tableName?: string) => QueryHint;
+    USE: (indexName: string | string[], tableName?: string) => QueryHint;
+    IGNORE: (indexName: string | string[], tableName?: string) => QueryHint;
+};
+/**
+ * Predefined query hints
+ */
+export declare const FORCE_INDEX: (indexName: string, tableName?: string) => QueryHint;
+export declare const USE_INDEX: (indexName: string | string[], tableName?: string) => QueryHint;
+export declare const JOIN_FIXED_ORDER: QueryHint;
+export declare const MERGE_HASH: QueryHint;
+export declare const NO_MERGE: QueryHint;
+export declare const NESTED_LOOP: QueryHint;
+export declare const SQL_BIG_RESULT: QueryHint;
+export declare const SQL_SMALL_RESULT: QueryHint;
+export declare const SQL_BUFFER_RESULT: QueryHint;
+export declare const SQL_CACHE: QueryHint;
+export declare const SQL_NO_CACHE: QueryHint;
+/**
+ * Maximum execution time hint
+ */
+export declare const MAX_EXECUTION_TIME: (seconds: number) => QueryHint;
+/**
+ * Query hint manager for applying hints to SQL queries
+ */
+export declare class QueryHintManager {
+    private dialect;
+    private enabled;
+    constructor(dialect: Dialect, options?: {
+        enabled?: boolean;
+    });
+    /**
+     * Enable or disable query hints
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if hints are enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Apply query hints to a SQL query
+     * @param sql - The base SQL query
+     * @param hints - Array of query hints to apply
+     * @returns SQL with hints applied
+     */
+    applyHints(sql: string, hints: QueryHint[]): string;
+    /**
+     * Check if a hint is supported by the current dialect
+     */
+    private isHintSupported;
+    /**
+     * Build the hint comment string for the dialect
+     */
+    private buildHintComment;
+    /**
+     * Build MySQL/MariaDB hint comments
+     */
+    private buildMySQLHints;
+    /**
+     * Build PostgreSQL hint comments (using pg_hint_plan format)
+     */
+    private buildPostgresHints;
+    /**
+     * Build SQLite hint comments
+     */
+    private buildSQLiteHints;
+    /**
+     * Build Oracle hint comments (placed immediately after SELECT/INSERT/UPDATE/DELETE,
+     * same position as the MySQL/PostgreSQL comment hints).
+     * - USE_NL:    force a nested loop join
+     * - USE_HASH:  force a hash join
+     * - NO_MERGE:  Oracle's real NO_MERGE hint (prevents view merging); used here as
+     *              the closest real Oracle equivalent for "disable merge join"
+     */
+    private buildOracleHints;
+    /**
+     * Build a SQL Server `OPTION (...)` query hint clause, appended to the end of
+     * the statement (SQL Server does not support inline `/*+ ... *\/` comment hints).
+     * SQL Server doesn't expose a direct "disable merge join" hint, so NO_MERGE is
+     * approximated by restricting the optimizer to HASH JOIN and LOOP JOIN, which
+     * excludes merge join from consideration.
+     */
+    private buildMssqlOptionClause;
+    /**
+     * Create a hint for forcing index usage
+     */
+    forceIndex(indexName: string, tableName?: string): QueryHint;
+    /**
+     * Create a hint for suggesting index usage
+     */
+    useIndex(indexName: string | string[], tableName?: string): QueryHint;
+    /**
+     * Create a hint for ignoring certain indexes
+     */
+    ignoreIndex(indexName: string | string[], tableName?: string): QueryHint;
+    /**
+     * Create a hint for maximum execution time
+     */
+    maxExecutionTime(seconds: number): QueryHint;
+    /**
+     * Create a hint for SQL_BIG_RESULT
+     */
+    sqlBigResult(): QueryHint;
+    /**
+     * Create a hint for SQL_SMALL_RESULT
+     */
+    sqlSmallResult(): QueryHint;
+    /**
+     * Create a hint for SQL_NO_CACHE
+     */
+    sqlNoCache(): QueryHint;
+}
+export declare enum HintTypeExtended {
+    SEQ_SCAN = "SEQ_SCAN",
+    NO_SEQ_SCAN = "NO_SEQ_SCAN",
+    INDEX_SCAN = "INDEX_SCAN",
+    NO_INDEX_SCAN = "NO_INDEX_SCAN",
+    OPTIMIZE = "OPTIMIZE",
+    QUERY_PLAN = "QUERY_PLAN"
+}
+declare const _default: {
+    QueryHintManager: typeof QueryHintManager;
+    HintType: typeof HintType;
+    INDEX_HINT: {
+        FORCE: (indexName: string, tableName?: string) => QueryHint;
+        USE: (indexName: string | string[], tableName?: string) => QueryHint;
+        IGNORE: (indexName: string | string[], tableName?: string) => QueryHint;
+    };
+    FORCE_INDEX: (indexName: string, tableName?: string) => QueryHint;
+    USE_INDEX: (indexName: string | string[], tableName?: string) => QueryHint;
+    JOIN_FIXED_ORDER: QueryHint;
+    MERGE_HASH: QueryHint;
+    NO_MERGE: QueryHint;
+    NESTED_LOOP: QueryHint;
+    MAX_EXECUTION_TIME: (seconds: number) => QueryHint;
+};
+export default _default;