ts-prorm-orm 1.1.0

package/dist/query-optimizers/explain-plans.js

@@ -0,0 +1,415 @@
+"use strict";
+/**
+ * Explain Query Plans
+ * Provides functionality to analyze and explain SQL query execution plans
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplainPlanGenerator = exports.ExplainFormat = void 0;
+exports.createExplainPlanGenerator = createExplainPlanGenerator;
+/**
+ * Explain output format options
+ */
+var ExplainFormat;
+(function (ExplainFormat) {
+    ExplainFormat["TEXT"] = "text";
+    ExplainFormat["JSON"] = "json";
+    ExplainFormat["XML"] = "xml";
+    ExplainFormat["YAML"] = "yaml";
+    ExplainFormat["TREE"] = "tree";
+})(ExplainFormat || (exports.ExplainFormat = ExplainFormat = {}));
+/**
+ * Explain plan generator for different database dialects
+ */
+class ExplainPlanGenerator {
+    constructor(dialect, defaultOptions) {
+        this.dialect = dialect;
+        this.defaultOptions = {
+            format: ExplainFormat.TEXT,
+            analyze: false,
+            verbose: false,
+            ...defaultOptions,
+        };
+    }
+    /**
+     * Set default options for EXPLAIN queries
+     */
+    setDefaultOptions(options) {
+        this.defaultOptions = { ...this.defaultOptions, ...options };
+    }
+    /**
+     * Generate an explain plan for a SQL query
+     */
+    async explain(sql, options) {
+        const startTime = Date.now();
+        const mergedOptions = { ...this.defaultOptions, ...options };
+        // Build EXPLAIN statement based on dialect
+        const explainSql = this.buildExplainSql(sql, mergedOptions);
+        // Execute the explain query
+        const rawResults = await this.dialect.query(explainSql, { raw: true });
+        const duration = Date.now() - startTime;
+        // Parse the explain output
+        const parsedPlan = this.parseExplainOutput(rawResults, mergedOptions.format || ExplainFormat.TEXT);
+        return {
+            sql,
+            plan: rawResults,
+            rawResults,
+            duration,
+            dialect: this.dialect.name,
+            parsedPlan,
+        };
+    }
+    /**
+     * Build the appropriate EXPLAIN SQL statement for the dialect
+     */
+    buildExplainSql(sql, options) {
+        const dialectName = this.dialect.name.toLowerCase();
+        const format = options.format || ExplainFormat.TEXT;
+        switch (dialectName) {
+            case 'mysql':
+            case 'mariadb':
+                return this.buildMySQLExplain(sql, options);
+            case 'postgres':
+            case 'postgresql':
+                return this.buildPostgresExplain(sql, options);
+            case 'sqlite':
+                return this.buildSQLiteExplain(sql, options);
+            default:
+                return `EXPLAIN ${sql}`;
+        }
+    }
+    /**
+     * Build MySQL EXPLAIN statement
+     */
+    buildMySQLExplain(sql, options) {
+        let explain = 'EXPLAIN';
+        // Add options
+        if (options.analyze) {
+            explain += ' ANALYZE';
+        }
+        if (options.format === ExplainFormat.JSON) {
+            explain += ' FORMAT=JSON';
+        }
+        else if (options.format === ExplainFormat.TREE) {
+            explain += ' FORMAT=TREE';
+        }
+        // Add statement type if provided
+        if (options.type) {
+            explain += ` ${options.type}`;
+        }
+        return `${explain} ${sql}`;
+    }
+    /**
+     * Build PostgreSQL EXPLAIN statement
+     */
+    buildPostgresExplain(sql, options) {
+        let explain = 'EXPLAIN';
+        if (options.analyze) {
+            explain += ' ANALYZE';
+        }
+        if (options.buffers) {
+            explain += ' BUFFERS';
+        }
+        if (options.timing) {
+            explain += ' TIMING';
+        }
+        if (options.format === ExplainFormat.JSON) {
+            explain += ' (FORMAT JSON)';
+        }
+        else if (options.format === ExplainFormat.XML) {
+            explain += ' (FORMAT XML)';
+        }
+        else if (options.format === ExplainFormat.YAML) {
+            explain += ' (FORMAT YAML)';
+        }
+        return `${explain} ${sql}`;
+    }
+    /**
+     * Build SQLite EXPLAIN statement
+     */
+    buildSQLiteExplain(sql, _options) {
+        // SQLite has QUERY_PLAN and EXPLAIN
+        return `EXPLAIN QUERY PLAN ${sql}`;
+    }
+    /**
+     * Parse EXPLAIN output into structured format
+     */
+    parseExplainOutput(results, format) {
+        const rows = results.rows || [];
+        if (rows.length === 0) {
+            return [];
+        }
+        const dialectName = this.dialect.name.toLowerCase();
+        switch (dialectName) {
+            case 'mysql':
+            case 'mariadb':
+                return this.parseMySQLExplain(rows);
+            case 'postgres':
+            case 'postgresql':
+                return this.parsePostgresExplain(rows);
+            case 'sqlite':
+                return this.parseSQLiteExplain(rows);
+            default:
+                return this.parseGenericExplain(rows);
+        }
+    }
+    /**
+     * Parse MySQL EXPLAIN output
+     */
+    parseMySQLExplain(rows) {
+        return rows.map((row) => ({
+            operation: row.type || row.select_type || 'UNKNOWN',
+            table: row.table,
+            index: row.possible_keys,
+            rows: row.rows ? parseInt(String(row.rows), 10) : undefined,
+            cost: row.key_len ? parseInt(String(row.key_len), 10) : undefined,
+            details: {
+                selectId: row.id,
+                selectType: row.select_type,
+                key: row.key,
+                keyLength: row.key_len,
+                ref: row.ref,
+                extra: row.Extra,
+            },
+        }));
+    }
+    /**
+     * Parse PostgreSQL EXPLAIN output
+     */
+    parsePostgresExplain(rows) {
+        return rows.map((row) => {
+            // Check if it's a JSON format result
+            if (row.Plan) {
+                return this.parsePostgresPlanNode(row.Plan);
+            }
+            // Text format - parse the output
+            const planText = row['Query Plan'] || row.plan || row;
+            return {
+                operation: 'UNKNOWN',
+                details: { raw: planText },
+            };
+        });
+    }
+    /**
+     * Recursively parse PostgreSQL plan nodes
+     */
+    parsePostgresPlanNode(plan) {
+        const step = {
+            operation: plan.NodeType || 'OPERATION',
+            table: plan.RelationName,
+            index: plan.IndexName,
+            rows: plan.PlanRows ? parseInt(String(plan.PlanRows), 10) : undefined,
+            cost: plan.TotalCost ? parseFloat(String(plan.TotalCost)) : undefined,
+            details: {
+                startupCost: plan.StartupCost,
+                totalCost: plan.TotalCost,
+                planWidth: plan.PlanWidth,
+                actualStartupTime: plan.ActualStartupTime,
+                actualTotalTime: plan.ActualTotalTime,
+                actualRows: plan.ActualRows,
+                sharedHitBlocks: plan.SharedHitBlocks,
+                sharedReadBlocks: plan.SharedReadBlocks,
+            },
+        };
+        if (plan.Plans && plan.Plans.length > 0) {
+            step.children = plan.Plans.map((p) => this.parsePostgresPlanNode(p));
+        }
+        return step;
+    }
+    /**
+     * Parse SQLite EXPLAIN QUERY PLAN output
+     */
+    parseSQLiteExplain(rows) {
+        return rows.map((row) => {
+            // SQLite returns: id, order, from, detail
+            const detail = row.detail || row.DETAIL || '';
+            const operation = this.extractSQLiteOperation(detail);
+            const table = this.extractSQLiteTable(detail);
+            const index = this.extractSQLiteIndex(detail);
+            return {
+                operation,
+                table,
+                index,
+                details: { detail },
+            };
+        });
+    }
+    /**
+     * Extract operation type from SQLite detail
+     */
+    extractSQLiteOperation(detail) {
+        if (detail.includes('SCAN'))
+            return 'SCAN';
+        if (detail.includes('SEARCH'))
+            return 'SEARCH';
+        if (detail.includes('USING INDEX'))
+            return 'INDEX';
+        if (detail.includes('USING COVERING INDEX'))
+            return 'COVERING INDEX';
+        if (detail.includes('USING TEMP'))
+            return 'TEMP';
+        if (detail.includes('USING FILESORT'))
+            return 'FILESORT';
+        if (detail.includes('COMPOUND'))
+            return 'COMPOUND';
+        return 'OPERATION';
+    }
+    /**
+     * Extract table name from SQLite detail
+     */
+    extractSQLiteTable(detail) {
+        const match = detail.match(/(?:SCAN|SEARCH)\s+(\w+)/i);
+        return match ? match[1] : undefined;
+    }
+    /**
+     * Extract index name from SQLite detail
+     */
+    extractSQLiteIndex(detail) {
+        const match = detail.match(/USING\s+INDEX\s+(\w+)/i);
+        return match ? match[1] : undefined;
+    }
+    /**
+     * Generic explain output parser
+     */
+    parseGenericExplain(rows) {
+        return rows.map((row) => ({
+            operation: 'ROW',
+            details: { ...row },
+        }));
+    }
+    /**
+     * Analyze a query and provide optimization recommendations
+     */
+    async analyzeQuery(sql, options) {
+        const plan = await this.explain(sql, options);
+        const recommendations = this.generateRecommendations(plan);
+        return { plan, recommendations };
+    }
+    /**
+     * Generate optimization recommendations based on explain plan
+     */
+    generateRecommendations(plan) {
+        const recommendations = [];
+        const dialectName = plan.dialect.toLowerCase();
+        if (!plan.parsedPlan || plan.parsedPlan.length === 0) {
+            return recommendations;
+        }
+        switch (dialectName) {
+            case 'mysql':
+            case 'mariadb':
+                return this.generateMySQLRecommendations(plan.parsedPlan);
+            case 'postgres':
+            case 'postgresql':
+                return this.generatePostgresRecommendations(plan.parsedPlan);
+            case 'sqlite':
+                return this.generateSQLiteRecommendations(plan.parsedPlan);
+            default:
+                return recommendations;
+        }
+    }
+    /**
+     * Generate MySQL-specific recommendations
+     */
+    generateMySQLRecommendations(plan) {
+        const recommendations = [];
+        for (const step of plan) {
+            // Check for full table scans
+            if (step.operation === 'ALL' || step.details?.extra?.includes('Using where')) {
+                recommendations.push({
+                    type: 'INDEX',
+                    severity: 'HIGH',
+                    message: 'Full table scan detected. Consider adding an index.',
+                    table: step.table,
+                });
+            }
+            // Check for missing indexes on WHERE
+            if (step.details?.possible_keys === null && step.details?.key === null) {
+                recommendations.push({
+                    type: 'INDEX',
+                    severity: 'MEDIUM',
+                    message: 'No suitable index found for query conditions.',
+                    table: step.table,
+                });
+            }
+            // Check for filesort
+            if (step.details?.extra?.includes('Using filesort')) {
+                recommendations.push({
+                    type: 'OPTIMIZATION',
+                    severity: 'MEDIUM',
+                    message: 'Filesort detected. Consider adding an index on the ORDER BY column.',
+                    table: step.table,
+                });
+            }
+            // Check for temporary tables
+            if (step.details?.extra?.includes('Using temporary')) {
+                recommendations.push({
+                    type: 'OPTIMIZATION',
+                    severity: 'LOW',
+                    message: 'Temporary table used. Query may benefit from optimization.',
+                    table: step.table,
+                });
+            }
+        }
+        return recommendations;
+    }
+    /**
+     * Generate PostgreSQL-specific recommendations
+     */
+    generatePostgresRecommendations(plan) {
+        const recommendations = [];
+        const checkNode = (node) => {
+            // Check for sequential scans
+            if (node.operation === 'Seq Scan') {
+                recommendations.push({
+                    type: 'INDEX',
+                    severity: 'HIGH',
+                    message: 'Sequential scan detected on table.',
+                    table: node.table,
+                });
+            }
+            // Check for high row estimates
+            if (node.rows && node.rows > 10000) {
+                recommendations.push({
+                    type: 'OPTIMIZATION',
+                    severity: 'MEDIUM',
+                    message: `High row estimate (${node.rows}). Consider using an index.`,
+                    table: node.table,
+                });
+            }
+            // Check children
+            if (node.children) {
+                node.children.forEach(checkNode);
+            }
+        };
+        plan.forEach(checkNode);
+        return recommendations;
+    }
+    /**
+     * Generate SQLite-specific recommendations
+     */
+    generateSQLiteRecommendations(plan) {
+        const recommendations = [];
+        for (const step of plan) {
+            if (step.operation === 'SCAN') {
+                recommendations.push({
+                    type: 'INDEX',
+                    severity: 'HIGH',
+                    message: 'Full table scan detected.',
+                    table: step.table,
+                });
+            }
+        }
+        return recommendations;
+    }
+}
+exports.ExplainPlanGenerator = ExplainPlanGenerator;
+/**
+ * Create an ExplainPlanGenerator instance
+ */
+function createExplainPlanGenerator(dialect, options) {
+    return new ExplainPlanGenerator(dialect, options);
+}
+exports.default = {
+    ExplainPlanGenerator,
+    ExplainFormat,
+    createExplainPlanGenerator,
+};

