turbine-orm 0.40.1 → 0.41.0

package/dist/query/builder.js

@@ -12,13 +12,16 @@
  */
 import { postgresDialect } from '../dialect.js';
 import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError } from '../errors.js';
+import { missingIndexForRelation, schemaHasIndexInfo } from '../index-advisor.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
-import { camelToSnake, snakeToCamel } from '../schema.js';
+import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
-import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, stripFields, } from './batched-loader.js';
+import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
+import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import * as relationsMod from './relations.js';
 import { LRUCache, ownLookup, parseDbDate, sqlToPreparedName } from './utils.js';
+import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
 /**
@@ -143,6 +146,34 @@ function cacheParamsEqual(a, b) {
     }
     return true;
 }
+/**
+ * Return `args` with any Prisma compound-unique selector in `args.where`
+ * expanded to its column conjunction (see {@link expandCompoundUniqueWhere}).
+ * Returns the same `args` reference when nothing expands, so untouched queries
+ * are byte-identical. Generic so it serves every unique-`where` arg shape.
+ */
+function maybeExpandCompoundUnique(meta, args) {
+    const where = args.where;
+    if (!where)
+        return args;
+    const expanded = expandCompoundUniqueWhere(meta, where);
+    return expanded === where ? args : { ...args, where: expanded };
+}
+/**
+ * Whether a relation `with`-clause `orderBy` carries no actual ordering: an
+ * empty array, or an object with no non-`undefined` own keys. Used by
+ * {@link QueryInterface.applyStableRelationOrder} so an explicit (non-empty)
+ * orderBy is never overwritten while an empty `{}` / `[]` still gets the
+ * synthesized PK order.
+ */
+function isEmptyOrderBy(orderBy) {
+    if (Array.isArray(orderBy))
+        return orderBy.length === 0;
+    if (orderBy && typeof orderBy === 'object') {
+        return Object.values(orderBy).every((v) => v === undefined);
+    }
+    return orderBy === undefined || orderBy === null;
+}
 // biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 export class QueryInterface {
     pool;
