linkgress-orm 0.4.68 → 0.4.70

package/dist/entity/db-context.js

@@ -268,23 +268,33 @@ class QueryExecutor {
      * `.expectedExecutionTime()`. If the query runs longer than this,
      * `onQueryTakingTooLong` fires. `undefined` means use the context default.
      */
-    overrideExpectedMs) {
+    overrideExpectedMs, 
+    /**
+     * Per-query prepared-statement override set via `.withPreparedStatements()`.
+     * `undefined` means use the context's `preparedStatements` default.
+     */
+    overridePrepare) {
         this.client = client;
         this.options = options;
         this.overrideTimeoutMs = overrideTimeoutMs;
         this.overrideExpectedMs = overrideExpectedMs;
+        this.overridePrepare = overridePrepare;
     }
     /**
-     * Build the per-query execution options (binary protocol + timeout override),
-     * or `undefined` when neither is set so the driver takes its fast path.
+     * Build the per-query execution options (binary protocol, timeout override, prepared
+     * statement), or `undefined` when none is set so the driver takes its fast path.
+     * `execution` is a per-call override a caller passes when it knows the statement's
+     * text is unique to this call (see {@link QueryOptions.preparedStatements}).
      */
-    buildExecutionOptions() {
-        if (!this.options.useBinaryProtocol && this.overrideTimeoutMs === undefined) {
+    buildExecutionOptions(execution) {
+        const prepare = execution?.prepare ?? this.overridePrepare ?? this.options.preparedStatements;
+        if (!this.options.useBinaryProtocol && this.overrideTimeoutMs === undefined && prepare !== true) {
             return undefined;
         }
         return {
             useBinaryProtocol: this.options.useBinaryProtocol,
             timeoutMs: this.overrideTimeoutMs,
+            ...(prepare === true ? { prepare: true } : {}),
         };
     }
     /**
@@ -293,7 +303,7 @@ class QueryExecutor {
      * the derived executor. Used by `.withTimeout()` on the query builders.
      */
     withTimeout(timeoutMs) {
-        return new QueryExecutor(this.client, this.options, timeoutMs, this.overrideExpectedMs);
+        return new QueryExecutor(this.client, this.options, timeoutMs, this.overrideExpectedMs, this.overridePrepare);
     }
     /**
      * Return a new executor that flags this query as expected to finish within
@@ -301,7 +311,16 @@ class QueryExecutor {
      * `.expectedExecutionTime()` on the query builders.
      */
     withExpectedExecutionTime(expectedMs) {
-        return new QueryExecutor(this.client, this.options, this.overrideTimeoutMs, expectedMs);
+        return new QueryExecutor(this.client, this.options, this.overrideTimeoutMs, expectedMs, this.overridePrepare);
+    }
+    /**
+     * Return a new executor that runs its statements as named server-side prepared
+     * statements (`true`) or as unnamed statements (`false`), overriding the context's
+     * `preparedStatements` default. Used by `.withPreparedStatements()` on tables and
+     * accessors.
+     */
+    withPreparedStatements(prepare) {
+        return new QueryExecutor(this.client, this.options, this.overrideTimeoutMs, this.overrideExpectedMs, prepare);
     }
     /** Whether slow-query detection is active (a callback is configured). */
     get slowQueryEnabled() {
@@ -341,7 +360,7 @@ class QueryExecutor {
             fireSlowQueryCallback(callback, sql, params, duration, this.expectedExecutionMs, timing.stackHolder);
         }
     }
-    async query(sql, params) {
+    async query(sql, params, execution) {
         const logger = this.options.logger || defaultLogger;
         const timing = this.beginTiming();
         if (this.options.logQueries) {
@@ -352,14 +371,12 @@ class QueryExecutor {
             }
         }
         try {
-            const result = await this.client.query(sql, params, this.buildExecutionOptions());
+            const result = await this.client.query(sql, params, this.buildExecutionOptions(execution));
             this.finishTiming(timing, logger, sql, params);
             return result;
         }
         catch (error) {
-            if (this.options.logQueries) {
-                logger(`[SQL Error] ${error instanceof Error ? error.message : String(error)}`, 'error');
-            }
+            this.logFailure(logger, error, sql, params);
             throw error;
         }
     }
@@ -387,9 +404,7 @@ class QueryExecutor {
             return result;
         }
         catch (error) {
-            if (this.options.logQueries) {
-                logger(`[SQL Error] ${error instanceof Error ? error.message : String(error)}`, 'error');
-            }
+            this.logFailure(logger, error, sql);
             throw error;
         }
     }
@@ -416,12 +431,36 @@ class QueryExecutor {
             }
         }
         catch (error) {
-            if (this.options.logQueries) {
-                logger(`[SQL Error] ${error instanceof Error ? error.message : String(error)}`, 'error');
-            }
+            this.logFailure(logger, error, sql);
             throw error;
         }
     }
