turbine-orm 0.55.0 → 0.57.0

package/dist/cjs/query/builder.d.ts

@@ -712,6 +712,51 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     resetUnlimitedWarnings(): void;
     private emitQueryEvent;
+    /**
+     * Resolve the prepared-statement name a read should execute under, honouring
+     * the per-query {@link FindManyArgs.forceCustomPlan} opt-in.
+     *
+     * `forceCustomPlan: true` returns `undefined`, which sends the statement
+     * UNNAMED. The mechanism is NOT "PostgreSQL treats an unnamed statement as a
+     * one-shot plan that never enters the plan cache": the backend builds and
+     * saves a `CachedPlanSource` for the unnamed statement too. It works because
+     * node-postgres only skips Parse for a statement it has already parsed BY
+     * NAME (`Query.hasBeenParsed` is `this.name && connection.parsedStatements[this.name]`),
+     * so an unnamed statement is re-Parsed on every execution, each Parse
+     * replaces the unnamed cached plan source with a fresh one whose custom-plan
+     * counter is zero, and the five-execution threshold that precedes promotion
+     * is never reached. Every execution is therefore planned with the real
+     * parameter values.
+     *
+     * No GUC is set, no `SET LOCAL` is emitted, no transaction is opened, and no
+     * extra round trip is added, which is exactly why the opt-in can be per query
+     * while the client-level `planCacheMode` (a connection parameter) cannot be.
+     *
+     * The refusal is deliberately here, at the one seam every read execution
+     * passes through, rather than in each build method: the flag changes NOTHING
+     * about the SQL text, so a build-time check would have had to be repeated in
+     * every builder and could still be bypassed by a hand-executed
+     * `DeferredQuery`.
+     *
+     * Engines whose dialect does not report {@link Dialect.supportsPlanCacheMode}
+     * throw {@link UnsupportedFeatureError} (E017): the flag names a PostgreSQL
+     * plan-cache guarantee, and an engine with no such cache cannot make it.
+     * The same flag left unset (or `false`) is accepted everywhere.
+     *
+     * THE ONE COMBINATION THAT IS REFUSED RATHER THAN HONOURED. A client-level
+     * `planCacheMode: 'force_generic_plan'` DEFEATS this option, and that was
+     * MEASURED rather than reasoned about: on PostgreSQL 16.14, five executions
+     * of one unnamed statement read 19,107 buffers with that setting in force and
+     * 55 buffers with the same connection set back to `auto`, against 19,107 for
+     * the named statement. So the setting governs the unnamed statement too, and
+     * withholding the name buys nothing against it. Accepting the flag there
+     * would report a guarantee the very next execution breaks, so the
+     * contradiction throws {@link ValidationError} (E003) naming both settings.
+     * Turbine can only see the setting IT applied: a `plan_cache_mode` installed
+     * by the caller's own `SET`, by `ALTER ROLE`, or by a pooler is invisible
+     * here and is not refused.
+     */
+    private preparedNameFor;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.

package/dist/cjs/query/builder.js

@@ -1388,11 +1388,11 @@ class QueryInterface {
             const deferred = single
                 ? this.buildFindUnique(baseArgs)
                 : this.buildFindMany(baseArgs);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             const rows = deferred.transform(result);
             const entities = single ? (rows ? [rows] : []) : rows;
             if (entities.length > 0) {
-                await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true), entities, batchedWith, args.timeout);
+                await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
             }
             (0, batched_loader_js_1.stripFields)(entities, proj.strip);
             return single ? (entities[0] ?? null) : entities;
