turbine-orm 0.60.1 → 0.62.0

package/dist/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/query/builder.js

@@ -20,6 +20,7 @@ import { defaultProjectionFields, includeKeysForBatching, loadRelationsBatched,
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import * as relationsMod from './relations.js';
+import { resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
 import { isTemporalInfinity, LRUCache, ownLookup, parseDbDate, resolveColumnName, sqlToPreparedName, unknownFieldMessage, } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
@@ -300,6 +301,49 @@ function maybeExpandCompoundUnique(meta, args) {
     const expanded = 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.
+ */
+export 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: 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
@@ -444,6 +488,12 @@ export 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;
     /**
@@ -1335,8 +1385,13 @@ export class QueryInterface {
         // on the batched subset up front.
         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 = resolveUnsafeFlag(args.includePii, 'includePii');
         const needed = neededParentKeyFields(this.tableMeta, batchedWith);
-        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, args.includePii));
+        const proj = includeKeysForBatching(args.select, args.omit, needed, 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.
@@ -1356,7 +1411,7 @@ export class QueryInterface {
             const rows = deferred.transform(result);
             const entities = single ? (rows ? [rows] : []) : rows;
             if (entities.length > 0) {
-                await loadRelationsBatched(this.batchedContext(args.timeout, skip, args.includePii === true, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
+                await loadRelationsBatched(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
             }
             stripFields(entities, proj.strip);
             return single ? (entities[0] ?? null) : entities;
@@ -1372,7 +1427,17 @@ export 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 = resolveSkipGlobalFilters(skip);
         const childOptions = {
             ...this.options,
             defaultLimit: undefined,
@@ -1396,7 +1461,7 @@ export 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];
@@ -1441,7 +1506,7 @@ export 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 loadRelationsBatched(this.batchedContext(args.timeout, skip, args.includePii === true, args.forceCustomPlan === true), entities, withClause, args.timeout);
+            await loadRelationsBatched(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, withClause, args.timeout);
         }
         stripFields(entities, strip);
         return entities;
@@ -1453,7 +1518,7 @@ export class QueryInterface {
      */
     prepareBatchedBase(args, withClause) {
         const needed = neededParentKeyFields(this.tableMeta, withClause);
-        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, args.includePii));
+        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, resolveUnsafeFlag(args.includePii, 'includePii')));
         const baseArgs = {
             ...args,
             with: undefined,
@@ -1826,23 +1891,47 @@ export class QueryInterface {
         // Same scope-rule parity as runFindManyBatched: reject before querying.
         rejectNestedPickOrder(withClause);
         const needed = neededParentKeyFields(this.tableMeta, withClause);
-        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, args.includePii));
+        const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, 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 loadRelationsBatched(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii === true, args.forceCustomPlan === true), [entity], withClause, args.timeout);
+        await loadRelationsBatched(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii, args.forceCustomPlan === true), [entity], withClause, args.timeout);
         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 = 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);
