@zero-server/orm 0.9.1 → 0.9.3

package/lib/orm/profiler.js

@@ -0,0 +1,233 @@
+/**
+ * @module orm/profiler
+ * @description Query profiling, slow query detection, and automatic N+1 detection.
+ *              Attach to a Database instance via `db.enableProfiling()`.
+ *
+ * @example
+ *   const { Database, QueryProfiler } = require('@zero-server/sdk');
+ *
+ *   const db = Database.connect('memory');
+ *   const profiler = db.enableProfiling({ slowThreshold: 100 });
+ *
+ *   // ... run queries ...
+ *
+ *   console.log(profiler.metrics());
+ *   console.log(profiler.slowQueries());
+ *   console.log(profiler.n1Detections());
+ */
+
+const log = require('../debug')('zero:profiler');
+
+class QueryProfiler
+{
+    /**
+     * @constructor
+     * @param {object}   [options] - Configuration options.
+     * @param {boolean}  [options.enabled=true]       - Enable/disable profiling.
+     * @param {number}   [options.slowThreshold=100]  - Duration (ms) above which a query is "slow".
+     * @param {number}   [options.maxHistory=1000]    - Maximum recorded query entries.
+     * @param {Function} [options.onSlow]             - Callback on slow query: (entry) => {}.
+     * @param {number}   [options.n1Threshold=5]      - Minimum rapid same-table SELECTs to flag N+1.
+     * @param {number}   [options.n1Window=100]       - Time window (ms) for N+1 detection.
+     * @param {Function} [options.onN1]               - Callback on N+1 detection: (info) => {}.
+     */
+    constructor(options = {})
+    {
+        this._enabled = options.enabled !== false;
+        this._slowThreshold = Math.max(0, options.slowThreshold != null ? Number(options.slowThreshold) : 100);
+        this._maxHistory = Math.max(1, Math.floor(Number(options.maxHistory) || 1000));
+        this._onSlow = typeof options.onSlow === 'function' ? options.onSlow : null;
+
+        // N+1 detection
+        this._n1Threshold = Math.max(2, Math.floor(Number(options.n1Threshold) || 5));
+        this._n1Window = Math.max(10, Number(options.n1Window) || 100);
+        this._onN1 = typeof options.onN1 === 'function' ? options.onN1 : null;
+        this._maxN1History = Math.max(1, Math.floor(Number(options.maxN1History) || 100));
+        this._n1Detected = [];
+
+        // Per-table SELECT counters for O(1) N+1 detection
+        /** @private Map<table, { count, firstTs }> */
+        this._selectCounters = new Map();
+
+        // Query history
+        this._queries = [];
+
+        // Aggregate stats
+        this._totalQueries = 0;
+        this._totalTime = 0;
+        this._slowCount = 0;
+        this._startTime = Date.now();
+    }
+
+    /**
+     * Record a query execution.
+     *
+     * @param {object} entry - Profiler entry object.
+     * @param {string} entry.table    - Table name.
+     * @param {string} entry.action   - Query action (select, insert, update, delete, count).
+     * @param {number} entry.duration - Execution time in milliseconds.
+     */
+    record(entry)
+    {
+        if (!this._enabled) return;
+
+        // Sanitize
+        const record = {
+            table: String(entry.table || ''),
+            action: String(entry.action || 'unknown'),
+            duration: Number(entry.duration) || 0,
+            timestamp: Date.now(),
+        };
+
+        this._totalQueries++;
+        this._totalTime += record.duration;
+
+        // Enforce history limit (evict oldest)
+        if (this._queries.length >= this._maxHistory)
+        {
+            this._queries.shift();
+        }
+        this._queries.push(record);
+
+        // Slow query detection
+        if (record.duration > this._slowThreshold)
+        {
+            this._slowCount++;
+            log.warn('Slow query: %s %s (%dms)', record.action, record.table, Math.round(record.duration));
+            if (this._onSlow) this._onSlow(record);
+        }
+
+        // N+1 detection (only for SELECTs)
+        this._detectN1(record.table, record.action);
+    }
+
+    /**
+     * Detect potential N+1 query patterns.
+     * Uses per-table sliding window counters for O(1) detection instead of scanning history.
+     * @param {string} table - Table involved.
+     * @param {string} action - CRUD action performed.
+     * @private
+     */
+    _detectN1(table, action)
+    {
+        if (action !== 'select') return;
+
+        const now = Date.now();
+        let counter = this._selectCounters.get(table);
+
+        if (!counter || (now - counter.firstTs) >= this._n1Window)
+        {
+            // Window expired or first query — start a new window
+            counter = { count: 1, firstTs: now };
+            this._selectCounters.set(table, counter);
+            return;
+        }
+
+        counter.count++;
+
+        if (counter.count >= this._n1Threshold)
+        {
+            // Prevent duplicate detection for same burst
+            const last = this._n1Detected.find(d => d.table === table);
+            if (last && (now - last.timestamp) < this._n1Window) return;
+
+            const detection = {
+                table,
+                count: counter.count,
+                timestamp: now,
+                message: `Potential N+1: ${counter.count} SELECT queries to "${table}" in ${this._n1Window}ms`,
+            };
+            // Cap N+1 detection history to prevent memory exhaustion
+            if (this._n1Detected.length >= this._maxN1History)
+            {
+                this._n1Detected.shift();
+            }
+            this._n1Detected.push(detection);
+            log.warn(detection.message);
+            if (this._onN1) this._onN1(detection);
+        }
+    }
+
+    /**
+     * Get aggregate profiling metrics.
+     *
+     * @returns {{
+     *   totalQueries: number,
+     *   totalTime: number,
+     *   avgLatency: number,
+     *   queriesPerSecond: number,
+     *   slowQueries: number,
+     *   n1Detections: number,
+     * }}
+     */
+    metrics()
+    {
+        const elapsed = (Date.now() - this._startTime) / 1000 || 1;
+        return {
+            totalQueries: this._totalQueries,
+            totalTime: Math.round(this._totalTime * 100) / 100,
+            avgLatency: this._totalQueries > 0
+                ? Math.round((this._totalTime / this._totalQueries) * 100) / 100
+                : 0,
+            queriesPerSecond: Math.round((this._totalQueries / elapsed) * 100) / 100,
+            slowQueries: this._slowCount,
+            n1Detections: this._n1Detected.length,
+        };
+    }
+
+    /**
+     * Get all slow queries from history.
+     * @returns {Array<{ table: string, action: string, duration: number, timestamp: number }>}
+     */
+    slowQueries()
+    {
+        return this._queries.filter(q => q.duration > this._slowThreshold);
+    }
+
+    /**
+     * Get all N+1 detections.
+     * @returns {Array<{ table: string, count: number, timestamp: number, message: string }>}
+     */
+    n1Detections()
+    {
+        return [...this._n1Detected];
+    }
+
+    /**
+     * Get filtered query history.
+     *
+     * @param {object}  [options] - Configuration options.
+     * @param {string}  [options.table]       - Filter by table name.
+     * @param {string}  [options.action]      - Filter by action type.
+     * @param {number}  [options.minDuration] - Minimum duration filter.
+     * @returns {Array<{ table: string, action: string, duration: number, timestamp: number }>} Filtered query history entries.
+     */
+    getQueries(options = {})
+    {
+        let results = [...this._queries];
+        if (options.table) results = results.filter(q => q.table === options.table);
+        if (options.action) results = results.filter(q => q.action === options.action);
+        if (options.minDuration !== undefined) results = results.filter(q => q.duration >= options.minDuration);
+        return results;
+    }
+
+    /**
+     * Reset all profiling state.
+     */
+    reset()
+    {
+        this._queries = [];
+        this._totalQueries = 0;
+        this._totalTime = 0;
+        this._slowCount = 0;
+        this._startTime = Date.now();
+        this._n1Detected = [];
+        this._selectCounters.clear();
+    }
+
+    /** @type {boolean} */
+    get enabled() { return this._enabled; }
+    set enabled(val) { this._enabled = !!val; }
+}
+
+module.exports = { QueryProfiler };