turbine-orm 0.56.0 → 0.57.0

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

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

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

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

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

@@ -420,6 +420,22 @@ export declare function jsonWireCoercionOid(pgType: string | undefined): number
 export declare function coerceJsonWireValue(oid: number, value: unknown): unknown;
 /** The closest name in `candidates` to `input`, or null when none is close. */
 export declare function closestName(input: string, candidates: Iterable<string>): string | null;
+/**
+ * The real option key `key` most likely meant, or null when nothing is close.
+ *
+ * Shared by every "unknown option" diagnostic (the client-config warner in
+ * client.ts and the prisma-compat query-option warner), so a reader who has
+ * seen one recognizes the ranking in the other.
+ *
+ * {@link closestName} decides first, which is bounded by edit distance and
+ * covers typos. It does not cover the miss these warnings exist for: a guessed
+ * name that omits a whole WORD. `logParams` is five edits from `logQueryParams`,
+ * past the bound, yet it names the same words in the same order; likewise
+ * `customPlan` for `forceCustomPlan`. So a second pass accepts a candidate whose
+ * camelCase words CONTAIN the guess's words in order, preferring the one that
+ * adds fewest words.
+ */
+export declare function suggestKey(key: string, candidates: Iterable<string>): string | null;
 /**
  * The "unknown field" error text, listing RELATIONS as well as columns.
  *

package/dist/cjs/query/utils.js

@@ -34,6 +34,7 @@ exports.registerUtcTemporalParsers = registerUtcTemporalParsers;
 exports.jsonWireCoercionOid = jsonWireCoercionOid;
 exports.coerceJsonWireValue = coerceJsonWireValue;
 exports.closestName = closestName;
+exports.suggestKey = suggestKey;
 exports.unknownFieldMessage = unknownFieldMessage;
 const pg_1 = __importDefault(require("pg"));
 const schema_js_1 = require("../schema.js");
@@ -814,6 +815,55 @@ function closestName(input, candidates) {
     }
     return best;
 }
+/** camelCase name → its lowercased words (`logQueryParams` → log, query, params). */
+function camelWords(name) {
+    return name
+        .split(/(?=[A-Z])/)
+        .map((w) => w.toLowerCase())
+        .filter(Boolean);
+}
+/**
+ * The real option key `key` most likely meant, or null when nothing is close.
+ *
+ * Shared by every "unknown option" diagnostic (the client-config warner in
+ * client.ts and the prisma-compat query-option warner), so a reader who has
+ * seen one recognizes the ranking in the other.
+ *
+ * {@link closestName} decides first, which is bounded by edit distance and
+ * covers typos. It does not cover the miss these warnings exist for: a guessed
+ * name that omits a whole WORD. `logParams` is five edits from `logQueryParams`,
+ * past the bound, yet it names the same words in the same order; likewise
+ * `customPlan` for `forceCustomPlan`. So a second pass accepts a candidate whose
+ * camelCase words CONTAIN the guess's words in order, preferring the one that
+ * adds fewest words.
+ */
+function suggestKey(key, candidates) {
+    const direct = closestName(key, candidates);
+    if (direct)
+        return direct;
+    const wanted = camelWords(key);
+    if (wanted.length < 2)
+        return null;
+    let best = null;
+    let bestExtra = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const words = camelWords(candidate);
+        if (words.length <= wanted.length)
+            continue;
+        let i = 0;
+        for (const w of words)
+            if (w === wanted[i])
+                i++;
+        if (i !== wanted.length)
+            continue;
+        const extra = words.length - wanted.length;
+        if (extra < bestExtra) {
+            bestExtra = extra;
+            best = candidate;
+        }
+    }
+    return best;
+}
 /**
  * The "unknown field" error text, listing RELATIONS as well as columns.
  *

package/dist/cjs/query/warn-registry.d.ts

@@ -96,6 +96,14 @@ export declare const WARN_NS: {
      * `warnParserOverwrite`). Keyed on the OID.
      */
     readonly parserOverwrite: "parserOverwrite";
+    /**
+     * A key on the args object passed to a `turbine-orm/prisma-compat` delegate
+     * call that is neither a Prisma arg for that operation nor a turbine-native
+     * query option (prisma-compat.ts `warnUnknownQueryOptions`). Keyed on
+     * `model.operation.key`, so the same typo on two models is two reports, and
+     * a million executions of one call site is one.
+     */
+    readonly unknownQueryOption: "unknownQueryOption";
     /**
      * `planCacheMode` was set on a client given an EXTERNAL pool, where Turbine
      * runs no connection setup, so the option is a no-op (client.ts constructor).

package/dist/cjs/query/warn-registry.js

@@ -137,6 +137,14 @@ exports.WARN_NS = {
      * `warnParserOverwrite`). Keyed on the OID.
      */
     parserOverwrite: 'parserOverwrite',
+    /**
+     * A key on the args object passed to a `turbine-orm/prisma-compat` delegate
+     * call that is neither a Prisma arg for that operation nor a turbine-native
+     * query option (prisma-compat.ts `warnUnknownQueryOptions`). Keyed on
+     * `model.operation.key`, so the same typo on two models is two reports, and
+     * a million executions of one call site is one.
+     */
+    unknownQueryOption: 'unknownQueryOption',
     /**
      * `planCacheMode` was set on a client given an EXTERNAL pool, where Turbine
      * runs no connection setup, so the option is a no-op (client.ts constructor).