ts-prorm-orm 1.1.0

package/dist/query-optimizers/query-hints.js

@@ -0,0 +1,438 @@
+"use strict";
+/**
+ * Query Hint Support
+ * Provides functionality to add database-specific query hints to optimize query execution
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HintTypeExtended = exports.QueryHintManager = exports.MAX_EXECUTION_TIME = exports.SQL_NO_CACHE = exports.SQL_CACHE = exports.SQL_BUFFER_RESULT = exports.SQL_SMALL_RESULT = exports.SQL_BIG_RESULT = exports.NESTED_LOOP = exports.NO_MERGE = exports.MERGE_HASH = exports.JOIN_FIXED_ORDER = exports.USE_INDEX = exports.FORCE_INDEX = exports.INDEX_HINT = exports.HintType = void 0;
+/**
+ * Types of query hints supported
+ */
+var HintType;
+(function (HintType) {
+    /** Force use of a specific index */
+    HintType["FORCE_INDEX"] = "FORCE INDEX";
+    /** Suggest using a specific index */
+    HintType["USE_INDEX"] = "USE INDEX";
+    /** Ignore certain indexes */
+    HintType["IGNORE_INDEX"] = "IGNORE INDEX";
+    /** Force join order */
+    HintType["JOIN_FIXED_ORDER"] = "JOIN_FIXED_ORDER";
+    /** Force hash join */
+    HintType["MERGE_HASH"] = "MERGE_HASH";
+    /** Disable merge join */
+    HintType["NO_MERGE"] = "NO_MERGE";
+    /** Use nested loop join */
+    HintType["NESTED_LOOP"] = "NESTED_LOOP";
+    /** Maximum execution time in seconds */
+    HintType["MAX_EXECUTION_TIME"] = "MAX_EXECUTION_TIME";
+    /** SQL_BIG_RESULT hint */
+    HintType["SQL_BIG_RESULT"] = "SQL_BIG_RESULT";
+    /** SQL_SMALL_RESULT hint */
+    HintType["SQL_SMALL_RESULT"] = "SQL_SMALL_RESULT";
+    /** PostgreSQL: Sequential scan */
+    HintType["SEQ_SCAN"] = "SEQ_SCAN";
+    /** PostgreSQL: No sequential scan */
+    HintType["NO_SEQ_SCAN"] = "NO_SEQ_SCAN";
+    /** PostgreSQL: Index scan */
+    HintType["INDEX_SCAN"] = "INDEX_SCAN";
+    /** PostgreSQL: No index scan */
+    HintType["NO_INDEX_SCAN"] = "NO_INDEX_SCAN";
+    /** SQLite: Optimize query */
+    HintType["OPTIMIZE"] = "OPTIMIZE";
+    /** SQLite: Query plan */
+    HintType["QUERY_PLAN"] = "QUERY_PLAN";
+    /** SQL_BUFFER_RESULT hint */
+    HintType["SQL_BUFFER_RESULT"] = "SQL_BUFFER_RESULT";
+    /** SQL_CACHE hint (MySQL query cache) */
+    HintType["SQL_CACHE"] = "SQL_CACHE";
+    /** SQL_NO_CACHE hint */
+    HintType["SQL_NO_CACHE"] = "SQL_NO_CACHE";
+    /** Index merge hints */
+    HintType["INDEX_MERGE"] = "INDEX_MERGE";
+    /** Subquery optimization hints */
+    HintType["SUBQUERY"] = "SUBQUERY";
+})(HintType || (exports.HintType = HintType = {}));
+/**
+ * Standard index hint for MySQL/MariaDB
+ */
+exports.INDEX_HINT = {
+    FORCE: (indexName, tableName) => ({
+        type: HintType.FORCE_INDEX,
+        value: indexName,
+        tableName,
+    }),
+    USE: (indexName, tableName) => ({
+        type: HintType.USE_INDEX,
+        value: indexName,
+        tableName,
+    }),
+    IGNORE: (indexName, tableName) => ({
+        type: HintType.IGNORE_INDEX,
+        value: indexName,
+        tableName,
+    }),
+};
+/**
+ * Predefined query hints
+ */
+exports.FORCE_INDEX = exports.INDEX_HINT.FORCE;
+exports.USE_INDEX = exports.INDEX_HINT.USE;
+exports.JOIN_FIXED_ORDER = { type: HintType.JOIN_FIXED_ORDER };
+exports.MERGE_HASH = { type: HintType.MERGE_HASH };
+exports.NO_MERGE = { type: HintType.NO_MERGE };
+exports.NESTED_LOOP = { type: HintType.NESTED_LOOP };
+exports.SQL_BIG_RESULT = { type: HintType.SQL_BIG_RESULT };
+exports.SQL_SMALL_RESULT = { type: HintType.SQL_SMALL_RESULT };
+exports.SQL_BUFFER_RESULT = { type: HintType.SQL_BUFFER_RESULT };
+exports.SQL_CACHE = { type: HintType.SQL_CACHE };
+exports.SQL_NO_CACHE = { type: HintType.SQL_NO_CACHE };
+/**
+ * Maximum execution time hint
+ */
+const MAX_EXECUTION_TIME = (seconds) => ({
+    type: HintType.MAX_EXECUTION_TIME,
+    value: seconds,
+});
+exports.MAX_EXECUTION_TIME = MAX_EXECUTION_TIME;
+/**
+ * Query hint manager for applying hints to SQL queries
+ */
+class QueryHintManager {
+    constructor(dialect, options) {
+        this.enabled = true;
+        this.dialect = dialect;
+        this.enabled = options?.enabled ?? true;
+    }
+    /**
+     * Enable or disable query hints
+     */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    /**
+     * Check if hints are enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * 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, hints) {
+        if (!this.enabled || hints.length === 0) {
+            return sql;
+        }
+        const dialectName = this.dialect.name.toLowerCase();
+        // Filter hints based on dialect support
+        const applicableHints = hints.filter((hint) => this.isHintSupported(hint, dialectName));
+        if (applicableHints.length === 0) {
+            return sql;
+        }
+        // SQL Server doesn't support the `/*+ ... */` comment-hint syntax used by the
+        // other dialects here; join hints are expressed as an `OPTION (...)` clause
+        // appended to the very end of the statement instead.
+        if (dialectName === 'mssql') {
+            const optionClause = this.buildMssqlOptionClause(applicableHints);
+            return optionClause ? `${sql} ${optionClause}` : sql;
+        }
+        // Build the hint comment
+        const hintComment = this.buildHintComment(applicableHints, dialectName);
+        if (!hintComment) {
+            return sql;
+        }
+        // Insert hint after SELECT keyword
+        const selectMatch = sql.match(/^(\s*SELECT\s+)/i);
+        if (selectMatch) {
+            const insertPosition = selectMatch[1].length;
+            return sql.slice(0, insertPosition) + hintComment + ' ' + sql.slice(insertPosition);
+        }
+        // For non-SELECT queries, prepend as comment
+        return hintComment + ' ' + sql;
+    }
+    /**
+     * Check if a hint is supported by the current dialect
+     */
+    isHintSupported(hint, dialectName) {
+        const mysqlMariaHints = [
+            HintType.FORCE_INDEX,
+            HintType.USE_INDEX,
+            HintType.IGNORE_INDEX,
+            HintType.JOIN_FIXED_ORDER,
+            HintType.MAX_EXECUTION_TIME,
+            HintType.SQL_BIG_RESULT,
+            HintType.SQL_SMALL_RESULT,
+            HintType.SQL_BUFFER_RESULT,
+            HintType.SQL_CACHE,
+            HintType.SQL_NO_CACHE,
+            HintType.INDEX_MERGE,
+        ];
+        const postgresHints = [
+            HintType.MAX_EXECUTION_TIME,
+            HintTypeExtended.SEQ_SCAN,
+            HintTypeExtended.NO_SEQ_SCAN,
+            HintTypeExtended.INDEX_SCAN,
+            HintTypeExtended.NO_INDEX_SCAN,
+        ];
+        const sqliteHints = [HintTypeExtended.OPTIMIZE, HintTypeExtended.QUERY_PLAN];
+        // Oracle and SQL Server both have real optimizer hints for forcing/disabling
+        // specific join strategies (Oracle: USE_NL/USE_HASH/NO_MERGE hints; SQL Server:
+        // the LOOP/HASH/MERGE JOIN query hints via OPTION()). No other hint types in
+        // this file are implemented for these two dialects yet, so only these three
+        // are declared supported here rather than silently falling through to `false`
+        // for hints that are simply unimplemented and being misread as "unsupported".
+        const oracleHints = [HintType.NESTED_LOOP, HintType.MERGE_HASH, HintType.NO_MERGE];
+        const mssqlHints = [HintType.NESTED_LOOP, HintType.MERGE_HASH, HintType.NO_MERGE];
+        switch (dialectName) {
+            case 'mysql':
+            case 'mariadb':
+                return mysqlMariaHints.includes(hint.type);
+            case 'postgres':
+            case 'postgresql':
+                return postgresHints.includes(hint.type);
+            case 'sqlite':
+                return sqliteHints.includes(hint.type);
+            case 'oracle':
+                return oracleHints.includes(hint.type);
+            case 'mssql':
+                return mssqlHints.includes(hint.type);
+            default:
+                // Honest "no support" answer for any dialect not handled above (e.g.
+                // unknown/custom dialects), rather than an implicit gap.
+                return false;
+        }
+    }
+    /**
+     * Build the hint comment string for the dialect
+     */
+    buildHintComment(hints, dialectName) {
+        switch (dialectName) {
+            case 'mysql':
+            case 'mariadb':
+                return this.buildMySQLHints(hints);
+            case 'postgres':
+            case 'postgresql':
+                return this.buildPostgresHints(hints);
+            case 'sqlite':
+                return this.buildSQLiteHints(hints);
+            case 'oracle':
+                return this.buildOracleHints(hints);
+            default:
+                return '';
+        }
+    }
+    /**
+     * Build MySQL/MariaDB hint comments
+     */
+    buildMySQLHints(hints) {
+        const hintParts = [];
+        for (const hint of hints) {
+            switch (hint.type) {
+                case HintType.FORCE_INDEX:
+                case HintType.USE_INDEX:
+                case HintType.IGNORE_INDEX: {
+                    const indexList = Array.isArray(hint.value) ? hint.value.join(', ') : String(hint.value);
+                    const tableRef = hint.tableName ? ` ${this.dialect.quoteTable(hint.tableName)}` : '';
+                    hintParts.push(`${hint.type} (${indexList})${tableRef}`);
+                    break;
+                }
+                case HintType.JOIN_FIXED_ORDER:
+                    hintParts.push('JOIN_FIXED_ORDER()');
+                    break;
+                case HintType.MAX_EXECUTION_TIME:
+                    hintParts.push(`MAX_EXECUTION_TIME(${hint.value})`);
+                    break;
+                case HintType.SQL_BIG_RESULT:
+                    hintParts.push('SQL_BIG_RESULT()');
+                    break;
+                case HintType.SQL_SMALL_RESULT:
+                    hintParts.push('SQL_SMALL_RESULT()');
+                    break;
+                case HintType.SQL_BUFFER_RESULT:
+                    hintParts.push('SQL_BUFFER_RESULT()');
+                    break;
+                case HintType.SQL_CACHE:
+                    hintParts.push('SQL_CACHE()');
+                    break;
+                case HintType.SQL_NO_CACHE:
+                    hintParts.push('SQL_NO_CACHE()');
+                    break;
+                case HintType.INDEX_MERGE: {
+                    const indexList = Array.isArray(hint.value) ? hint.value.join(', ') : String(hint.value);
+                    hintParts.push(`INDEX_MERGE(${indexList})`);
+                    break;
+                }
+            }
+        }
+        return hintParts.length > 0 ? `/*+ ${hintParts.join(' ')} */` : '';
+    }
+    /**
+     * Build PostgreSQL hint comments (using pg_hint_plan format)
+     */
+    buildPostgresHints(hints) {
+        const hintParts = [];
+        for (const hint of hints) {
+            switch (hint.type) {
+                case HintType.MAX_EXECUTION_TIME:
+                    hintParts.push(`SET LOCAL statement_timeout = ${Number(hint.value) * 1000}`);
+                    break;
+                // PostgreSQL uses pg_hint_plan for other hints
+                // These would need pg_hint_plan extension installed
+                case HintTypeExtended.SEQ_SCAN:
+                    hintParts.push('SeqScan on');
+                    break;
+                case HintTypeExtended.NO_SEQ_SCAN:
+                    hintParts.push('SeqScan off');
+                    break;
+                case HintTypeExtended.INDEX_SCAN:
+                    hintParts.push('IndexScan on');
+                    break;
+                case HintTypeExtended.NO_INDEX_SCAN:
+                    hintParts.push('IndexScan off');
+                    break;
+            }
+        }
+        // PostgreSQL hints are in a different format
+        return hintParts.length > 0 ? `/*+ ${hintParts.join(' ')} */` : '';
+    }
+    /**
+     * Build SQLite hint comments
+     */
+    buildSQLiteHints(hints) {
+        const hintParts = [];
+        for (const hint of hints) {
+            switch (hint.type) {
+                case HintTypeExtended.OPTIMIZE:
+                    hintParts.push(`OPTIMIZE ${hint.value || ''}`);
+                    break;
+                case HintTypeExtended.QUERY_PLAN:
+                    hintParts.push('QUERY_PLAN');
+                    break;
+            }
+        }
+        return hintParts.length > 0 ? `/*+ ${hintParts.join(' ')} */` : '';
+    }
+    /**
+     * 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"
+     */
+    buildOracleHints(hints) {
+        const hintParts = [];
+        for (const hint of hints) {
+            switch (hint.type) {
+                case HintType.NESTED_LOOP:
+                    hintParts.push(hint.tableName ? `USE_NL(${hint.tableName})` : 'USE_NL');
+                    break;
+                case HintType.MERGE_HASH:
+                    hintParts.push(hint.tableName ? `USE_HASH(${hint.tableName})` : 'USE_HASH');
+                    break;
+                case HintType.NO_MERGE:
+                    hintParts.push(hint.tableName ? `NO_MERGE(${hint.tableName})` : 'NO_MERGE');
+                    break;
+            }
+        }
+        return hintParts.length > 0 ? `/*+ ${hintParts.join(' ')} */` : '';
+    }
+    /**
+     * 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.
+     */
+    buildMssqlOptionClause(hints) {
+        const optionParts = [];
+        const addOption = (option) => {
+            if (!optionParts.includes(option)) {
+                optionParts.push(option);
+            }
+        };
+        for (const hint of hints) {
+            switch (hint.type) {
+                case HintType.NESTED_LOOP:
+                    addOption('LOOP JOIN');
+                    break;
+                case HintType.MERGE_HASH:
+                    addOption('HASH JOIN');
+                    break;
+                case HintType.NO_MERGE:
+                    addOption('HASH JOIN');
+                    addOption('LOOP JOIN');
+                    break;
+            }
+        }
+        return optionParts.length > 0 ? `OPTION (${optionParts.join(', ')})` : '';
+    }
+    /**
+     * Create a hint for forcing index usage
+     */
+    forceIndex(indexName, tableName) {
+        return { type: HintType.FORCE_INDEX, value: indexName, tableName };
+    }
+    /**
+     * Create a hint for suggesting index usage
+     */
+    useIndex(indexName, tableName) {
+        return { type: HintType.USE_INDEX, value: indexName, tableName };
+    }
+    /**
+     * Create a hint for ignoring certain indexes
+     */
+    ignoreIndex(indexName, tableName) {
+        return { type: HintType.IGNORE_INDEX, value: indexName, tableName };
+    }
+    /**
+     * Create a hint for maximum execution time
+     */
+    maxExecutionTime(seconds) {
+        return { type: HintType.MAX_EXECUTION_TIME, value: seconds };
+    }
+    /**
+     * Create a hint for SQL_BIG_RESULT
+     */
+    sqlBigResult() {
+        return { type: HintType.SQL_BIG_RESULT };
+    }
+    /**
+     * Create a hint for SQL_SMALL_RESULT
+     */
+    sqlSmallResult() {
+        return { type: HintType.SQL_SMALL_RESULT };
+    }
+    /**
+     * Create a hint for SQL_NO_CACHE
+     */
+    sqlNoCache() {
+        return { type: HintType.SQL_NO_CACHE };
+    }
+}
+exports.QueryHintManager = QueryHintManager;
+// Add missing hint types for PostgreSQL
+var HintTypeExtended;
+(function (HintTypeExtended) {
+    HintTypeExtended["SEQ_SCAN"] = "SEQ_SCAN";
+    HintTypeExtended["NO_SEQ_SCAN"] = "NO_SEQ_SCAN";
+    HintTypeExtended["INDEX_SCAN"] = "INDEX_SCAN";
+    HintTypeExtended["NO_INDEX_SCAN"] = "NO_INDEX_SCAN";
+    HintTypeExtended["OPTIMIZE"] = "OPTIMIZE";
+    HintTypeExtended["QUERY_PLAN"] = "QUERY_PLAN";
+})(HintTypeExtended || (exports.HintTypeExtended = HintTypeExtended = {}));
+exports.default = {
+    QueryHintManager,
+    HintType,
+    INDEX_HINT: exports.INDEX_HINT,
+    FORCE_INDEX: exports.FORCE_INDEX,
+    USE_INDEX: exports.USE_INDEX,
+    JOIN_FIXED_ORDER: exports.JOIN_FIXED_ORDER,
+    MERGE_HASH: exports.MERGE_HASH,
+    NO_MERGE: exports.NO_MERGE,
+    NESTED_LOOP: exports.NESTED_LOOP,
+    MAX_EXECUTION_TIME: exports.MAX_EXECUTION_TIME,
+};