@@ -1408,7 +1408,7 @@ class QueryInterface {
      * and unlimited-warnings silenced, a relation load must fetch every matching
      * child, and the per-relation `limit` is applied client-side by the loader.
      */
-    batchedContext(timeout, skip, includePii) {
+    batchedContext(timeout, skip, includePii, forceCustomPlan = false) {
         const childOptions = {
             ...this.options,
             defaultLimit: undefined,
@@ -1418,7 +1418,11 @@ class QueryInterface {
             parentMeta: this.tableMeta,
             schema: this.schema,
             makeChild: (table) => new QueryInterface(this.pool, table, this.schema, [], childOptions),
-            exec: (sql, params, preparedName) => this.queryWithTimeout(sql, params, timeout, preparedName),
+            // The per-query `forceCustomPlan` opt-in covers the relation follow-ups
+            // too: a batched load re-issues the SAME tenant-shaped predicate one
+            // level down, so leaving those named would keep exactly the plan-cache
+            // exposure the caller asked to be rid of.
+            exec: (sql, params, preparedName) => this.queryWithTimeout(sql, params, timeout, this.preparedNameFor({ forceCustomPlan }, preparedName)),
             quote: (name) => this.q(name),
             buildInClause: (expr, paramRef, negated) => this.inClause(expr, paramRef, negated),
             inClauseParam: (values) => this.inParam(values),
@@ -1470,10 +1474,10 @@ class QueryInterface {
         const { baseArgs, strip } = this.prepareBatchedBase(args, withClause);
         // baseArgs.with is always undefined here; the cast just bridges the R generic.
         const deferred = this.buildFindMany(baseArgs);
-        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
         const entities = deferred.transform(result);
         if (entities.length > 0) {
-            await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true), entities, withClause, args.timeout);
+            await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true, args.forceCustomPlan === true), entities, withClause, args.timeout);
         }
         (0, batched_loader_js_1.stripFields)(entities, strip);
         return entities;
@@ -1629,6 +1633,69 @@ class QueryInterface {
             // Listener errors must never crash a query
         }
     }
+    /**
+     * Resolve the prepared-statement name a read should execute under, honouring
+     * the per-query {@link FindManyArgs.forceCustomPlan} opt-in.
+     *
+     * `forceCustomPlan: true` returns `undefined`, which sends the statement
+     * UNNAMED. The mechanism is NOT "PostgreSQL treats an unnamed statement as a
+     * one-shot plan that never enters the plan cache": the backend builds and
+     * saves a `CachedPlanSource` for the unnamed statement too. It works because
+     * node-postgres only skips Parse for a statement it has already parsed BY
+     * NAME (`Query.hasBeenParsed` is `this.name && connection.parsedStatements[this.name]`),
+     * so an unnamed statement is re-Parsed on every execution, each Parse
+     * replaces the unnamed cached plan source with a fresh one whose custom-plan
+     * counter is zero, and the five-execution threshold that precedes promotion
+     * is never reached. Every execution is therefore planned with the real
+     * parameter values.
+     *
+     * No GUC is set, no `SET LOCAL` is emitted, no transaction is opened, and no
+     * extra round trip is added, which is exactly why the opt-in can be per query
+     * while the client-level `planCacheMode` (a connection parameter) cannot be.
+     *
+     * The refusal is deliberately here, at the one seam every read execution
+     * passes through, rather than in each build method: the flag changes NOTHING
+     * about the SQL text, so a build-time check would have had to be repeated in
+     * every builder and could still be bypassed by a hand-executed
+     * `DeferredQuery`.
+     *
+     * Engines whose dialect does not report {@link Dialect.supportsPlanCacheMode}
+     * throw {@link UnsupportedFeatureError} (E017): the flag names a PostgreSQL
+     * plan-cache guarantee, and an engine with no such cache cannot make it.
+     * The same flag left unset (or `false`) is accepted everywhere.
+     *
+     * THE ONE COMBINATION THAT IS REFUSED RATHER THAN HONOURED. A client-level
+     * `planCacheMode: 'force_generic_plan'` DEFEATS this option, and that was
+     * MEASURED rather than reasoned about: on PostgreSQL 16.14, five executions
+     * of one unnamed statement read 19,107 buffers with that setting in force and
+     * 55 buffers with the same connection set back to `auto`, against 19,107 for
+     * the named statement. So the setting governs the unnamed statement too, and
+     * withholding the name buys nothing against it. Accepting the flag there
+     * would report a guarantee the very next execution breaks, so the
+     * contradiction throws {@link ValidationError} (E003) naming both settings.
+     * Turbine can only see the setting IT applied: a `plan_cache_mode` installed
+     * by the caller's own `SET`, by `ALTER ROLE`, or by a pooler is invisible
+     * here and is not refused.
+     */
+    preparedNameFor(args, name) {
+        if (args?.forceCustomPlan !== true)
+            return name;
+        if (this.dialect.supportsPlanCacheMode !== true) {
+            throw new errors_js_1.UnsupportedFeatureError('The forceCustomPlan query option', this.dialect.name, 'Forcing a per-query custom plan means keeping the statement out of the PostgreSQL plan cache, and this ' +
+                'engine has no such cache to keep it out of. Remove the option, or set it only on PostgreSQL queries.');
+        }
+        if (this.options?.planCacheMode === 'force_generic_plan') {
+            throw new errors_js_1.ValidationError('[turbine] forceCustomPlan: true cannot be honoured on a client configured with ' +
+                "planCacheMode: 'force_generic_plan'. That setting is a connection parameter and it governs UNNAMED " +
+                'statements as well as named ones, so the mechanism this option uses (withholding the ' +
+                'prepared-statement name, so the driver re-parses the statement on every execution and it is planned ' +
+                'with its real values) is ' +
+                'overridden by it and the query would be planned generically anyway. Leave the client on the default ' +
+                '(`planCacheMode` unset, or `auto`) and force the custom plan per query: that is the combination that ' +
+                'expresses "custom here, auto there".');
+        }
+        return undefined;
+    }
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
@@ -1777,7 +1844,7 @@ class QueryInterface {
                 }
             }
             const deferred = this.buildFindUnique(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -1798,11 +1865,11 @@ class QueryInterface {
         const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, args.includePii));
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
         const deferred = this.buildFindUnique(baseArgs);
