turbine-orm 0.64.1 → 0.65.0

package/dist/client.js

@@ -1025,7 +1025,7 @@ export class TurbineClient {
         if (value === undefined)
             return undefined;
         if (value !== 'null' && value !== 'preserve') {
-            throw new ValidationError(`Invalid temporalInfinity: ${JSON.stringify(value)}. Expected 'preserve' (default: read a Postgres ` +
+            throw new ValidationError(`[turbine] Invalid temporalInfinity: ${JSON.stringify(value)}. Expected 'preserve' (default: read a Postgres ` +
                 'temporal `infinity` as the JS number `Infinity` / `-Infinity`, which round-trips through a write ' +
                 "but breaks the declared `Date` type) or 'null' (read it as null, which serializes cleanly but " +
                 'makes it indistinguishable from a stored NULL, so a read-modify-write destroys the value).');

package/dist/dialect.js

@@ -80,7 +80,10 @@ export const postgresDialect = {
     },
     buildBulkInsertStatement(input) {
         if (!input.columnArrayTypes || input.columnArrayTypes.length !== input.columns.length) {
-            throw new ValidationError('PostgreSQL bulk insert requires one array type per column');
+            throw new ValidationError(`[turbine] createMany bulk insert into "${input.table}": columnArrayTypes must supply one UNNEST cast ` +
+                `per column, got ${input.columnArrayTypes?.length ?? 0} for ${input.columns.length} columns ` +
+                `(${input.columns.join(', ')}). Schema metadata is missing a pgType for at least one column; ` +
+                'regenerate it with `npx turbine generate`.');
         }
         // Row-major form: required when a target column is itself array-typed,
         // because the UNNEST transpose below flattens nested arrays (see

package/dist/errors.d.ts

@@ -29,6 +29,8 @@ export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErr
 /** Base error class for all Turbine errors */
 export declare class TurbineError extends Error {
     readonly code: TurbineErrorCode;
+    /** Docs page for this code, e.g. `https://turbineorm.dev/errors#e003`. */
+    readonly docsUrl: string;
     constructor(code: TurbineErrorCode, message: string, options?: {
         cause?: unknown;
     });

package/dist/errors.js

@@ -25,23 +25,44 @@ export const TurbineErrorCode = {
     UNSUPPORTED_FEATURE: 'TURBINE_E017',
     READ_ONLY: 'TURBINE_E018',
 };
+/**
+ * The docs page anchor for a code: `TURBINE_E003` -> `.../errors#e003`.
+ *
+ * Every code has a row on that page (enforced by a unit test that reads the
+ * MDX source, so a new code cannot ship without its docs entry). The URL is
+ * carried both in the message and as {@link TurbineError.docsUrl} so
+ * structured sinks (Sentry, pino) get it without parsing text.
+ */
+function docsUrlForCode(code) {
+    return `https://turbineorm.dev/errors#${code.slice('TURBINE_'.length).toLowerCase()}`;
+}
 /**
  * Prefix a human message with its stable error code so logs are greppable
- * without requiring structured field access. Idempotent if the message already
- * starts with `[TURBINE_E0NN]`.
+ * without requiring structured field access, and suffix it with the docs URL
+ * for the code so a log line is one click from its explanation. Idempotent on
+ * both ends: a message already starting with `[TURBINE_E0NN]` keeps its tag,
+ * and one already carrying THIS code's link (a same-code re-wrap) does not
+ * gain a second. The check is code-specific on purpose: a message embedding a
+ * DIFFERENT code's error text (say an E003 wrapped into an E017) still gets
+ * its own code's link appended, so the trailing link always agrees with
+ * `.docsUrl` and the outermost code.
+ *
+ * STABILITY.md declares message TEXT non-contract (only the code tag is), so
+ * adding the suffix is not a breaking change; branch on `err.code`, never on
+ * the message.
  */
 function formatErrorMessage(code, message) {
     const tag = `[${code}]`;
-    if (message.startsWith(tag))
-        return message;
+    const link = message.includes(docsUrlForCode(code)) ? '' : ` (${docsUrlForCode(code)})`;
     // Empty message → just the code (defensive; callers always pass text today).
-    if (!message)
-        return tag;
-    return `${tag} ${message}`;
+    const body = message.startsWith(tag) ? message : message ? `${tag} ${message}` : tag;
+    return `${body}${link}`;
 }
 /** Base error class for all Turbine errors */
 export class TurbineError extends Error {
     code;
+    /** Docs page for this code, e.g. `https://turbineorm.dev/errors#e003`. */
+    docsUrl;
     constructor(code, message, options) {
         // The cause is redacted in 'safe' mode (see redactCauseForMode). Only pass
         // an options object through when the caller actually supplied a `cause`
@@ -52,6 +73,7 @@ export class TurbineError extends Error {
         super(formatErrorMessage(code, message), opts);
         this.name = 'TurbineError';
         this.code = code;
+        this.docsUrl = docsUrlForCode(code);
     }
 }
 let errorMessageMode = 'safe';

package/dist/mysql.js

@@ -480,6 +480,25 @@ export const mysqlDialect = {
     castAggregate(expr, target) {
         return `CAST(${expr} AS ${target === 'int' ? 'SIGNED' : 'DECIMAL(65,30)'})`;
     },
+    // MySQL has no bare OFFSET: the grammar requires a LIMIT for OFFSET to
+    // attach to, so `offset` without `limit` (valid on Postgres, which the
+    // default path is written for) is a syntax error here. The MySQL manual's
+    // own idiom for "from this offset to the end" is a LIMIT of
+    // 18446744073709551615 (2^64-1). The other shapes emit byte-identically to
+    // the default path. Values arrive as inlined validated-integer literals
+    // (inlineLimitOffset), so this only concatenates text the builder already
+    // vetted.
+    buildLimitOffset(input) {
+        const { limitPlaceholder, offsetPlaceholder } = input;
+        if (limitPlaceholder === undefined && offsetPlaceholder === undefined)
+            return '';
+        if (limitPlaceholder === undefined)
+            return ` LIMIT 18446744073709551615 OFFSET ${offsetPlaceholder}`;
+        let s = ` LIMIT ${limitPlaceholder}`;
+        if (offsetPlaceholder !== undefined)
+            s += ` OFFSET ${offsetPlaceholder}`;
+        return s;
+    },
     // No array params in MySQL. JSON_TABLE expands a single JSON-array param into a
     // row set, keeping ONE placeholder (so the SQL cache stays valid regardless of
     // list length) and handling the empty-list case (zero rows). MySQL coerces the

package/dist/observe.js

@@ -154,7 +154,9 @@ export class ObserveEngine {
     stopped = false;
     constructor(config) {
         if (!config.sink && !config.connectionString) {
-            throw new ValidationError('ObserveEngine requires either a connectionString or a sink');
+            throw new ValidationError('[turbine] ObserveEngine: neither `connectionString` nor `sink` was provided, so there is nowhere to ' +
+                'flush metrics. Pass `connectionString` (a separate metrics database URL, often TURBINE_OBSERVE_URL) ' +
+                'or a custom `sink` implementing ObserveSink.');
         }
         this.sink =
             config.sink ??

package/dist/powql.js

@@ -45,7 +45,7 @@ import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/fil
 // are unlocked ONLY by the UNSAFE symbol, on this engine exactly as on the SQL
 // engines, so a spread request body cannot turn either on here either.
 import { assertDirectionToken, resolveUnsafeFlag, UNSAFE } from './query/types.js';
-import { escapeLike, ownLookup, relationInProjectionMessage } from './query/utils.js';
+import { escapeLike, ownLookup, relationInProjectionMessage, selectNamesNothingMessage, selectOmitExclusiveMessage, } from './query/utils.js';
 import { assertJsonFilterKeys, jsonStringEntries } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -887,6 +887,23 @@ export class PowqlInterface {
         return this.column(field).name;
     }
     projectedColumns(select, omit, includePii) {
+        // Same two shape refusals as `resolveProjection` on the SQL engines, with
+        // the shared messages, and for a live reason here: this path used to
+        // APPLY select-minus-omit while the SQL engines ignored the `omit` half,
+        // so one query meant different columns depending on the backend. And a
+        // zero-key/all-false select used to fall through to the DEFAULT
+        // projection here while the SQL engines emitted broken or empty rows;
+        // both shapes are ambiguous and now refused identically on every engine.
+        // Presence-decided, exactly like resolveProjection (see its comment for
+        // the strategy-flip this prevents).
+        if (select) {
+            if (!Object.values(select).some(Boolean)) {
+                throw new ValidationError(selectNamesNothingMessage(this.table));
+            }
+            if (omit && Object.values(omit).some(Boolean)) {
+                throw new ValidationError(selectOmitExclusiveMessage(this.table));
+            }
+        }
         const pk = new Set(this.meta.primaryKey);
         let cols = this.meta.columns.map((c) => c.name);
         const hasSelect = select && Object.keys(select).length;
@@ -1444,6 +1461,18 @@ export class PowqlInterface {
             // stitching (the join path already gets this for free via `__tpk`).
             const userSelect = options.select;
             const userOmit = options.omit;
+            // The RAW shape rules, before the force-add below: the forced key makes
+            // an all-falsy select look populated to the child's projectedColumns,
+            // which would accept here what the nested-projection path refuses. Same
+            // messages as the SQL engines' assertProjectionShape, same reason.
+            if (userSelect) {
+                if (!Object.values(userSelect).some(Boolean)) {
+                    throw new ValidationError(selectNamesNothingMessage(targetMeta.name));
+                }
+                if (userOmit && Object.values(userOmit).some(Boolean)) {
+                    throw new ValidationError(selectOmitExclusiveMessage(targetMeta.name));
+                }
+            }
             const fkProjected = userSelect ? Boolean(userSelect[childKeyField]) : userOmit ? !userOmit[childKeyField] : true;
             let fetchOptions = options;
             if (!fkProjected) {

package/dist/query/aggregates.js

@@ -12,7 +12,7 @@ import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
 import { isJsonPathOrderBy, isUnmatchedPlainObject, isVectorOrderBy, isWhereOperator, normalizeOrderBy, orderByEntries, } from './filters.js';
 import { assertOrderDirection, resolveSkipGlobalFilters, resolveUnsafeFlag } from './types.js';
-import { isTemporalInfinity, ownLookup } from './utils.js';
+import { isTemporalInfinity, ownLookup, unknownFieldMessage } from './utils.js';
 import * as whereMod from './where.js';
 /**
  * Enforce the PII contract on the aggregate surface. A PII-tagged
@@ -48,7 +48,7 @@ export function buildGroupBy(qi, args) {
     if (meta) {
         for (const key of args.by) {
             if (typeof key === 'string' && !(key in meta.columnMap)) {
-                throw new ValidationError(`Unknown column "${key}" in groupBy for table "${qi.table}"`);
+                throw new ValidationError(unknownFieldMessage(qi.table, key, meta));
             }
         }
     }
@@ -785,7 +785,7 @@ export function buildAggregate(qi, args) {
             if (group && typeof group === 'object') {
                 for (const key of Object.keys(group)) {
                     if (!(key in meta.columnMap)) {
-                        throw new ValidationError(`Unknown column "${key}" in aggregate for table "${qi.table}"`);
+                        throw new ValidationError(unknownFieldMessage(qi.table, key, meta));
                     }
                 }
             }
@@ -796,7 +796,7 @@ export function buildAggregate(qi, args) {
                 if (key === '_all')
                     continue;
                 if (!(key in meta.columnMap)) {
-                    throw new ValidationError(`Unknown column "${key}" in aggregate for table "${qi.table}"`);
+                    throw new ValidationError(unknownFieldMessage(qi.table, key, meta));
                 }
             }
         }

package/dist/query/batched-loader.d.ts

@@ -146,6 +146,16 @@ export declare function defaultProjectionFields(meta: TableMetadata, includePii:
  * keys) so a caller's `select: { title: true }` on a relation still stitches even
  * though the FK was not requested, and the FK never appears in the output.
  */
+/**
+ * The two projection SHAPE rules from `resolveProjection`, checked on the RAW
+ * caller args BEFORE `includeKeysForBatching` adjusts them. The adjustment
+ * force-adds correlation keys to a `select`, so a shape that is invalid as
+ * written (an all-falsy select, or select + omit together) can look valid
+ * after it, and the batched plan would then accept a query the join plan
+ * refuses, with 'auto' picking between them on data. Same messages as the
+ * resolver so the two strategies refuse identically, word for word.
+ */
+export declare function assertProjectionShape(table: string, select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined): void;
 export declare function includeKeysForBatching(select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined, fields: string[], 
 /**
  * The default projection for this table when it is NOT `select`/`omit`-driven:

package/dist/query/batched-loader.js

@@ -56,7 +56,7 @@
 import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { normalizeKeyColumns } from '../schema.js';
 import { isRelationPickOrderBy, sortedEntries } from './filters.js';
-import { ownLookup } from './utils.js';
+import { ownLookup, selectNamesNothingMessage, selectOmitExclusiveMessage } from './utils.js';
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
  * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit, it
@@ -103,6 +103,27 @@ includePii) {
  * keys) so a caller's `select: { title: true }` on a relation still stitches even
  * though the FK was not requested, and the FK never appears in the output.
  */
+/**
+ * The two projection SHAPE rules from `resolveProjection`, checked on the RAW
+ * caller args BEFORE `includeKeysForBatching` adjusts them. The adjustment
+ * force-adds correlation keys to a `select`, so a shape that is invalid as
+ * written (an all-falsy select, or select + omit together) can look valid
+ * after it, and the batched plan would then accept a query the join plan
+ * refuses, with 'auto' picking between them on data. Same messages as the
+ * resolver so the two strategies refuse identically, word for word.
+ */
+export function assertProjectionShape(table, select, omit) {
+    // Array shapes fall through: buildFindMany's resolver has their specific
+    // "must be an object" messages, and compiling is where they surface.
+    if (!select || Array.isArray(select))
+        return;
+    if (!Object.values(select).some(Boolean)) {
+        throw new ValidationError(selectNamesNothingMessage(table));
+    }
+    if (omit && !Array.isArray(omit) && Object.values(omit).some(Boolean)) {
+        throw new ValidationError(selectOmitExclusiveMessage(table));
+    }
+}
 export function includeKeysForBatching(select, omit, fields, 
 /**
  * The default projection for this table when it is NOT `select`/`omit`-driven:
@@ -272,12 +293,19 @@ export function rejectNestedPickOrder(withClause) {
 export async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0, path = [ctx.parentMeta.name]) {
     if (depth >= MAX_DEPTH)
         throw new CircularRelationError([...path, '…']);
-    // Scope-rule parity with the join strategy: validate the whole tree BEFORE
-    // the empty-parents early return, so accept/reject never depends on data.
+    // Scope-rule parity with the join strategy: the whole tree validates even
+    // with zero parents, so accept/reject never depends on data. There is
+    // DELIBERATELY no `parents.length === 0` early return here: one used to sit
+    // below this line, and it skipped relation-NAME resolution and every child
+    // compile whenever the base query matched nothing, so a typo'd relation or
+    // child select threw on populated data and passed silently on empty. The
+    // loaders below all compile their child query before their own
+    // data-dependent exits (one SQL string build per relation node; makeChild
+    // creates a fresh QueryInterface, so this is NOT a template-cache hit, and
+    // nothing executes), which keeps this path's acceptance byte-aligned with
+    // the join plan's compile-time validation.
     if (depth === 0)
         rejectNestedPickOrder(withClause);
-    if (parents.length === 0)
-        return;
     // Resolve the relations to load in the SAME order the join plan emits their
     // columns (`sortedEntries` in buildSelectWithRelations), with the reserved
     // `_count` key last.
@@ -287,7 +315,10 @@ export async function loadRelationsBatched(ctx, parents, withClause, timeout, de
             continue;
         const rel = ownLookup(ctx.parentMeta.relations, relName);
         if (!rel) {
-            throw new ValidationError(`[turbine] Unknown relation "${relName}" on table "${ctx.parentMeta.name}". ` +
+            // RelationError (E005), NOT ValidationError: the join strategy throws
+            // E005 for this exact shape (relations.ts), and under 'auto' the two
+            // must refuse identically or the error CODE depends on table size.
+            throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${ctx.parentMeta.name}". ` +
                 `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}`);
         }
         resolved.push({ relName, rel, options: spec === true ? {} : spec });
@@ -413,11 +444,6 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     assertCorrelationKeyProjected(parents, parentKeyField, relName, ctx.parentMeta.name);
     const keys = uniqueKeys(parents, parentKeyField);
     const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
-    if (keys.length === 0) {
-        for (const parent of parents)
-            parent[relName] = single ? null : [];
-        return;
-    }
     // The follow-up must project the child correlation key even if the caller's
     // select/omit excluded it; strip it back off afterwards so the shape matches join.
     //
@@ -429,8 +455,26 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     // ones did not, so the defect needed a `select` (or an `omit` of the FK) on a
     // to-many with a to-one inside it, which is why `include` and `join` were both
     // clean and seventeen rounds of parity capture missed it.
+    assertProjectionShape(targetMeta.name, options.select, options.omit);
     const proj = includeKeysForBatching(options.select, options.omit, [childKeyField, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
+    const buildChunk = (chunk) => child.buildFindMany({
+        where: mergeChildWhere(options.where, childKeyField, chunk),
+        select: proj.select,
+        omit: proj.omit,
+        orderBy: options.orderBy,
+        skipGlobalFilters: ctx.skipGlobalFilters,
+        includePii: ctx.includePii,
+    });
+    // Zero keys (no parents, or every parent's key is NULL): nothing to fetch,
+    // but the child query still COMPILES, because compiling is where the
+    // caller's select/omit/where/orderBy names are validated and the join plan
+    // validates them regardless of data. Skipping this made a typo'd child
+    // select throw or pass based on which rows the base query matched. Cost:
+    // one SQL string build (the child is a fresh QueryInterface with its own
+    // template LRU, so this is a build, not a cache hit); nothing executes.
+    if (keys.length === 0)
+        buildChunk([]);
     const chunks = [];
     for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS)
         chunks.push(keys.slice(i, i + MAX_RELATION_KEYS));
@@ -439,20 +483,16 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     // whole batch would cap TOTAL children, not children-per-parent. It is applied
     // client-side per group after stitching (below).
     const chunkResults = await Promise.all(chunks.map(async (chunk) => {
-        const deferred = child.buildFindMany({
-            where: mergeChildWhere(options.where, childKeyField, chunk),
-            select: proj.select,
-            omit: proj.omit,
-            orderBy: options.orderBy,
-            skipGlobalFilters: ctx.skipGlobalFilters,
-            includePii: ctx.includePii,
-        });
+        const deferred = buildChunk(chunk);
         const result = await ctx.exec(deferred.sql, deferred.params, deferred.preparedName);
         return deferred.transform(result);
     }));
     const allChildren = chunkResults.flat();
-    // Recurse for nested `with` BEFORE stripping keys (children carry their own keys).
-    if (options.with && allChildren.length > 0) {
+    // Recurse for nested `with` BEFORE stripping keys (children carry their own
+    // keys). Recursion runs even with zero children: it is the validation walk
+    // for the deeper levels of the tree (each level compiles its own child
+    // query above), so a typo three levels down throws with or without data.
+    if (options.with) {
         await loadRelationsBatched({ ...ctx, parentMeta: targetMeta }, allChildren, options.with, timeout, depth + 1, [...path, relName]);
     }
     // Symmetric to the parent-side assertion above. If the CHILD key were ever
@@ -500,12 +540,11 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
     const parentRefField = ctx.parentMeta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
     const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
     assertCorrelationKeyProjected(parents, parentRefField, relName, ctx.parentMeta.name);
+    // No early return on zero parent keys: the code below flows through
+    // naturally (zero junction chunks, zero target chunks), and the compile-only
+    // build further down still validates the caller's names, same rule as the
+    // to-one/to-many loader.
     const parentKeys = uniqueKeys(parents, parentRefField);
-    if (parentKeys.length === 0) {
-        for (const parent of parents)
-            parent[relName] = [];
-        return;
-    }
     // (1) Junction rows: sourceKeyVal → [targetKeyVal]. Raw SQL through the caller's
     // executor (the junction table has no relations we need, so no child reader).
     const targetsBySource = new Map();
@@ -541,28 +580,36 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
     // Plus the keys the target's own nested relations need, same rule and same
     // reason as the to-many loader above: this level's PK is not the only key the
     // recursion below will ask these rows for.
+    assertProjectionShape(targetMeta.name, options.select, options.omit);
     const proj = includeKeysForBatching(options.select, options.omit, [targetPkField, ...neededParentKeyFields(targetMeta, (options.with ?? {}))], defaultProjectionFields(targetMeta, ctx.includePii));
     const child = ctx.makeChild(rel.to);
+    const buildTargetChunk = (chunk) => child.buildFindMany({
+        where: mergeChildWhere(options.where, targetPkField, chunk),
+        select: proj.select,
+        omit: proj.omit,
+        orderBy: options.orderBy,
+        skipGlobalFilters: ctx.skipGlobalFilters,
+        includePii: ctx.includePii,
+    });
     const targetVals = [...targetValSet];
+    // Compile-only when there is nothing to fetch: validation of the caller's
+    // names lives in the build, and it must not depend on whether any junction
+    // row matched (same rule as the to-one/to-many loader).
+    if (targetVals.length === 0)
+        buildTargetChunk([]);
     const tChunks = [];
     for (let i = 0; i < targetVals.length; i += MAX_RELATION_KEYS) {
         tChunks.push(targetVals.slice(i, i + MAX_RELATION_KEYS));
     }
     const tResults = await Promise.all(tChunks.map(async (chunk) => {
-        const deferred = child.buildFindMany({
-            where: mergeChildWhere(options.where, targetPkField, chunk),
-            select: proj.select,
-            omit: proj.omit,
-            orderBy: options.orderBy,
-            skipGlobalFilters: ctx.skipGlobalFilters,
-            includePii: ctx.includePii,
-        });
+        const deferred = buildTargetChunk(chunk);
         const result = await ctx.exec(deferred.sql, deferred.params, deferred.preparedName);
         return deferred.transform(result);
     }));
     const targetsInOrder = tResults.flat();
-    // Nested `with` on the target rows (before stripping their PK).
-    if (options.with && targetsInOrder.length > 0) {
+    // Nested `with` on the target rows (before stripping their PK). Runs even
+    // with zero targets: it is the validation walk for the deeper levels.
+    if (options.with) {
         await loadRelationsBatched({ ...ctx, parentMeta: targetMeta }, targetsInOrder, options.with, timeout, depth + 1, [...path, relName]);
     }
     const targetByPk = new Map();
@@ -794,10 +841,16 @@ function groupBy(rows, field) {
     }
     return map;
 }
-/** Resolve a table's metadata or throw a clear relation error. */
+/**
+ * Resolve a table's metadata or throw a clear relation error. E005
+ * (RelationError), matching the class the join path throws for its "Unknown
+ * relation target" twin in relations.ts: only corrupt/partial metadata can
+ * trigger either, but the error CODE must still not depend on which strategy
+ * ran (the same rule as the unknown relation NAME above).
+ */
 function requireTable(schema, table, relName) {
     const meta = schema.tables[table];
     if (!meta)
-        throw new ValidationError(`[turbine] Relation "${relName}" targets unknown table "${table}".`);
+        throw new RelationError(`[turbine] Unknown relation target "${table}" (relation "${relName}").`);
     return meta;
 }

package/dist/query/builder.js

@@ -16,7 +16,7 @@ import { missingIndexForRelation, schemaHasIndexInfo } from '../index-advisor.js
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
-import { defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
+import { assertProjectionShape, defaultProjectionFields, 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';
@@ -1391,6 +1391,7 @@ export class QueryInterface {
         // refused one step later.
         const includePii = resolveUnsafeFlag(args.includePii, 'includePii');
         const needed = neededParentKeyFields(this.tableMeta, batchedWith);
+        assertProjectionShape(this.table, args.select, args.omit);
         const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, includePii));
         const hasJoin = Object.keys(joinWith).length > 0;
         // Force the residual `with` onto the join plan so the base query never
@@ -1410,9 +1411,11 @@ export class QueryInterface {
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, 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, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
-            }
+            // Unconditionally, even for zero rows: with no parents the loader is a
+            // pure validation walk over the `with` tree (compile-only child builds),
+            // which is what keeps accept/reject identical to the join plan when the
+            // base query matches nothing.
+            await loadRelationsBatched(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
             stripFields(entities, proj.strip);
             return single ? (entities[0] ?? null) : entities;
         }
@@ -1505,9 +1508,9 @@ export class QueryInterface {
         const deferred = this.buildFindMany(baseArgs);
         const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
         const entities = deferred.transform(result);
-        if (entities.length > 0) {
-            await loadRelationsBatched(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, withClause, args.timeout);
-        }
+        // Unconditionally, even for zero rows: see the 'auto' path above, the
+        // loader doubles as the compile-time validation walk of the `with` tree.
+        await loadRelationsBatched(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, withClause, args.timeout);
         stripFields(entities, strip);
         return entities;
     }
@@ -1518,6 +1521,7 @@ export class QueryInterface {
      */
     prepareBatchedBase(args, withClause) {
         const needed = neededParentKeyFields(this.tableMeta, withClause);
+        assertProjectionShape(this.table, args.select, args.omit);
         const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, resolveUnsafeFlag(args.includePii, 'includePii')));
         const baseArgs = {
             ...args,
@@ -1891,14 +1895,18 @@ export class QueryInterface {
         // Same scope-rule parity as runFindManyBatched: reject before querying.
         rejectNestedPickOrder(withClause);
         const needed = neededParentKeyFields(this.tableMeta, withClause);
+        assertProjectionShape(this.table, args.select, args.omit);
         const proj = includeKeysForBatching(args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, resolveUnsafeFlag(args.includePii, 'includePii')));
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
         const deferred = this.buildFindUnique(baseArgs);
         const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
         const entity = deferred.transform(result);
+        // A miss still walks the `with` tree (compile-only child builds), so the
+        // same args throw or pass identically whether or not the row exists,
+        // matching the join plan which validates the whole statement up front.
+        await loadRelationsBatched(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii, args.forceCustomPlan === true), entity ? [entity] : [], withClause, args.timeout);
         if (!entity)
             return null;
-        await loadRelationsBatched(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii, args.forceCustomPlan === true), [entity], withClause, args.timeout);
         stripFields([entity], proj.strip);
         return entity;
     }

package/dist/query/relations.js

@@ -18,7 +18,7 @@ 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 { assertDirectionToken, assertOrderDirection } from './types.js';
-import { ownLookup, relationInProjectionMessage, resolveColumnName, unknownFieldMessage } from './utils.js';
+import { ownLookup, relationInProjectionMessage, resolveColumnName, 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';
@@ -75,6 +75,34 @@ function projectionColumn(table, meta, field, clause) {
  * name handling would mean reimplementing those too.
  */
 export function resolveProjection(qi, table, meta, select, omit, includePii) {
+    // Projection SHAPE refusals, in order (array shapes fall through to their
+    // own, more specific messages below):
+    //
+    // 1. A `select` naming no fields (empty, or every value false) is refused,
+    //    not resolved to an empty column list: at the top level that list used
+    //    to emit `SELECT  FROM`, invalid SQL, while a relation quietly returned
+    //    `[{}]` rows, two silent third outcomes of the kind this function was
+    //    merged to abolish.
+    // 2. `select` + `omit` together is refused, not half-resolved: a narrowed
+    //    projection minus fields is ambiguous, Prisma refuses the pair, and
+    //    prisma-compat here already did. Before this check the `select` branch
+    //    below returned early, so the `omit` names were never validated at all
+    //    (a typo in the `omit` half passed while the same typo alone threw).
+    //
+    // Check 1 runs first so both are PRESENCE-decided exactly like the branch
+    // below (`if (select)`): a truthiness-decided refusal here flipped verdicts
+    // between strategies when the batched loader force-added correlation keys
+    // to an all-falsy select (review-caught in 0.65). The batched loader
+    // asserts the same two rules on the RAW args (`assertProjectionShape`)
+    // before any adjustment, with these same messages.
+    if (select && !Array.isArray(select)) {
+        if (!Object.values(select).some(Boolean)) {
+            throw new ValidationError(selectNamesNothingMessage(table));
+        }
+        if (omit && !Array.isArray(omit) && Object.values(omit).some(Boolean)) {
+            throw new ValidationError(selectOmitExclusiveMessage(table));
+        }
+    }
     if (select) {
         // An array here means a caller wrote `select: ['id', 'name']` (Drizzle/SQL
         // style) instead of the object shape. Object.entries() would iterate the

package/dist/query/utils.d.ts

@@ -467,3 +467,16 @@ export declare function unknownFieldMessage(table: string, field: string, meta:
  * it. Naming the fix costs one sentence and saves a search.
  */
 export declare function relationInProjectionMessage(table: string, field: string, clause: 'select' | 'omit'): string;
+/**
+ * The two projection SHAPE refusals (0.65), shared by the SQL engines' single
+ * resolver, the batched loader's raw-arg check, and PowDB, so every path that
+ * refuses these shapes does so with one message.
+ *
+ * Both checks look at TRUTHY keys, and the raw-arg check in the batched
+ * loader exists because the loader force-adds correlation keys to a `select`
+ * before the resolver sees it: evaluated after that adjustment, an all-falsy
+ * user `select` looks populated and the verdict flips between strategies,
+ * which is exactly the class 0.64/0.65 exist to kill.
+ */
+export declare function selectNamesNothingMessage(table: string): string;
+export declare function selectOmitExclusiveMessage(table: string): string;

package/dist/query/utils.js

@@ -876,3 +876,22 @@ export function relationInProjectionMessage(table, field, clause) {
         : `${head} A relation is only present when you ask for it in \`with\`, so leave it out of \`with\` to leave it` +
             ' out of the result.';
 }
+/**
+ * The two projection SHAPE refusals (0.65), shared by the SQL engines' single
+ * resolver, the batched loader's raw-arg check, and PowDB, so every path that
+ * refuses these shapes does so with one message.
+ *
+ * Both checks look at TRUTHY keys, and the raw-arg check in the batched
+ * loader exists because the loader force-adds correlation keys to a `select`
+ * before the resolver sees it: evaluated after that adjustment, an all-falsy
+ * user `select` looks populated and the verdict flips between strategies,
+ * which is exactly the class 0.64/0.65 exist to kill.
+ */
+export function selectNamesNothingMessage(table) {
+    return (`[turbine] "select" names no fields (on table "${table}"): every value is false or it is empty. ` +
+        `Pass at least one field as true, or drop "select" to get the default projection.`);
+}
+export function selectOmitExclusiveMessage(table) {
+    return (`[turbine] "select" and "omit" are mutually exclusive (on table "${table}"). ` +
+        `A select already lists exactly the fields you want.`);
+}