linkgress-orm 0.4.33 → 0.4.35

package/dist/entity/db-context.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DatabaseContext = exports.DbEntityTable = exports.EntityInsertBuilder = exports.DataContext = exports.TableAccessor = exports.InsertBuilder = exports.QueryExecutor = exports.TimeTracer = void 0;
+exports.defaultLogger = defaultLogger;
 const database_client_interface_1 = require("../database/database-client.interface");
 const entity_base_1 = require("./entity-base");
 const model_config_1 = require("./model-config");
@@ -9,6 +10,113 @@ const query_builder_1 = require("../query/query-builder");
 const db_schema_manager_1 = require("../migration/db-schema-manager");
 const sequence_builder_1 = require("../schema/sequence-builder");
 const sql_utils_1 = require("../query/sql-utils");
+/**
+ * Default logger used when no custom `logger` is provided. Routes by section to
+ * the appropriate console method.
+ */
+function defaultLogger(message, section) {
+    if (section === 'error') {
+        console.error(message);
+    }
+    else if (section === 'warn') {
+        console.warn(message);
+    }
+    else {
+        console.log(message);
+    }
+}
+/**
+ * Basenames (without extension) of the linkgress source files that can appear in
+ * a query's call stack between the public terminal method (`.toList()` etc.) and
+ * the user's code. Internal frames are stripped from {@link SlowQueryInfo.stack}
+ * by matching these file IDENTITIES — not an install path — so it works wherever
+ * the package lives (node_modules, a monorepo, ts-node/ts-jest, a global link).
+ */
+const LINKGRESS_INTERNAL_FILES = new Set([
+    'db-context',
+    'query-builder',
+    'grouped-query',
+    'union-builder',
+    'join-builder',
+    'future-query',
+    'prepared-query',
+]);
+/** Extract the source-file basename (without extension) from a V8 stack frame line. */
+function stackFrameFile(line) {
+    // Matches the "<file>:<line>:<col>" tail, e.g.
+    //   "    at SelectQueryBuilder.toList (C:\repo\src\query\query-builder.ts:2019:17)"
+    //   "    at /repo/dist/entity/db-context.js:574:22"
+    const match = line.match(/([^()\s]+):\d+:\d+\)?\s*$/);
+    if (!match)
+        return undefined;
+    const base = match[1].split(/[\\/]/).pop();
+    return base ? base.replace(/\.[cm]?[jt]s$/, '') : undefined;
+}
+/**
+ * Capture a stack-trace holder cheaply — the `.stack` string is only formatted
+ * on access, so this is paid for fully only when the query turns out slow. Call
+ * it from within the user's synchronous call chain (before awaiting), so the
+ * user's frames are present. Temporarily raises the capture depth so deep user
+ * frames survive the internal frames sitting above them.
+ */
+function captureStackHolder() {
+    const holder = {};
+    const previousLimit = Error.stackTraceLimit;
+    Error.stackTraceLimit = 50;
+    if (typeof Error.captureStackTrace === 'function') {
+        Error.captureStackTrace(holder, captureStackHolder);
+    }
+    else {
+        holder.stack = new Error().stack;
+    }
+    Error.stackTraceLimit = previousLimit;
+    return holder;
+}
+/**
+ * Turn a captured stack into the user-facing call stack: drop the leading run of
+ * linkgress-internal frames (identified by source-file basename, so it is robust
+ * to wherever the package is installed and catches anonymous internal closures
+ * too), leaving the user's terminal-method call site as the first frame. Falls
+ * back to all frames if filtering would leave nothing.
+ */
+function extractUserStack(holder) {
+    const raw = holder?.stack;
+    if (!raw)
+        return '';
+    const frames = raw.split('\n').filter(line => line.trim().startsWith('at '));
+    let i = 0;
+    while (i < frames.length) {
+        const file = stackFrameFile(frames[i]);
+        if (file && LINKGRESS_INTERNAL_FILES.has(file)) {
+            i++;
+        }
+        else {
+            break;
+        }
+    }
+    const userFrames = frames.slice(i);
+    return (userFrames.length > 0 ? userFrames : frames).join('\n');
+}
+/**
+ * Invoke the slow-query callback defensively: resolve the user stack lazily and
+ * swallow any error from the callback so a diagnostic notice can never break the
+ * query that triggered it.
+ */
+function fireSlowQueryCallback(callback, sql, params, durationMs, thresholdMs, stackHolder) {
+    let stack = '';
+    try {
+        stack = extractUserStack(stackHolder);
+    }
+    catch {
+        /* ignore stack-extraction failures */
+    }
+    try {
+        callback({ sql, params, durationMs, thresholdMs, stack });
+    }
+    catch {
+        /* swallow — the slow-query notice must never affect the query */
+    }
+}
 /**
  * Time tracer utility for measuring query phases
  */
