turbine-orm 0.61.0 → 0.62.0

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

@@ -154,6 +154,29 @@ export declare const AUTO_TO_ONE_JOIN_ROWS_MAX = 100000;
  * it.
  */
 export declare const AUTO_COUNT_BATCH_MIN_PARENT_ROWS = 2;
+/**
+ * Bridge the nested-write engine's table handles onto the privilege sentinel.
+ *
+ * `nested-write.ts` clears a `set` relation by calling
+ * `updateMany({ where, data, allowFullTableScan: true })`: an INTERNAL,
+ * fully-derived predicate (the parent's own FK match, guarded there against a
+ * null reference key), not caller input, and the flag is what lets that
+ * unconditional-looking statement through the empty-`where` guard. Since
+ * `allowFullTableScan` now only accepts {@link UNSAFE}, that literal `true`
+ * would throw and every nested `set` would fail.
+ *
+ * Rather than hand the nested-write engine the sentinel (which would put the
+ * privilege value on a second, less obvious import path), the translation
+ * happens HERE, at the single seam where core hands it a table accessor. The
+ * rewrite is deliberately narrow: `updateMany` only, and only when the value is
+ * exactly `true`, so nothing else about the call is touched and no other
+ * operation gains an escape hatch.
+ *
+ * @internal Exported for its unit test; not part of the public surface.
+ */
+export declare function unlockNestedWriteTx<X extends {
+    table(name: string): Record<string, unknown>;
+}>(tx: X): X;
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, TemporalInfinityReading, } from './deferred.js';
 import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
 export declare class QueryInterface<T extends object, R extends object = {}> {
@@ -284,6 +307,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * `orderBy` all see it without threading it through dozens of signatures.
      * Only load-bearing when {@link globalFilters} is configured; build+collect are
      * synchronous per call, so this transient is never observed across an await.
+     *
+     * Holds the RESOLVED form ({@link ResolvedSkipGlobalFilters}), never the raw
+     * arg: every assignment goes through `resolveSkipGlobalFilters`, which is
+     * where a non-sentinel value (`true`, `['users']`, anything a JSON body can
+     * carry) is refused. Keeping the raw value here would push that decision out
+     * to each reader, and one reader forgetting it is the whole bug class.
      */
     private currentSkip;
     /**
@@ -927,6 +956,24 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     update(args: UpdateArgs<T, R>): Promise<T>;
     private nestedCreate;
     private nestedUpdate;
+    /**
+     * Check out a pooled connection, translating a driver failure into a typed
+     * Turbine error.
+     *
+     * `pool.connect()` is where the first-run failures land: wrong password
+     * (SQLSTATE 28P01), no such database (3D000), nothing listening
+     * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
+     * those surfaces from an ordinary `db.users.create({ data: { ...nested } })`
+     * as a raw pg `DatabaseError` whose `.code` is a SQLSTATE, on the same
+     * property Turbine puts `TURBINE_E0NN` in.
+     *
+     * client.ts has its own copy for `$transaction` / `connect()`; this one
+     * exists because `query/` must not import client.ts (circular dependency).
+     * The query paths need no equivalent: `pool.query()` opens the connection
+     * itself and rejects with the connect error, which the query boundary
+     * already wraps.
+     */
+    private acquireConnection;
     private runInImplicitTx;
     private buildNestedCtx;
     private makeTxProxy;

package/dist/cjs/query/builder.js

@@ -46,6 +46,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryInterface = exports.AUTO_COUNT_BATCH_MIN_PARENT_ROWS = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = void 0;
+exports.unlockNestedWriteTx = unlockNestedWriteTx;
 const dialect_js_1 = require("../dialect.js");
 const errors_js_1 = require("../errors.js");
 const index_advisor_js_1 = require("../index-advisor.js");
@@ -56,6 +57,7 @@ const batched_loader_js_1 = require("./batched-loader.js");
 const compound_unique_js_1 = require("./compound-unique.js");
 const filters_js_1 = require("./filters.js");
 const relationsMod = __importStar(require("./relations.js"));
+const types_js_1 = require("./types.js");
 const utils_js_1 = require("./utils.js");
 const warn_registry_js_1 = require("./warn-registry.js");
 const whereMod = __importStar(require("./where.js"));
@@ -336,6 +338,49 @@ function maybeExpandCompoundUnique(meta, args) {
     const expanded = (0, compound_unique_js_1.expandCompoundUniqueWhere)(meta, where);
     return expanded === where ? args : { ...args, where: expanded };
 }
+/**
+ * Bridge the nested-write engine's table handles onto the privilege sentinel.
+ *
+ * `nested-write.ts` clears a `set` relation by calling
+ * `updateMany({ where, data, allowFullTableScan: true })`: an INTERNAL,
+ * fully-derived predicate (the parent's own FK match, guarded there against a
+ * null reference key), not caller input, and the flag is what lets that
+ * unconditional-looking statement through the empty-`where` guard. Since
+ * `allowFullTableScan` now only accepts {@link UNSAFE}, that literal `true`
+ * would throw and every nested `set` would fail.
+ *
+ * Rather than hand the nested-write engine the sentinel (which would put the
+ * privilege value on a second, less obvious import path), the translation
+ * happens HERE, at the single seam where core hands it a table accessor. The
+ * rewrite is deliberately narrow: `updateMany` only, and only when the value is
+ * exactly `true`, so nothing else about the call is touched and no other
+ * operation gains an escape hatch.
+ *
+ * @internal Exported for its unit test; not part of the public surface.
+ */
+function unlockNestedWriteTx(tx) {
+    const wrapped = {
+        table(name) {
+            const handle = tx.table(name);
+            // A Proxy rather than a copied object: the handle is a class instance
+            // whose methods live on the prototype, so a spread would produce an
+            // object with no methods, and re-listing them by hand would silently
+            // drop any method added later.
+            return new Proxy(handle, {
+                get(target, prop) {
+                    const value = Reflect.get(target, prop, target);
+                    if (typeof value !== 'function')
+                        return value;
+                    const method = value;
+                    if (prop !== 'updateMany')
+                        return method.bind(target);
+                    return (args) => method.call(target, args?.allowFullTableScan === true ? { ...args, allowFullTableScan: types_js_1.UNSAFE } : args);
+                },
+            });
+        },
+    };
+    return wrapped;
+}
 /**
  * Whether a relation `with`-clause `orderBy` carries no actual ordering: an
  * empty array, or an object with no non-`undefined` own keys. Used by
@@ -480,6 +525,12 @@ class QueryInterface {
      * `orderBy` all see it without threading it through dozens of signatures.
      * Only load-bearing when {@link globalFilters} is configured; build+collect are
      * synchronous per call, so this transient is never observed across an await.
+     *
+     * Holds the RESOLVED form ({@link ResolvedSkipGlobalFilters}), never the raw
+     * arg: every assignment goes through `resolveSkipGlobalFilters`, which is
+     * where a non-sentinel value (`true`, `['users']`, anything a JSON body can
+     * carry) is refused. Keeping the raw value here would push that decision out
+     * to each reader, and one reader forgetting it is the whole bug class.
      */
     currentSkip;
     /**
@@ -1371,8 +1422,13 @@ class QueryInterface {
         // on the batched subset up front.
         (0, batched_loader_js_1.rejectNestedPickOrder)(batchedWith);
         const skip = args.skipGlobalFilters;
+        // Resolve the sentinel HERE, not just in buildFindMany below: this method
+        // decides the base projection before it ever builds SQL, so a literal
+        // `true` would otherwise shape the projection (truthily) and only be
+        // refused one step later.
+        const includePii = (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii');
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, batchedWith);
-        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, args.includePii));
+        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, includePii));
         const hasJoin = Object.keys(joinWith).length > 0;
         // Force the residual `with` onto the join plan so the base query never
         // re-enters this auto planning.
@@ -1392,7 +1448,7 @@ class QueryInterface {
             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, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
+                await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
             }
             (0, batched_loader_js_1.stripFields)(entities, proj.strip);
             return single ? (entities[0] ?? null) : entities;
@@ -1408,7 +1464,17 @@ 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, forceCustomPlan = false) {
+    batchedContext(timeout, skip, 
+    // BOTH privilege values stay in their RAW (sentinel) form here, and that is
+    // load-bearing rather than laziness: the batched loader re-enters
+    // `buildFindMany` one level down with these exact values on the child args,
+    // where they are resolved (and refused) again. Handing it a plain `true`
+    // would make every relation follow-up throw. The caller has already
+    // resolved them once for its own projection decisions, so an invalid value
+    // never reaches this point.
+    includePii, forceCustomPlan = false) {
+        // The loader's own global-filter callback below needs the RESOLVED form.
+        const resolvedSkip = (0, types_js_1.resolveSkipGlobalFilters)(skip);
         const childOptions = {
             ...this.options,
             defaultLimit: undefined,
@@ -1432,7 +1498,7 @@ class QueryInterface {
             // so a batched load excludes/includes PII exactly as the join strategy.
             includePii,
             tableGlobalFilter: (table, alias, precedingParams) => {
-                const gf = this.resolveGlobalFilter(table, skip);
+                const gf = this.resolveGlobalFilter(table, resolvedSkip);
                 if (!gf)
                     return null;
                 const meta = this.schema.tables[table];
@@ -1477,7 +1543,7 @@ class QueryInterface {
         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, args.forceCustomPlan === true), entities, withClause, args.timeout);
+            await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, withClause, args.timeout);
         }
         (0, batched_loader_js_1.stripFields)(entities, strip);
         return entities;
@@ -1489,7 +1555,7 @@ class QueryInterface {
      */
     prepareBatchedBase(args, withClause) {
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, withClause);
-        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, args.includePii));
+        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii')));
         const baseArgs = {
             ...args,
             with: undefined,
@@ -1862,20 +1928,20 @@ class QueryInterface {
         // Same scope-rule parity as runFindManyBatched: reject before querying.
         (0, batched_loader_js_1.rejectNestedPickOrder)(withClause);
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, withClause);
-        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, args.includePii));
+        const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, (0, types_js_1.resolveUnsafeFlag)(args.includePii, '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, 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, args.forceCustomPlan === true), [entity], withClause, args.timeout);
+        await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii, args.forceCustomPlan === true), [entity], withClause, args.timeout);
         (0, batched_loader_js_1.stripFields)([entity], proj.strip);
         return entity;
     }
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindUnique(args) {
-        this.currentSkip = args.skipGlobalFilters;
+        this.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
         // Prisma compound-unique selector expansion (before global-filter merge and
         // fingerprinting, so the cache only ever sees the canonical expanded where).
         args = maybeExpandCompoundUnique(this.tableMeta, args);
@@ -1910,7 +1976,8 @@ class QueryInterface {
             if (normalized !== args.with)
                 args = { ...args, with: normalized };
         }
-        const includePii = args.includePii === true;
+        // Resolved once, see buildFindMany.
+        const includePii = (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii');
         // findUnique is never flatten-planned: it reads ONE parent row, so the
         // correlated subquery already runs exactly once and a join buys nothing.
         // Say so, because the caller did ask for a strategy that is not running.
@@ -2021,7 +2088,7 @@ class QueryInterface {
         this.collectWhereParams(whereObj, params);
         this.collectWithParams(args.with, params);
         this.crossCheckCache('findUnique', ck, entry, buildSql, params);
-        const parseWith = this.makeNestedParser(args.with, args.includePii === true);
+        const parseWith = this.makeNestedParser(args.with, includePii);
         return {
             sql: entry.sql,
             params,
@@ -2213,7 +2280,7 @@ class QueryInterface {
     }
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindMany(args) {
-        this.currentSkip = args?.skipGlobalFilters;
+        this.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args?.skipGlobalFilters);
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations BEFORE fingerprinting, so the two orderings get distinct cache
         // entries and every downstream path (SQL build, collect, parser) inherits it.
@@ -2254,7 +2321,10 @@ class QueryInterface {
                 }
             }
         }
-        const includePii = args?.includePii === true;
+        // Resolve the PII opt-in ONCE, before any projection decision. The value is
+        // the UNSAFE sentinel or nothing: a literal `true` (what a spread request
+        // body carries) throws here rather than unlocking the projection.
+        const includePii = (0, types_js_1.resolveUnsafeFlag)(args?.includePii, 'includePii');
         const columnsList = this.resolveColumns(args?.select, args?.omit, includePii);
         const colKey = columnsList ? columnsList.join(',') : '*';
         // AND-merge this table's global filter into the user where; `hasWhere` gates
@@ -2505,9 +2575,14 @@ class QueryInterface {
         // function of the schema, the `with` shape and `includePii`, never of
         // `limit`, so the batch-size override the speculative fetch applies cannot
         // change it, and the stream's parser matches the emitted SQL.
-        const streamFlattenPlan = hasRelations ? this.planFlatten(args, args?.includePii === true) : null;
+        // Resolved once for the whole stream: the flatten plan and the row parser
+        // MUST agree with the SQL buildFindMany emits below, and reading the raw
+        // sentinel with `=== true` here would have quietly planned a no-PII parser
+        // over a with-PII statement.
+        const streamPii = (0, types_js_1.resolveUnsafeFlag)(args?.includePii, 'includePii');
+        const streamFlattenPlan = hasRelations ? this.planFlatten(args, streamPii) : null;
         const parseWith = hasRelations
-            ? this.makeNestedParser(args.with, args?.includePii === true, streamFlattenPlan)
+            ? this.makeNestedParser(args.with, streamPii, streamFlattenPlan)
             : null;
         // --- Speculative first fetch: try to satisfy the entire drain in one RTT ---
         const speculativeDeferred = this.buildFindMany({
@@ -2541,7 +2616,7 @@ class QueryInterface {
         // connection, so `pool.query` already IS that connection. The stream rides
         // on it, is never released here, and the dialect is told to emit no
         // transaction control of its own (`ambientTransaction`).
-        const client = this.txScoped ? null : await this.pool.connect();
+        const client = this.txScoped ? null : await this.acquireConnection();
         const conn = client ?? {
             query: async (text, values) => (await this.pool.query(text, values)),
         };
@@ -2723,8 +2798,33 @@ class QueryInterface {
             return result;
         });
     }
+    /**
+     * Check out a pooled connection, translating a driver failure into a typed
+     * Turbine error.
+     *
+     * `pool.connect()` is where the first-run failures land: wrong password
+     * (SQLSTATE 28P01), no such database (3D000), nothing listening
+     * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
+     * those surfaces from an ordinary `db.users.create({ data: { ...nested } })`
+     * as a raw pg `DatabaseError` whose `.code` is a SQLSTATE, on the same
+     * property Turbine puts `TURBINE_E0NN` in.
+     *
+     * client.ts has its own copy for `$transaction` / `connect()`; this one
+     * exists because `query/` must not import client.ts (circular dependency).
+     * The query paths need no equivalent: `pool.query()` opens the connection
+     * itself and rejects with the connect error, which the query boundary
+     * already wraps.
+     */
+    async acquireConnection() {
+        try {
+            return await this.pool.connect();
+        }
+        catch (err) {
+            throw (0, errors_js_1.wrapPgError)(err);
+        }
+    }
     async runInImplicitTx(fn) {
-        const client = await this.pool.connect();
+        const client = await this.acquireConnection();
         let began = false;
         try {
             await client.query(this.dialect.beginStatement());
@@ -2741,8 +2841,12 @@ class QueryInterface {
             // older-engine client falls back to the full capability set inside the
             // implicit transaction.
             this.pool);
-            // biome-ignore lint/suspicious/noExplicitAny: TransactionClient satisfies NestedWriteContext['tx'] at runtime
-            const ctx = { schema: this.schema, tx: tx, scopedConnect: this.scopedConnect };
+            const ctx = {
+                schema: this.schema,
+                // biome-ignore lint/suspicious/noExplicitAny: TransactionClient satisfies NestedWriteContext['tx'] at runtime
+                tx: unlockNestedWriteTx(tx),
+                scopedConnect: this.scopedConnect,
+            };
             const result = await fn(ctx);
             await client.query(this.dialect.commitStatement());
             return result;
@@ -2771,7 +2875,7 @@ class QueryInterface {
         const opts = { ...this.options, _txScoped: true };
         return {
             schema,
-            tx: this.makeTxProxy(pool, schema, middlewares, opts),
+            tx: unlockNestedWriteTx(this.makeTxProxy(pool, schema, middlewares, opts)),
         };
     }
     // biome-ignore lint/suspicious/noExplicitAny: bridges MiddlewareFn[] ↔ Middleware[] and QI ↔ NestedWriteContext type gap
@@ -2829,7 +2933,7 @@ class QueryInterface {
         });
     }
     buildCount(args) {
-        this.currentSkip = args?.skipGlobalFilters;
+        this.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args?.skipGlobalFilters);
         const effWhere = this.mergeGlobalFilter(args?.where);
         const hasWhere = effWhere !== undefined;
         const whereObj = (effWhere ?? {});

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

@@ -5,11 +5,13 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-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 { 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, ResolvedSkipGlobalFilters, 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 { PrivilegeOption, Unsafe } from './types.js';
+export { assertOrderDirection, resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.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,7 +7,7 @@
  * 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.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;
+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.UNSAFE = exports.resolveUnsafeFlag = exports.resolveSkipGlobalFilters = exports.assertOrderDirection = 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");
@@ -27,6 +27,12 @@ Object.defineProperty(exports, "optionKeysOfKind", { enumerable: true, get: func
 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; } });
+// The privilege sentinel: a runtime value, not a type (see types.ts).
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "assertOrderDirection", { enumerable: true, get: function () { return types_js_1.assertOrderDirection; } });
+Object.defineProperty(exports, "resolveSkipGlobalFilters", { enumerable: true, get: function () { return types_js_1.resolveSkipGlobalFilters; } });
+Object.defineProperty(exports, "resolveUnsafeFlag", { enumerable: true, get: function () { return types_js_1.resolveUnsafeFlag; } });
+Object.defineProperty(exports, "UNSAFE", { enumerable: true, get: function () { return types_js_1.UNSAFE; } });
 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

@@ -38,6 +38,17 @@
  * 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.
  *
+ * ## The privilege options
+ *
+ * `skipGlobalFilters`, `includePii` and `allowFullTableScan` are `'native'` and
+ * MUST stay that way. Their values are the `UNSAFE` sentinel (plus, for
+ * skipGlobalFilters, table ACCESSOR names, which the rule above explicitly
+ * allows), and forwarding them verbatim is what lets core be the single place
+ * that decides whether a value is a real opt-in. Hand-translating them here
+ * would mean a second copy of that decision, and a consumer's
+ * `includePii: true` would then be judged by whichever copy it happened to
+ * reach first.
+ *
  * @module
  */
 import type { AggregateArgs, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, UpdateArgs, UpdateManyArgs, UpsertArgs } from './types.js';

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

@@ -39,6 +39,17 @@
  * 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.
  *
+ * ## The privilege options
+ *
+ * `skipGlobalFilters`, `includePii` and `allowFullTableScan` are `'native'` and
+ * MUST stay that way. Their values are the `UNSAFE` sentinel (plus, for
+ * skipGlobalFilters, table ACCESSOR names, which the rule above explicitly
+ * allows), and forwarding them verbatim is what lets core be the single place
+ * that decides whether a value is a real opt-in. Hand-translating them here
+ * would mean a second copy of that decision, and a consumer's
+ * `includePii: true` would then be judged by whichever copy it happened to
+ * reach first.
+ *
  * @module
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -57,6 +68,8 @@ exports.FIND_UNIQUE_OPTIONS = {
     relationLoadStrategy: 'prisma',
     timeout: 'native',
     stableRelationOrder: 'native',
+    // Privilege options: forwarded verbatim, refused by core unless the value is
+    // the UNSAFE sentinel. See the note at the top of this file.
     skipGlobalFilters: 'native',
     includePii: 'native',
     forceCustomPlan: 'native',

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

@@ -59,6 +59,14 @@ export declare function collectRelationSubqueryParams(qi: BuilderCtx, relDef: Re
  * ORDER BY differs only in nulls placement, vector metric, or relation-count
  * vs relation-column never collide on one cached SQL string. Captures the
  * SQL-shaping bits (direction, nulls, metric, relation keys), never values.
+ *
+ * NOTE for the direction guard (see {@link assertOrderDirection}): every
+ * direction is embedded here BYTE-FOR-BYTE (`String(d)` for the plain form,
+ * `d.sort` / `d.direction` for the spec forms), never normalized to ASC/DESC.
+ * That is what lets the direction validation live on the BUILD side alone: a
+ * bad direction has a fingerprint no good direction can produce, so it can
+ * never be served by a warm cache entry whose build already validated. Do not
+ * "tidy" this into a normalized token.
  */
 export declare function orderByEntryFingerprint(qi: BuilderCtx, d: unknown, targetTable?: string): string;
 export declare function buildOrderBy(qi: BuilderCtx, orderBy: OrderByClause, params?: unknown[], lateralSink?: string[]): string;

package/dist/cjs/query/relations.js

@@ -94,6 +94,7 @@ const index_advisor_js_1 = require("../index-advisor.js");
 const schema_js_1 = require("../schema.js");
 const batched_loader_js_1 = require("./batched-loader.js");
 const filters_js_1 = require("./filters.js");
+const types_js_1 = require("./types.js");
 const utils_js_1 = require("./utils.js");
 const warn_registry_js_1 = require("./warn-registry.js");
 const whereMod = __importStar(require("./where.js"));
@@ -119,7 +120,7 @@ function resolveColumns(qi, select, omit, includePii) {
             .map(([k]) => qi.toColumn(k));
     }
     // Default / omit-only projection: PII-tagged columns are excluded unless the
-    // caller passed `includePii: true`. An empty set (untagged schema) keeps the
+    // caller opted in with `includePii: UNSAFE`. An empty set (untagged schema) keeps the
     // `null`/`*` fast path so the emitted SQL is byte-identical to before.
     const piiCols = includePii ? undefined : writesMod.piiColumns(qi, qi.tableMeta);
     const hasPii = piiCols !== undefined && piiCols.size > 0;
@@ -341,6 +342,14 @@ function collectRelationSubqueryParams(qi, relDef, spec, params, _parentRef, dep
  * ORDER BY differs only in nulls placement, vector metric, or relation-count
  * vs relation-column never collide on one cached SQL string. Captures the
  * SQL-shaping bits (direction, nulls, metric, relation keys), never values.
+ *
+ * NOTE for the direction guard (see {@link assertOrderDirection}): every
+ * direction is embedded here BYTE-FOR-BYTE (`String(d)` for the plain form,
+ * `d.sort` / `d.direction` for the spec forms), never normalized to ASC/DESC.
+ * That is what lets the direction validation live on the BUILD side alone: a
+ * bad direction has a fingerprint no good direction can produce, so it can
+ * never be served by a warm cache entry whose build already validated. Do not
+ * "tidy" this into a normalized token.
  */
 function orderByEntryFingerprint(qi, d, targetTable) {
     // Vector KNN ordering changes the emitted operator by metric and adds a
@@ -424,6 +433,7 @@ function buildOrderBy(qi, orderBy, params, lateralSink) {
             const rawColumn = qi.toColumn(key);
             const operator = whereMod.vectorOperator(qi, key, rawColumn, value.distance.metric);
             const placeholder = whereMod.pushVectorParam(qi, key, rawColumn, value.distance.to, params);
+            (0, types_js_1.assertDirectionToken)(value.distance.direction, `vector distance orderBy on "${key}"`);
             const safeDir = value.distance.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
             return `${qi.q(rawColumn)} ${operator} ${placeholder} ${safeDir}`;
         }
@@ -443,6 +453,10 @@ function buildOrderBy(qi, orderBy, params, lateralSink) {
             throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${qi.table}". ` +
                 `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
         }
+        // Refuse a direction that is neither asc nor desc. normalizeOrderBy is
+        // `=== 'desc' ? DESC : ASC`, so without this every typo sorted ASCENDING
+        // and returned a correct-looking page in the reverse order.
+        (0, types_js_1.assertOrderDirection)(value, `orderBy "${key}" on table "${qi.table}"`);
         const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
         return `${qi.toSqlColumn(key)} ${dir}${nullsSuffix(qi, nulls)}`;
     })
@@ -529,6 +543,7 @@ function buildJsonPathOrderEntry(qi, table, meta, field, spec, prefix, params) {
     params.push(whereMod.jsonPathParam(qi, spec.path));
     const extract = qi.dialect.buildJsonPathExtract(`${prefix}${qi.q(col)}`, qi.p(params.length));
     const lhs = spec.type === 'numeric' ? whereMod.castJsonNumeric(qi, extract) : extract;
+    (0, types_js_1.assertDirectionToken)(spec.direction, `JSON-path orderBy on "${field}"`);
     const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
     // Rows whose document lacks the path extract to NULL. Without a nulls
     // clause, Postgres DESC defaults to NULLS FIRST, which both diverges from
@@ -623,6 +638,7 @@ function buildChainedToOneOrderBy(qi, head, nextRelName, nextValue, params) {
         if (!currentMeta.allColumns.includes(snakeCol)) {
             throw new errors_js_1.ValidationError(`[turbine] Unknown column "${key}" in orderBy on relation "${path.join('.')}" (table "${currentMeta.name}").`);
         }
+        (0, types_js_1.assertOrderDirection)(entryValue, `orderBy on relation path "${path.join('.')}"`);
         const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(entryValue);
         let where = head.correlation;
         if (params) {
@@ -685,6 +701,7 @@ function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lateralSin
             throw new errors_js_1.ValidationError(`[turbine] orderBy on to-many relation "${relName}" only supports "_count" ` +
                 `or a pick-row ordering ({ pick, by }) (got: ${keys.join(', ') || '(empty)'}).`);
         }
+        (0, types_js_1.assertOrderDirection)(value._count, `orderBy { ${relName}: { _count } }`);
         const { dir } = (0, filters_js_1.normalizeOrderBy)(value._count);
         return `${buildRelationCountExpr(qi, relDef, parentRef, alias, params)} ${dir}`;
     }
@@ -722,6 +739,7 @@ function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lateralSin
                 : '';
             throw new errors_js_1.ValidationError(`[turbine] Unknown column "${col}" in orderBy on relation "${relName}" (table "${relDef.to}").${relationHint}`);
         }
+        (0, types_js_1.assertOrderDirection)(dirValue, `orderBy "${col}" on relation "${relName}"`);
         const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(dirValue);
         // Target's global filter applies here too, otherwise ordering keys off
         // a soft-deleted / other-tenant related row's value (matches the with
@@ -823,6 +841,7 @@ function buildRelationPickOrderBy(qi, relName, relDef, spec, alias, parentRef, p
     const targetMeta = qi.schema.tables[relDef.to];
     if (!targetMeta)
         throw new errors_js_1.RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+    (0, types_js_1.assertDirectionToken)(spec.direction, `pick-row orderBy on relation "${relName}"`);
     const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
     const limitOne = qi.buildPagination('1', undefined, true);
     // Parents with ZERO surviving related rows have no row to pick: the
@@ -957,6 +976,7 @@ function buildRelationOrderClause(qi, targetTable, targetMeta, alias, orderEntri
             return buildRelationOrderBy(qi, key, dirValue, `${alias}ord${relOrdCounter++}`, params, { meta: targetMeta, table: targetTable, parentRef: alias });
         }
         const col = resolveOrderByColumn(qi, targetTable, targetMeta, key);
+        (0, types_js_1.assertOrderDirection)(dirValue, `orderBy "${key}" in the \`with\` clause for "${targetTable}"`);
         const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(dirValue);
         return `${alias}.${qi.q(col)} ${dir}${nullsSuffix(qi, nulls)}`;
     })