turbine-orm 0.63.0 → 0.64.1

package/dist/cjs/powql.d.ts

@@ -307,6 +307,15 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
      * and returns it regardless. Untagged tables project exactly as before.
      */
+    /**
+     * Resolve one projection field name, or throw. PowQL already refused an
+     * unresolvable name here (via {@link column}), unlike the SQL engines' join
+     * path, which filtered it out silently until 0.64. What this adds is the
+     * RELATION case: naming a relation inside `select` is a Prisma habit rather
+     * than a typo, and the generic "unknown column" text sends the reader looking
+     * for a misspelling that is not there. Same message as the SQL engines.
+     */
+    private projectionColumn;
     private projectedColumns;
     /**
      * The snake_case names of this table's PII-tagged columns. Empty for a table

package/dist/cjs/powql.js

@@ -908,6 +908,20 @@ class PowqlInterface {
      * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
      * and returns it regardless. Untagged tables project exactly as before.
      */
+    /**
+     * Resolve one projection field name, or throw. PowQL already refused an
+     * unresolvable name here (via {@link column}), unlike the SQL engines' join
+     * path, which filtered it out silently until 0.64. What this adds is the
+     * RELATION case: naming a relation inside `select` is a Prisma habit rather
+     * than a typo, and the generic "unknown column" text sends the reader looking
+     * for a misspelling that is not there. Same message as the SQL engines.
+     */
+    projectionColumn(field, clause) {
+        if ((0, utils_js_1.ownLookup)(this.meta.relations, field)) {
+            throw new errors_js_1.ValidationError((0, utils_js_1.relationInProjectionMessage)(this.table, field, clause));
+        }
+        return this.column(field).name;
+    }
     projectedColumns(select, omit, includePii) {
         const pk = new Set(this.meta.primaryKey);
         let cols = this.meta.columns.map((c) => c.name);
@@ -915,7 +929,7 @@ class PowqlInterface {
         if (hasSelect) {
             const picked = new Set(Object.entries(select)
                 .filter(([, v]) => v)
-                .map(([k]) => this.column(k).name));
+                .map(([k]) => this.projectionColumn(k, 'select')));
             // Always keep the PK so reselect / relation stitching has a key to work with.
             for (const key of pk)
                 picked.add(key);
@@ -936,7 +950,7 @@ class PowqlInterface {
         if (omit && Object.keys(omit).length) {
             const dropped = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
-                .map(([k]) => this.column(k).name));
+                .map(([k]) => this.projectionColumn(k, 'omit')));
             // The PK survives `omit` too. This filter ran unconditionally and after
             // the `select` branch's force-add, so `omit: { id: true }` undid the very
             // guarantee that force-add exists to provide: the m2m loader keys its

package/dist/cjs/query/relations.d.ts

@@ -34,8 +34,41 @@ export interface RelationShape {
     cardinality: 'many' | 'one';
 }
 /**
- * Resolve select/omit options into a list of snake_case column names.
- * Returns null if neither is provided (meaning all columns).
+ * Resolve `select` / `omit` into a list of snake_case column names, for the
+ * query's own table and for a relation target alike. `null` means "no
+ * projection", i.e. all columns, which keeps the `*` fast path.
+ *
+ * ## Why this is one function
+ *
+ * It used to be two, `resolveColumns` for the top level and
+ * `resolveTargetColumns` for a relation target, doing the same job against
+ * different metadata. They drifted, and the drift was invisible from either
+ * side: the top level resolved every name through a throwing lookup, while the
+ * relation side filtered unresolvable names out and emitted SQL for whatever
+ * survived. So the SAME key in the SAME query threw at the top and was silently
+ * ignored one level down, where `select: { titel: true }` returned `{}` rows
+ * and `omit: { titel: true }` returned the column it was asked to hide.
+ *
+ * It was worse than an inconsistency between depths. The batched loader runs
+ * each relation as a real query against the target table, so it went through
+ * the THROWING path, while the join plan went through the silent one. The two
+ * strategies therefore disagreed about whether the query was even valid, and
+ * under `relationLoadStrategy: 'auto'` which one runs is decided by a cost
+ * heuristic reading index coverage and table size. The same code threw on one
+ * table and quietly returned the wrong shape on another.
+ *
+ * Merging them is the fix that outlives this bug. Two functions that must agree
+ * are kept in step by whoever remembers; one function cannot disagree with
+ * itself. This mirrors `walkWhere` in where-compile.ts, which exists for the
+ * same reason after the top-level and relation-scoped WHERE walkers drifted
+ * twice, and it is why a new projection site is safe by default: PII exclusion,
+ * the `*` fast path and name resolution all live here, so reimplementing the
+ * name handling would mean reimplementing those too.
+ */
+export declare function resolveProjection(qi: BuilderCtx, table: string, meta: TableMetadata, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
+/**
+ * The query's own table. Thin wrapper over {@link resolveProjection} kept for
+ * the existing call sites in builder.ts.
  */
 export declare function resolveColumns(qi: BuilderCtx, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
 /**
@@ -254,8 +287,14 @@ export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unkno
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
  * {@link buildRelationShape} (decode key order) so they can never diverge.
+ *
+ * A relation always projects SOMETHING, so the `null` that
+ * {@link resolveProjection} uses for the top level's `SELECT *` fast path
+ * becomes the target's full column list here. That is the only difference
+ * between the two, and it is why this is a four-line wrapper rather than a
+ * second implementation.
  */
-export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean): string[];
+export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean, targetTable?: string): string[];
 /**
  * Render a single relation row's JSON: a keyed object (`'object'`) or a
  * positional array (`'positional'`). The array drops the keys but keeps the

package/dist/cjs/query/relations.js

@@ -47,6 +47,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjection = resolveProjection;
 exports.resolveColumns = resolveColumns;
 exports.withFingerprint = withFingerprint;
 exports.collectWithParams = collectWithParams;
@@ -100,10 +101,58 @@ const warn_registry_js_1 = require("./warn-registry.js");
 const whereMod = __importStar(require("./where.js"));
 const writesMod = __importStar(require("./writes.js"));
 /**
- * Resolve select/omit options into a list of snake_case column names.
- * Returns null if neither is provided (meaning all columns).
+ * Turn ONE caller-supplied projection field name into a column, or throw.
+ *
+ * The whole point of this function is that it has no third outcome. The
+ * relation-side projection used to filter unresolvable names out
+ * (`.filter((col) => allColumns.includes(col))`) instead of rejecting them, and
+ * a filter that discards is exactly how a name typed by a human becomes SQL
+ * that no longer reflects what was asked for.
  */
-function resolveColumns(qi, select, omit, includePii) {
+function projectionColumn(table, meta, field, clause) {
+    const column = (0, utils_js_1.resolveColumnName)(meta, field);
+    if (column)
+        return column;
+    // A relation named in a projection is a habit, not a typo, so it gets its own
+    // message pointing at `with`. Checked BEFORE the generic throw because the
+    // generic one degrades into "Did you mean <exactly what you typed>?".
+    if ((0, utils_js_1.ownLookup)(meta.relations, field))
+        throw new errors_js_1.ValidationError((0, utils_js_1.relationInProjectionMessage)(table, field, clause));
+    throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(table, field, meta));
+}
+/**
+ * Resolve `select` / `omit` into a list of snake_case column names, for the
+ * query's own table and for a relation target alike. `null` means "no
+ * projection", i.e. all columns, which keeps the `*` fast path.
+ *
+ * ## Why this is one function
+ *
+ * It used to be two, `resolveColumns` for the top level and
+ * `resolveTargetColumns` for a relation target, doing the same job against
+ * different metadata. They drifted, and the drift was invisible from either
+ * side: the top level resolved every name through a throwing lookup, while the
+ * relation side filtered unresolvable names out and emitted SQL for whatever
+ * survived. So the SAME key in the SAME query threw at the top and was silently
+ * ignored one level down, where `select: { titel: true }` returned `{}` rows
+ * and `omit: { titel: true }` returned the column it was asked to hide.
+ *
+ * It was worse than an inconsistency between depths. The batched loader runs
+ * each relation as a real query against the target table, so it went through
+ * the THROWING path, while the join plan went through the silent one. The two
+ * strategies therefore disagreed about whether the query was even valid, and
+ * under `relationLoadStrategy: 'auto'` which one runs is decided by a cost
+ * heuristic reading index coverage and table size. The same code threw on one
+ * table and quietly returned the wrong shape on another.
+ *
+ * Merging them is the fix that outlives this bug. Two functions that must agree
+ * are kept in step by whoever remembers; one function cannot disagree with
+ * itself. This mirrors `walkWhere` in where-compile.ts, which exists for the
+ * same reason after the top-level and relation-scoped WHERE walkers drifted
+ * twice, and it is why a new projection site is safe by default: PII exclusion,
+ * the `*` fast path and name resolution all live here, so reimplementing the
+ * name handling would mean reimplementing those too.
+ */
+function resolveProjection(qi, table, meta, select, omit, includePii) {
     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
@@ -117,12 +166,12 @@ function resolveColumns(qi, select, omit, includePii) {
         // PII column IS the opt-in: it comes back regardless of `includePii`.
         return Object.entries(select)
             .filter(([, v]) => v)
-            .map(([k]) => qi.toColumn(k));
+            .map(([k]) => projectionColumn(table, meta, k, 'select'));
     }
     // Default / omit-only projection: PII-tagged columns are excluded unless the
     // caller opted in with `includePii: UNSAFE`. An empty set (untagged schema) keeps the
     // `null`/`*` fast path so the emitted SQL is byte-identical to before.
-    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, qi.tableMeta);
+    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, meta);
     const hasPii = piiCols !== undefined && piiCols.size > 0;
     if (omit) {
         if (Array.isArray(omit)) {
@@ -131,14 +180,21 @@ function resolveColumns(qi, select, omit, includePii) {
         // Include all columns except those where value is true (and PII columns).
         const omitCols = new Set(Object.entries(omit)
             .filter(([, v]) => v)
-            .map(([k]) => qi.toColumn(k)));
-        return qi.tableMeta.allColumns.filter((col) => !omitCols.has(col) && !(hasPii && piiCols.has(col)));
+            .map(([k]) => projectionColumn(table, meta, k, 'omit')));
+        return meta.allColumns.filter((col) => !omitCols.has(col) && !(hasPii && piiCols.has(col)));
     }
     if (hasPii) {
-        return qi.tableMeta.allColumns.filter((col) => !piiCols.has(col));
+        return meta.allColumns.filter((col) => !piiCols.has(col));
     }
     return null;
 }
+/**
+ * The query's own table. Thin wrapper over {@link resolveProjection} kept for
+ * the existing call sites in builder.ts.
+ */
+function resolveColumns(qi, select, omit, includePii) {
+    return resolveProjection(qi, qi.table, qi.tableMeta, select, omit, includePii);
+}
 /**
  * Produce a fingerprint for a `with` clause tree. Recursion mirrors
  * buildSelectWithRelations / buildRelationSubquery.
@@ -403,20 +459,17 @@ function orderByEntryFingerprint(qi, d, targetTable) {
     return String(d);
 }
 function buildOrderBy(qi, orderBy, params, lateralSink) {
-    // Dev-only: validate that orderBy fields exist in the table schema. Relation
-    // orderBy keys (object values that are neither a vector nor an OrderBySpec)
-    // are validated in the relation branch below, so skip them here.
-    if (process.env.NODE_ENV !== 'production') {
-        for (const [key, value] of (0, filters_js_1.orderByEntries)(orderBy)) {
-            if (isRelationOrderByValue(qi, value) && (0, utils_js_1.ownLookup)(qi.tableMeta.relations, key))
-                continue;
-            const snakeKey = (0, schema_js_1.camelToSnake)(key);
-            if (!qi.tableMeta.columns.some((c) => c.name === snakeKey) && !Object.hasOwn(qi.tableMeta.columnMap, key)) {
-                console.warn(`[turbine] Unknown orderBy field "${key}" for table "${qi.tableMeta.name}". ` +
-                    'This will cause a runtime error.');
-            }
-        }
-    }
+    // There used to be a dev-only pre-scan here that printed `Unknown orderBy
+    // field "x" for table "y". This will cause a runtime error.` and then let
+    // compilation continue into the code below, which throws for the same key
+    // with a better message (it names the table, suggests the closest column and
+    // lists the valid relations). Every unknown-key shape was measured: plain
+    // direction, OrderBySpec, JSON path, both relation-shaped values, and array
+    // form. All six warn-and-then-throw; none reaches the end of this function.
+    // A warning whose entire content is a prediction of the exception on the next
+    // line is noise in dev logs and a second place to keep the key-resolution
+    // rules in step, so it is gone. See orderby-unknown-field.test.ts, which pins
+    // the refusal itself across that surface.
     const meta = qi.schema.tables[qi.table];
     let relOrdCounter = 0;
     return (0, filters_js_1.orderByEntries)(orderBy)
@@ -1210,30 +1263,17 @@ function parseNestedRow(qi, row, table, fromJson = false) {
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
  * {@link buildRelationShape} (decode key order) so they can never diverge.
+ *
+ * A relation always projects SOMETHING, so the `null` that
+ * {@link resolveProjection} uses for the top level's `SELECT *` fast path
+ * becomes the target's full column list here. That is the only difference
+ * between the two, and it is why this is a four-line wrapper rather than a
+ * second implementation.
  */
-function resolveTargetColumns(qi, spec, targetMeta, includePii) {
-    if (spec !== true && spec.select) {
-        // Explicit `select` names the columns: a PII column named here IS the
-        // opt-in and comes back regardless of the query's `includePii`.
-        const selectedFields = Object.entries(spec.select)
-            .filter(([, v]) => v)
-            .map(([k]) => (0, utils_js_1.ownLookup)(targetMeta.columnMap, k) ?? (0, schema_js_1.camelToSnake)(k));
-        return selectedFields.filter((col) => targetMeta.allColumns.includes(col));
-    }
-    // Default / omit-only relation projection: PII columns are excluded unless
-    // the query opted in via `includePii`.
-    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, targetMeta);
-    const hasPii = piiCols !== undefined && piiCols.size > 0;
-    if (spec !== true && spec.omit) {
-        const omittedFields = new Set(Object.entries(spec.omit)
-            .filter(([, v]) => v)
-            .map(([k]) => (0, utils_js_1.ownLookup)(targetMeta.columnMap, k) ?? (0, schema_js_1.camelToSnake)(k)));
-        return targetMeta.allColumns.filter((col) => !omittedFields.has(col) && !(hasPii && piiCols.has(col)));
-    }
-    if (hasPii) {
-        return targetMeta.allColumns.filter((col) => !piiCols.has(col));
-    }
-    return targetMeta.allColumns;
+function resolveTargetColumns(qi, spec, targetMeta, includePii, targetTable = targetMeta.name) {
+    const select = spec === true ? undefined : spec.select;
+    const omit = spec === true ? undefined : spec.omit;
+    return resolveProjection(qi, targetTable, targetMeta, select, omit, includePii) ?? targetMeta.allColumns;
 }
 /**
  * Render a single relation row's JSON: a keyed object (`'object'`) or a
@@ -1384,7 +1424,7 @@ function buildRelationShape(qi, relDef, spec, parentMeta, includePii) {
     const targetMeta = qi.schema.tables[relDef.to];
     if (!targetMeta)
         return { keys: [], nested: {}, cardinality: 'many' };
-    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     const keys = targetColumns.map((col) => targetMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col));
     const nested = {};
     if (spec !== true && spec.with) {
@@ -1642,7 +1682,7 @@ function planFlattenNode(qi, counter, relName, relDef, spec, depth, path, includ
         }
     }
     const alias = `${FLATTEN_ALIAS_PREFIX}${counter.n++}`;
-    const cols = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const cols = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     const discAlias = `${alias}__${FLATTEN_DISCRIMINATOR}`;
     const node = {
         relName,
@@ -2212,7 +2252,7 @@ function buildRelationSubquery(qi, relDef, spec, params, parentRef, aliasCounter
     // `includePii` opt-in). Shared with the positional-shape builder so the
     // emitted json_build_array column order and the decode-side key order can
     // never drift apart.
-    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     // Engine override seam (additive): a dialect whose JSON-aggregation shape does
     // not map onto buildJsonObject/buildJsonArrayAgg (SQL Server FOR JSON PATH) owns
     // the WHOLE subquery. Absent for PG/MySQL/SQLite → the native path below runs

package/dist/cjs/query/utils.d.ts

@@ -451,3 +451,19 @@ export declare function unknownFieldMessage(table: string, field: string, meta:
     columnMap: Record<string, string>;
     relations?: Record<string, unknown>;
 }): string;
+/**
+ * The error text for a RELATION named inside `select` / `omit`.
+ *
+ * Separate from {@link unknownFieldMessage} because the generic text degrades
+ * into nonsense here: `closestName` matches an exactly-spelled relation name at
+ * distance zero, so the message would read `Unknown field "comments". Did you
+ * mean "comments" (a relation)?`, which answers a question nobody asked and
+ * hides the actual fix.
+ *
+ * It is worth its own message for a second reason: this is not really a typo,
+ * it is a habit. Prisma nests a relation inside `select`, so writing
+ * `select: { comments: true }` is the natural first guess, and in Turbine a
+ * relation is loaded by `with`, which sits BESIDE `select` rather than inside
+ * it. Naming the fix costs one sentence and saves a search.
+ */
+export declare function relationInProjectionMessage(table: string, field: string, clause: 'select' | 'omit'): string;

package/dist/cjs/query/utils.js

@@ -36,6 +36,7 @@ exports.coerceJsonWireValue = coerceJsonWireValue;
 exports.closestName = closestName;
 exports.suggestKey = suggestKey;
 exports.unknownFieldMessage = unknownFieldMessage;
+exports.relationInProjectionMessage = relationInProjectionMessage;
 const pg_1 = __importDefault(require("pg"));
 const schema_js_1 = require("../schema.js");
 const warn_registry_js_1 = require("./warn-registry.js");
@@ -886,3 +887,27 @@ function unknownFieldMessage(table, field, meta) {
         ` Known columns: ${columns.join(', ') || '(none)'}.` +
         (relations.length ? ` Known relations (valid in \`where\` and \`with\`): ${relations.join(', ')}.` : ''));
 }
