turbine-orm 0.56.0 → 0.58.0

package/dist/query/option-surface.js

@@ -0,0 +1,209 @@
+/**
+ * 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
+ */
+export const 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',
+};
+export const 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',
+};
+export const FIND_MANY_STREAM_OPTIONS = {
+    ...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',
+};
+export const CREATE_OPTIONS = {
+    data: 'prisma',
+    timeout: 'native',
+};
+export const CREATE_MANY_OPTIONS = {
+    data: 'prisma',
+    skipDuplicates: 'prisma',
+    timeout: 'native',
+};
+export const 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',
+};
+export const UPDATE_MANY_OPTIONS = {
+    where: 'prisma',
+    data: 'prisma',
+    timeout: 'native',
+    allowFullTableScan: 'native',
+    skipGlobalFilters: 'native',
+};
+export const DELETE_OPTIONS = {
+    where: 'prisma',
+    timeout: 'native',
+    allowFullTableScan: 'native',
+    skipGlobalFilters: 'native',
+};
+export const DELETE_MANY_OPTIONS = {
+    where: 'prisma',
+    timeout: 'native',
+    allowFullTableScan: 'native',
+    skipGlobalFilters: 'native',
+};
+export const UPSERT_OPTIONS = {
+    where: 'prisma',
+    create: 'prisma',
+    update: 'prisma',
+    timeout: 'native',
+    skipGlobalFilters: 'native',
+};
+export const COUNT_OPTIONS = {
+    where: 'prisma',
+    timeout: 'native',
+    skipGlobalFilters: 'native',
+    forceCustomPlan: 'native',
+};
+export const AGGREGATE_OPTIONS = {
+    where: 'prisma',
+    _count: 'prisma',
+    _sum: 'prisma',
+    _avg: 'prisma',
+    _min: 'prisma',
+    _max: 'prisma',
+    timeout: 'native',
+    skipGlobalFilters: 'native',
+    includePii: 'native',
+    forceCustomPlan: 'native',
+};
+export const 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).
+ */
+export const ALL_OPTION_TABLES = {
+    findUnique: FIND_UNIQUE_OPTIONS,
+    findMany: FIND_MANY_OPTIONS,
+    findManyStream: FIND_MANY_STREAM_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,
+};
+/**
+ * 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 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. */
+export function optionKeysOfKind(table, ...kinds) {
+    return Object.keys(table).filter((k) => kinds.includes(table[k]));
+}

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

@@ -781,6 +781,55 @@ export 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.
+ */
+export 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/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/query/warn-registry.js

@@ -131,6 +131,14 @@ export const 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",