@@ -107,28 +215,28 @@ class TimeTracer {
         if (!this.enabled)
             return;
         const trace = this.getTrace(rowCount);
-        const log = this.logger || console.log;
-        log('\n[Time Trace Summary]', 'debug');
-        log(`  Total: ${trace.totalMs.toFixed(2)}ms`, 'debug');
+        const log = this.logger || defaultLogger;
+        log('\n[Time Trace Summary]', 'timing');
+        log(`  Total: ${trace.totalMs.toFixed(2)}ms`, 'timing');
         if (trace.phases.queryBuild !== undefined) {
-            log(`  Query Build: ${trace.phases.queryBuild.toFixed(2)}ms`, 'debug');
+            log(`  Query Build: ${trace.phases.queryBuild.toFixed(2)}ms`, 'timing');
         }
         if (trace.phases.queryExecution !== undefined) {
-            log(`  Query Execution: ${trace.phases.queryExecution.toFixed(2)}ms`, 'debug');
+            log(`  Query Execution: ${trace.phases.queryExecution.toFixed(2)}ms`, 'timing');
         }
         if (trace.phases.resultProcessing !== undefined) {
-            log(`  Result Processing: ${trace.phases.resultProcessing.toFixed(2)}ms`, 'debug');
+            log(`  Result Processing: ${trace.phases.resultProcessing.toFixed(2)}ms`, 'timing');
         }
         if (rowCount !== undefined) {
-            log(`  Rows: ${rowCount}`, 'debug');
+            log(`  Rows: ${rowCount}`, 'timing');
         }
         // Log detailed entries if there are any significant operations
         const significantEntries = this.entries.filter(e => e.durationMs > 0.1);
         if (significantEntries.length > 0) {
-            log('\n[Detailed Trace]', 'debug');
+            log('\n[Detailed Trace]', 'timing');
             for (const entry of significantEntries) {
                 const details = entry.details ? ` (${JSON.stringify(entry.details)})` : '';
-                log(`  [${entry.phase}] ${entry.operation}: ${entry.durationMs.toFixed(2)}ms${details}`, 'debug');
+                log(`  [${entry.phase}] ${entry.operation}: ${entry.durationMs.toFixed(2)}ms${details}`, 'timing');
             }
         }
     }