+        // A findUnique whose `where` carries NO predicate must not run.
+        //
+        // `{ id: undefined }` is what `{ id: req.params.id }` becomes on a request
+        // that omitted the parameter, or on a typo'd one. Undefined keys are dropped
+        // downstream, so that used to emit `SELECT … FROM t LIMIT 1`: no predicate,
+        // and the caller gets an ARBITRARY row where it asked for a specific one and
+        // would have handled `null`. On an authorization check keyed by id that is a
+        // silent cross-record read, and `findUniqueOrThrow` made it worse by
+        // promising to throw when nothing matched and then returning a stranger's
+        // row instead.
+        //
+        // Checked against the USER's where, before the global-filter merge, and
+        // deliberately so: a tenant filter is not a unique selector, and letting it
+        // satisfy this would still hand back an arbitrary row from inside the tenant.
+        //
+        // `findFirst` is intentionally NOT guarded. "The first row matching an
+        // optional filter" is its whole contract and Prisma's `findFirst` behaves
+        // the same way; ask for one row by identity with `findUnique`.
+        if (whereMod.userPredicateIsEmpty(this.ctx, (args.where ?? {}))) {
+            throw new ValidationError(`[turbine] findUnique on "${this.table}" refused: the \`where\` clause has no predicate, ` +
+                'so this would return an arbitrary row rather than a specific one. ' +
+                'A key whose value is `undefined` does not count, check that the value you are looking up is defined. ' +
+                'If you meant "any row matching an optional filter", use `findFirst`.');
+        }
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations before fingerprinting (see buildFindMany).
         if (args.with && this.resolveStableOrder(args.stableRelationOrder)) {
@@ -1850,7 +1939,8 @@ export class QueryInterface {
             if (normalized !== args.with)
                 args = { ...args, with: normalized };
         }
-        const includePii = args.includePii === true;
+        // Resolved once, see buildFindMany.
+        const includePii = 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.
@@ -1961,7 +2051,7 @@ export 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,
@@ -2153,7 +2243,7 @@ export class QueryInterface {
     }
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindMany(args) {
-        this.currentSkip = args?.skipGlobalFilters;
+        this.currentSkip = 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.
@@ -2194,7 +2284,10 @@ export 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 = 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
@@ -2445,9 +2538,14 @@ export 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 = 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({
@@ -2481,7 +2579,7 @@ export 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)),
         };
@@ -2663,8 +2761,33 @@ export 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 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());
@@ -2681,8 +2804,12 @@ export 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;
@@ -2711,7 +2838,7 @@ export 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
@@ -2769,7 +2896,7 @@ export class QueryInterface {
         });
     }
     buildCount(args) {
-        this.currentSkip = args?.skipGlobalFilters;
+        this.currentSkip = resolveSkipGlobalFilters(args?.skipGlobalFilters);
         const effWhere = this.mergeGlobalFilter(args?.where);
         const hasWhere = effWhere !== undefined;
         const whereObj = (effWhere ?? {});

package/dist/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/query/index.js

@@ -7,5 +7,7 @@
  */
 export { postgresDialect } from '../dialect.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';
+// The privilege sentinel: a runtime value, not a type (see types.ts).
+export { assertOrderDirection, resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
 export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, } from './builder.js';

package/dist/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/query/option-surface.js

@@ -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
  */
 export const FIND_UNIQUE_OPTIONS = {
@@ -52,6 +63,8 @@ export const 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/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/query/relations.js

@@ -17,6 +17,7 @@ import { missingIndexForRelation } from '../index-advisor.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { resolveCountRelations } from './batched-loader.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
+import { assertDirectionToken, assertOrderDirection } from './types.js';
 import { ownLookup } from './utils.js';
 import { hasWarnedOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
@@ -42,7 +43,7 @@ export 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;
@@ -264,6 +265,14 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
  * 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 function orderByEntryFingerprint(qi, d, targetTable) {
     // Vector KNN ordering changes the emitted operator by metric and adds a
@@ -347,6 +356,7 @@ export 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);
+            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}`;
         }
@@ -366,6 +376,10 @@ export function buildOrderBy(qi, orderBy, params, lateralSink) {
             throw new 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.
+        assertOrderDirection(value, `orderBy "${key}" on table "${qi.table}"`);
         const { dir, nulls } = normalizeOrderBy(value);
         return `${qi.toSqlColumn(key)} ${dir}${nullsSuffix(qi, nulls)}`;
     })
@@ -452,6 +466,7 @@ export function buildJsonPathOrderEntry(qi, table, meta, field, spec, prefix, pa
     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;
+    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
@@ -546,6 +561,7 @@ function buildChainedToOneOrderBy(qi, head, nextRelName, nextValue, params) {
         if (!currentMeta.allColumns.includes(snakeCol)) {
             throw new ValidationError(`[turbine] Unknown column "${key}" in orderBy on relation "${path.join('.')}" (table "${currentMeta.name}").`);
         }
+        assertOrderDirection(entryValue, `orderBy on relation path "${path.join('.')}"`);
         const { dir, nulls } = normalizeOrderBy(entryValue);
         let where = head.correlation;
         if (params) {
@@ -608,6 +624,7 @@ export function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lat
             throw new ValidationError(`[turbine] orderBy on to-many relation "${relName}" only supports "_count" ` +
                 `or a pick-row ordering ({ pick, by }) (got: ${keys.join(', ') || '(empty)'}).`);
         }
+        assertOrderDirection(value._count, `orderBy { ${relName}: { _count } }`);
         const { dir } = normalizeOrderBy(value._count);
         return `${buildRelationCountExpr(qi, relDef, parentRef, alias, params)} ${dir}`;
     }
@@ -645,6 +662,7 @@ export function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lat
                 : '';
             throw new ValidationError(`[turbine] Unknown column "${col}" in orderBy on relation "${relName}" (table "${relDef.to}").${relationHint}`);
         }
+        assertOrderDirection(dirValue, `orderBy "${col}" on relation "${relName}"`);
         const { dir, nulls } = 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
@@ -746,6 +764,7 @@ export function buildRelationPickOrderBy(qi, relName, relDef, spec, alias, paren
     const targetMeta = qi.schema.tables[relDef.to];
     if (!targetMeta)
         throw new RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+    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
@@ -880,6 +899,7 @@ export function buildRelationOrderClause(qi, targetTable, targetMeta, alias, ord
             return buildRelationOrderBy(qi, key, dirValue, `${alias}ord${relOrdCounter++}`, params, { meta: targetMeta, table: targetTable, parentRef: alias });
         }
         const col = resolveOrderByColumn(qi, targetTable, targetMeta, key);
+        assertOrderDirection(dirValue, `orderBy "${key}" in the \`with\` clause for "${targetTable}"`);
         const { dir, nulls } = normalizeOrderBy(dirValue);
         return `${alias}.${qi.q(col)} ${dir}${nullsSuffix(qi, nulls)}`;
     })