package/dist/query-optimizers/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultOptimizerConfig = exports.createQueryOptimizer = exports.QueryOptimizer = exports.createPreparedStatementCache = exports.PreparedStatementCache = exports.optimizeBatchDelete = exports.optimizeBatchUpdate = exports.optimizeBatchInsert = exports.BatchQueryOptimizer = exports.createSlowQueryLogger = exports.SlowQueryLogger = exports.createExplainPlanGenerator = exports.ExplainFormat = exports.ExplainPlanGenerator = exports.NO_MERGE = exports.MERGE_HASH = exports.JOIN_FIXED_ORDER = exports.USE_INDEX = exports.FORCE_INDEX = exports.INDEX_HINT = exports.HintType = exports.QueryHintManager = void 0;
+var query_hints_1 = require("./query-hints");
+Object.defineProperty(exports, "QueryHintManager", { enumerable: true, get: function () { return query_hints_1.QueryHintManager; } });
+Object.defineProperty(exports, "HintType", { enumerable: true, get: function () { return query_hints_1.HintType; } });
+Object.defineProperty(exports, "INDEX_HINT", { enumerable: true, get: function () { return query_hints_1.INDEX_HINT; } });
+Object.defineProperty(exports, "FORCE_INDEX", { enumerable: true, get: function () { return query_hints_1.FORCE_INDEX; } });
+Object.defineProperty(exports, "USE_INDEX", { enumerable: true, get: function () { return query_hints_1.USE_INDEX; } });
+Object.defineProperty(exports, "JOIN_FIXED_ORDER", { enumerable: true, get: function () { return query_hints_1.JOIN_FIXED_ORDER; } });
+Object.defineProperty(exports, "MERGE_HASH", { enumerable: true, get: function () { return query_hints_1.MERGE_HASH; } });
+Object.defineProperty(exports, "NO_MERGE", { enumerable: true, get: function () { return query_hints_1.NO_MERGE; } });
+var explain_plans_1 = require("./explain-plans");
+Object.defineProperty(exports, "ExplainPlanGenerator", { enumerable: true, get: function () { return explain_plans_1.ExplainPlanGenerator; } });
+Object.defineProperty(exports, "ExplainFormat", { enumerable: true, get: function () { return explain_plans_1.ExplainFormat; } });
+Object.defineProperty(exports, "createExplainPlanGenerator", { enumerable: true, get: function () { return explain_plans_1.createExplainPlanGenerator; } });
+var slow_query_logger_1 = require("./slow-query-logger");
+Object.defineProperty(exports, "SlowQueryLogger", { enumerable: true, get: function () { return slow_query_logger_1.SlowQueryLogger; } });
+Object.defineProperty(exports, "createSlowQueryLogger", { enumerable: true, get: function () { return slow_query_logger_1.createSlowQueryLogger; } });
+var batch_optimizer_1 = require("./batch-optimizer");
+Object.defineProperty(exports, "BatchQueryOptimizer", { enumerable: true, get: function () { return batch_optimizer_1.BatchQueryOptimizer; } });
+Object.defineProperty(exports, "optimizeBatchInsert", { enumerable: true, get: function () { return batch_optimizer_1.optimizeBatchInsert; } });
+Object.defineProperty(exports, "optimizeBatchUpdate", { enumerable: true, get: function () { return batch_optimizer_1.optimizeBatchUpdate; } });
+Object.defineProperty(exports, "optimizeBatchDelete", { enumerable: true, get: function () { return batch_optimizer_1.optimizeBatchDelete; } });
+var prepared_statement_cache_1 = require("./prepared-statement-cache");
+Object.defineProperty(exports, "PreparedStatementCache", { enumerable: true, get: function () { return prepared_statement_cache_1.PreparedStatementCache; } });
+Object.defineProperty(exports, "createPreparedStatementCache", { enumerable: true, get: function () { return prepared_statement_cache_1.createPreparedStatementCache; } });
+var query_optimizer_1 = require("./query-optimizer");
+Object.defineProperty(exports, "QueryOptimizer", { enumerable: true, get: function () { return query_optimizer_1.QueryOptimizer; } });
+Object.defineProperty(exports, "createQueryOptimizer", { enumerable: true, get: function () { return query_optimizer_1.createQueryOptimizer; } });
+/**
+ * Default configuration for query optimizers
+ */
+exports.defaultOptimizerConfig = {
+    slowQueryThreshold: 1000, // ms
+    preparedStatementCacheSize: 500,
+    batchInsertChunkSize: 1000,
+    batchUpdateChunkSize: 500,
+    batchDeleteChunkSize: 500,
+    enableExplainPlans: process.env.NODE_ENV === 'development',
+    enableQueryHints: true,
+};