turbine-orm 0.56.0 → 0.58.0

package/dist/prisma-compat.js

@@ -31,6 +31,15 @@
  *   atomic.
  * - **Result reshaping**: `_count` objects keyed back to Prisma relation names,
  *   and to-one relations surfaced as `object | null`.
+ * - **Turbine-native query options** (`timeout`, `forceCustomPlan`,
+ *   `warnOnUnlimited`, `skipGlobalFilters`, `stableRelationOrder`,
+ *   `allowFullTableScan`, `includePii`, `optimisticLock`, `distinctOn`) reach
+ *   core on every operation whose arg surface declares them. The set is not a
+ *   hand-maintained list here: it comes from the compiler-checked tables in
+ *   `query/option-surface.ts`, so a new core option cannot be silently stranded
+ *   by this layer, and a key that is neither a Prisma arg nor a turbine option
+ *   gets a dev-mode warning instead of vanishing (see
+ *   {@link PRISMA_ARG_KEYS} and `warnUnknownQueryOptions`).
  *
  * ## What it deliberately does NOT do (documented divergences)
  *
@@ -63,6 +72,14 @@
  *   exclusive-cursor + `offset` translation.
  * - **Negative `take`** (take-from-end) and **`skip` on a nested relation
  *   include** throw, Turbine's `with` clause has no offset and no reverse-take.
+ * - **`limit` on `updateMany` / `deleteMany`** (Prisma 6.7+) throws. Turbine has
+ *   no row-bounded mass mutation, and dropping a SAFETY BOUND with a warning
+ *   would turn "change at most 10 rows" into "change every matching row".
+ * - **Write projections** (`select` / `include` / `omit` on
+ *   create/update/delete/upsert), **`select` on `count`**, and
+ *   **`orderBy` / `cursor` / `take` / `skip` on `aggregate`** are accepted and
+ *   IGNORED (they are legitimate Prisma, so they never warn); the full row / a
+ *   plain number comes back.
  *
  * ## Type dependencies (0.41.0)
  *
@@ -94,7 +111,9 @@
  */
 import { TurbineError, TurbineErrorCode, UnsupportedFeatureError, ValidationError, wrapPgError } from './errors.js';
 import { createManyShapeRuns } from './nested-write.js';
-import { shouldWarnOnce } from './query/warn-registry.js';
+import { AGGREGATE_OPTIONS, applyNativeOptions, COUNT_OPTIONS, CREATE_MANY_OPTIONS, CREATE_OPTIONS, DELETE_MANY_OPTIONS, DELETE_OPTIONS, FIND_MANY_OPTIONS, FIND_UNIQUE_OPTIONS, GROUP_BY_OPTIONS, optionKeysOfKind, UPDATE_MANY_OPTIONS, UPDATE_OPTIONS, UPSERT_OPTIONS, } from './query/index.js';
+import { suggestKey } from './query/utils.js';
+import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 // ---------------------------------------------------------------------------
 // Prisma.sql-style raw fragments (local, minimal, never imports @prisma/client)
 // ---------------------------------------------------------------------------
