turbine-orm 0.75.0 → 0.76.0

package/dist/query/relations.js

@@ -18,7 +18,7 @@ import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { resolveCountRelations } from './batched-loader.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, MAX_NAMED_ORDER_KEYS, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
 import { assertDirectionToken, assertOrderDirection } from './types.js';
-import { canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelation, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, unknownFieldMessage, } from './utils.js';
+import { availableClause, canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelation, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, unknownFieldMessage, } from './utils.js';
 import { hasWarnedOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -175,6 +175,46 @@ export function resolveProjection(qi, table, meta, select, omit, includePii) {
 export function resolveColumns(qi, select, omit, includePii) {
     return resolveProjection(qi, qi.table, qi.tableMeta, select, omit, includePii);
 }
+/**
+ * The one place `with: { posts: true }` becomes an options object.
+ *
+ * `true` is not a third kind of relation spec, it is shorthand for "include
+ * this relation with no options", i.e. `{}`. Every walker over a `with` tree
+ * needs the same reading of it, and there are SIX of them: the build path
+ * ({@link buildRelationSubquery} / {@link buildManyToManySubquery}), the
+ * param-collect mirror ({@link collectRelationSubqueryParams}), the cache
+ * fingerprint ({@link withFingerprint}), the decode shape
+ * ({@link buildRelationShape}), the projection resolver
+ * ({@link resolveTargetColumns}) and the flatten planner.
+ *
+ * Each of them USED TO spell the shorthand out for itself, with a
+ * `spec !== true && spec.x` guard per option on the build side and a single
+ * `if (spec === true) return` early exit on the collect side. Those two
+ * readings are not the same, and the difference was a live bug: since global
+ * filters reached relation subqueries the build path has emitted the target's
+ * filter UNCONDITIONALLY (a `with` must never surface rows the filter hides),
+ * while the collect path's early exit returned before pushing its params. A
+ * value-bearing filter on a relation target therefore compiled a `$N` that no
+ * value backed, and `with: { posts: true }` failed at bind time with
+ * "bind message supplies N parameters, but prepared statement requires N+1"
+ * while the identical query written `with: { posts: {} }` worked.
+ *
+ * Returning ONE frozen empty options object removes the branch instead of
+ * duplicating it: below this call there is no `true` case left to keep in
+ * sync, so a future option added to one walker cannot be forgotten by the
+ * shorthand in another. Frozen and shared because it is read-only by
+ * construction (every consumer only reads `select`/`omit`/`where`/`orderBy`/
+ * `limit`/`with`), so one instance serves every call and allocates nothing on
+ * the hot path.
+ */
+const EMPTY_WITH_OPTIONS = Object.freeze({});
+/**
+ * Read a relation spec as options. See {@link EMPTY_WITH_OPTIONS} for why this
+ * is a shared authority rather than a guard repeated per walker.
+ */
+export function relationOptions(spec) {
+    return spec === true ? EMPTY_WITH_OPTIONS : spec;
+}
 /**
  * Produce a fingerprint for a `with` clause tree. Recursion mirrors
  * buildSelectWithRelations / buildRelationSubquery.
@@ -211,11 +251,7 @@ export function withFingerprint(qi, withClause, table, depth = 0) {
             parts.push(`unknown:${relName}`);
             continue;
         }
-        if (spec === true) {
-            parts.push(relName);
-            continue;
-        }
-        const opts = spec;
+        const opts = relationOptions(spec);
         const subParts = [];
         // select/omit shape
         if (opts.select) {
@@ -293,8 +329,10 @@ export function collectWithParams(qi, withClause, params, table, flattenPlan) {
  * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
  */
 export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentRef, depth = 0) {
-    if (spec === true)
-        return; // No params for default include
+    // `true` IS `{}` (see {@link relationOptions}). This used to be an early
+    // `return`, which skipped the target's global-filter params the build path
+    // always pushes.
+    const opts = relationOptions(spec);
     const targetTable = relDef.to;
     const targetMeta = qi.schema.tables[targetTable];
     if (!targetMeta)
@@ -309,19 +347,19 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
     //   orderBy params → where params → limit param → nested-with params
     //   (always, both paths).
     if (relDef.type === 'manyToMany') {
-        const m2mOrderEntries = spec.orderBy ? orderByEntries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+        const m2mOrderEntries = opts.orderBy ? orderByEntries(opts.orderBy).filter(([, dir]) => dir !== undefined) : [];
         if (nativeOrderPath && m2mOrderEntries.length > 0) {
             collectRelationOrderParams(qi, targetTable, targetMeta, m2mOrderEntries, params);
         }
-        if (spec.where) {
-            whereMod.collectAliasWhereParams(qi, targetTable, targetMeta, spec.where, params);
+        if (opts.where) {
+            whereMod.collectAliasWhereParams(qi, targetTable, targetMeta, opts.where, params);
         }
         whereMod.collectTargetGlobalFilterAlias(qi, targetTable, params);
-        if (spec.limit !== undefined && !qi.dialect.inlineLimitOffset) {
-            params.push(qi.paginationValue(spec.limit, 'relation limit'));
+        if (opts.limit !== undefined && !qi.dialect.inlineLimitOffset) {
+            params.push(qi.paginationValue(opts.limit, 'relation limit'));
         }
-        if (spec.with) {
-            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
+        if (opts.with) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
                 const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
                 if (!nestedRelDef)
                     continue;
@@ -331,12 +369,12 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
         return;
     }
     // Mirrors buildRelationSubquery's willWrap: `orderBy: {}` is treated as absent.
-    const relOrderEntries = spec.orderBy ? orderByEntries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const relOrderEntries = opts.orderBy ? orderByEntries(opts.orderBy).filter(([, dir]) => dir !== undefined) : [];
     const hasOrder = relOrderEntries.length > 0;
-    const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
+    const willWrap = relDef.type === 'hasMany' && (opts.limit !== undefined || hasOrder);
     // Non-wrapped path: nested relations BEFORE where/limit
-    if (!willWrap && spec.with) {
-        for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
+    if (!willWrap && opts.with) {
+        for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
             const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
             if (!nestedRelDef)
                 continue;
@@ -350,8 +388,8 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
         collectRelationOrderParams(qi, targetTable, targetMeta, relOrderEntries, params);
     }
     // where params, mirrors buildAliasWhere push order
-    if (spec.where) {
-        whereMod.collectAliasWhereParams(qi, targetTable, targetMeta, spec.where, params);
+    if (opts.where) {
+        whereMod.collectAliasWhereParams(qi, targetTable, targetMeta, opts.where, params);
     }
     // Global filter on the target, mirrors targetGlobalFilterAlias in
     // buildRelationSubquery (pushed after spec.where, before limit).
@@ -360,12 +398,12 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
     // buildRelationSubquery). belongsTo/hasOne ignore limit (always LIMIT 1), so
     // pushing one here would orphan a param and desync the collect path.
     // `limit: 0` pushes (LIMIT 0 is honored), so check !== undefined.
-    if (relDef.type === 'hasMany' && spec.limit !== undefined && !qi.dialect.inlineLimitOffset) {
-        params.push(qi.paginationValue(spec.limit, 'relation limit'));
+    if (relDef.type === 'hasMany' && opts.limit !== undefined && !qi.dialect.inlineLimitOffset) {
+        params.push(qi.paginationValue(opts.limit, 'relation limit'));
     }
     // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
-    if (willWrap && spec.with) {
-        for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
+    if (willWrap && opts.with) {
+        for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
             const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
             if (!nestedRelDef)
                 continue;
@@ -734,13 +772,12 @@ export function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lat
         // landing here on such a table is an orderBy VALUE of the wrong shape on a
         // scalar column, which deserves to be named rather than reported as a
         // missing relation.
-        const known = Object.keys(ownerMeta.relations);
         const isColumn = resolveColumnName(ownerMeta, relName) !== undefined;
         throw new RelationError(isColumn
             ? `[turbine] orderBy on "${ownerTable}.${relName}" got a relation-shaped value, but "${relName}" is a ` +
                 `column. Order a column with 'asc' / 'desc' (or { sort, nulls }); the object form is for relations.`
             : `[turbine] Unknown relation "${relName}" in orderBy on table "${ownerTable}". ` +
-                (known.length > 0 ? `Available: ${known.join(', ')}` : `"${ownerTable}" has no relations.`));
+                availableClause(Object.keys(ownerMeta.relations), `"${ownerTable}" has no relations.`));
     }
     // Pick-row ordering (`{ pick, by }`): order by a value from ONE related
     // row: a correlated scalar subquery with its own ORDER BY … LIMIT 1.
@@ -1319,8 +1356,9 @@ export function parseNestedRow(qi, row, table, fromJson = false) {
  * second implementation.
  */
 export function resolveTargetColumns(qi, spec, targetMeta, includePii, targetTable = targetMeta.name) {
-    const select = spec === true ? undefined : spec.select;
-    const omit = spec === true ? undefined : spec.omit;
+    const opts = relationOptions(spec);
+    const select = opts.select;
+    const omit = opts.omit;
     return resolveProjection(qi, targetTable, targetMeta, select, omit, includePii) ?? targetMeta.allColumns;
 }
 /**
@@ -1475,8 +1513,9 @@ export function buildRelationShape(qi, relDef, spec, parentMeta, includePii) {
     const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     const keys = targetColumns.map((col) => targetMeta.reverseColumnMap[col] ?? snakeToCamel(col));
     const nested = {};
-    if (spec !== true && spec.with) {
-        for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
+    const nestedWith = relationOptions(spec).with;
+    if (nestedWith) {
+        for (const [nestedRelName, nestedSpec] of sortedEntries(nestedWith)) {
             const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
             if (!nestedRelDef)
                 continue;
@@ -1713,15 +1752,13 @@ function planFlattenNode(qi, counter, relName, relDef, spec, depth, path, includ
             : `its correlation column(s) on "${relDef.to}" are not provably unique (no primary key, ` +
                 'unique constraint or non-partial unique index covers them), so a join could multiply parent rows');
     }
-    const opts = spec === true ? undefined : spec;
-    if (opts) {
-        if (opts.limit !== undefined)
-            return decline('it declares a `limit`');
-        if (opts.orderBy && orderByEntries(opts.orderBy).some(([, dir]) => dir !== undefined)) {
-            return decline('it declares an `orderBy`');
-        }
+    const opts = relationOptions(spec);
+    if (opts.limit !== undefined)
+        return decline('it declares a `limit`');
+    if (opts.orderBy && orderByEntries(opts.orderBy).some(([, dir]) => dir !== undefined)) {
+        return decline('it declares an `orderBy`');
     }
-    const nestedEntries = opts?.with ? sortedEntries(opts.with) : [];
+    const nestedEntries = opts.with ? sortedEntries(opts.with) : [];
     for (const [nestedRelName] of nestedEntries) {
         if (nestedRelName === '_count')
             return decline('its nested `with` uses `_count`');
@@ -1922,8 +1959,9 @@ function emitFlattenInner(qi, node, params, innerSelects, innerJoins, innerWhere
     // than dropping the parent row, matching what the correlated subquery's
     // `LIMIT 1` did when it returned NULL.
     const filters = innerWhere;
-    if (node.spec !== true && node.spec.where) {
-        const extra = whereMod.buildAliasWhere(qi, targetTable, targetMeta, srcAlias, node.spec.where, params);
+    const nodeWhere = relationOptions(node.spec).where;
+    if (nodeWhere) {
+        const extra = whereMod.buildAliasWhere(qi, targetTable, targetMeta, srcAlias, nodeWhere, params);
         if (extra)
             filters.push(extra);
     }
@@ -1989,8 +2027,9 @@ function projectFlattenNode(qi, node, outerAlias, selectSink) {
 }
 /** Param-collect mirror of {@link emitFlattenNode}. */
 export function collectFlattenNodeParams(qi, node, params) {
-    if (node.spec !== true && node.spec.where) {
-        whereMod.collectAliasWhereParams(qi, node.targetTable, node.targetMeta, node.spec.where, params);
+    const nodeWhere = relationOptions(node.spec).where;
+    if (nodeWhere) {
+        whereMod.collectAliasWhereParams(qi, node.targetTable, node.targetMeta, nodeWhere, params);
     }
     whereMod.collectTargetGlobalFilterAlias(qi, node.targetTable, params);
     for (const slot of node.slots) {
@@ -2139,7 +2178,7 @@ export function buildSelectWithRelations(qi, table, withClause, params, columnsL
         const relDef = ownLookup(meta.relations, relName);
         if (!relDef) {
             throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${table}". ` +
-                `Available: ${Object.keys(meta.relations).join(', ')}`);
+                availableClause(Object.keys(meta.relations), `"${table}" has no relations.`));
         }
         // `relationLoadStrategy: 'flatten'`: an eligible to-one relation becomes a
         // LEFT JOIN + prefixed scalar projection instead of a per-parent-row
@@ -2273,6 +2312,11 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     const targetMeta = qi.schema.tables[targetTable];
     if (!targetMeta)
         throw new RelationError(`[turbine] Unknown relation target "${targetTable}"`);
+    // `true` IS `{}`; below this line there is no `true` case, which is what
+    // keeps this walk and collectRelationSubqueryParams reading one shape.
+    // The raw `spec` is still what crosses the dialect seam below, since
+    // RelationSubqueryContext is a published contract.
+    const opts = relationOptions(spec);
     // Dev-only: correlated relation loading probes the child table once per parent
     // row, so a missing FK index multiplies into per-parent full-table scans (a
     // batched-loader ORM pays the same missing index only once, which is why
@@ -2321,9 +2365,33 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
             depth: currentDepth,
             path: currentPath,
             quote: (name) => qi.q(name),
-            buildWhere: (whereAlias) => (spec !== true && spec.where
-                ? whereMod.buildAliasWhere(qi, targetTable, targetMeta, whereAlias, spec.where, params)
-                : '') ?? '',
+            // The relation target's WHERE, which is the caller's `spec.where` AND the
+            // target table's GLOBAL FILTER. Both, not just the first.
+            //
+            // A dialect that overrides buildRelationSubquery takes over the whole
+            // subquery, so the generic builder returns at this seam BEFORE it would
+            // have applied targetGlobalFilterAlias itself. The override cannot apply
+            // the filter on its own: RelationSubqueryContext deliberately hands it no
+            // BuilderCtx, so `targetGlobalFilterAlias` is not reachable from a dialect
+            // file. That left SQL Server's `FOR JSON PATH` path emitting a correlation
+            // predicate and nothing else, so a `with` returned rows a tenancy or
+            // soft-delete filter is supposed to hide, while the collect mirror still
+            // pushed the filter's params. Wrong rows AND an orphan param, on every
+            // spec shape.
+            //
+            // Folding it in here rather than at each override keeps ONE authority for
+            // "what does this relation's WHERE contain", and lands the params exactly
+            // where collectRelationSubqueryParams already expects them: after
+            // spec.where, before the limit.
+            buildWhere: (whereAlias) => {
+                const userWhere = (opts.where
+                    ? whereMod.buildAliasWhere(qi, targetTable, targetMeta, whereAlias, opts.where, params)
+                    : '') ?? '';
+                const gf = whereMod.targetGlobalFilterAlias(qi, targetTable, whereAlias, params);
+                if (userWhere && gf)
+                    return `${userWhere} AND ${gf}`;
+                return userWhere || gf || '';
+            },
             recurse: (nRelDef, nSpec, nParent, nDepth, nPath) => buildRelationSubquery(qi, nRelDef, nSpec, params, nParent, aliasCounter, nDepth, nPath, includePii),
         });
     }
@@ -2335,8 +2403,8 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // An orderBy with no defined entries (`orderBy: {}`) is treated as absent -
     // it must neither trigger the wrap (dropping nested relations) nor render a
     // dangling `ORDER BY `. `limit: 0` is meaningful (LIMIT 0) and DOES wrap.
-    const relOrderEntries = spec !== true && spec.orderBy ? orderByEntries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
-    const willWrap = relDef.type === 'hasMany' && spec !== true && (spec.limit !== undefined || relOrderEntries.length > 0);
+    const relOrderEntries = opts.orderBy ? orderByEntries(opts.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const willWrap = relDef.type === 'hasMany' && (opts.limit !== undefined || relOrderEntries.length > 0);
     // manyToMany takes a dedicated JOIN-through-junction path. Nested relations,
     // where, orderBy, and select/omit are handled there (the target alias is the
     // row source, exactly like hasMany), so short-circuit before the hasMany logic.
@@ -2344,12 +2412,12 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
         return buildManyToManySubquery(qi, relDef, spec, params, parentRef, aliasCounter, currentDepth, currentPath, alias, targetMeta, targetColumns, includePii);
     }
     // Nested relations, only in the non-wrapped path (wrapped path builds them separately)
-    if (!willWrap && spec !== true && spec.with) {
-        for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
+    if (!willWrap && opts.with) {
+        for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
             const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
             if (!nestedRelDef) {
                 throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
-                    `Available: ${Object.keys(targetMeta.relations).join(', ')}`);
+                    availableClause(Object.keys(targetMeta.relations), `"${relDef.to}" has no relations.`));
             }
             // Recursively build nested subquery, passing THIS alias as the parent reference
             const nestedSubquery = buildRelationSubquery(qi, nestedRelDef, nestedSpec, params, alias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name], includePii);
@@ -2386,8 +2454,8 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     }
     // Additional filters, full scalar where surface (equality, null, operator
     // objects, OR/AND/NOT), properly parameterized against this alias.
-    if (spec !== true && spec.where) {
-        const extra = whereMod.buildAliasWhere(qi, targetTable, targetMeta, alias, spec.where, params);
+    if (opts.where) {
+        const extra = whereMod.buildAliasWhere(qi, targetTable, targetMeta, alias, opts.where, params);
         if (extra)
             whereClause += ` AND ${extra}`;
     }
@@ -2404,8 +2472,8 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // (and shifts every later placeholder by one). To-one relations ignore limit.
     // `limit: 0` is honored (LIMIT 0 → empty array), so check !== undefined.
     let limitClause = '';
-    if (relDef.type === 'hasMany' && spec !== true && spec.limit !== undefined) {
-        limitClause = ` LIMIT ${qi.paginationRef(spec.limit, params, 'relation limit')}`;
+    if (relDef.type === 'hasMany' && opts.limit !== undefined) {
+        limitClause = ` LIMIT ${qi.paginationRef(opts.limit, params, 'relation limit')}`;
     }
     if (relDef.type === 'hasMany') {
         // When LIMIT or ORDER BY is used, wrap in a subquery so LIMIT applies to rows
@@ -2418,12 +2486,12 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
             // For the json_build_object, reference the inner alias, only include resolved columns
             const innerJsonPairs = jsonScalarPairs(qi, targetMeta, targetColumns, innerAlias);
             // Build nested relation subqueries referencing innerAlias
-            if (spec !== true && spec.with) {
-                for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
+            if (opts.with) {
+                for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
                     const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
                     if (!nestedRelDef) {
                         throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
-                            `Available: ${Object.keys(targetMeta.relations).join(', ')}`);
+                            availableClause(Object.keys(targetMeta.relations), `"${relDef.to}" has no relations.`));
                     }
                     const nestedSub = buildRelationSubquery(qi, nestedRelDef, nestedSpec, params, innerAlias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name], includePii);
                     const fallback = nestedRelDef.type === 'hasMany' ? qi.dialect.emptyJsonArrayLiteral : qi.dialect.nullJsonLiteral;
@@ -2468,6 +2536,9 @@ export function buildManyToManySubquery(qi, relDef, spec, params, parentRef, ali
     if (!relDef.through) {
         throw new ValidationError(`[turbine] manyToMany relation "${relDef.name}" is missing a \`through\` junction descriptor.`);
     }
+    // `true` IS `{}`; see {@link relationOptions}. Same reading as
+    // buildRelationSubquery and collectRelationSubqueryParams' m2m branch.
+    const opts = relationOptions(spec);
     const targetTable = relDef.to;
     const qTarget = qi.q(targetTable);
     const qJunction = qi.q(relDef.through.table);
@@ -2503,15 +2574,15 @@ export function buildManyToManySubquery(qi, relDef, spec, params, parentRef, ali
     // `orderBy: {}` (no defined entries) is treated as absent: it must not
     // render a dangling `ORDER BY `. Param pushes here land BEFORE the
     // spec.where params, mirrored by collectRelationSubqueryParams' m2m branch.
-    const relOrderEntries = spec !== true && spec.orderBy ? orderByEntries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const relOrderEntries = opts.orderBy ? orderByEntries(opts.orderBy).filter(([, dir]) => dir !== undefined) : [];
     let orderClause = '';
     if (relOrderEntries.length > 0) {
         orderClause = buildRelationOrderClause(qi, targetTable, targetMeta, talias, relOrderEntries, params);
     }
     // Additional WHERE filters on the target, full scalar where surface,
     // properly parameterized against the target alias.
-    if (spec !== true && spec.where) {
-        const extra = whereMod.buildAliasWhere(qi, targetTable, targetMeta, talias, spec.where, params);
+    if (opts.where) {
+        const extra = whereMod.buildAliasWhere(qi, targetTable, targetMeta, talias, opts.where, params);
         if (extra)
             whereClause += ` AND ${extra}`;
     }
@@ -2522,8 +2593,8 @@ export function buildManyToManySubquery(qi, relDef, spec, params, parentRef, ali
         whereClause += ` AND ${gfExtra}`;
     // LIMIT, `limit: 0` is honored (LIMIT 0 → empty array)
     let limitClause = '';
-    if (spec !== true && spec.limit !== undefined) {
-        limitClause = ` LIMIT ${qi.paginationRef(spec.limit, params, 'relation limit')}`;
+    if (opts.limit !== undefined) {
+        limitClause = ` LIMIT ${qi.paginationRef(opts.limit, params, 'relation limit')}`;
     }
     const fromJoin = `FROM ${qTarget} ${talias} JOIN ${qJunction} ${jalias} ON ${joinOn}`;
     // When LIMIT or ORDER BY is present, wrap the joined rows in an inner subquery
@@ -2534,12 +2605,12 @@ export function buildManyToManySubquery(qi, relDef, spec, params, parentRef, ali
             `${fromJoin} WHERE ${whereClause}${orderClause}${limitClause}`;
         const innerJsonPairs = jsonScalarPairs(qi, targetMeta, targetColumns, innerAlias);
         // Nested relations reference the inner alias.
-        if (spec !== true && spec.with) {
-            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
+        if (opts.with) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
                 const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
                 if (!nestedRelDef) {
                     throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
-                        `Available: ${Object.keys(targetMeta.relations).join(', ')}`);
+                        availableClause(Object.keys(targetMeta.relations), `"${relDef.to}" has no relations.`));
                 }
                 const nestedSub = buildRelationSubquery(qi, nestedRelDef, nestedSpec, params, innerAlias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name], includePii);
                 const fallback = nestedRelDef.type === 'belongsTo' || nestedRelDef.type === 'hasOne'
@@ -2554,12 +2625,12 @@ export function buildManyToManySubquery(qi, relDef, spec, params, parentRef, ali
     // Simple path: build the json object pairs directly off the target alias,
     // including any nested relations (correlated to the target alias).
     const jsonPairs = jsonScalarPairs(qi, targetMeta, targetColumns, talias);
-    if (spec !== true && spec.with) {
-        for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
+    if (opts.with) {
+        for (const [nestedRelName, nestedSpec] of sortedEntries(opts.with)) {
             const nestedRelDef = ownLookup(targetMeta.relations, nestedRelName);
             if (!nestedRelDef) {
                 throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
-                    `Available: ${Object.keys(targetMeta.relations).join(', ')}`);
+                    availableClause(Object.keys(targetMeta.relations), `"${relDef.to}" has no relations.`));
             }
             const nestedSub = buildRelationSubquery(qi, nestedRelDef, nestedSpec, params, talias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name], includePii);
             const fallback = nestedRelDef.type === 'belongsTo' || nestedRelDef.type === 'hasOne'

package/dist/query/utils.d.ts

@@ -677,6 +677,19 @@ export declare function unknownFieldMessage(table: string, field: string, meta:
     columnMap: Record<string, string>;
     relations?: Record<string, unknown>;
 }): string;
+/**
+ * The trailing "Available: a, b, c" clause of a name-not-found error, or
+ * `emptySentence` when there is nothing to list.
+ *
+ * The empty branch is the whole reason this exists. Fifteen error sites
+ * interpolated `Object.keys(...).join(', ')` directly, and on a table with no
+ * relations (or a schema with no tables) that renders a dangling
+ * `Available: ` with nothing after the colon, which reads as a broken error
+ * message rather than as an answer. One site already got this right by hand;
+ * the other fourteen are now the same function, so the next one cannot get it
+ * wrong by omission.
+ */
+export declare function availableClause(names: readonly string[], emptySentence: string): string;
 /**
  * The error text for a RELATION named inside `select` / `omit`.
  *

package/dist/query/utils.js

@@ -1419,6 +1419,21 @@ export function unknownFieldMessage(table, field, meta) {
         ` Known columns: ${columns.join(', ') || '(none)'}.` +
         (relations.length ? ` Known relations (valid in \`where\` and \`with\`): ${relations.join(', ')}.` : ''));
 }
+/**
+ * The trailing "Available: a, b, c" clause of a name-not-found error, or
+ * `emptySentence` when there is nothing to list.
+ *
+ * The empty branch is the whole reason this exists. Fifteen error sites
+ * interpolated `Object.keys(...).join(', ')` directly, and on a table with no
+ * relations (or a schema with no tables) that renders a dangling
+ * `Available: ` with nothing after the colon, which reads as a broken error
+ * message rather than as an answer. One site already got this right by hand;
+ * the other fourteen are now the same function, so the next one cannot get it
+ * wrong by omission.
+ */
+export function availableClause(names, emptySentence) {
+    return names.length > 0 ? `Available: ${names.join(', ')}` : emptySentence;
+}
 /**
  * The error text for a RELATION named inside `select` / `omit`.
  *

package/dist/serverless.d.ts

@@ -143,7 +143,7 @@ export type TurbineHttpOptions = Omit<TurbineConfig, 'pool'>;
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
- * import type { TurbineClient } from './generated/turbine';
+ * import type { TurbineClient } from './generated/turbine/index.js';
  * import { SCHEMA } from './generated/turbine/metadata.js';
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });

package/dist/serverless.js

@@ -123,7 +123,7 @@ import { TurbineClient } from './client.js';
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
- * import type { TurbineClient } from './generated/turbine';
+ * import type { TurbineClient } from './generated/turbine/index.js';
  * import { SCHEMA } from './generated/turbine/metadata.js';
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });

package/dist/sqlite.d.ts

@@ -34,7 +34,7 @@
  * - **Case-insensitive matching** uses `COLLATE NOCASE`, which is **ASCII-only**
  *   (no Unicode case folding).
  *
- * ## Example, `:memory:` database
+ * ## Example, `:memory:` database, from a generated schema
  *
  * ```ts
  * import { turbineSqlite } from 'turbine-orm/sqlite';
@@ -44,6 +44,38 @@
  * const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
  * await db.disconnect();
  * ```
+ *
+ * ## Example, SQLite with no Postgres anywhere
+ *
+ * The snippet above needs `turbine generate`, which reads a live **Postgres**
+ * catalog, so it is the wrong starting point if SQLite is your only database.
+ * Describe the schema in code instead: `schemaToSQL` emits the DDL and
+ * `schemaDefToMetadata` derives the runtime metadata (relations included, from
+ * the same `references:`), both pure functions with no database involved.
+ *
+ * ```ts
+ * import { defineSchema, schemaDefToMetadata, schemaToSQL } from 'turbine-orm';
+ * import { sqliteDialect, turbineSqlite } from 'turbine-orm/sqlite';
+ *
+ * const schema = defineSchema({
+ *   users: { id: { type: 'serial', primaryKey: true }, email: { type: 'text', notNull: true } },
+ *   posts: {
+ *     id: { type: 'serial', primaryKey: true },
+ *     userId: { type: 'integer', notNull: true, references: 'users.id' },
+ *     title: { type: 'text', notNull: true },
+ *   },
+ * });
+ *
+ * const db = turbineSqlite(':memory:', schemaDefToMetadata(schema));
+ * for (const stmt of schemaToSQL(schema, { dialect: sqliteDialect })) {
+ *   await db.raw([stmt] as never);
+ * }
+ *
+ * // `db.table(...)`, not `db.users`: the typed property accessors are emitted
+ * // by `turbine generate`, and this path skips it.
+ * const users = await db.table('users').findMany({ with: { posts: true }, orderBy: { id: 'asc' } });
+ * await db.disconnect();
+ * ```
  */
 import type { DatabaseSync } from 'node:sqlite';
 import { type PgCompatPool, type PgCompatPoolClient, TurbineClient } from './client.js';