-        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
         const entity = deferred.transform(result);
         if (!entity)
             return null;
-        await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii === true), [entity], withClause, args.timeout);
+        await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii === true, args.forceCustomPlan === true), [entity], withClause, args.timeout);
         (0, batched_loader_js_1.stripFields)([entity], proj.strip);
         return entity;
     }
@@ -1973,7 +2040,7 @@ class QueryInterface {
                 }
             }
             const deferred = this.buildFindMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2424,7 +2491,13 @@ class QueryInterface {
             limit: batchSize + 1,
         });
         this.currentAction = 'findManyStream';
-        const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout);
+        // Streaming is ALREADY immune to the generic-plan cliff: the speculative
+        // fetch has never passed a prepared name, and the cursor path runs through
+        // DECLARE, so neither statement enters the plan cache. `preparedNameFor` is
+        // still called with no name so that `forceCustomPlan: true` is VALIDATED on
+        // an engine that cannot honour it here either, rather than being quietly
+        // satisfied by an accident of this code path.
+        const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout, this.preparedNameFor(args, undefined));
         if (speculativeResult.rows.length <= batchSize) {
             // Small drain, yield all rows and return, no cursor needed
             for (const row of speculativeResult.rows) {
@@ -2487,7 +2560,7 @@ class QueryInterface {
                 }
             }
             const deferred = this.buildFindFirst(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2512,7 +2585,7 @@ class QueryInterface {
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2542,7 +2615,7 @@ class QueryInterface {
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2727,7 +2800,7 @@ class QueryInterface {
     async count(args) {
         return this.executeWithMiddleware('count', (args ?? {}), async () => {
             const deferred = this.buildCount(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2771,7 +2844,7 @@ class QueryInterface {
     async groupBy(args) {
         return this.executeWithMiddleware('groupBy', args, async () => {
             const deferred = this.buildGroupBy(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2790,7 +2863,7 @@ class QueryInterface {
     async aggregate(args) {
         return this.executeWithMiddleware('aggregate', args, async () => {
             const deferred = this.buildAggregate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }

package/dist/cjs/query/deferred.d.ts

@@ -127,6 +127,15 @@ export interface QueryInterfaceOptions {
      * (serverless drivers may not support named statements).
      */
     preparedStatements?: boolean;
+    /**
+     * The client-level `plan_cache_mode` this interface's connections were opened
+     * with, forwarded from `TurbineConfig.planCacheMode` purely so the per-query
+     * `forceCustomPlan` option can REFUSE the one combination it cannot honour
+     * (`'force_generic_plan'`, see `preparedNameFor` in builder.ts). Nothing else
+     * reads it, and it is never emitted into SQL: the setting itself travels as a
+     * connection parameter, set by client.ts when it opens the pool.
+     */
+    planCacheMode?: 'auto' | 'force_custom_plan' | 'force_generic_plan';
     /**
      * Enable the SQL template cache. When true, repeated queries with the
      * same shape (same keys, operators, relations, different values) reuse

package/dist/cjs/query/index.d.ts

@@ -8,6 +8,8 @@
 export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, GroupByResult, HavingClause, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderByObject, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationPickBy, RelationPickOrderBy, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithOrderByObject, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
+export type { OptionKind, OptionTable } from './option-surface.js';
+export { AGGREGATE_OPTIONS, ALL_OPTION_TABLES, applyNativeOptions, COUNT_OPTIONS, CREATE_MANY_OPTIONS, CREATE_OPTIONS, DELETE_MANY_OPTIONS, DELETE_OPTIONS, FIND_MANY_OPTIONS, FIND_MANY_STREAM_OPTIONS, FIND_UNIQUE_OPTIONS, GROUP_BY_OPTIONS, optionKeysOfKind, UPDATE_MANY_OPTIONS, UPDATE_OPTIONS, UPSERT_OPTIONS, } from './option-surface.js';
 export type { SqlCacheEntry } from './utils.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, TemporalInfinityReading, } from './builder.js';

package/dist/cjs/query/index.js

@@ -7,9 +7,26 @@
  * former monolithic `import { … } from './query.js'`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryInterface = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = exports.AUTO_COUNT_BATCH_MIN_PARENT_ROWS = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.sqlToPreparedName = exports.quoteIdent = exports.OPERATOR_KEYS = exports.LRUCache = exports.fnv1a64Hex = exports.escSingleQuote = exports.escapeLike = exports.buildCorrelation = exports.postgresDialect = void 0;
+exports.QueryInterface = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = exports.AUTO_COUNT_BATCH_MIN_PARENT_ROWS = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.sqlToPreparedName = exports.quoteIdent = exports.OPERATOR_KEYS = exports.LRUCache = exports.fnv1a64Hex = exports.escSingleQuote = exports.escapeLike = exports.buildCorrelation = exports.UPSERT_OPTIONS = exports.UPDATE_OPTIONS = exports.UPDATE_MANY_OPTIONS = exports.optionKeysOfKind = exports.GROUP_BY_OPTIONS = exports.FIND_UNIQUE_OPTIONS = exports.FIND_MANY_STREAM_OPTIONS = exports.FIND_MANY_OPTIONS = exports.DELETE_OPTIONS = exports.DELETE_MANY_OPTIONS = exports.CREATE_OPTIONS = exports.CREATE_MANY_OPTIONS = exports.COUNT_OPTIONS = exports.applyNativeOptions = exports.ALL_OPTION_TABLES = exports.AGGREGATE_OPTIONS = exports.postgresDialect = void 0;
 var dialect_js_1 = require("../dialect.js");
 Object.defineProperty(exports, "postgresDialect", { enumerable: true, get: function () { return dialect_js_1.postgresDialect; } });
+var option_surface_js_1 = require("./option-surface.js");
+Object.defineProperty(exports, "AGGREGATE_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.AGGREGATE_OPTIONS; } });
+Object.defineProperty(exports, "ALL_OPTION_TABLES", { enumerable: true, get: function () { return option_surface_js_1.ALL_OPTION_TABLES; } });
+Object.defineProperty(exports, "applyNativeOptions", { enumerable: true, get: function () { return option_surface_js_1.applyNativeOptions; } });
+Object.defineProperty(exports, "COUNT_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.COUNT_OPTIONS; } });
+Object.defineProperty(exports, "CREATE_MANY_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.CREATE_MANY_OPTIONS; } });
+Object.defineProperty(exports, "CREATE_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.CREATE_OPTIONS; } });
+Object.defineProperty(exports, "DELETE_MANY_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.DELETE_MANY_OPTIONS; } });
+Object.defineProperty(exports, "DELETE_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.DELETE_OPTIONS; } });
+Object.defineProperty(exports, "FIND_MANY_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.FIND_MANY_OPTIONS; } });
+Object.defineProperty(exports, "FIND_MANY_STREAM_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.FIND_MANY_STREAM_OPTIONS; } });
+Object.defineProperty(exports, "FIND_UNIQUE_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.FIND_UNIQUE_OPTIONS; } });
+Object.defineProperty(exports, "GROUP_BY_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.GROUP_BY_OPTIONS; } });
+Object.defineProperty(exports, "optionKeysOfKind", { enumerable: true, get: function () { return option_surface_js_1.optionKeysOfKind; } });
+Object.defineProperty(exports, "UPDATE_MANY_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.UPDATE_MANY_OPTIONS; } });
+Object.defineProperty(exports, "UPDATE_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.UPDATE_OPTIONS; } });
+Object.defineProperty(exports, "UPSERT_OPTIONS", { enumerable: true, get: function () { return option_surface_js_1.UPSERT_OPTIONS; } });
 var utils_js_1 = require("./utils.js");
 Object.defineProperty(exports, "buildCorrelation", { enumerable: true, get: function () { return utils_js_1.buildCorrelation; } });
 Object.defineProperty(exports, "escapeLike", { enumerable: true, get: function () { return utils_js_1.escapeLike; } });

package/dist/cjs/query/option-surface.d.ts

@@ -0,0 +1,100 @@
+/**
+ * turbine-orm, the query-argument OPTION SURFACE as runtime data.
+ *
+ * ## Why this file exists
+ *
+ * TypeScript erases interfaces, so `FindManyArgs` does not exist at runtime and
+ * any layer that has to decide, key by key, what to do with an args object has
+ * to keep its own hand-written list. `turbine-orm/prisma-compat` is exactly
+ * such a layer: it builds a FRESH turbine args object out of Prisma-shaped
+ * input and copies over the keys it recognizes. Every time core gained a
+ * query-level option, that ad-hoc allowlist silently failed to gain it, and the
+ * option was accepted by the caller's type-checker and then dropped on the
+ * floor. There was no feedback of any kind: no error, no warning, no test.
+ *
+ * These tables are the fix. Each one is a `Record<keyof SomeArgs<Row>,
+ * OptionKind>`, the same mechanism `TURBINE_CONFIG_KEYS` (client.ts) uses for
+ * the client-config surface, and it binds the compiler in BOTH directions:
+ *
+ *   - add an option to an arg interface and this file stops compiling until a
+ *     human classifies it ("Property 'fooMode' is missing in type ..."), so an
+ *     option can no longer be stranded BY OMISSION;
+ *   - list a key here that is not on the interface and it fails as an excess
+ *     property, so a table can never drift into describing an option that does
+ *     not exist.
+ *
+ * It deliberately does NOT make "add the option in one place" sufficient: it
+ * makes the second edit a BUILD FAILURE rather than a silent drop. That trade is
+ * intentional. A passthrough-by-default translator would satisfy the shorter
+ * wording and be actively wrong, because two of the options below carry FIELD
+ * NAMES in their values (`optimisticLock.field`, `distinctOn.columns`), which a
+ * compat layer must rename before core ever sees them. Copying those blind
+ * works on a schema whose names happen to coincide and breaks on one that
+ * renames a column, i.e. it makes the failure mode depend on the schema.
+ *
+ * ## THE ONE RULE for classifying a new option
+ *
+ * Classify a key `'native'` ONLY when its value contains no field, relation,
+ * column, or model NAME. If the value names anything in the schema, it is
+ * `'prisma'`: a name-translating consumer has to walk it by hand.
+ *
+ * @module
+ */
+import type { AggregateArgs, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, UpdateArgs, UpdateManyArgs, UpsertArgs } from './types.js';
+/**
+ * How a name-translating consumer (today: `turbine-orm/prisma-compat`) must
+ * handle one key of a turbine query-arg interface.
+ *
+ * - `'prisma'`, the key is a Prisma concept too, or its VALUE carries names
+ *   that live in the caller's naming space. Translated by hand; NEVER copied
+ *   verbatim.
+ * - `'native'`, turbine-only and its value is opaque to naming (a boolean, a
+ *   number, a list of table names). Copied through untouched.
+ * - `'nativeAlias'`, the turbine SPELLING of a concept the caller's surface
+ *   already has under another name (`with`/`limit`/`offset` vs
+ *   `include`/`take`/`skip`). Refused, because forwarding it would collide with
+ *   the translated key and would carry turbine relation names into a call
+ *   written in the caller's names. The diagnostic names the right key instead.
+ * - `'internal'`, not reachable through the compat surface at all
+ *   (`batchSize` belongs to a streaming method compat does not expose), so it
+ *   is not part of any known set and passing it is reported as unknown.
+ */
+export type OptionKind = 'prisma' | 'native' | 'nativeAlias' | 'internal';
+/**
+ * The generic parameter the tables are instantiated at. `keyof FindManyArgs<T>`
+ * is the literal union of the DECLARED key names regardless of `T`, so a
+ * neutral row type keeps the tables stable and free of entity coupling.
+ */
+type Row = Record<string, unknown>;
+/** One option table: every declared key of one arg interface, classified. */
+export type OptionTable<A> = Readonly<Record<keyof A, OptionKind>>;
+export declare const FIND_UNIQUE_OPTIONS: OptionTable<FindUniqueArgs<Row>>;
+export declare const FIND_MANY_OPTIONS: OptionTable<FindManyArgs<Row>>;
+export declare const FIND_MANY_STREAM_OPTIONS: OptionTable<FindManyStreamArgs<Row>>;
+export declare const CREATE_OPTIONS: OptionTable<CreateArgs<Row>>;
+export declare const CREATE_MANY_OPTIONS: OptionTable<CreateManyArgs<Row>>;
+export declare const UPDATE_OPTIONS: OptionTable<UpdateArgs<Row>>;
+export declare const UPDATE_MANY_OPTIONS: OptionTable<UpdateManyArgs<Row>>;
+export declare const DELETE_OPTIONS: OptionTable<DeleteArgs<Row>>;
+export declare const DELETE_MANY_OPTIONS: OptionTable<DeleteManyArgs<Row>>;
+export declare const UPSERT_OPTIONS: OptionTable<UpsertArgs<Row>>;
+export declare const COUNT_OPTIONS: OptionTable<CountArgs<Row>>;
+export declare const AGGREGATE_OPTIONS: OptionTable<AggregateArgs<Row>>;
+export declare const GROUP_BY_OPTIONS: OptionTable<GroupByArgs<Row>>;
+/**
+ * Every table, so a test can assert the set is complete and well-formed without
+ * naming each one (a table stubbed out during a refactor shows up here).
+ */
+export declare const ALL_OPTION_TABLES: Readonly<Record<string, Readonly<Record<string, OptionKind>>>>;
+/**
+ * Copy every `'native'` key present on `src` onto `dst`.
+ *
+ * Iterates `src` (a small caller-supplied object) rather than the table, so the
+ * cost is proportional to what was actually passed. `undefined` values are
+ * skipped: `{ ...maybeOpts }` routinely materializes keys with no value, and
+ * writing `undefined` through would be indistinguishable from passing it.
+ */
+export declare function applyNativeOptions(table: Readonly<Record<string, OptionKind>>, src: Record<string, unknown>, dst: Record<string, unknown>): void;
+/** The keys of `table` with the given kind, as a set. */
+export declare function optionKeysOfKind(table: Readonly<Record<string, OptionKind>>, ...kinds: OptionKind[]): string[];
+export {};

package/dist/cjs/query/option-surface.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * turbine-orm, the query-argument OPTION SURFACE as runtime data.
+ *
+ * ## Why this file exists
+ *
+ * TypeScript erases interfaces, so `FindManyArgs` does not exist at runtime and
+ * any layer that has to decide, key by key, what to do with an args object has
+ * to keep its own hand-written list. `turbine-orm/prisma-compat` is exactly
+ * such a layer: it builds a FRESH turbine args object out of Prisma-shaped
+ * input and copies over the keys it recognizes. Every time core gained a
+ * query-level option, that ad-hoc allowlist silently failed to gain it, and the
+ * option was accepted by the caller's type-checker and then dropped on the
+ * floor. There was no feedback of any kind: no error, no warning, no test.
+ *
+ * These tables are the fix. Each one is a `Record<keyof SomeArgs<Row>,
+ * OptionKind>`, the same mechanism `TURBINE_CONFIG_KEYS` (client.ts) uses for
+ * the client-config surface, and it binds the compiler in BOTH directions:
+ *
+ *   - add an option to an arg interface and this file stops compiling until a
+ *     human classifies it ("Property 'fooMode' is missing in type ..."), so an
+ *     option can no longer be stranded BY OMISSION;
+ *   - list a key here that is not on the interface and it fails as an excess
+ *     property, so a table can never drift into describing an option that does
+ *     not exist.
+ *
+ * It deliberately does NOT make "add the option in one place" sufficient: it
+ * makes the second edit a BUILD FAILURE rather than a silent drop. That trade is
+ * intentional. A passthrough-by-default translator would satisfy the shorter
+ * wording and be actively wrong, because two of the options below carry FIELD
+ * NAMES in their values (`optimisticLock.field`, `distinctOn.columns`), which a
+ * compat layer must rename before core ever sees them. Copying those blind
+ * works on a schema whose names happen to coincide and breaks on one that
+ * renames a column, i.e. it makes the failure mode depend on the schema.
+ *
+ * ## THE ONE RULE for classifying a new option
+ *
+ * Classify a key `'native'` ONLY when its value contains no field, relation,
+ * column, or model NAME. If the value names anything in the schema, it is
+ * `'prisma'`: a name-translating consumer has to walk it by hand.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_OPTION_TABLES = exports.GROUP_BY_OPTIONS = exports.AGGREGATE_OPTIONS = exports.COUNT_OPTIONS = exports.UPSERT_OPTIONS = exports.DELETE_MANY_OPTIONS = exports.DELETE_OPTIONS = exports.UPDATE_MANY_OPTIONS = exports.UPDATE_OPTIONS = exports.CREATE_MANY_OPTIONS = exports.CREATE_OPTIONS = exports.FIND_MANY_STREAM_OPTIONS = exports.FIND_MANY_OPTIONS = exports.FIND_UNIQUE_OPTIONS = void 0;
+exports.applyNativeOptions = applyNativeOptions;
+exports.optionKeysOfKind = optionKeysOfKind;
+exports.FIND_UNIQUE_OPTIONS = {
+    where: 'prisma',
+    select: 'prisma',
+    omit: 'prisma',
+    // Prisma spells this `include`; forwarding `with` would collide with the
+    // translated projection and carry turbine relation names into a Prisma call.
+    with: 'nativeAlias',
+    // Same key on both surfaces, DIFFERENT value domains ('query' | 'join' vs
+    // 'join' | 'batched' | 'auto' | 'flatten'), so the value needs mapping.
+    relationLoadStrategy: 'prisma',
+    timeout: 'native',
+    stableRelationOrder: 'native',
+    skipGlobalFilters: 'native',
+    includePii: 'native',
+    forceCustomPlan: 'native',
+};
+exports.FIND_MANY_OPTIONS = {
+    where: 'prisma',
+    select: 'prisma',
+    omit: 'prisma',
+    orderBy: 'prisma',
+    cursor: 'prisma',
+    take: 'prisma',
+    distinct: 'prisma',
+    relationLoadStrategy: 'prisma',
+    with: 'nativeAlias',
+    limit: 'nativeAlias',
+    offset: 'nativeAlias',
+    timeout: 'native',
+    stableRelationOrder: 'native',
+    skipGlobalFilters: 'native',
+    warnOnUnlimited: 'native',
+    includePii: 'native',
+    forceCustomPlan: 'native',
+};
+exports.FIND_MANY_STREAM_OPTIONS = {
+    ...exports.FIND_MANY_OPTIONS,
+    // No streaming delegate exists on the compat surface, so this is not a known
+    // key there and passing it is reported rather than quietly ignored.
+    batchSize: 'internal',
+};
+exports.CREATE_OPTIONS = {
+    data: 'prisma',
+    timeout: 'native',
+};
+exports.CREATE_MANY_OPTIONS = {
+    data: 'prisma',
+    skipDuplicates: 'prisma',
+    timeout: 'native',
+};
+exports.UPDATE_OPTIONS = {
+    where: 'prisma',
+    data: 'prisma',
+    // `{ field, expected }`, and `field` is a FIELD NAME, so it has to be renamed
+    // into turbine's naming space rather than copied. See THE ONE RULE above.
+    optimisticLock: 'prisma',
+    timeout: 'native',
+    allowFullTableScan: 'native',
+    skipGlobalFilters: 'native',
+};
+exports.UPDATE_MANY_OPTIONS = {
+    where: 'prisma',
+    data: 'prisma',
+    timeout: 'native',
+    allowFullTableScan: 'native',
+    skipGlobalFilters: 'native',
+};
+exports.DELETE_OPTIONS = {
+    where: 'prisma',
+    timeout: 'native',
+    allowFullTableScan: 'native',
+    skipGlobalFilters: 'native',
+};
+exports.DELETE_MANY_OPTIONS = {
+    where: 'prisma',
+    timeout: 'native',
+    allowFullTableScan: 'native',
+    skipGlobalFilters: 'native',
+};
+exports.UPSERT_OPTIONS = {
+    where: 'prisma',
+    create: 'prisma',
+    update: 'prisma',
+    timeout: 'native',
+    skipGlobalFilters: 'native',
+};
+exports.COUNT_OPTIONS = {
+    where: 'prisma',
+    timeout: 'native',
+    skipGlobalFilters: 'native',
+    forceCustomPlan: 'native',
+};
+exports.AGGREGATE_OPTIONS = {
+    where: 'prisma',
+    _count: 'prisma',
+    _sum: 'prisma',
+    _avg: 'prisma',
+    _min: 'prisma',
+    _max: 'prisma',
+    timeout: 'native',
+    skipGlobalFilters: 'native',
+    includePii: 'native',
+    forceCustomPlan: 'native',
+};
+exports.GROUP_BY_OPTIONS = {
+    by: 'prisma',
+    where: 'prisma',
+    having: 'prisma',
+    orderBy: 'prisma',
+    _count: 'prisma',
+    _sum: 'prisma',
+    _avg: 'prisma',
+    _min: 'prisma',
+    _max: 'prisma',
+    // `{ columns, orderBy }`, both in FIELD-NAME space. See THE ONE RULE.
+    distinctOn: 'prisma',
+    limit: 'nativeAlias',
+    offset: 'nativeAlias',
+    timeout: 'native',
+    skipGlobalFilters: 'native',
+    includePii: 'native',
+    forceCustomPlan: 'native',
+};
+/**
+ * Every table, so a test can assert the set is complete and well-formed without
+ * naming each one (a table stubbed out during a refactor shows up here).
+ */
+exports.ALL_OPTION_TABLES = {
+    findUnique: exports.FIND_UNIQUE_OPTIONS,
+    findMany: exports.FIND_MANY_OPTIONS,
+    findManyStream: exports.FIND_MANY_STREAM_OPTIONS,
+    create: exports.CREATE_OPTIONS,
+    createMany: exports.CREATE_MANY_OPTIONS,
+    update: exports.UPDATE_OPTIONS,
+    updateMany: exports.UPDATE_MANY_OPTIONS,
+    delete: exports.DELETE_OPTIONS,
+    deleteMany: exports.DELETE_MANY_OPTIONS,
+    upsert: exports.UPSERT_OPTIONS,
+    count: exports.COUNT_OPTIONS,
+    aggregate: exports.AGGREGATE_OPTIONS,
+    groupBy: exports.GROUP_BY_OPTIONS,
+};
+/**
+ * Copy every `'native'` key present on `src` onto `dst`.
+ *
+ * Iterates `src` (a small caller-supplied object) rather than the table, so the
+ * cost is proportional to what was actually passed. `undefined` values are
+ * skipped: `{ ...maybeOpts }` routinely materializes keys with no value, and
+ * writing `undefined` through would be indistinguishable from passing it.
+ */
+function applyNativeOptions(table, src, dst) {
+    // Total on any input: a delegate whose args are optional can be called with
+    // none, and a diagnostic-adjacent helper must not be the thing that throws.
+    if (src === null || typeof src !== 'object')
+        return;
+    for (const key of Object.keys(src)) {
+        if (table[key] !== 'native')
+            continue;
+        const value = src[key];
+        if (value !== undefined)
+            dst[key] = value;
+    }
+}
+/** The keys of `table` with the given kind, as a set. */
+function optionKeysOfKind(table, ...kinds) {
+    return Object.keys(table).filter((k) => kinds.includes(table[k]));
+}