turbine-orm 0.64.1 → 0.65.0

package/dist/cjs/client.js

@@ -1033,7 +1033,7 @@ class TurbineClient {
         if (value === undefined)
             return undefined;
         if (value !== 'null' && value !== 'preserve') {
-            throw new errors_js_1.ValidationError(`Invalid temporalInfinity: ${JSON.stringify(value)}. Expected 'preserve' (default: read a Postgres ` +
+            throw new errors_js_1.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/cjs/dialect.js

@@ -116,7 +116,10 @@ exports.postgresDialect = {
     },
     buildBulkInsertStatement(input) {
         if (!input.columnArrayTypes || input.columnArrayTypes.length !== input.columns.length) {
-            throw new errors_js_1.ValidationError('PostgreSQL bulk insert requires one array type per column');
+            throw new errors_js_1.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/cjs/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/cjs/errors.js

@@ -32,23 +32,44 @@ exports.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 */
 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`
@@ -59,6 +80,7 @@ class TurbineError extends Error {
         super(formatErrorMessage(code, message), opts);
         this.name = 'TurbineError';
         this.code = code;
+        this.docsUrl = docsUrlForCode(code);
     }
 }
 exports.TurbineError = TurbineError;

package/dist/cjs/mysql.js

@@ -491,6 +491,25 @@ exports.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/cjs/observe.js

@@ -164,7 +164,9 @@ class ObserveEngine {
     stopped = false;
     constructor(config) {
         if (!config.sink && !config.connectionString) {
-            throw new errors_js_1.ValidationError('ObserveEngine requires either a connectionString or a sink');
+            throw new errors_js_1.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/cjs/powql.js

@@ -923,6 +923,23 @@ 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 errors_js_1.ValidationError((0, utils_js_1.selectNamesNothingMessage)(this.table));
+            }
+            if (omit && Object.values(omit).some(Boolean)) {
+                throw new errors_js_1.ValidationError((0, utils_js_1.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;
@@ -1480,6 +1497,18 @@ 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 errors_js_1.ValidationError((0, utils_js_1.selectNamesNothingMessage)(targetMeta.name));
+                }
+                if (userOmit && Object.values(userOmit).some(Boolean)) {
+                    throw new errors_js_1.ValidationError((0, utils_js_1.selectOmitExclusiveMessage)(targetMeta.name));
+                }
+            }
             const fkProjected = userSelect ? Boolean(userSelect[childKeyField]) : userOmit ? !userOmit[childKeyField] : true;
             let fetchOptions = options;
             if (!fkProjected) {

package/dist/cjs/query/aggregates.js

@@ -91,7 +91,7 @@ function buildGroupBy(qi, args) {
     if (meta) {
         for (const key of args.by) {
             if (typeof key === 'string' && !(key in meta.columnMap)) {
-                throw new errors_js_1.ValidationError(`Unknown column "${key}" in groupBy for table "${qi.table}"`);
+                throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(qi.table, key, meta));
             }
         }
     }
@@ -828,7 +828,7 @@ function buildAggregate(qi, args) {
             if (group && typeof group === 'object') {
                 for (const key of Object.keys(group)) {
                     if (!(key in meta.columnMap)) {
-                        throw new errors_js_1.ValidationError(`Unknown column "${key}" in aggregate for table "${qi.table}"`);
+                        throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(qi.table, key, meta));
                     }
                 }
             }
@@ -839,7 +839,7 @@ function buildAggregate(qi, args) {
                 if (key === '_all')
                     continue;
                 if (!(key in meta.columnMap)) {
-                    throw new errors_js_1.ValidationError(`Unknown column "${key}" in aggregate for table "${qi.table}"`);
+                    throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(qi.table, key, meta));
                 }
             }
         }

package/dist/cjs/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/cjs/query/batched-loader.js

@@ -56,6 +56,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultProjectionFields = defaultProjectionFields;
+exports.assertProjectionShape = assertProjectionShape;
 exports.includeKeysForBatching = includeKeysForBatching;
 exports.stripFields = stripFields;
 exports.neededParentKeyFields = neededParentKeyFields;
@@ -112,6 +113,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.
+ */
+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 errors_js_1.ValidationError((0, utils_js_1.selectNamesNothingMessage)(table));
+    }
+    if (omit && !Array.isArray(omit) && Object.values(omit).some(Boolean)) {
+        throw new errors_js_1.ValidationError((0, utils_js_1.selectOmitExclusiveMessage)(table));
+    }
+}
 function includeKeysForBatching(select, omit, fields, 
 /**
  * The default projection for this table when it is NOT `select`/`omit`-driven:
@@ -281,12 +303,19 @@ function rejectNestedPickOrder(withClause) {
 async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0, path = [ctx.parentMeta.name]) {
     if (depth >= MAX_DEPTH)
         throw new errors_js_1.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.
@@ -296,7 +325,10 @@ async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0
             continue;
         const rel = (0, utils_js_1.ownLookup)(ctx.parentMeta.relations, relName);
         if (!rel) {
-            throw new errors_js_1.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 errors_js_1.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 });
@@ -422,11 +454,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.
     //
@@ -438,8 +465,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));
@@ -448,20 +493,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
@@ -509,12 +550,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();
@@ -550,28 +590,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();
@@ -803,10 +851,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 errors_js_1.ValidationError(`[turbine] Relation "${relName}" targets unknown table "${table}".`);
+        throw new errors_js_1.RelationError(`[turbine] Unknown relation target "${table}" (relation "${relName}").`);
     return meta;
 }

package/dist/cjs/query/builder.js

@@ -1428,6 +1428,7 @@ class QueryInterface {
         // refused one step later.
         const includePii = (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii');
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, batchedWith);
+        (0, batched_loader_js_1.assertProjectionShape)(this.table, args.select, args.omit);
         const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, includePii));
         const hasJoin = Object.keys(joinWith).length > 0;
         // Force the residual `with` onto the join plan so the base query never
@@ -1447,9 +1448,11 @@ 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 (0, batched_loader_js_1.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 (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
             (0, batched_loader_js_1.stripFields)(entities, proj.strip);
             return single ? (entities[0] ?? null) : entities;
         }
@@ -1542,9 +1545,9 @@ 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 (0, batched_loader_js_1.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 (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii, args.forceCustomPlan === true), entities, withClause, args.timeout);
         (0, batched_loader_js_1.stripFields)(entities, strip);
         return entities;
     }
@@ -1555,6 +1558,7 @@ class QueryInterface {
      */
     prepareBatchedBase(args, withClause) {
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, withClause);
+        (0, batched_loader_js_1.assertProjectionShape)(this.table, args.select, args.omit);
         const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii')));
         const baseArgs = {
             ...args,
@@ -1928,14 +1932,18 @@ class QueryInterface {
         // Same scope-rule parity as runFindManyBatched: reject before querying.
         (0, batched_loader_js_1.rejectNestedPickOrder)(withClause);
         const needed = (0, batched_loader_js_1.neededParentKeyFields)(this.tableMeta, withClause);
+        (0, batched_loader_js_1.assertProjectionShape)(this.table, args.select, args.omit);
         const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, (0, types_js_1.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 (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii, args.forceCustomPlan === true), entity ? [entity] : [], withClause, args.timeout);
         if (!entity)
             return null;
-        await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii, args.forceCustomPlan === true), [entity], withClause, args.timeout);
         (0, batched_loader_js_1.stripFields)([entity], proj.strip);
         return entity;
     }

package/dist/cjs/query/relations.js

@@ -153,6 +153,34 @@ function projectionColumn(table, meta, field, clause) {
  * name handling would mean reimplementing those too.
  */
 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 errors_js_1.ValidationError((0, utils_js_1.selectNamesNothingMessage)(table));
+        }
+        if (omit && !Array.isArray(omit) && Object.values(omit).some(Boolean)) {
+            throw new errors_js_1.ValidationError((0, utils_js_1.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/cjs/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/cjs/query/utils.js

@@ -37,6 +37,8 @@ exports.closestName = closestName;
 exports.suggestKey = suggestKey;
 exports.unknownFieldMessage = unknownFieldMessage;
 exports.relationInProjectionMessage = relationInProjectionMessage;
+exports.selectNamesNothingMessage = selectNamesNothingMessage;
+exports.selectOmitExclusiveMessage = selectOmitExclusiveMessage;
 const pg_1 = __importDefault(require("pg"));
 const schema_js_1 = require("../schema.js");
 const warn_registry_js_1 = require("./warn-registry.js");
@@ -911,3 +913,22 @@ 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.
+ */
+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.`);
+}
+function selectOmitExclusiveMessage(table) {
+    return (`[turbine] "select" and "omit" are mutually exclusive (on table "${table}"). ` +
+        `A select already lists exactly the fields you want.`);
+}

package/dist/cjs/sqlite.js

@@ -461,6 +461,22 @@ exports.sqliteDialect = {
     castAggregate(expr, target) {
         return `CAST(${expr} AS ${target === 'int' ? 'INTEGER' : 'REAL'})`;
     },
+    // SQLite's grammar only allows OFFSET after LIMIT, so `offset` without
+    // `limit` (valid on Postgres, which the default path is written for) is a
+    // syntax error here. A negative LIMIT is SQLite's documented "no upper
+    // bound", so that shape becomes `LIMIT -1 OFFSET n`. The other shapes emit
+    // byte-identically to the default path.
+    buildLimitOffset(input) {
+        const { limitPlaceholder, offsetPlaceholder } = input;
+        if (limitPlaceholder === undefined && offsetPlaceholder === undefined)
+            return '';
+        if (limitPlaceholder === undefined)
+            return ` LIMIT -1 OFFSET ${offsetPlaceholder}`;
+        let s = ` LIMIT ${limitPlaceholder}`;
+        if (offsetPlaceholder !== undefined)
+            s += ` OFFSET ${offsetPlaceholder}`;
+        return s;
+    },
     // No `= ANY(array)` in SQLite. `json_each` 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 correctly.