@@ -252,6 +271,199 @@ function isPlainObject(v) {
 function renameField(mm, prismaField) {
     return mm.fields[prismaField] ?? prismaField;
 }
+/** The turbine arg surface each operation compiles into. */
+const OPERATION_TABLES = {
+    findMany: FIND_MANY_OPTIONS,
+    findFirst: FIND_MANY_OPTIONS,
+    findFirstOrThrow: FIND_MANY_OPTIONS,
+    findUnique: FIND_UNIQUE_OPTIONS,
+    findUniqueOrThrow: FIND_UNIQUE_OPTIONS,
+    create: CREATE_OPTIONS,
+    createMany: CREATE_MANY_OPTIONS,
+    update: UPDATE_OPTIONS,
+    updateMany: UPDATE_MANY_OPTIONS,
+    delete: DELETE_OPTIONS,
+    deleteMany: DELETE_MANY_OPTIONS,
+    upsert: UPSERT_OPTIONS,
+    count: COUNT_OPTIONS,
+    aggregate: AGGREGATE_OPTIONS,
+    groupBy: GROUP_BY_OPTIONS,
+};
+/**
+ * Every argument key Prisma itself accepts, per operation.
+ *
+ * Extracted from a generated `@prisma/client` 7.9.0 `index.d.ts` (the
+ * `<Model><Op>Args` blocks). It must stay the UNION across the Prisma majors
+ * this adapter supports, never one version's set: a key a newer major
+ * introduces should degrade to one noisy dev line, never to a throw, and a key
+ * an older major had must keep working. The drift test in
+ * `src/test/prisma-compat-option-surface.test.ts` re-extracts from a generated
+ * client when one is present and asserts this stays a superset.
+ */
+export const PRISMA_ARG_KEYS = {
+    findMany: [
+        'select',
+        'omit',
+        'include',
+        'where',
+        'orderBy',
+        'cursor',
+        'take',
+        'skip',
+        'distinct',
+        'relationLoadStrategy',
+    ],
+    findFirst: [
+        'select',
+        'omit',
+        'include',
+        'where',
+        'orderBy',
+        'cursor',
+        'take',
+        'skip',
+        'distinct',
+        'relationLoadStrategy',
+    ],
+    findFirstOrThrow: [
+        'select',
+        'omit',
+        'include',
+        'where',
+        'orderBy',
+        'cursor',
+        'take',
+        'skip',
+        'distinct',
+        'relationLoadStrategy',
+    ],
+    findUnique: ['select', 'omit', 'include', 'where', 'relationLoadStrategy'],
+    findUniqueOrThrow: ['select', 'omit', 'include', 'where', 'relationLoadStrategy'],
+    create: ['select', 'omit', 'include', 'data', 'relationLoadStrategy'],
+    createMany: ['data', 'skipDuplicates'],
+    update: ['select', 'omit', 'include', 'data', 'where', 'relationLoadStrategy'],
+    updateMany: ['data', 'where', 'limit'],
+    delete: ['select', 'omit', 'include', 'where', 'relationLoadStrategy'],
+    deleteMany: ['where', 'limit'],
+    upsert: ['select', 'omit', 'include', 'where', 'create', 'update', 'relationLoadStrategy'],
+    count: ['where', 'orderBy', 'cursor', 'take', 'skip', 'select'],
+    aggregate: ['where', 'orderBy', 'cursor', 'take', 'skip', '_count', '_avg', '_sum', '_min', '_max'],
+    groupBy: ['where', 'orderBy', 'by', 'having', 'take', 'skip', '_count', '_avg', '_sum', '_min', '_max'],
+};
+/**
+ * Turbine spellings whose Prisma equivalent is spelled differently. A caller
+ * who reaches for one of these is not confused about the NAME, they are
+ * confused about which surface they are on, so they get a specific message
+ * rather than a fuzzy did-you-mean.
+ */
+const ALIAS_HINT = {
+    limit: 'take',
+    offset: 'skip',
+    with: 'include',
+};
+/**
+ * Known(op) = Prisma's own keys for that operation, plus every key the
+ * operation's turbine arg surface declares except the `'internal'` ones.
+ *
+ * The second half is NOT just the `'native'` keys. Two turbine-only options are
+ * classified `'prisma'` because their values carry field names and so must be
+ * hand-translated (`optimisticLock`, `distinctOn`); they are fully honoured, and
+ * warning about a key the adapter just acted on would be the worst possible
+ * diagnostic. `'nativeAlias'` members are in the set on purpose too: `limit` on
+ * `findMany` IS recognized, it simply gets the alias message rather than the
+ * generic one. Only `'internal'` is excluded, because nothing on this surface
+ * can reach it.
+ *
+ * A `Set` rather than an `in` test on a record, so an inherited
+ * `Object.prototype` name (`toString`, `constructor`) is treated as the unknown
+ * key it is.
+ */
+const KNOWN_KEYS = (() => {
+    const out = {};
+    for (const op of Object.keys(OPERATION_TABLES)) {
+        out[op] = new Set([
+            ...PRISMA_ARG_KEYS[op],
+            ...optionKeysOfKind(OPERATION_TABLES[op], 'prisma', 'native', 'nativeAlias'),
+        ]);
+    }
+    return out;
+})();
+/**
+ * Dev-mode notice for a key on a delegate's args object that this operation has
+ * no meaning for.
+ *
+ * An unrecognized key is silently ignored (JavaScript objects have no schema),
+ * which makes a typo, a turbine spelling, and a genuinely missing feature all
+ * look identical: nothing happens. The client-config warner
+ * (`warnUnknownConfigKeys` in client.ts) exists for the same reason and this is
+ * its query-level twin, down to the ranking of the suggestion.
+ *
+ * Deliberately a WARNING, never an error. Throwing would turn a working app
+ * into a failing one on upgrade over one stray key, and a key from a Prisma
+ * major newer than {@link PRISMA_ARG_KEYS} would be exactly that key. The whole
+ * body is wrapped so a hostile or exotic args object (a Proxy whose `ownKeys`
+ * throws) can never be the reason a query fails. Dev-only and once per
+ * `model.operation.key` per process, like every other advisory here.
+ */
+function warnUnknownQueryOptions(model, op, args) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    if (!isPlainObject(args))
+        return;
+    try {
+        const known = KNOWN_KEYS[op];
+        const table = OPERATION_TABLES[op];
+        for (const key of Object.keys(args)) {
+            // `{ ...maybeOptions }` routinely materializes keys with no value.
+            // Nothing is being dropped when the value is undefined.
+            if (args[key] === undefined)
+                continue;
+            const alias = table[key] === 'nativeAlias' ? ALIAS_HINT[key] : undefined;
+            if (!alias && known.has(key))
+                continue;
+            if (!shouldWarnOnce(WARN_NS.unknownQueryOption, `${model}.${op}.${key}`))
+                continue;
+            if (alias) {
+                console.warn(`[turbine] prisma-compat: "${key}" is Turbine's spelling and is ignored here;` +
+                    ` prisma-compat takes Prisma's "${alias}". (${model}.${op})`);
+                continue;
+            }
+            const suggestion = suggestKey(key, known);
+            console.warn(`[turbine] prisma-compat: unknown option "${key}" in ${model}.${op}(), it is ignored.` +
+                (suggestion ? ` Did you mean "${suggestion}"?` : ''));
+        }
+    }
+    catch {
+        // Key enumeration is the only thing that can fail here, and a diagnostic
+        // must never be the reason a query fails.
+    }
+}
+/**
+ * Prisma 6.7+ accepts `limit` on `updateMany` / `deleteMany` to BOUND how many
+ * rows a mass mutation touches. Turbine has no row-bounded mass mutation, so
+ * this one is refused rather than warned about: everywhere else in this design
+ * a dropped option costs the caller a feature, but silently dropping a safety
+ * bound turns "change at most 10 rows" into "change every row".
+ */
+function refuseRowLimit(model, op, args) {
+    if (!isPlainObject(args) || args.limit === undefined)
+        return;
+    throw new UnsupportedFeatureError(`\`limit\` on ${op} (row-bounded mass mutation)`, 'prisma-compat', `Turbine has no row-bounded ${op}; select the rows you mean with \`where\`` +
+        ` (on ${model}.${op}), or page them and mutate by primary key.`);
+}
+/**
+ * Prisma's `relationLoadStrategy` and Turbine's share a name and NOT a value
+ * domain: Prisma has `'query' | 'join'`, Turbine has
+ * `'join' | 'batched' | 'auto' | 'flatten'`. Core's strategy resolution has no
+ * branch for `'query'` and returns the value unchanged, so forwarding it
+ * verbatim gave a caller who asked for the per-relation query plan the JOIN
+ * plan, the exact opposite of the request. Prisma's `'query'` IS Turbine's
+ * `'batched'` (one follow-up statement per relation); the turbine-only values
+ * pass through so a compat caller can still reach them.
+ */
+function mapRelationLoadStrategy(value) {
+    return value === 'query' ? 'batched' : value;
+}
 /**
  * Translate a Prisma `where` (or nested relation where) into a Turbine `where`.
  * Renames scalar field keys and relation keys through the map, recurses into
@@ -446,6 +658,13 @@ function modelName(ctx, mm) {
  */
 function translateReadArgs(ctx, mm, prismaArgs, kind) {
     const t = {};
+    // FIRST, so a per-call `stableRelationOrder` overrides it: the client-level
+    // option is a default, the arg is an instruction.
+    if (ctx.options.stablePkOrder)
+        t.stableRelationOrder = true;
+    // Every turbine-native option the arg surface declares, in one line that
+    // cannot fall behind the interface (see the option-surface tables).
+    applyNativeOptions(kind === 'unique' ? FIND_UNIQUE_OPTIONS : FIND_MANY_OPTIONS, prismaArgs, t);
     if (prismaArgs.where !== undefined)
         t.where = translateWhere(ctx, mm, prismaArgs.where);
     if (prismaArgs.orderBy !== undefined)
@@ -458,17 +677,9 @@ function translateReadArgs(ctx, mm, prismaArgs, kind) {
     if (Array.isArray(prismaArgs.distinct)) {
         t.distinct = prismaArgs.distinct.map((f) => renameField(mm, f));
     }
-    if (prismaArgs.relationLoadStrategy !== undefined)
-        t.relationLoadStrategy = prismaArgs.relationLoadStrategy;
-    if (typeof prismaArgs.timeout === 'number')
-        t.timeout = prismaArgs.timeout;
-    // Turbine-only passthrough. Prisma has no PII concept, so a compat caller
-    // whose schema tags columns needs SOME way to opt in; without this the
-    // adapter is a one-way door into redacted reads and refused aggregates.
-    if (prismaArgs.includePii !== undefined)
-        t.includePii = prismaArgs.includePii;
-    if (ctx.options.stablePkOrder)
-        t.stableRelationOrder = true;
+    if (prismaArgs.relationLoadStrategy !== undefined) {
+        t.relationLoadStrategy = mapRelationLoadStrategy(prismaArgs.relationLoadStrategy);
+    }
     // ORDER IS LOAD-BEARING: translateCursor MUST run BEFORE applyImplicitPkOrder.
     // The cursor translation reads `t.orderBy` to decide the seek direction and to
     // validate that a bare inclusive cursor names the sort key; it must see the
@@ -767,6 +978,7 @@ function translateUpsertNested(ctx, target, p) {
 const AGG_FIELD_BLOCKS = ['_sum', '_avg', '_min', '_max'];
 function translateAggregateArgs(ctx, mm, args, isGroupBy) {
     const t = {};
+    applyNativeOptions(isGroupBy ? GROUP_BY_OPTIONS : AGGREGATE_OPTIONS, args, t);
     if (args.where !== undefined)
         t.where = translateWhere(ctx, mm, args.where);
     if (args._count !== undefined)
@@ -775,12 +987,6 @@ function translateAggregateArgs(ctx, mm, args, isGroupBy) {
         if (args[block] !== undefined)
             t[block] = renameAggBlock(mm, args[block], false);
     }
-    if (typeof args.timeout === 'number')
-        t.timeout = args.timeout;
-    // Turbine-only passthrough: the PII gate on groupBy keys and _min/_max needs
-    // an opt-in that Prisma's arg shape has no equivalent for.
-    if (args.includePii !== undefined)
-        t.includePii = args.includePii;
     if (isGroupBy) {
         if (Array.isArray(args.by))
             t.by = args.by.map((f) => renameField(mm, f));
@@ -788,6 +994,8 @@ function translateAggregateArgs(ctx, mm, args, isGroupBy) {
             t.orderBy = translateOrderBy(ctx, mm, args.orderBy);
         if (args.having !== undefined)
             t.having = renameHaving(mm, args.having);
+        if (args.distinctOn !== undefined)
+            t.distinctOn = translateDistinctOn(ctx, mm, args.distinctOn);
         if (typeof args.take === 'number')
             t.limit = mapTake(args.take);
         if (typeof args.skip === 'number')
@@ -795,6 +1003,23 @@ function translateAggregateArgs(ctx, mm, args, isGroupBy) {
     }
     return t;
 }
+/**
+ * Translate a turbine-native groupBy `distinctOn`. Both halves of its value
+ * (`columns`, `orderBy`) are FIELD NAMES, so this is the concrete reason the
+ * option surface refuses to copy unknown keys through by default: a blind
+ * passthrough is correct on a model whose Prisma and turbine names coincide and
+ * silently wrong on one with a `@map`.
+ */
+function translateDistinctOn(ctx, mm, val) {
+    if (!isPlainObject(val))
+        return val;
+    const out = { ...val };
+    if (Array.isArray(val.columns))
+        out.columns = val.columns.map((f) => renameField(mm, f));
+    if (val.orderBy !== undefined)
+        out.orderBy = translateOrderBy(ctx, mm, val.orderBy);
+    return out;
+}
 /** Rename field keys inside an aggregate block; `_count`'s `_all` passes through. */
 function renameAggBlock(mm, block, isCount) {
     if (block === true || !isPlainObject(block))
@@ -1139,6 +1364,8 @@ async function createManyByRun(qi, t, runs) {
         const args = { data: run };
         if (t.skipDuplicates)
             args.skipDuplicates = true;
+        if (t.timeout !== undefined)
+            args.timeout = t.timeout;
         count += (await qi.createMany(args)).length;
     }
     return { count };
@@ -1154,7 +1381,14 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
     // async run wrapper also converts any synchronous throw from the underlying
     // `qi.*` build into a rejection; the array `$transaction([...])` batch path
     // catches the same throw from `batch.build`.
-    const defer = (translate, run, batch) => {
+    const defer = (op, rawArgs, translateRaw, run, batch) => {
+        // The unknown-key check rides the SAME deferred boundary as the translation
+        // itself, for the same reason (see the comment above): a compat promise that
+        // is built and never awaited must produce no output at all.
+        const translate = () => {
+            warnUnknownQueryOptions(modelName(ctx, mm), op, rawArgs);
+            return translateRaw();
+        };
         const batchable = batch
             ? {
                 build: () => batch.build(getQI(), translate()),
@@ -1194,27 +1428,27 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
         return args;
     };
     return {
-        findMany: (args = {}) => defer(() => translateReadArgs(ctx, mm, args, 'many'), (qi, t) => qi.findMany(t).then((r) => reshapeRows(ctx, mm, r)), { build: (qi, t) => qi.buildFindMany(t), reshape: (raw) => reshapeRows(ctx, mm, raw) }),
-        findFirst: (args = {}) => defer(() => translateReadArgs(ctx, mm, args, 'first'), (qi, t) => qi.findFirst(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirst(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
-        findUnique: (args) => defer(() => translateReadArgs(ctx, mm, requireWhere(args, 'findUnique'), 'unique'), (qi, t) => qi.findUnique(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindUnique(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
-        findFirstOrThrow: (args = {}) => defer(() => translateReadArgs(ctx, mm, args, 'first'), (qi, t) => qi.findFirstOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirstOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
-        findUniqueOrThrow: (args) => defer(() => translateReadArgs(ctx, mm, requireWhere(args, 'findUniqueOrThrow'), 'unique'), (qi, t) => qi.findUniqueOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindUniqueOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
-        create: (args) => defer(() => {
+        findMany: (args = {}) => defer('findMany', args, () => translateReadArgs(ctx, mm, args, 'many'), (qi, t) => qi.findMany(t).then((r) => reshapeRows(ctx, mm, r)), { build: (qi, t) => qi.buildFindMany(t), reshape: (raw) => reshapeRows(ctx, mm, raw) }),
+        findFirst: (args = {}) => defer('findFirst', args, () => translateReadArgs(ctx, mm, args, 'first'), (qi, t) => qi.findFirst(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirst(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
+        findUnique: (args) => defer('findUnique', args, () => translateReadArgs(ctx, mm, requireWhere(args, 'findUnique'), 'unique'), (qi, t) => qi.findUnique(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindUnique(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
+        findFirstOrThrow: (args = {}) => defer('findFirstOrThrow', args, () => translateReadArgs(ctx, mm, args, 'first'), (qi, t) => qi.findFirstOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirstOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
+        findUniqueOrThrow: (args) => defer('findUniqueOrThrow', args, () => translateReadArgs(ctx, mm, requireWhere(args, 'findUniqueOrThrow'), 'unique'), (qi, t) => qi.findUniqueOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindUniqueOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
+        create: (args) => defer('create', args, () => {
             const t = { data: translateWriteData(ctx, mm, applyCreateDefaults(mm, args.data)) };
-            if (typeof args.timeout === 'number')
-                t.timeout = args.timeout;
+            applyNativeOptions(CREATE_OPTIONS, args, t);
             return t;
         }, (qi, t) => qi.create(t).then((r) => reshapeRow(ctx, mm, r)), {
             build: (qi, t) => qi.buildCreate(t),
             reshape: (raw) => reshapeRow(ctx, mm, raw),
             nested: (t) => hasNestedKeys(ctx, mm, t.data),
         }),
-        createMany: (args) => defer(() => {
+        createMany: (args) => defer('createMany', args, () => {
             const data = args.data;
             const rows = Array.isArray(data)
                 ? data.map((d) => translateWriteData(ctx, mm, applyCreateDefaults(mm, d)))
                 : [];
             const t = { data: rows };
+            applyNativeOptions(CREATE_MANY_OPTIONS, args, t);
             if (args.skipDuplicates)
                 t.skipDuplicates = true;
             return t;
@@ -1235,45 +1469,68 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
             nested: (t) => createManyRunsOf(t).length > 1,
             execInTx: (table, t) => createManyByRun(table(mm.table), t, createManyRunsOf(t)),
         }),
-        update: (args) => defer(() => {
+        update: (args) => defer('update', args, () => {
             const a = requireWhere(args, 'update');
-            return {
+            const t = {
                 where: translateWhere(ctx, mm, a.where),
                 data: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.data)),
             };
+            applyNativeOptions(UPDATE_OPTIONS, a, t);
+            // `optimisticLock.field` is a FIELD NAME, so it is renamed rather than
+            // copied: a blind passthrough would send the Prisma spelling into core
+            // and break on any model whose column is `@map`ped.
+            if (isPlainObject(a.optimisticLock)) {
+                t.optimisticLock = {
+                    ...a.optimisticLock,
+                    field: renameField(mm, String(a.optimisticLock.field)),
+                };
+            }
+            return t;
         }, (qi, t) => qi.update(t).then((r) => reshapeRow(ctx, mm, r)), {
             build: (qi, t) => qi.buildUpdate(t),
             reshape: (raw) => reshapeRow(ctx, mm, raw),
             nested: (t) => hasNestedKeys(ctx, mm, t.data),
         }),
-        updateMany: (args) => defer(() => {
+        updateMany: (args) => defer('updateMany', args, () => {
             const a = args;
+            refuseRowLimit(modelName(ctx, mm), 'updateMany', a);
             const t = {
                 where: translateWhere(ctx, mm, a.where ?? {}),
                 data: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.data)),
             };
+            applyNativeOptions(UPDATE_MANY_OPTIONS, a, t);
+            // LAST, so it wins: a Prisma updateMany with no `where` affects every
+            // row, and an explicit `allowFullTableScan: false` must not be able to
+            // turn that parity into a thrown empty-where guard.
             if (a.where === undefined)
                 t.allowFullTableScan = true;
             return t;
         }, (qi, t) => qi.updateMany(t), { build: (qi, t) => qi.buildUpdateMany(t), reshape: (raw) => raw }),
-        delete: (args) => defer(() => {
+        delete: (args) => defer('delete', args, () => {
             const a = requireWhere(args, 'delete');
-            return { where: translateWhere(ctx, mm, a.where) };
+            const t = { where: translateWhere(ctx, mm, a.where) };
+            applyNativeOptions(DELETE_OPTIONS, a, t);
+            return t;
         }, (qi, t) => qi.delete(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildDelete(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
-        deleteMany: (args = {}) => defer(() => {
+        deleteMany: (args = {}) => defer('deleteMany', args, () => {
             const a = args;
+            refuseRowLimit(modelName(ctx, mm), 'deleteMany', a);
             const t = { where: translateWhere(ctx, mm, a.where ?? {}) };
+            applyNativeOptions(DELETE_MANY_OPTIONS, a, t);
+            // LAST, so it wins. See the same note on updateMany.
             if (a.where === undefined)
                 t.allowFullTableScan = true;
             return t;
         }, (qi, t) => qi.deleteMany(t), { build: (qi, t) => qi.buildDeleteMany(t), reshape: (raw) => raw }),
-        upsert: (args) => defer(() => {
+        upsert: (args) => defer('upsert', args, () => {
             const a = requireWhere(args, 'upsert');
-            return {
+            const t = {
                 where: translateWhere(ctx, mm, a.where),
                 create: translateWriteData(ctx, mm, applyCreateDefaults(mm, a.create)),
                 update: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.update)),
             };
+            applyNativeOptions(UPSERT_OPTIONS, a, t);
+            return t;
         }, (qi, t) => {
             // Native ON CONFLICT upsert is only Prisma-equivalent when the where
             // key values equal the create values AND no nested write data is
@@ -1296,16 +1553,15 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
                 return reshapeRow(ctx, mm, await upsertLookupFirst(table(mm.table), t));
             },
         }),
-        count: (args = {}) => defer(() => {
+        count: (args = {}) => defer('count', args, () => {
             const t = {};
+            applyNativeOptions(COUNT_OPTIONS, args, t);
             if (args.where !== undefined)
                 t.where = translateWhere(ctx, mm, args.where);
-            if (typeof args.timeout === 'number')
-                t.timeout = args.timeout;
             return t;
         }, (qi, t) => qi.count(t), { build: (qi, t) => qi.buildCount(t), reshape: (raw) => raw }),
-        aggregate: (args) => defer(() => translateAggregateArgs(ctx, mm, args, false), (qi, t) => qi.aggregate(t).then((r) => reshapeAggregate(ctx, mm, r)), { build: (qi, t) => qi.buildAggregate(t), reshape: (raw) => reshapeAggregate(ctx, mm, raw) }),
-        groupBy: (args) => defer(() => translateAggregateArgs(ctx, mm, args, true), (qi, t) => qi.groupBy(t).then((rows) => rows.map((r) => reshapeGroupRow(ctx, mm, r))), {
+        aggregate: (args) => defer('aggregate', args, () => translateAggregateArgs(ctx, mm, args, false), (qi, t) => qi.aggregate(t).then((r) => reshapeAggregate(ctx, mm, r)), { build: (qi, t) => qi.buildAggregate(t), reshape: (raw) => reshapeAggregate(ctx, mm, raw) }),
+        groupBy: (args) => defer('groupBy', args, () => translateAggregateArgs(ctx, mm, args, true), (qi, t) => qi.groupBy(t).then((rows) => rows.map((r) => reshapeGroupRow(ctx, mm, r))), {
             build: (qi, t) => qi.buildGroupBy(t),
             reshape: (raw) => raw.map((r) => reshapeGroupRow(ctx, mm, r)),
         }),

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

@@ -6,5 +6,6 @@
  * former monolithic `import { … } from './query.js'`.
  */
 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';
 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

@@ -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 {};