@@ -176,8 +207,16 @@ export class QueryInterface {
      */
     sqlCacheEnabled;
     dialect;
-    /** Client-level default relation-loading strategy ('join' unless configured). */
+    /**
+     * Client-level default relation-loading strategy. When nothing is configured
+     * this is `'auto'` (the implicit default): per-relation, keep the single-
+     * statement join unless the introspected metadata proves a probe is unindexed,
+     * in which case that relation falls back to the batched loader. An explicit
+     * `'join'`/`'batched'` (client or query level) always wins.
+     */
     relationLoadStrategy;
+    /** Client-level default for {@link applyStableRelationOrder} (off unless configured). */
+    stableRelationOrder;
     /** Nested-relation JSON encoding: 'object' (default) or 'positional'. */
     jsonEncoding;
     /**
@@ -208,8 +247,6 @@ export class QueryInterface {
      * must never receive this schema's `::"enum"` cast (see enumTypeForColumn).
      */
     crossSchemaTypeColumns;
-    /** Tracks tables that have already triggered a deep-with warning (one-time) */
-    deepWithWarned = new Set();
     /**
      * Per-table memo of date columns keyed by their camelCase FIELD name.
      * `meta.dateColumns` is keyed by raw snake_case column name, which matches
@@ -224,6 +261,15 @@ export class QueryInterface {
     options;
     /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
     currentAction = 'raw';
+    /**
+     * Tags the query events of an in-flight `relationLoadStrategy: 'auto'` query
+     * that engaged the batched fallback (`'auto-batched'`), so observability sees
+     * which queries the auto default re-planned. Same transient-instance-state
+     * caveat as {@link currentAction}: set for the whole auto-split operation and
+     * cleared afterward; a concurrent unrelated query on the same accessor during
+     * that window could read it (a best-effort diagnostic tag, not load-bearing).
+     */
+    currentStrategyTag;
     /**
      * The active query's `skipGlobalFilters` opt-out, set at the top of each
      * `build*` method and read deep in the (synchronous) SQL-build + param-collect
@@ -290,7 +336,8 @@ export class QueryInterface {
         this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
         this.sqlTemplateCache = new LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? postgresDialect;
-        this.relationLoadStrategy = options?.relationLoadStrategy ?? 'join';
+        this.relationLoadStrategy = options?.relationLoadStrategy ?? 'auto';
+        this.stableRelationOrder = options?.stableRelationOrder === true;
         this.jsonEncoding = options?.jsonEncoding ?? 'object';
         // Only retain the map when it has at least one entry, so `globalFilters`
         // stays `undefined` (and every merge path a no-op) for the common case.
@@ -456,12 +503,277 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     /**
      * Resolve the effective relation-loading strategy for a query: the per-query
-     * arg wins, then the client-level default, then `'join'`. Only meaningful when
+     * arg wins, then the client-level default, then `'auto'`. Only meaningful when
      * a `with` clause is present; the callers gate on that.
      */
     resolveLoadStrategy(argStrategy) {
         return argStrategy ?? this.relationLoadStrategy;
     }
+    /**
+     * The effective {@link QueryInterfaceOptions.stableRelationOrder} for a query:
+     * the per-query arg wins, then the client-level default (off).
+     */
+    resolveStableOrder(argFlag) {
+        return argFlag ?? this.stableRelationOrder;
+    }
+    /**
+     * Fill a PK-ascending `orderBy` into every to-many `with` relation that has no
+     * explicit one, recursing into nested `with`. Returns a CLONED clause (user
+     * args are never mutated); when nothing needs filling it returns the input
+     * object unchanged, so the byte-identical fast path stays free. Only called
+     * when {@link resolveStableOrder} is true; runs BEFORE `withFingerprint`, so
+     * the two orderings get distinct SQL-cache entries automatically. To-one
+     * relations are single rows (no array to order) and PK-less targets have
+     * nothing stable to order by, so both are left untouched.
+     */
+    applyStableRelationOrder(withClause, table, depth = 0) {
+        if (depth >= 10)
+            return withClause; // parity with the build depth cap
+        const meta = this.schema.tables[table];
+        if (!meta)
+            return withClause;
+        let out;
+        for (const [relName, spec] of Object.entries(withClause)) {
+            if (relName === '_count' || !spec)
+                continue; // `_count` is a count, not a row load
+            const rel = ownLookup(meta.relations, relName);
+            if (!rel)
+                continue; // unknown relation, let the build path surface E005
+            const options = spec === true ? {} : spec;
+            // Recurse first so a nested change alone still clones this level.
+            const nestedWith = options.with;
+            const newNested = nestedWith ? this.applyStableRelationOrder(nestedWith, rel.to, depth + 1) : undefined;
+            const nestedChanged = newNested !== undefined && newNested !== nestedWith;
+            const isToMany = rel.type === 'hasMany' || rel.type === 'manyToMany';
+            const hasOrder = options.orderBy !== undefined && !isEmptyOrderBy(options.orderBy);
+            let synthOrder;
+            if (isToMany && !hasOrder) {
+                const targetMeta = this.schema.tables[rel.to];
+                const pk = targetMeta?.primaryKey ?? [];
+                if (targetMeta && pk.length > 0) {
+                    const pkFields = pk.map((c) => targetMeta.reverseColumnMap[c] ?? c);
+                    synthOrder =
+                        pkFields.length === 1 ? { [pkFields[0]]: 'asc' } : pkFields.map((f) => ({ [f]: 'asc' }));
+                }
+            }
+            if (!synthOrder && !nestedChanged)
+                continue; // nothing to change, keep the ref
+            out ??= { ...withClause };
+            const clonedSpec = { ...options };
+            if (synthOrder)
+                clonedSpec.orderBy = synthOrder;
+            if (nestedChanged)
+                clonedSpec.with = newNested;
+            out[relName] = clonedSpec;
+        }
+        return out ?? withClause;
+    }
+    // -------------------------------------------------------------------------
+    // relationLoadStrategy: 'auto', per-relation batched fallback when the
+    // introspected metadata proves a probe is unindexed (finding 13).
+    // -------------------------------------------------------------------------
+    /**
+     * Whether a relation can be served by the batched loader, i.e. all its
+     * correlation keys are single-column (the loader throws E017 on composite
+     * keys). Composite-key relations therefore always stay on the join plan under
+     * `'auto'` (and keep the existing unindexed-probe dev warning).
+     */
+    relationBatchEligible(rel) {
+        if (rel.type === 'manyToMany') {
+            const through = rel.through;
+            if (!through)
+                return false;
+            const pkLen = this.schema.tables[rel.to]?.primaryKey.length ?? 0;
+            return (normalizeKeyColumns(through.sourceKey).length === 1 &&
+                normalizeKeyColumns(through.targetKey).length === 1 &&
+                normalizeKeyColumns(rel.referenceKey).length === 1 &&
+                pkLen === 1);
+        }
+        return normalizeKeyColumns(rel.foreignKey).length === 1 && normalizeKeyColumns(rel.referenceKey).length === 1;
+    }
+    /**
+     * The verdict for one relation SUBTREE under `'auto'`: is any probe in the
+     * subtree unindexed, is EVERY relation in the subtree batched-eligible, and
+     * the first unindexed probe found (for the dev note). Subtree-atomic: a whole
+     * top-level relation falls back only when its entire subtree is eligible,
+     * mirroring the batched loader recursing the same tree.
+     */
+    autoSubtreeVerdict(rel, spec, depth) {
+        let eligible = this.relationBatchEligible(rel);
+        const ownMiss = missingIndexForRelation(this.schema, rel);
+        let unindexed = ownMiss !== null;
+        let miss = ownMiss ?? undefined;
+        const options = spec === true ? {} : spec;
+        const nested = options.with;
+        if (nested && depth < 10) {
+            const targetMeta = this.schema.tables[rel.to];
+            for (const [childName, childSpec] of Object.entries(nested)) {
+                if (!childSpec)
+                    continue;
+                if (childName === '_count') {
+                    const cv = this.autoCountVerdict(childSpec, targetMeta);
+                    eligible = eligible && cv.eligible;
+                    unindexed = unindexed || cv.unindexed;
+                    if (!miss && cv.miss)
+                        miss = cv.miss;
+                    continue;
+                }
+                const childRel = ownLookup(targetMeta?.relations ?? {}, childName);
+                if (!childRel)
+                    continue; // unknown nested relation, let the build path surface it
+                const v = this.autoSubtreeVerdict(childRel, childSpec, depth + 1);
+                eligible = eligible && v.eligible;
+                unindexed = unindexed || v.unindexed;
+                if (!miss && v.miss)
+                    miss = v.miss;
+            }
+        }
+        return { unindexed, eligible, miss };
+    }
+    /** The `_count` verdict under `'auto'`: any counted probe unindexed + all single-key. */
+    autoCountVerdict(countSpec, parentMeta) {
+        if (!parentMeta)
+            return { unindexed: false, eligible: true };
+        let rels;
+        try {
+            rels = resolveCountRelations(parentMeta, countSpec);
+        }
+        catch {
+            return { unindexed: false, eligible: true }; // let the join/loader path surface the error
+        }
+        let unindexed = false;
+        let eligible = true;
+        let miss;
+        for (const rel of rels) {
+            if (!this.relationBatchEligible(rel))
+                eligible = false;
+            const m = missingIndexForRelation(this.schema, rel);
+            if (m) {
+                unindexed = true;
+                miss ??= m;
+            }
+        }
+        return { unindexed, eligible, miss };
+    }
+    /**
+     * Partition a top-level `with` clause under `'auto'`: each relation whose
+     * subtree has a PROVEN unindexed probe AND is fully batched-eligible routes to
+     * `batchedWith`; everything else (indexed, composite-key, unknown) stays in
+     * `joinWith` (byte-identical join). The reserved `_count` key partitions the
+     * same way. Also returns the engaged relations for the dev note.
+     */
+    partitionWithForAuto(withClause) {
+        const joinWith = {};
+        const batchedWith = {};
+        const engaged = [];
+        for (const [key, spec] of Object.entries(withClause)) {
+            if (!spec)
+                continue;
+            if (key === '_count') {
+                const cv = this.autoCountVerdict(spec, this.tableMeta);
+                if (cv.unindexed && cv.eligible) {
+                    batchedWith[key] = spec;
+                    engaged.push({ relation: '_count', miss: cv.miss });
+                }
+                else {
+                    joinWith[key] = spec;
+                }
+                continue;
+            }
+            const rel = ownLookup(this.tableMeta.relations, key);
+            if (!rel) {
+                joinWith[key] = spec; // unknown relation, let the join path surface E005
+                continue;
+            }
+            const v = this.autoSubtreeVerdict(rel, spec, 0);
+            if (v.unindexed && v.eligible) {
+                batchedWith[key] = spec;
+                engaged.push({ relation: key, miss: v.miss });
+            }
+            else {
+                joinWith[key] = spec;
+            }
+        }
+        return { joinWith, batchedWith, engaged };
+    }
+    /**
+     * Plan the `'auto'` split for a query's `with` clause: normalize stable order,
+     * partition, and return the split ONLY when at least one relation falls back
+     * to batched. Returns `null` (→ run the plain join path, byte-identical, same
+     * cache keys) when there is no DB-backed index metadata or nothing qualifies.
+     */
+    planAuto(withArg, stableFlag) {
+        // No DB-backed index info (code-first / defineSchema-only) → cannot PROVE any
+        // probe is unindexed, so 'auto' behaves exactly like 'join'.
+        if (!schemaHasIndexInfo(this.schema))
+            return null;
+        const withClause = this.resolveStableOrder(stableFlag)
+            ? this.applyStableRelationOrder(withArg, this.table)
+            : withArg;
+        const split = this.partitionWithForAuto(withClause);
+        if (Object.keys(split.batchedWith).length === 0)
+            return null;
+        return split;
+    }
+    /** Dev-only once-per-relation note that `'auto'` engaged the batched fallback. */
+    emitAutoNotes(engaged) {
+        if (process.env.NODE_ENV === 'production')
+            return;
+        for (const e of engaged) {
+            if (!shouldWarnOnce(WARN_NS.autoStrategy, `${this.table}.${e.relation}`))
+                continue;
+            const probe = e.miss
+                ? `probe "${e.miss.table}"(${e.miss.columns.join(', ')}) has no covering index`
+                : 'a probe in its subtree has no covering index';
+            console.warn(`[turbine] auto strategy: relation "${e.relation}" on "${this.table}" loads batched (${probe}). ` +
+                "Create the covering index (or set `relationLoadStrategy: 'join'` to force the single-statement " +
+                'plan); run `npx turbine doctor` for the exact CREATE INDEX SQL.');
+        }
+    }
+    /**
+     * Execute a findMany/findUnique `'auto'` split: run the base query with the
+     * residual `joinWith` (plus any parent stitch keys the batched subset needs),
+     * then load `batchedWith` via the batched loader and stitch. `single` returns
+     * the first entity (findUnique) instead of the array. Output is identical in
+     * shape to the pure join plan.
+     */
+    async runAutoSplit(args, split, single) {
+        this.emitAutoNotes(split.engaged);
+        const { joinWith, batchedWith } = split;
+        // Scope-rule parity with the batched strategy: reject nested pick ordering
+        // on the batched subset up front.
+        rejectNestedPickOrder(batchedWith);
+        const skip = args.skipGlobalFilters;
+        const needed = neededParentKeyFields(this.tableMeta, batchedWith);
+        const proj = includeKeysForBatching(args.select, args.omit, needed);
+        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.
+        const baseArgs = {
+            ...args,
+            with: hasJoin ? joinWith : undefined,
+            select: proj.select,
+            omit: proj.omit,
+            relationLoadStrategy: 'join',
+        };
+        this.currentStrategyTag = 'auto-batched';
+        try {
+            const deferred = single
+                ? this.buildFindUnique(baseArgs)
+                : this.buildFindMany(baseArgs);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            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), entities, batchedWith, args.timeout);
+            }
+            stripFields(entities, proj.strip);
+            return single ? (entities[0] ?? null) : entities;
+        }
+        finally {
+            this.currentStrategyTag = undefined;
+        }
+    }
     /**
      * Build the {@link RelationLoadContext} the batched loader needs, closing over
      * this interface's pool/dialect/executor. Child readers are constructed on the
@@ -513,7 +825,12 @@ export class QueryInterface {
      * from the returned rows, so the shape matches the join strategy exactly.
      */
     async runFindManyBatched(args) {
-        const withClause = args.with;
+        // Stable relation order (opt-in): the batched loader forwards each relation's
+        // orderBy into its follow-up query, so filling the synthesized PK order here
+        // makes the batched output deterministic exactly like the join path.
+        const withClause = this.resolveStableOrder(args.stableRelationOrder)
+            ? this.applyStableRelationOrder(args.with, this.table)
+            : args.with;
         // Scope-rule parity with the join strategy (which throws at SQL build):
         // reject nested pick-row ordering BEFORE the base query so acceptance
         // never depends on how many rows come back.
@@ -669,7 +986,17 @@ export class QueryInterface {
         if (!onQuery)
             return;
         try {
-            onQuery({ sql, params, duration, model: this.table, action, rows, timestamp: new Date(), error });
+            onQuery({
+                sql,
+                params,
+                duration,
+                model: this.table,
+                action,
+                rows,
+                timestamp: new Date(),
+                error,
+                strategy: this.currentStrategyTag,
+            });
         }
         catch {
             // Listener errors must never crash a query
@@ -808,8 +1135,15 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     async findUnique(args) {
         return this.executeWithMiddleware('findUnique', args, async () => {
-            if (args.with && this.resolveLoadStrategy(args.relationLoadStrategy) === 'batched') {
-                return this.runFindUniqueBatched(args);
+            if (args.with) {
+                const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
+                if (strategy === 'batched')
+                    return this.runFindUniqueBatched(args);
+                if (strategy === 'auto') {
+                    const split = this.planAuto(args.with, args.stableRelationOrder);
+                    if (split)
+                        return this.runAutoSplit(args, split, true);
+                }
             }
             const deferred = this.buildFindUnique(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
@@ -823,7 +1157,10 @@ export class QueryInterface {
      * strategy's shape for the one row.
      */
     async runFindUniqueBatched(args) {
-        const withClause = args.with;
+        // Stable relation order (opt-in), see runFindManyBatched.
+        const withClause = this.resolveStableOrder(args.stableRelationOrder)
+            ? this.applyStableRelationOrder(args.with, this.table)
+            : args.with;
         // Same scope-rule parity as runFindManyBatched: reject before querying.
         rejectNestedPickOrder(withClause);
         const needed = neededParentKeyFields(this.tableMeta, withClause);
@@ -841,6 +1178,16 @@ export class QueryInterface {
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindUnique(args) {
         this.currentSkip = 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);
+        // 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)) {
+            const normalized = this.applyStableRelationOrder(args.with, this.table);
+            if (normalized !== args.with)
+                args = { ...args, with: normalized };
+        }
         const includePii = args.includePii === true;
         const columnsList = this.resolveColumns(args.select, args.omit, includePii);
         // A global filter turns the where into `{ AND: [...] }`, which the
@@ -958,16 +1305,22 @@ export class QueryInterface {
         if (process.env.NODE_ENV !== 'production') {
             if (args?.with) {
                 const depth = this.measureWithDepth(args.with);
-                if (depth > 5 && !this.deepWithWarned.has(this.table)) {
-                    this.deepWithWarned.add(this.table);
+                if (depth > 5 && shouldWarnOnce(WARN_NS.deepWith, this.table)) {
                     console.warn(`[turbine] Deep with clause (depth ${depth}) on "${this.tableMeta.name}" — ` +
                         'consider splitting into separate queries for better performance.');
                 }
             }
         }
         return this.executeWithMiddleware('findMany', (args ?? {}), async () => {
-            if (args?.with && this.resolveLoadStrategy(args.relationLoadStrategy) === 'batched') {
-                return this.runFindManyBatched(args);
+            if (args?.with) {
+                const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
+                if (strategy === 'batched')
+                    return this.runFindManyBatched(args);
+                if (strategy === 'auto') {
+                    const split = this.planAuto(args.with, args.stableRelationOrder);
+                    if (split)
+                        return this.runAutoSplit(args, split, false);
+                }
             }
             const deferred = this.buildFindMany(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
@@ -1076,6 +1429,14 @@ export class QueryInterface {
     // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindMany(args) {
         this.currentSkip = 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.
+        if (args?.with && this.resolveStableOrder(args.stableRelationOrder)) {
+            const normalized = this.applyStableRelationOrder(args.with, this.table);
+            if (normalized !== args.with)
+                args = { ...args, with: normalized };
+        }
         // `distinct` + relation orderBy is refused up front (E003): the distinct
         // path re-orders in an outer wrapper (`... AS "<table>_distinct" ORDER BY
         // <userOrder>`) where a correlated relation subquery (pick-row, `_count`,
@@ -1357,10 +1718,20 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     async findFirst(args) {
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
-            if (args?.with && this.resolveLoadStrategy(args.relationLoadStrategy) === 'batched') {
+            if (args?.with) {
+                const strategy = this.resolveLoadStrategy(args.relationLoadStrategy);
                 // findFirst is findMany + LIMIT 1: batch the single base row, then load.
-                const rows = await this.runFindManyBatched({ ...args, limit: 1 });
-                return (rows[0] ?? null);
+                if (strategy === 'batched') {
+                    const rows = await this.runFindManyBatched({ ...args, limit: 1 });
+                    return (rows[0] ?? null);
+                }
+                if (strategy === 'auto') {
+                    const split = this.planAuto(args.with, args.stableRelationOrder);
+                    if (split) {
+                        const rows = (await this.runAutoSplit({ ...args, limit: 1 }, split, false));
+                        return (rows[0] ?? null);
+                    }
+                }
             }
             const deferred = this.buildFindFirst(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);

package/dist/query/compound-unique.d.ts

@@ -0,0 +1,49 @@
+/**
+ * turbine-orm — Prisma-style compound-unique `where` selectors.
+ *
+ * Prisma lets a `findUnique`-family `where` address a multi-column unique
+ * constraint through a single synthetic key holding the member columns:
+ *
+ * ```ts
+ * db.members.findUnique({ where: { orgId_userId: { orgId: 1, userId: 7 } } })
+ * // ≡ where: { orgId: 1, userId: 7 }  →  WHERE "org_id" = $1 AND "user_id" = $2
+ * ```
+ *
+ * {@link expandCompoundUniqueWhere} rewrites such a selector into the equivalent
+ * column conjunction BEFORE the where is fingerprinted / SQL-compiled, so the
+ * template cache only ever sees the canonical expanded form (no new cache-key
+ * segment, and the expanded shape shares its entry with the spelled-out form).
+ *
+ * Selector NAMES come from the table metadata, in priority order:
+ *   1. a composite primary key (length ≥ 2);
+ *   2. each composite `uniqueColumns` entry (introspected composite UNIQUE
+ *      constraints);
+ *   3. each composite UNIQUE index in `indexes` (`unique && !docPath`, the ONLY
+ *      composite-unique source a `defineSchema` code-first client has, since
+ *      `defineSchema` records single-column uniques in `uniqueColumns` and
+ *      composite uniques as declared unique indexes).
+ *
+ * For every column set two lookup names are registered (both mapping to the same
+ * ordered FIELD list): the underscore join of the camelCase FIELD names
+ * (`orgId_userId`, Prisma's default) and, when different, the underscore join of
+ * the raw snake_case column names (`org_id_user_id`).
+ *
+ * Collision rules (deterministic, documented):
+ *   - a synthetic name equal to a real field / column / relation name is never
+ *     registered (real members always win);
+ *   - two DIFFERENT column sets producing the same name drop that name entirely.
+ *
+ * The map is pure metadata, so it is computed lazily and memoized per
+ * {@link TableMetadata} in a module-level `WeakMap`.
+ */
+import type { TableMetadata } from '../schema.js';
+/**
+ * Expand any Prisma compound-unique selector keys in `where` into their column
+ * conjunction. Returns the SAME object reference when nothing expands (the
+ * byte-identical fast path), else a shallow clone with the selector keys
+ * replaced. A selector key whose members do not exactly match the constraint's
+ * fields throws a {@link ValidationError} (E003) naming the required members; a
+ * non-selector unknown key is left untouched to fall through to the existing
+ * unknown-column error at SQL-build time.
+ */
+export declare function expandCompoundUniqueWhere(meta: TableMetadata, where: Record<string, unknown>): Record<string, unknown>;

package/dist/query/deferred.d.ts

@@ -55,6 +55,14 @@ export interface QueryEvent {
     rows: number;
     timestamp: Date;
     error?: Error;
+    /**
+     * Set to `'auto-batched'` on the statements of a query whose
+     * `relationLoadStrategy: 'auto'` engaged the per-relation batched fallback
+     * (the base statement and every batched follow-up). Absent for the plain join
+     * path, explicit `'join'`/`'batched'`, and non-auto queries, so production
+     * observability can see exactly which queries the auto default re-planned.
+     */
+    strategy?: 'auto-batched';
 }
 export type QueryEventListener = (event: QueryEvent) => void;
 /** Options passed from TurbineClient to QueryInterface */
@@ -137,6 +145,16 @@ export interface QueryInterfaceOptions {
      * silently; see the PowDB docs).
      */
     relationLoadStrategy?: RelationLoadStrategy;
+    /**
+     * When `true`, every to-many `with` relation that carries no explicit
+     * `orderBy` is loaded ordered by the target table's primary key ascending, so
+     * unordered child arrays come back in a deterministic order (json_agg / batched
+     * loaders otherwise leave child-array order engine-dependent). An explicit
+     * per-relation `orderBy` always wins, and a per-query `stableRelationOrder`
+     * overrides this default. Default `false`; when off the emitted SQL is
+     * byte-identical to before. SQL engines only (PowDB keeps its own defaults).
+     */
+    stableRelationOrder?: boolean;
     /**
      * How nested-relation subqueries encode each row's JSON: `'object'` (default,
      * `json_build_object`) or `'positional'` (`json_build_array`, key-less — see

package/dist/query/relations.js

@@ -18,10 +18,9 @@ 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 { ownLookup } from './utils.js';
+import { hasWarnedOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
-/** Relations already warned about missing FK indexes (once per process, dev only). */
-const unindexedRelationWarned = new Set();
 /**
  * Resolve select/omit options into a list of snake_case column names.
  * Returns null if neither is provided (meaning all columns).
@@ -1326,10 +1325,13 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // instead of letting the slowness look like an ORM problem.
     if (process.env.NODE_ENV !== 'production') {
         const warnKey = `${relDef.from}.${relDef.name}`;
-        if (!unindexedRelationWarned.has(warnKey)) {
+        // Compute the (potentially costly) probe only for a key not yet warned, and
+        // claim the key through the process-wide registry ONLY when we actually warn,
+        // so a dual-package / HMR-reevaluated second module copy cannot re-warn the
+        // same relation, and indexed relations never consume the dedupe cap.
+        if (!hasWarnedOnce(WARN_NS.unindexedRelation, warnKey)) {
             const miss = missingIndexForRelation(qi.schema, relDef);
-            if (miss) {
-                unindexedRelationWarned.add(warnKey);
+            if (miss && shouldWarnOnce(WARN_NS.unindexedRelation, warnKey)) {
                 console.warn(`[turbine] Relation "${relDef.name}" on "${relDef.from}" probes ` +
                     `"${miss.table}"(${miss.columns.join(', ')}) which has no covering index — ` +
                     `each parent row scans the full table. Fix: ${miss.createSql}; ` +