linkgress-orm 0.4.69 → 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,7 +371,7 @@ 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;
         }
@@ -421,7 +440,11 @@ class QueryExecutor {
      * 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);
+        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
@@ -677,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
@@ -1548,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
@@ -2184,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);
         }
@@ -2200,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);
         }
@@ -2377,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 = [];