turbine-orm 0.81.0 → 0.90.0

package/dist/query/option-surface.js

@@ -52,9 +52,10 @@
  * @module
  */
 // Runtime imports, and the only ones in this file: the unknown-key warning at
-// the bottom needs the once-per-process registry and the name suggester. Both
-// are leaves that do not import this module, so the type-only shape of
-// everything above is unaffected.
+// the bottom needs the logger, the once-per-process registry and the name
+// suggester. All are leaves that do not import this module, so the type-only
+// shape of everything above is unaffected.
+import { logTo } from '../logger.js';
 import { suggestKey } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 export const FIND_UNIQUE_OPTIONS = {
@@ -78,6 +79,9 @@ export const FIND_UNIQUE_OPTIONS = {
     // schema's naming space, so THE ONE RULE puts it here rather than in the
     // hand-translated set.
     jsonEncoding: 'native',
+    // A lock mode and a wait flag: no schema name in the value, so compat
+    // forwards it unchanged.
+    lock: 'native',
 };
 export const FIND_MANY_OPTIONS = {
     where: 'prisma',
@@ -105,12 +109,17 @@ export const FIND_MANY_OPTIONS = {
     forceCustomPlan: 'native',
     // See FIND_UNIQUE_OPTIONS: an encoding name carries no schema name.
     jsonEncoding: 'native',
+    lock: 'native',
 };
+// Streams take findMany's surface minus `lock` (a cursor cannot hold its rows
+// locked across fetches), so the spread drops it by name.
+const { lock: _streamsTakeNoLock, ...FIND_MANY_STREAM_BASE } = FIND_MANY_OPTIONS;
 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.
+    ...FIND_MANY_STREAM_BASE,
+    // No streaming delegate exists on the compat surface, so these are not known
+    // keys there and passing one is reported rather than quietly ignored.
     batchSize: 'internal',
+    idleTimeoutMs: 'internal',
 };
 export const CREATE_OPTIONS = {
     data: 'prisma',
@@ -122,7 +131,13 @@ export const CREATE_OPTIONS = {
 export const CREATE_MANY_OPTIONS = {
     data: 'prisma',
     skipDuplicates: 'prisma',
+    // Field names (the target, the update columns, the projection), and compat's
+    // createMany does not expose them, so they are not known keys there.
+    onConflict: 'internal',
+    select: 'internal',
+    omit: 'internal',
     timeout: 'native',
+    skipGlobalFilters: 'native',
 };
 export const UPDATE_OPTIONS = {
     where: 'prisma',
@@ -182,6 +197,8 @@ export const AGGREGATE_OPTIONS = {
     _avg: 'prisma',
     _min: 'prisma',
     _max: 'prisma',
+    // Field names in the keys, and Prisma has no percentile aggregate.
+    _percentile: 'internal',
     timeout: 'native',
     skipGlobalFilters: 'native',
     includePii: 'native',
@@ -197,6 +214,7 @@ export const GROUP_BY_OPTIONS = {
     _avg: 'prisma',
     _min: 'prisma',
     _max: 'prisma',
+    _percentile: 'internal',
     // `{ columns, orderBy }`, both in FIELD-NAME space. See THE ONE RULE.
     distinctOn: 'prisma',
     limit: 'nativeAlias',
@@ -278,7 +296,25 @@ const PRISMA_SPELLING = {
     include: 'with',
 };
 /**
- * Dev-mode warning for a key that is not part of the operation's option
+ * Keys an operation does not declare but REFUSES by name with its own error
+ * (E003 naming the key and the alternative), rather than ignoring. Warning
+ * "it is ignored" about one of these would contradict the error that follows,
+ * so the warning skips them. Every entry must have a refusal behind it;
+ * `src/test/fix-where-option-warnings.test.ts` checks that each one throws.
+ */
+export const REFUSED_OPTION_KEYS = {
+    // A bounded batch is not what these statements do (assertNoBulkWritePaging).
+    updateMany: new Set(['limit', 'take', 'offset', 'skip', 'optimisticLock']),
+    deleteMany: new Set(['limit', 'take', 'offset', 'skip', 'optimisticLock']),
+    // `optimisticLock` is an `update` option (assertNoOptimisticLock).
+    upsert: new Set(['optimisticLock']),
+    delete: new Set(['optimisticLock']),
+    // A streaming cursor cannot hold its rows locked across fetches.
+    findManyStream: new Set(['lock']),
+    findManyStreamBatches: new Set(['lock']),
+};
+/**
+ * Advice for a key that is not part of the operation's option
  * surface, and is therefore doing nothing.
  *
  * The motivating case is `include`. It is Prisma's word for `with`, it is what
@@ -295,17 +331,21 @@ const PRISMA_SPELLING = {
  * working query start throwing. A warning costs a correct program nothing and
  * tells an incorrect one exactly what happened.
  *
- * Dev-only, once per `table.operation.key` per process, and total: the whole
- * body is wrapped, because a diagnostic must never be the reason a query fails.
+ * Advice: emitted only when the client's `diagnostics.advice` is on. The
+ * caller passes its advice logger, or `null` when advice is off, so this
+ * module never reads the environment. Once per `table.operation.key` per
+ * process, and total: the whole body is wrapped, because a diagnostic must
+ * never be the reason a query fails.
  */
-export function warnUnknownQueryOptions(table, operation, args) {
-    if (process.env.NODE_ENV === 'production')
+export function warnUnknownQueryOptions(table, operation, args, advice) {
+    if (!advice)
         return;
     if (args === null || typeof args !== 'object' || Array.isArray(args))
         return;
     const known = OPERATION_TABLE[operation];
     if (!known)
         return;
+    const refused = REFUSED_OPTION_KEYS[operation];
     try {
         for (const key of Object.keys(args)) {
             // `{ ...maybeOptions }` routinely materializes keys with no value.
@@ -314,13 +354,16 @@ export function warnUnknownQueryOptions(table, operation, args) {
                 continue;
             if (Object.hasOwn(known, key))
                 continue;
+            // Refused with its own error, which is the diagnostic; not ignored.
+            if (refused?.has(key))
+                continue;
             if (!shouldWarnOnce(WARN_NS.unknownQueryOption, `${table}.${operation}.${key}`))
                 continue;
             const prismaSpelling = PRISMA_SPELLING[key];
             const suggestion = prismaSpelling ?? suggestKey(key, Object.keys(known));
             const because = prismaSpelling ? ` Turbine spells this "${prismaSpelling}".` : '';
-            console.warn(`[turbine] unknown option "${key}" in ${table}.${operation}(), it is ignored.${because}` +
-                (!prismaSpelling && suggestion ? ` Did you mean "${suggestion}"?` : ''));
+            logTo(advice, 'warn', `unknown option "${key}" in ${table}.${operation}(), it is ignored.${because}` +
+                (!prismaSpelling && suggestion ? ` Did you mean "${suggestion}"?` : ''), { code: 'unknown-query-option', table, operation, key });
         }
     }
     catch {

package/dist/query/relation-names.d.ts

@@ -68,3 +68,17 @@ export declare function normalizeWithClause(schema: SchemaMetadata, table: strin
  * byte-identical.
  */
 export declare function applyStableRelationOrderTo(schema: SchemaMetadata, withClause: WithClause, table: string, depth?: number): WithClause;
+/**
+ * Fold Prisma's `take` / `skip` into `limit` / `offset` inside every `with`
+ * level, by the same rule {@link normalizePagination} applies at the top level
+ * (both spellings of one bound with different values throw). Runs once, before
+ * any walker reads the tree, so the fingerprint, the join build, the batched
+ * loader and the row parser all see `limit` / `offset` and never the aliases.
+ *
+ * A per-relation `offset` on a to-one relation is refused: the relation is a
+ * single row or `null`, so there is nothing to skip past, and silently
+ * returning the row anyway would ignore what the caller wrote.
+ *
+ * Returns the input by reference when nothing changed.
+ */
+export declare function normalizeWithPagination(schema: SchemaMetadata, table: string, withClause: WithClause | undefined, depth?: number): WithClause | undefined;

package/dist/query/relation-names.js

@@ -41,8 +41,9 @@
  * available relations; rejecting it here would move that error away from its
  * context and change which error type callers see.
  */
+import { ValidationError } from '../errors.js';
 import { isEmptyOrderBy } from './filters.js';
-import { resolveRelation, resolveRelationDef } from './utils.js';
+import { normalizePagination, resolveRelation, resolveRelationDef } from './utils.js';
 /** Depth cap mirroring the builder's own, so a cyclic `with` cannot spin here. */
 const MAX_DEPTH = 12;
 /**
@@ -57,27 +58,36 @@ export function normalizeWithClause(schema, table, withClause, depth = 0) {
     const meta = schema.tables[table];
     if (!meta)
         return withClause;
-    let changed = false;
-    const out = {};
-    for (const [key, spec] of Object.entries(withClause)) {
+    // The copy is allocated only once something changes (the common call
+    // spells every relation the declared way and allocates nothing); the keys
+    // before that point are copied in order, so the result is the same object
+    // the eager version built.
+    let out;
+    const source = withClause;
+    const keys = Object.keys(source);
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const spec = source[key];
+        let name = key;
+        let nextSpec;
         if (key === '_count') {
-            const nextCount = normalizeCount(meta, spec);
-            if (nextCount !== spec)
-                changed = true;
-            out[key] = nextCount;
-            continue;
+            nextSpec = normalizeCount(meta, spec);
         }
-        const resolved = resolveRelation(meta.relations, key);
-        // Unknown key: keep it verbatim and let the builder raise E005 by name.
-        const name = resolved?.name ?? key;
-        if (name !== key)
-            changed = true;
-        const nextSpec = resolved ? normalizeSpec(schema, resolved.def.to, spec, depth) : spec;
-        if (nextSpec !== spec)
-            changed = true;
-        out[name] = nextSpec;
+        else {
+            const resolved = resolveRelation(meta.relations, key);
+            // Unknown key: keep it verbatim and let the builder raise E005 by name.
+            name = resolved?.name ?? key;
+            nextSpec = resolved ? normalizeSpec(schema, resolved.def.to, spec, depth) : spec;
+        }
+        if (out === undefined && (name !== key || nextSpec !== spec)) {
+            out = {};
+            for (let j = 0; j < i; j++)
+                out[keys[j]] = source[keys[j]];
+        }
+        if (out !== undefined)
+            out[name] = nextSpec;
     }
-    return changed ? out : withClause;
+    return out ?? withClause;
 }
 /** A relation's `with` options, normalizing its nested `with` against the TARGET table. */
 function normalizeSpec(schema, target, spec, depth) {
@@ -174,3 +184,51 @@ export function applyStableRelationOrderTo(schema, withClause, table, depth = 0)
     }
     return out ?? withClause;
 }
+/**
+ * Fold Prisma's `take` / `skip` into `limit` / `offset` inside every `with`
+ * level, by the same rule {@link normalizePagination} applies at the top level
+ * (both spellings of one bound with different values throw). Runs once, before
+ * any walker reads the tree, so the fingerprint, the join build, the batched
+ * loader and the row parser all see `limit` / `offset` and never the aliases.
+ *
+ * A per-relation `offset` on a to-one relation is refused: the relation is a
+ * single row or `null`, so there is nothing to skip past, and silently
+ * returning the row anyway would ignore what the caller wrote.
+ *
+ * Returns the input by reference when nothing changed.
+ */
+export function normalizeWithPagination(schema, table, withClause, depth = 0) {
+    if (!withClause || typeof withClause !== 'object' || depth > MAX_DEPTH)
+        return withClause;
+    const meta = schema.tables[table];
+    if (!meta)
+        return withClause;
+    let out;
+    // Object.keys, not Object.entries: no [key, value] pair allocated per key.
+    const keys = Object.keys(withClause);
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const spec = withClause[key];
+        if (key === '_count' || spec === null || typeof spec !== 'object')
+            continue;
+        const rel = resolveRelation(meta.relations, key);
+        if (!rel)
+            continue; // unknown relation: the builder raises E005 by name
+        const folded = normalizePagination(spec);
+        const offset = folded.offset;
+        if (offset !== undefined && (rel.def.type === 'belongsTo' || rel.def.type === 'hasOne')) {
+            throw new ValidationError(`\`offset\` (or \`skip\`) on the to-one relation "${rel.name}" of "${table}" has nothing to skip: ` +
+                'a to-one relation is a single row or null. Remove it, or page the relation from its own table.');
+        }
+        const nested = folded.with;
+        const nextNested = nested ? normalizeWithPagination(schema, rel.def.to, nested, depth + 1) : nested;
+        let next = folded;
+        if (nextNested !== nested)
+            next = { ...folded, with: nextNested };
+        if (next !== spec) {
+            out ??= { ...withClause };
+            out[key] = next;
+        }
+    }
+    return out ?? withClause;
+}

package/dist/query/relations.d.ts

@@ -33,6 +33,14 @@ export interface RelationShape {
     nested: Record<string, RelationShape>;
     cardinality: 'many' | 'one';
 }
+/**
+ * The E003 text for a PII-tagged column named in `select` without
+ * `includePii: UNSAFE`. Shared by every projection path through
+ * {@link resolveProjection}, so a top-level read, a `with` relation (join,
+ * batched, flatten and positional alike) and a single-row write refuse in the
+ * same words. The write path is named because it cannot pass the opt-in at all.
+ */
+export declare function piiSelectRefusedMessage(table: string, field: string): string;
 /**
  * Resolve `select` / `omit` into a list of snake_case column names, for the
  * query's own table and for a relation target alike. `null` means "no
@@ -76,6 +84,11 @@ export declare function resolveColumns(qi: BuilderCtx, select?: Record<string, b
  * is a shared authority rather than a guard repeated per walker.
  */
 export declare function relationOptions(spec: true | WithOptions): WithOptions;
+/**
+ * A to-many relation's `offset` (`skip` is folded into it at the args seam by
+ * `normalizeWithPagination`, which also refuses it on a to-one relation).
+ */
+export declare function relationOffset(opts: WithOptions): unknown;
 /**
  * Produce a fingerprint for a `with` clause tree. Recursion mirrors
  * buildSelectWithRelations / buildRelationSubquery.
@@ -116,9 +129,9 @@ export declare function buildOrderBy(qi: BuilderCtx, orderBy: OrderByClause, par
 export declare function isRelationOrderByValue(_qi: BuilderCtx, value: unknown): boolean;
 /**
  * Render the ` NULLS FIRST` / ` NULLS LAST` suffix for a column ordering.
- * Only PostgreSQL and SQLite support the `NULLS FIRST/LAST` grammar, on any
- * other engine a caller asking for explicit nulls placement gets a clear
- * {@link UnsupportedFeatureError} (E017) instead of broken SQL.
+ * On an engine without the `NULLS FIRST/LAST` grammar (`nullsOrderingClause`:
+ * PostgreSQL and SQLite have it) a caller asking for explicit nulls placement
+ * gets a clear {@link UnsupportedFeatureError} (E017) instead of broken SQL.
  */
 export declare function nullsSuffix(qi: BuilderCtx, nulls: 'first' | 'last' | undefined): string;
 /**
@@ -171,6 +184,20 @@ export declare function buildRelationOrderBy(qi: BuilderCtx, relName: string, va
     table: string;
     parentRef: string;
 }, lateralSink?: string[]): string;
+/**
+ * Param-collect mirror of a TO-ONE relation orderBy entry, done by running
+ * {@link buildRelationOrderBy} and discarding its SQL. The build pushes the
+ * target's global filter once per ordered column and, for a chained
+ * `{ author: { org: { name } } }` ordering, once more per hop table, in hop
+ * order. A hand-written mirror that pushed one filter per column bound too few
+ * params (and in the wrong order) as soon as a hop table had a filter, so this
+ * mirror is the build itself and cannot drift from it.
+ */
+export declare function collectToOneRelationOrderParams(qi: BuilderCtx, relName: string, value: Record<string, unknown>, params: unknown[], ctx?: {
+    meta: TableMetadata;
+    table: string;
+    parentRef: string;
+}): void;
 /**
  * Validate a {@link RelationPickOrderBy} entry's scope and shape. Shared by
  * the SQL-build path ({@link buildRelationPickOrderBy}) and the cache-hit