+    /**
+     * Whether these options call for an executor at all — any logging, failure reporting,
+     * timing or slow-query duty. A context without any of them talks to the client directly.
+     */
+    static isNeeded(options) {
+        return !!options && !!(options.logQueries
+            || options.logFailedQueries
+            || options.logExecutionTime
+            || options.onQueryTakingTooLong
+            || options.preparedStatements);
+    }
+    /**
+     * The `[SQL Error]` line for a failed statement: the driver's message, the statement text
+     * and — only while `logParameters` is on — the parameters. Gated on `logFailedQueries`,
+     * which defaults to `logQueries` (see {@link QueryOptions.logFailedQueries}).
+     */
+    logFailure(logger, error, sql, params) {
+        if (!(this.options.logFailedQueries ?? this.options.logQueries)) {
+            return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        const parameters = this.options.logParameters && params && params.length > 0
+            ? `\n[Parameters] ${JSON.stringify(params)}`
+            : '';
+        logger(`[SQL Error] ${message}\n${sql.trim()}${parameters}`, 'error');
+    }
     /**
      * Get the query options for this executor
      */
@@ -637,7 +676,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 || options.onQueryTakingTooLong) {
+        if (QueryExecutor.isNeeded(options)) {
             newExecutor = new QueryExecutor(this.client, {
                 ...options,
                 collectionStrategy: mergedStrategy,
@@ -661,6 +700,20 @@ class TableAccessor {
             : new QueryExecutor(this.client, undefined, timeoutMs);
         return new TableAccessor(this.tableBuilder, this.client, this.schemaRegistry, newExecutor, this.collectionStrategy);
     }
+    /**
+     * Run every query started from the returned accessor as a named server-side prepared
+     * statement (`true`) or as an unnamed statement (`false`), overriding the context's
+     * `preparedStatements` default. See {@link QueryOptions.preparedStatements}.
+     *
+     * @example
+     * await db.users.withPreparedStatements(false).where(u => gt(u.id, 0)).toList();
+     */
+    withPreparedStatements(prepare) {
+        const newExecutor = this.executor
+            ? this.executor.withPreparedStatements(prepare)
+            : new QueryExecutor(this.client, undefined, undefined, undefined, prepare);
+        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
@@ -984,7 +1037,7 @@ class DataContext {
         this.client = client;
         this.queryOptions = queryOptions;
         // Create executor if logging is enabled
-        if (queryOptions?.logQueries || queryOptions?.logExecutionTime || queryOptions?.onQueryTakingTooLong) {
+        if (QueryExecutor.isNeeded(queryOptions)) {
             this.executor = new QueryExecutor(client, queryOptions);
         }
         this.initializeSchema(schema);
@@ -1141,7 +1194,7 @@ class DataContext {
             : this.queryOptions;
         txContext.queryOptions = effectiveOptions;
         // Create executor for the transactional client if logging is enabled
-        if (effectiveOptions?.logQueries || effectiveOptions?.logExecutionTime || effectiveOptions?.onQueryTakingTooLong) {
+        if (QueryExecutor.isNeeded(effectiveOptions)) {
             txContext.executor = new QueryExecutor(txClient, effectiveOptions);
         }
         // Create fresh table accessors bound to the transactional client
@@ -1484,7 +1537,7 @@ class DbEntityTable {
         const mergedOptions = { ...originalOptions, ...options };
         // Create new executor if logging options are provided
         let newExecutor = originalContext.executor;
-        if (mergedOptions.logQueries || mergedOptions.logExecutionTime || mergedOptions.onQueryTakingTooLong) {
+        if (QueryExecutor.isNeeded(mergedOptions)) {
             newExecutor = new QueryExecutor(originalContext.client, mergedOptions);
         }
         // Create a proxy context that overrides queryOptions, executor, and getTable
@@ -1532,6 +1585,19 @@ class DbEntityTable {
     withTimeout(timeoutMs) {
         return this._deriveWithExecutor((current, client) => current ? current.withTimeout(timeoutMs) : new QueryExecutor(client, undefined, timeoutMs));
     }
+    /**
+     * Run every query and CRUD operation started from the returned table as a named
+     * server-side prepared statement (`true`) or as an unnamed statement (`false`),
+     * overriding the context's `preparedStatements` default. Use `false` to keep a wide
+     * analytical query on custom plans inside a prepared context, `true` to prepare a
+     * single hot lookup on an unprepared one. See {@link QueryOptions.preparedStatements}.
+     *
+     * @example
+     * await db.products.withPreparedStatements(false).where(p => eq(p.active, true)).toList();
+     */
+    withPreparedStatements(prepare) {
+        return this._deriveWithExecutor((current, client) => current ? current.withPreparedStatements(prepare) : new QueryExecutor(client, undefined, undefined, undefined, prepare));
+    }
     /**
      * Mark queries started from the returned table as expected to finish within
      * `expectedMs` (ms). If a query runs longer, the context's
@@ -2168,7 +2234,8 @@ ${parentSql}
                         '__iwc_parent__',
                     ]]),
             });
-            const result = executor ? await executor.query(built.sql, built.params) : await client.query(built.sql, built.params);
+            // Per-call VALUES list ⇒ unique text ⇒ never a prepared statement (see QueryOptions.preparedStatements).
+            const result = executor ? await executor.query(built.sql, built.params, { prepare: false }) : await client.query(built.sql, built.params);
             rawRows = result.rows;
             mapChildren = stripped => childTable.mapReturningResultsWithNavigation(stripped, navigationInfo.navigationFields, built.nestedPaths);
         }
@@ -2184,7 +2251,8 @@ RETURNING ${returningClause.sql}${pkExtra}
 SELECT "__mutation__".*, ${extraSelects.join(', ')}
 FROM "__mutation__"
 ${extraJoins.join('\n')}${orderBy}`;
-            const result = executor ? await executor.query(sql, params) : await client.query(sql, params);
+            // Per-call VALUES list ⇒ unique text ⇒ never a prepared statement (see QueryOptions.preparedStatements).
+            const result = executor ? await executor.query(sql, params, { prepare: false }) : await client.query(sql, params);
             rawRows = result.rows;
             mapChildren = stripped => childTable.mapReturningResults(stripped.map(({ __iwc_child_pk__: _pk, ...rest }) => rest), returningClause.aliasToProperty);
         }
@@ -2361,7 +2429,8 @@ SELECT "__mutation__".*, ${parentJoinSelects.join(', ')}
 FROM "__mutation__"
 JOIN "__ibwc_pord__" "__ibwc_pj__" ON "__ibwc_pj__"."${parentPkDbName}" = "__mutation__"."__ibwc_child_fk__"
 ORDER BY "__mutation__"."__ibwc_child_pk__"`;
-        const result = executor ? await executor.query(sql, params) : await client.query(sql, params);
+        // Per-call VALUES lists ⇒ unique text ⇒ never a prepared statement (see QueryOptions.preparedStatements).
+        const result = executor ? await executor.query(sql, params, { prepare: false }) : await client.query(sql, params);
         const rawRows = result.rows;
         const parentsByOrd = new Map();
         const strippedRows = [];