+/**
+ * The error text for a RELATION named inside `select` / `omit`.
+ *
+ * Separate from {@link unknownFieldMessage} because the generic text degrades
+ * into nonsense here: `closestName` matches an exactly-spelled relation name at
+ * distance zero, so the message would read `Unknown field "comments". Did you
+ * mean "comments" (a relation)?`, which answers a question nobody asked and
+ * hides the actual fix.
+ *
+ * It is worth its own message for a second reason: this is not really a typo,
+ * it is a habit. Prisma nests a relation inside `select`, so writing
+ * `select: { comments: true }` is the natural first guess, and in Turbine a
+ * relation is loaded by `with`, which sits BESIDE `select` rather than inside
+ * it. Naming the fix costs one sentence and saves a search.
+ */
+function relationInProjectionMessage(table, field, clause) {
+    const head = `[turbine] "${field}" is a relation on table "${table}", not a column, so it cannot be named in \`${clause}\`.`;
+    return clause === 'select'
+        ? `${head} Load it with \`with: { ${field}: true }\`, which is a sibling of \`select\`, not a member of it.` +
+            " To narrow the relation's own columns, put a `select` inside that relation's options:" +
+            ` \`with: { ${field}: { select: { … } } }\`.`
+        : `${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.';
+}

package/dist/powql.d.ts

@@ -307,6 +307,15 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
      * and returns it regardless. Untagged tables project exactly as before.
      */
+    /**
+     * Resolve one projection field name, or throw. PowQL already refused an
+     * unresolvable name here (via {@link column}), unlike the SQL engines' join
+     * path, which filtered it out silently until 0.64. What this adds is the
+     * RELATION case: naming a relation inside `select` is a Prisma habit rather
+     * than a typo, and the generic "unknown column" text sends the reader looking
+     * for a misspelling that is not there. Same message as the SQL engines.
+     */
+    private projectionColumn;
     private projectedColumns;
     /**
      * The snake_case names of this table's PII-tagged columns. Empty for a table

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 } from './query/utils.js';
+import { escapeLike, ownLookup, relationInProjectionMessage } from './query/utils.js';
 import { assertJsonFilterKeys, jsonStringEntries } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -872,6 +872,20 @@ export class PowqlInterface {
      * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
      * and returns it regardless. Untagged tables project exactly as before.
      */
+    /**
+     * Resolve one projection field name, or throw. PowQL already refused an
+     * unresolvable name here (via {@link column}), unlike the SQL engines' join
+     * path, which filtered it out silently until 0.64. What this adds is the
+     * RELATION case: naming a relation inside `select` is a Prisma habit rather
+     * than a typo, and the generic "unknown column" text sends the reader looking
+     * for a misspelling that is not there. Same message as the SQL engines.
+     */
+    projectionColumn(field, clause) {
+        if (ownLookup(this.meta.relations, field)) {
+            throw new ValidationError(relationInProjectionMessage(this.table, field, clause));
+        }
+        return this.column(field).name;
+    }
     projectedColumns(select, omit, includePii) {
         const pk = new Set(this.meta.primaryKey);
         let cols = this.meta.columns.map((c) => c.name);
@@ -879,7 +893,7 @@ export class PowqlInterface {
         if (hasSelect) {
             const picked = new Set(Object.entries(select)
                 .filter(([, v]) => v)
-                .map(([k]) => this.column(k).name));
+                .map(([k]) => this.projectionColumn(k, 'select')));
             // Always keep the PK so reselect / relation stitching has a key to work with.
             for (const key of pk)
                 picked.add(key);
@@ -900,7 +914,7 @@ export class PowqlInterface {
         if (omit && Object.keys(omit).length) {
             const dropped = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
-                .map(([k]) => this.column(k).name));
+                .map(([k]) => this.projectionColumn(k, 'omit')));
             // The PK survives `omit` too. This filter ran unconditionally and after
             // the `select` branch's force-add, so `omit: { id: true }` undid the very
             // guarantee that force-add exists to provide: the m2m loader keys its

package/dist/query/relations.d.ts

@@ -34,8 +34,41 @@ export interface RelationShape {
     cardinality: 'many' | 'one';
 }
 /**
- * Resolve select/omit options into a list of snake_case column names.
- * Returns null if neither is provided (meaning all columns).
+ * Resolve `select` / `omit` into a list of snake_case column names, for the
+ * query's own table and for a relation target alike. `null` means "no
+ * projection", i.e. all columns, which keeps the `*` fast path.
+ *
+ * ## Why this is one function
+ *
+ * It used to be two, `resolveColumns` for the top level and
+ * `resolveTargetColumns` for a relation target, doing the same job against
+ * different metadata. They drifted, and the drift was invisible from either
+ * side: the top level resolved every name through a throwing lookup, while the
+ * relation side filtered unresolvable names out and emitted SQL for whatever
+ * survived. So the SAME key in the SAME query threw at the top and was silently
+ * ignored one level down, where `select: { titel: true }` returned `{}` rows
+ * and `omit: { titel: true }` returned the column it was asked to hide.
+ *
+ * It was worse than an inconsistency between depths. The batched loader runs
+ * each relation as a real query against the target table, so it went through
+ * the THROWING path, while the join plan went through the silent one. The two
+ * strategies therefore disagreed about whether the query was even valid, and
+ * under `relationLoadStrategy: 'auto'` which one runs is decided by a cost
+ * heuristic reading index coverage and table size. The same code threw on one
+ * table and quietly returned the wrong shape on another.
+ *
+ * Merging them is the fix that outlives this bug. Two functions that must agree
+ * are kept in step by whoever remembers; one function cannot disagree with
+ * itself. This mirrors `walkWhere` in where-compile.ts, which exists for the
+ * same reason after the top-level and relation-scoped WHERE walkers drifted
+ * twice, and it is why a new projection site is safe by default: PII exclusion,
+ * the `*` fast path and name resolution all live here, so reimplementing the
+ * name handling would mean reimplementing those too.
+ */
+export declare function resolveProjection(qi: BuilderCtx, table: string, meta: TableMetadata, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
+/**
+ * The query's own table. Thin wrapper over {@link resolveProjection} kept for
+ * the existing call sites in builder.ts.
  */
 export declare function resolveColumns(qi: BuilderCtx, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
 /**
@@ -254,8 +287,14 @@ export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unkno
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
  * {@link buildRelationShape} (decode key order) so they can never diverge.
+ *
+ * A relation always projects SOMETHING, so the `null` that
+ * {@link resolveProjection} uses for the top level's `SELECT *` fast path
+ * becomes the target's full column list here. That is the only difference
+ * between the two, and it is why this is a four-line wrapper rather than a
+ * second implementation.
  */
-export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean): string[];
+export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean, targetTable?: string): string[];
 /**
  * Render a single relation row's JSON: a keyed object (`'object'`) or a
  * positional array (`'positional'`). The array drops the keys but keeps the

package/dist/query/relations.js

@@ -18,15 +18,63 @@ 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 } from './utils.js';
+import { ownLookup, relationInProjectionMessage, resolveColumnName, 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';
 /**
- * Resolve select/omit options into a list of snake_case column names.
- * Returns null if neither is provided (meaning all columns).
+ * Turn ONE caller-supplied projection field name into a column, or throw.
+ *
+ * The whole point of this function is that it has no third outcome. The
+ * relation-side projection used to filter unresolvable names out
+ * (`.filter((col) => allColumns.includes(col))`) instead of rejecting them, and
+ * a filter that discards is exactly how a name typed by a human becomes SQL
+ * that no longer reflects what was asked for.
  */
-export function resolveColumns(qi, select, omit, includePii) {
+function projectionColumn(table, meta, field, clause) {
+    const column = resolveColumnName(meta, field);
+    if (column)
+        return column;
+    // A relation named in a projection is a habit, not a typo, so it gets its own
+    // message pointing at `with`. Checked BEFORE the generic throw because the
+    // generic one degrades into "Did you mean <exactly what you typed>?".
+    if (ownLookup(meta.relations, field))
+        throw new ValidationError(relationInProjectionMessage(table, field, clause));
+    throw new ValidationError(unknownFieldMessage(table, field, meta));
+}
+/**
+ * Resolve `select` / `omit` into a list of snake_case column names, for the
+ * query's own table and for a relation target alike. `null` means "no
+ * projection", i.e. all columns, which keeps the `*` fast path.
+ *
+ * ## Why this is one function
+ *
+ * It used to be two, `resolveColumns` for the top level and
+ * `resolveTargetColumns` for a relation target, doing the same job against
+ * different metadata. They drifted, and the drift was invisible from either
+ * side: the top level resolved every name through a throwing lookup, while the
+ * relation side filtered unresolvable names out and emitted SQL for whatever
+ * survived. So the SAME key in the SAME query threw at the top and was silently
+ * ignored one level down, where `select: { titel: true }` returned `{}` rows
+ * and `omit: { titel: true }` returned the column it was asked to hide.
+ *
+ * It was worse than an inconsistency between depths. The batched loader runs
+ * each relation as a real query against the target table, so it went through
+ * the THROWING path, while the join plan went through the silent one. The two
+ * strategies therefore disagreed about whether the query was even valid, and
+ * under `relationLoadStrategy: 'auto'` which one runs is decided by a cost
+ * heuristic reading index coverage and table size. The same code threw on one
+ * table and quietly returned the wrong shape on another.
+ *
+ * Merging them is the fix that outlives this bug. Two functions that must agree
+ * are kept in step by whoever remembers; one function cannot disagree with
+ * itself. This mirrors `walkWhere` in where-compile.ts, which exists for the
+ * same reason after the top-level and relation-scoped WHERE walkers drifted
+ * twice, and it is why a new projection site is safe by default: PII exclusion,
+ * the `*` fast path and name resolution all live here, so reimplementing the
+ * name handling would mean reimplementing those too.
+ */
+export function resolveProjection(qi, table, meta, select, omit, includePii) {
     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
@@ -40,12 +88,12 @@ export function resolveColumns(qi, select, omit, includePii) {
         // PII column IS the opt-in: it comes back regardless of `includePii`.
         return Object.entries(select)
             .filter(([, v]) => v)
-            .map(([k]) => qi.toColumn(k));
+            .map(([k]) => projectionColumn(table, meta, k, 'select'));
     }
     // Default / omit-only projection: PII-tagged columns are excluded unless the
     // caller opted in with `includePii: UNSAFE`. An empty set (untagged schema) keeps the
     // `null`/`*` fast path so the emitted SQL is byte-identical to before.
-    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, qi.tableMeta);
+    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, meta);
     const hasPii = piiCols !== undefined && piiCols.size > 0;
     if (omit) {
         if (Array.isArray(omit)) {
@@ -54,14 +102,21 @@ export function resolveColumns(qi, select, omit, includePii) {
         // Include all columns except those where value is true (and PII columns).
         const omitCols = new Set(Object.entries(omit)
             .filter(([, v]) => v)
-            .map(([k]) => qi.toColumn(k)));
-        return qi.tableMeta.allColumns.filter((col) => !omitCols.has(col) && !(hasPii && piiCols.has(col)));
+            .map(([k]) => projectionColumn(table, meta, k, 'omit')));
+        return meta.allColumns.filter((col) => !omitCols.has(col) && !(hasPii && piiCols.has(col)));
     }
     if (hasPii) {
-        return qi.tableMeta.allColumns.filter((col) => !piiCols.has(col));
+        return meta.allColumns.filter((col) => !piiCols.has(col));
     }
     return null;
 }
+/**
+ * The query's own table. Thin wrapper over {@link resolveProjection} kept for
+ * the existing call sites in builder.ts.
+ */
+export function resolveColumns(qi, select, omit, includePii) {
+    return resolveProjection(qi, qi.table, qi.tableMeta, select, omit, includePii);
+}
 /**
  * Produce a fingerprint for a `with` clause tree. Recursion mirrors
  * buildSelectWithRelations / buildRelationSubquery.
@@ -326,20 +381,17 @@ export function orderByEntryFingerprint(qi, d, targetTable) {
     return String(d);
 }
 export function buildOrderBy(qi, orderBy, params, lateralSink) {
-    // Dev-only: validate that orderBy fields exist in the table schema. Relation
-    // orderBy keys (object values that are neither a vector nor an OrderBySpec)
-    // are validated in the relation branch below, so skip them here.
-    if (process.env.NODE_ENV !== 'production') {
-        for (const [key, value] of orderByEntries(orderBy)) {
-            if (isRelationOrderByValue(qi, value) && ownLookup(qi.tableMeta.relations, key))
-                continue;
-            const snakeKey = camelToSnake(key);
-            if (!qi.tableMeta.columns.some((c) => c.name === snakeKey) && !Object.hasOwn(qi.tableMeta.columnMap, key)) {
-                console.warn(`[turbine] Unknown orderBy field "${key}" for table "${qi.tableMeta.name}". ` +
-                    'This will cause a runtime error.');
-            }
-        }
-    }
+    // There used to be a dev-only pre-scan here that printed `Unknown orderBy
+    // field "x" for table "y". This will cause a runtime error.` and then let
+    // compilation continue into the code below, which throws for the same key
+    // with a better message (it names the table, suggests the closest column and
+    // lists the valid relations). Every unknown-key shape was measured: plain
+    // direction, OrderBySpec, JSON path, both relation-shaped values, and array
+    // form. All six warn-and-then-throw; none reaches the end of this function.
+    // A warning whose entire content is a prediction of the exception on the next
+    // line is noise in dev logs and a second place to keep the key-resolution
+    // rules in step, so it is gone. See orderby-unknown-field.test.ts, which pins
+    // the refusal itself across that surface.
     const meta = qi.schema.tables[qi.table];
     let relOrdCounter = 0;
     return orderByEntries(orderBy)
@@ -1133,30 +1185,17 @@ export function parseNestedRow(qi, row, table, fromJson = false) {
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
  * {@link buildRelationShape} (decode key order) so they can never diverge.
+ *
+ * A relation always projects SOMETHING, so the `null` that
+ * {@link resolveProjection} uses for the top level's `SELECT *` fast path
+ * becomes the target's full column list here. That is the only difference
+ * between the two, and it is why this is a four-line wrapper rather than a
+ * second implementation.
  */
-export function resolveTargetColumns(qi, spec, targetMeta, includePii) {
-    if (spec !== true && spec.select) {
-        // Explicit `select` names the columns: a PII column named here IS the
-        // opt-in and comes back regardless of the query's `includePii`.
-        const selectedFields = Object.entries(spec.select)
-            .filter(([, v]) => v)
-            .map(([k]) => ownLookup(targetMeta.columnMap, k) ?? camelToSnake(k));
-        return selectedFields.filter((col) => targetMeta.allColumns.includes(col));
-    }
-    // Default / omit-only relation projection: PII columns are excluded unless
-    // the query opted in via `includePii`.
-    const piiCols = includePii ? undefined : writesMod.piiColumns(qi, targetMeta);
-    const hasPii = piiCols !== undefined && piiCols.size > 0;
-    if (spec !== true && spec.omit) {
-        const omittedFields = new Set(Object.entries(spec.omit)
-            .filter(([, v]) => v)
-            .map(([k]) => ownLookup(targetMeta.columnMap, k) ?? camelToSnake(k)));
-        return targetMeta.allColumns.filter((col) => !omittedFields.has(col) && !(hasPii && piiCols.has(col)));
-    }
-    if (hasPii) {
-        return targetMeta.allColumns.filter((col) => !piiCols.has(col));
-    }
-    return targetMeta.allColumns;
+export function resolveTargetColumns(qi, spec, targetMeta, includePii, targetTable = targetMeta.name) {
+    const select = spec === true ? undefined : spec.select;
+    const omit = spec === true ? undefined : spec.omit;
+    return resolveProjection(qi, targetTable, targetMeta, select, omit, includePii) ?? targetMeta.allColumns;
 }
 /**
  * Render a single relation row's JSON: a keyed object (`'object'`) or a
@@ -1307,7 +1346,7 @@ export function buildRelationShape(qi, relDef, spec, parentMeta, includePii) {
     const targetMeta = qi.schema.tables[relDef.to];
     if (!targetMeta)
         return { keys: [], nested: {}, cardinality: 'many' };
-    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, 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) {
@@ -1565,7 +1604,7 @@ function planFlattenNode(qi, counter, relName, relDef, spec, depth, path, includ
         }
     }
     const alias = `${FLATTEN_ALIAS_PREFIX}${counter.n++}`;
-    const cols = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const cols = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     const discAlias = `${alias}__${FLATTEN_DISCRIMINATOR}`;
     const node = {
         relName,
@@ -2135,7 +2174,7 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // `includePii` opt-in). Shared with the positional-shape builder so the
     // emitted json_build_array column order and the decode-side key order can
     // never drift apart.
-    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii);
+    const targetColumns = resolveTargetColumns(qi, spec, targetMeta, includePii, relDef.to);
     // Engine override seam (additive): a dialect whose JSON-aggregation shape does
     // not map onto buildJsonObject/buildJsonArrayAgg (SQL Server FOR JSON PATH) owns
     // the WHOLE subquery. Absent for PG/MySQL/SQLite → the native path below runs

package/dist/query/utils.d.ts

@@ -451,3 +451,19 @@ export declare function unknownFieldMessage(table: string, field: string, meta:
     columnMap: Record<string, string>;
     relations?: Record<string, unknown>;
 }): string;
+/**
+ * The error text for a RELATION named inside `select` / `omit`.
+ *
+ * Separate from {@link unknownFieldMessage} because the generic text degrades
+ * into nonsense here: `closestName` matches an exactly-spelled relation name at
+ * distance zero, so the message would read `Unknown field "comments". Did you
+ * mean "comments" (a relation)?`, which answers a question nobody asked and
+ * hides the actual fix.
+ *
+ * It is worth its own message for a second reason: this is not really a typo,
+ * it is a habit. Prisma nests a relation inside `select`, so writing
+ * `select: { comments: true }` is the natural first guess, and in Turbine a
+ * relation is loaded by `with`, which sits BESIDE `select` rather than inside
+ * it. Naming the fix costs one sentence and saves a search.
+ */
+export declare function relationInProjectionMessage(table: string, field: string, clause: 'select' | 'omit'): string;

package/dist/query/utils.js

@@ -852,3 +852,27 @@ export function unknownFieldMessage(table, field, meta) {
         ` Known columns: ${columns.join(', ') || '(none)'}.` +
         (relations.length ? ` Known relations (valid in \`where\` and \`with\`): ${relations.join(', ')}.` : ''));
 }
+/**
+ * The error text for a RELATION named inside `select` / `omit`.
+ *
+ * Separate from {@link unknownFieldMessage} because the generic text degrades
+ * into nonsense here: `closestName` matches an exactly-spelled relation name at
+ * distance zero, so the message would read `Unknown field "comments". Did you
+ * mean "comments" (a relation)?`, which answers a question nobody asked and
+ * hides the actual fix.
+ *
+ * It is worth its own message for a second reason: this is not really a typo,
+ * it is a habit. Prisma nests a relation inside `select`, so writing
+ * `select: { comments: true }` is the natural first guess, and in Turbine a
+ * relation is loaded by `with`, which sits BESIDE `select` rather than inside
+ * it. Naming the fix costs one sentence and saves a search.
+ */
+export function relationInProjectionMessage(table, field, clause) {
+    const head = `[turbine] "${field}" is a relation on table "${table}", not a column, so it cannot be named in \`${clause}\`.`;
+    return clause === 'select'
+        ? `${head} Load it with \`with: { ${field}: true }\`, which is a sibling of \`select\`, not a member of it.` +
+            " To narrow the relation's own columns, put a `select` inside that relation's options:" +
+            ` \`with: { ${field}: { select: { … } } }\`.`
+        : `${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.';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.63.0",
+  "version": "0.64.1",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",