@@ -138,30 +246,103 @@ exports.TimeTracer = TimeTracer;
  * Query executor with optional logging
  */
 class QueryExecutor {
-    constructor(client, options = {}) {
+    constructor(client, options = {}, 
+    /**
+     * Per-query timeout override (ms) set via `.withTimeout()`. Threaded down to
+     * the driver as `QueryExecutionOptions.timeoutMs`. `undefined` means no
+     * override (the connection-level default, if any, applies).
+     */
+    overrideTimeoutMs, 
+    /**
+     * Per-query "expected execution time" override (ms) set via
+     * `.expectedExecutionTime()`. If the query runs longer than this,
+     * `onQueryTakingTooLong` fires. `undefined` means use the context default.
+     */
+    overrideExpectedMs) {
         this.client = client;
         this.options = options;
+        this.overrideTimeoutMs = overrideTimeoutMs;
+        this.overrideExpectedMs = overrideExpectedMs;
+    }
+    /**
+     * Build the per-query execution options (binary protocol + timeout override),
+     * or `undefined` when neither is set so the driver takes its fast path.
+     */
+    buildExecutionOptions() {
+        if (!this.options.useBinaryProtocol && this.overrideTimeoutMs === undefined) {
+            return undefined;
+        }
+        return {
+            useBinaryProtocol: this.options.useBinaryProtocol,
+            timeoutMs: this.overrideTimeoutMs,
+        };
+    }
+    /**
+     * Return a new executor sharing this one's client and options but applying the
+     * given per-query timeout override (ms). Pass `0` to disable the timeout for
+     * the derived executor. Used by `.withTimeout()` on the query builders.
+     */
+    withTimeout(timeoutMs) {
+        return new QueryExecutor(this.client, this.options, timeoutMs, this.overrideExpectedMs);
+    }
+    /**
+     * Return a new executor that flags this query as expected to finish within
+     * `expectedMs` — if it runs longer, `onQueryTakingTooLong` fires. Used by
+     * `.expectedExecutionTime()` on the query builders.
+     */
+    withExpectedExecutionTime(expectedMs) {
+        return new QueryExecutor(this.client, this.options, this.overrideTimeoutMs, expectedMs);
+    }
+    /** Whether slow-query detection is active (a callback is configured). */
+    get slowQueryEnabled() {
+        return typeof this.options.onQueryTakingTooLong === 'function';
+    }
+    /** Effective "too long" threshold for the current query (ms). */
+    get expectedExecutionMs() {
+        return this.overrideExpectedMs ?? this.options.longRunningQueryThreshold ?? 10000;
+    }
+    /**
+     * Begin timing/stack capture for a query. Returns `undefined` when neither
+     * execution-time logging nor slow-query detection is active (zero overhead).
+     * The stack is captured here — synchronously, inside the caller's call chain —
+     * so the slow-query callback can report the user's code, not an async frame.
+     */
+    beginTiming() {
+        if (!this.options.logExecutionTime && !this.slowQueryEnabled) {
+            return undefined;
+        }
+        const stackHolder = this.slowQueryEnabled ? captureStackHolder() : undefined;
+        return { startTime: performance.now(), stackHolder };
+    }
+    /**
+     * Finish timing: log execution time (if enabled) and fire the slow-query
+     * callback (if enabled and the expected threshold was exceeded).
+     */
+    finishTiming(timing, logger, sql, params) {
+        if (!timing)
+            return;
+        const duration = performance.now() - timing.startTime;
+        if (this.options.logExecutionTime) {
+            logger(`[Execution Time] ${duration.toFixed(2)}ms`, 'timing');
+        }
+        const callback = this.options.onQueryTakingTooLong;
+        if (callback && duration > this.expectedExecutionMs) {
+            fireSlowQueryCallback(callback, sql, params, duration, this.expectedExecutionMs, timing.stackHolder);
+        }
     }
     async query(sql, params) {
-        const logger = this.options.logger || console.log;
-        const startTime = this.options.logExecutionTime ? performance.now() : 0;
+        const logger = this.options.logger || defaultLogger;
+        const timing = this.beginTiming();
         if (this.options.logQueries) {
-            logger(`\n[SQL Query]`, 'debug');
-            logger(sql.trim(), 'debug');
+            logger(`\n[SQL Query]`, 'sql');
+            logger(sql.trim(), 'sql');
             if (this.options.logParameters && params && params.length > 0) {
-                logger(`[Parameters] ${JSON.stringify(params)}`, 'debug');
+                logger(`[Parameters] ${JSON.stringify(params)}`, 'params');
             }
         }
         try {
-            // Pass binary protocol option if enabled
-            const queryOptions = this.options.useBinaryProtocol
-                ? { useBinaryProtocol: true }
-                : undefined;
-            const result = await this.client.query(sql, params, queryOptions);
-            if (this.options.logExecutionTime) {
-                const duration = (performance.now() - startTime).toFixed(2);
-                logger(`[Execution Time] ${duration}ms`, 'debug');
-            }
+            const result = await this.client.query(sql, params, this.buildExecutionOptions());
+            this.finishTiming(timing, logger, sql, params);
             return result;
         }
         catch (error) {
@@ -176,31 +357,23 @@ class QueryExecutor {
      * Only available for clients that support it (e.g., PostgresClient)
      */
     async querySimple(sql) {
-        const logger = this.options.logger || console.log;
-        const startTime = this.options.logExecutionTime ? performance.now() : 0;
+        const logger = this.options.logger || defaultLogger;
+        const timing = this.beginTiming();
         if (this.options.logQueries) {
-            logger(`\n[SQL Query - Multi-Statement]`, 'debug');
-            logger(sql.trim(), 'debug');
+            logger(`\n[SQL Query - Multi-Statement]`, 'sql');
+            logger(sql.trim(), 'sql');
         }
         try {
-            // Check if client has querySimple method
+            let result;
             if ('querySimple' in this.client && typeof this.client.querySimple === 'function') {
-                const result = await this.client.querySimple(sql);
-                if (this.options.logExecutionTime) {
-                    const duration = (performance.now() - startTime).toFixed(2);
-                    logger(`[Execution Time] ${duration}ms`, 'debug');
-                }
-                return result;
+                result = await this.client.querySimple(sql);
             }
             else {
                 // Fallback to regular query
-                const result = await this.client.query(sql, []);
-                if (this.options.logExecutionTime) {
-                    const duration = (performance.now() - startTime).toFixed(2);
-                    logger(`[Execution Time] ${duration}ms`, 'debug');
-                }
-                return result;
+                result = await this.client.query(sql, []);
             }
+            this.finishTiming(timing, logger, sql);
+            return result;
         }
         catch (error) {
             if (this.options.logQueries) {
@@ -214,20 +387,17 @@ class QueryExecutor {
      * Only available for PostgresClient
      */
     async querySimpleMulti(sql) {
-        const logger = this.options.logger || console.log;
-        const startTime = this.options.logExecutionTime ? performance.now() : 0;
+        const logger = this.options.logger || defaultLogger;
+        const timing = this.beginTiming();
         if (this.options.logQueries) {
-            logger(`\n[SQL Query - Fully Optimized Multi-Statement]`, 'debug');
-            logger(sql.trim(), 'debug');
+            logger(`\n[SQL Query - Fully Optimized Multi-Statement]`, 'sql');
+            logger(sql.trim(), 'sql');
         }
         try {
             // Check if client has querySimpleMulti method
             if ('querySimpleMulti' in this.client && typeof this.client.querySimpleMulti === 'function') {
                 const results = await this.client.querySimpleMulti(sql);
-                if (this.options.logExecutionTime) {
-                    const duration = (performance.now() - startTime).toFixed(2);
-                    logger(`[Execution Time] ${duration}ms`, 'debug');
-                }
+                this.finishTiming(timing, logger, sql);
                 return results;
             }
             else {
@@ -456,7 +626,7 @@ class TableAccessor {
         const mergedStrategy = options.collectionStrategy ?? this.collectionStrategy;
         // Create new executor if logging options are provided
         let newExecutor = this.executor;
-        if (options.logQueries || options.logExecutionTime) {
+        if (options.logQueries || options.logExecutionTime || options.onQueryTakingTooLong) {
             newExecutor = new QueryExecutor(this.client, {
                 ...options,
                 collectionStrategy: mergedStrategy,
@@ -465,6 +635,33 @@ class TableAccessor {
         // Return new instance with updated options
         return new TableAccessor(this.tableBuilder, this.client, this.schemaRegistry, newExecutor, mergedStrategy);
     }
+    /**
+     * Set a per-query timeout (ms) applied to every query and CRUD operation
+     * started from the returned accessor. Each such query is wrapped individually
+     * (`SET LOCAL statement_timeout`); pass `0` to disable. Overrides the
+     * connection-level default. On timeout a `QueryTimeoutError` is thrown.
+     *
+     * @example
+     * await db.users.withTimeout(5000).where(u => gt(u.id, 0)).toList();
+     */
+    withTimeout(timeoutMs) {
+        const newExecutor = this.executor
+            ? this.executor.withTimeout(timeoutMs)
+            : new QueryExecutor(this.client, undefined, timeoutMs);
+        return new TableAccessor(this.tableBuilder, this.client, this.schemaRegistry, newExecutor, this.collectionStrategy);
+    }
+    /**
+     * Mark queries started from the returned accessor as expected to finish within
+     * `expectedMs` (ms). If a query runs longer, the context's
+     * `onQueryTakingTooLong` callback fires — the query is NOT cancelled (use
+     * `.withTimeout()` for that). Overrides the context's `longRunningQueryThreshold`.
+     */
+    expectedExecutionTime(expectedMs) {
+        const newExecutor = this.executor
+            ? this.executor.withExpectedExecutionTime(expectedMs)
+            : new QueryExecutor(this.client, undefined, undefined, expectedMs);
+        return new TableAccessor(this.tableBuilder, this.client, this.schemaRegistry, newExecutor, this.collectionStrategy);
+    }
     /**
      * Start a select query with automatic type inference
      * UnwrapSelection extracts the value types from SqlFragment<T> expressions
@@ -776,7 +973,7 @@ class DataContext {
         this.client = client;
         this.queryOptions = queryOptions;
         // Create executor if logging is enabled
-        if (queryOptions?.logQueries || queryOptions?.logExecutionTime) {
+        if (queryOptions?.logQueries || queryOptions?.logExecutionTime || queryOptions?.onQueryTakingTooLong) {
             this.executor = new QueryExecutor(client, queryOptions);
         }
         this.initializeSchema(schema);
@@ -853,12 +1050,26 @@ class DataContext {
      * Creates a scoped transactional context to avoid race conditions with concurrent transactions.
      * Each transaction gets its own isolated context instance with fresh table accessors.
      */
-    async transaction(fn) {
+    async transaction(fn, options) {
         return await this.client.transaction(async (queryFn) => {
             // Create a transactional client that routes all queries through the transaction
             const txClient = new database_client_interface_1.TransactionalClient(queryFn, this.client);
+            // Raise the per-statement timeout for the WHOLE transaction up-front. `SET LOCAL`
+            // is transaction-scoped (auto-resets at COMMIT/ROLLBACK) and applies to every
+            // subsequent statement — including bulk inserts/upserts that don't expose a
+            // per-query `.withTimeout()`. Clamp to a safe non-negative integer (it is
+            // inlined into the SQL); `0` disables the timeout for the transaction.
+            if (options?.timeoutMs !== undefined) {
+                const ms = Math.max(0, Math.floor(Number(options.timeoutMs) || 0));
+                await txClient.query(`SET LOCAL statement_timeout = ${ms}`);
+            }
+            // Within the transaction, raise the slow-query "expected" threshold so a
+            // deliberately long unit of work doesn't trip the global threshold. Defaults
+            // to the transaction timeout when not given explicitly.
+            const expectedMs = options?.expectedExecutionMs ?? options?.timeoutMs;
+            const optionsOverride = expectedMs !== undefined ? { longRunningQueryThreshold: expectedMs } : undefined;
             // Create an isolated transactional context instead of mutating this.client
-            const txContext = this.createTransactionalContext(txClient);
+            const txContext = this.createTransactionalContext(txClient, optionsOverride);
             return await fn(txContext);
         });
     }
@@ -867,22 +1078,27 @@ class DataContext {
      * Used internally for transaction isolation to prevent race conditions
      * when multiple transactions run concurrently.
      */
-    createTransactionalContext(txClient) {
+    createTransactionalContext(txClient, queryOptionsOverride) {
         // Create new instance preserving the prototype chain (including subclass methods/getters)
         const txContext = Object.create(Object.getPrototypeOf(this));
         // Set up the transactional client
         txContext.client = txClient;
         // Share read-only schema registry
         txContext.schemaRegistry = this.schemaRegistry;
-        txContext.queryOptions = this.queryOptions;
+        // Merge any per-transaction option override (e.g. a raised slow-query threshold)
+        // over the context's base options so the transaction's executor + accessors use it.
+        const effectiveOptions = queryOptionsOverride
+            ? { ...(this.queryOptions ?? {}), ...queryOptionsOverride }
+            : this.queryOptions;
+        txContext.queryOptions = effectiveOptions;
         // Create executor for the transactional client if logging is enabled
-        if (this.queryOptions?.logQueries || this.queryOptions?.logExecutionTime) {
-            txContext.executor = new QueryExecutor(txClient, this.queryOptions);
+        if (effectiveOptions?.logQueries || effectiveOptions?.logExecutionTime || effectiveOptions?.onQueryTakingTooLong) {
+            txContext.executor = new QueryExecutor(txClient, effectiveOptions);
         }
         // Create fresh table accessors bound to the transactional client
         txContext.tableAccessors = new Map();
         for (const [key, accessor] of this.tableAccessors) {
-            const newAccessor = new TableAccessor(accessor.tableBuilder, txClient, this.schemaRegistry, txContext.executor, this.queryOptions?.collectionStrategy);
+            const newAccessor = new TableAccessor(accessor.tableBuilder, txClient, this.schemaRegistry, txContext.executor, effectiveOptions?.collectionStrategy);
             txContext.tableAccessors.set(key, newAccessor);
             // Only attach as direct property if not a getter on the prototype
             // (DatabaseContext subclasses use getters like `get users()` that call this.table())
@@ -1219,7 +1435,7 @@ class DbEntityTable {
         const mergedOptions = { ...originalOptions, ...options };
         // Create new executor if logging options are provided
         let newExecutor = originalContext.executor;
-        if (mergedOptions.logQueries || mergedOptions.logExecutionTime) {
+        if (mergedOptions.logQueries || mergedOptions.logExecutionTime || mergedOptions.onQueryTakingTooLong) {
             newExecutor = new QueryExecutor(originalContext.client, mergedOptions);
         }
         // Create a proxy context that overrides queryOptions, executor, and getTable
@@ -1255,6 +1471,66 @@ class DbEntityTable {
         // Return new instance with proxy context
         return new DbEntityTable(proxyContext, this.tableName, this.tableBuilder);
     }
+    /**
+     * Set a per-query timeout (ms) applied to every query and CRUD operation
+     * started from the returned table. Each such query is wrapped individually
+     * (`SET LOCAL statement_timeout`); pass `0` to disable. Overrides the
+     * connection-level default. On timeout a `QueryTimeoutError` is thrown.
+     *
+     * @example
+     * await db.users.withTimeout(5000).where(u => gt(u.id, 0)).toList();
+     */
+    withTimeout(timeoutMs) {
+        return this._deriveWithExecutor((current, client) => current ? current.withTimeout(timeoutMs) : new QueryExecutor(client, undefined, timeoutMs));
+    }
+    /**
+     * Mark queries started from the returned table as expected to finish within
+     * `expectedMs` (ms). If a query runs longer, the context's
+     * `onQueryTakingTooLong` callback fires — the query is NOT cancelled (use
+     * `.withTimeout()` for that). Overrides the context's `longRunningQueryThreshold`.
+     *
+     * @example
+     * await db.users.expectedExecutionTime(2000).where(u => gt(u.id, 0)).toList();
+     */
+    expectedExecutionTime(expectedMs) {
+        return this._deriveWithExecutor((current, client) => current ? current.withExpectedExecutionTime(expectedMs) : new QueryExecutor(client, undefined, undefined, expectedMs));
+    }
+    /**
+     * Build a derived table whose context surfaces a transformed executor (via a
+     * proxy context, threaded into this table's accessor). Shared by
+     * `.withTimeout()` and `.expectedExecutionTime()`.
+     * @internal
+     */
+    _deriveWithExecutor(makeExecutor) {
+        const originalContext = this.context;
+        const tableName = this.tableName;
+        const client = originalContext.client;
+        const newExecutor = makeExecutor(originalContext.executor, client);
+        const collectionStrategy = originalContext.queryOptions?.collectionStrategy;
+        const proxyContext = new Proxy(originalContext, {
+            get(target, prop) {
+                if (prop === 'executor') {
+                    return newExecutor;
+                }
+                if (prop === 'getTable') {
+                    return (name) => {
+                        const originalAccessor = target.tableAccessors.get(name);
+                        if (!originalAccessor) {
+                            return target.getTable(name);
+                        }
+                        if (name === tableName) {
+                            const schemaRegistry = target.schemaRegistry;
+                            const originalTableBuilder = originalAccessor.tableBuilder;
+                            return new TableAccessor(originalTableBuilder, client, schemaRegistry, newExecutor, collectionStrategy);
+                        }
+                        return originalAccessor;
+                    };
+                }
+                return target[prop];
+            }
+        });
+        return new DbEntityTable(proxyContext, this.tableName, this.tableBuilder);
+    }
     /**
      * Select all records - returns full entities with unwrapped DbColumns
      */