turbine-orm 0.71.0 → 0.72.0

package/dist/query/relations.js

@@ -14,11 +14,11 @@
  */
 import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { missingIndexForRelation } from '../index-advisor.js';
-import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
+import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { resolveCountRelations } from './batched-loader.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, MAX_NAMED_ORDER_KEYS, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
 import { assertDirectionToken, assertOrderDirection } from './types.js';
-import { canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, selectNamesNothingMessage, selectOmitExclusiveMessage, unknownFieldMessage, } from './utils.js';
+import { canonicalColumnOrder, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelation, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, unknownFieldMessage, } from './utils.js';
 import { hasWarnedOnce, shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -38,7 +38,10 @@ function projectionColumn(table, meta, field, clause) {
     // 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))
+    // Resolved, so `select: { ripening_checks: true }` gets the "that is a
+    // relation, use `with`" message rather than degrading to an unknown-field
+    // suggestion that names the relation back at the caller.
+    if (resolveRelationDef(meta.relations, field))
         throw new ValidationError(relationInProjectionMessage(table, field, clause));
     throw new ValidationError(unknownFieldMessage(table, field, meta));
 }
@@ -462,10 +465,8 @@ export function buildOrderBy(qi, orderBy, params, lateralSink) {
         .map(([key, value]) => {
         // Vector KNN ordering: { distance: { to, metric, direction? } }
         if (isVectorOrderBy(value)) {
-            if (meta && !(key in meta.columnMap)) {
-                throw new ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${qi.table}". ` +
-                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
-            }
+            if (meta)
+                resolveOrderByColumn(qi, qi.table, meta, key);
             if (!params) {
                 throw new ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
             }
@@ -488,10 +489,13 @@ export function buildOrderBy(qi, orderBy, params, lateralSink) {
             return buildRelationOrderBy(qi, key, value, `ord${relOrdCounter++}`, params, undefined, lateralSink);
         }
         // Scalar column ordering, a plain direction or an OrderBySpec (nulls).
-        if (meta && !(key in meta.columnMap)) {
-            throw new ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${qi.table}". ` +
-                `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
-        }
+        // Through `resolveOrderByColumn`, which is the same resolve-or-E003 the
+        // nested orderBy paths below already used and emits the same message
+        // this used to inline. It used to test `key in meta.columnMap`, which
+        // knows only the FIELD spelling, and so rejected the snake_case COLUMN
+        // name that `where` / `select` / `distinct` accept on the same table.
+        if (meta)
+            resolveOrderByColumn(qi, qi.table, meta, key);
         // Refuse a direction that is neither asc nor desc. normalizeOrderBy is
         // `=== 'desc' ? DESC : ASC`, so without this every typo sorted ASCENDING
         // and returned a correct-looking page in the reverse order.
@@ -529,16 +533,21 @@ export function nullsSuffix(qi, nulls) {
     return nulls === 'first' ? ' NULLS FIRST' : ' NULLS LAST';
 }
 /**
- * Resolve an orderBy key to its snake_case column via the table's columnMap
- * (camelToSnake fallback), throwing the SAME unknown-field E003 the top-level
- * where path uses. Shared by top-level JSON-path ordering and every nested
- * relation orderBy path so nested orderBy accepts exactly what top-level
- * accepts (the 0.30.x bug: nested orderBy skipped the columnMap and rejected
- * camelCase-named DB columns like "sortOrder").
+ * Resolve an orderBy key to its snake_case column via {@link resolveColumnName},
+ * throwing the SAME unknown-field E003 the top-level where path uses. Shared by
+ * top-level JSON-path ordering and every nested relation orderBy path so nested
+ * orderBy accepts exactly what top-level accepts (the 0.30.x bug: nested orderBy
+ * skipped the columnMap and rejected camelCase-named DB columns like
+ * "sortOrder").
+ *
+ * The rule is REACHED here, never restated: this used to inline
+ * `columnMap ?? camelToSnake` + an `allColumns` check, which agreed with
+ * `resolveColumnName` while the top-level scalar path a few lines up disagreed
+ * with both.
  */
 export function resolveOrderByColumn(_qi, table, meta, key) {
-    const col = ownLookup(meta.columnMap, key) ?? camelToSnake(key);
-    if (!meta.allColumns.includes(col)) {
+    const col = resolveColumnName(meta, key);
+    if (col === undefined) {
         throw new ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${table}". ` +
             `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
     }
@@ -667,14 +676,18 @@ function buildChainedToOneOrderBy(qi, head, nextRelName, nextValue, params) {
                 `(got: ${entries.map(([k]) => k).join(', ') || '(empty)'}).`);
         }
         const [key, entryValue] = entries[0];
-        if (ownLookup(currentMeta.relations, key) && isRelationOrderByValue(qi, entryValue)) {
-            relName = key;
+        // Resolved, so a chained orderBy descends through the snake_case spelling
+        // of a relation exactly as `with` does; `relName` carries the DECLARED
+        // name onward so the path reported in errors is the canonical one.
+        const chained = resolveRelation(currentMeta.relations, key);
+        if (chained && isRelationOrderByValue(qi, entryValue)) {
+            relName = chained.name;
             value = entryValue;
             continue;
         }
         // Terminal: a column on the last table in the chain.
-        const snakeCol = ownLookup(currentMeta.columnMap, key) ?? camelToSnake(key);
-        if (!currentMeta.allColumns.includes(snakeCol)) {
+        const snakeCol = resolveColumnName(currentMeta, key);
+        if (snakeCol === undefined) {
             throw new ValidationError(`[turbine] Unknown column "${key}" in orderBy on relation "${path.join('.')}" (table "${currentMeta.name}").`);
         }
         assertOrderDirection(entryValue, `orderBy on relation path "${path.join('.')}"`);
@@ -709,7 +722,12 @@ export function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lat
     const ownerMeta = ctx?.meta ?? qi.tableMeta;
     const ownerTable = ctx?.table ?? qi.table;
     const parentRef = ctx?.parentRef ?? qi.table;
-    const relDef = ownLookup(ownerMeta.relations, relName);
+    // Resolved, then `relName` is rebound to the declared spelling so the alias
+    // and every message below use one name.
+    const resolvedOwner = resolveRelation(ownerMeta.relations, relName);
+    if (resolvedOwner)
+        relName = resolvedOwner.name;
+    const relDef = resolvedOwner?.def;
     if (!relDef) {
         // A table with no relations at all would otherwise render a dangling
         // "Available: " and read as a broken message; and the most likely cause of
@@ -717,7 +735,7 @@ export function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lat
         // scalar column, which deserves to be named rather than reported as a
         // missing relation.
         const known = Object.keys(ownerMeta.relations);
-        const isColumn = Object.hasOwn(ownerMeta.columnMap, relName) || ownerMeta.allColumns.includes(relName);
+        const isColumn = resolveColumnName(ownerMeta, relName) !== undefined;
         throw new RelationError(isColumn
             ? `[turbine] orderBy on "${ownerTable}.${relName}" got a relation-shaped value, but "${relName}" is a ` +
                 `column. Order a column with 'asc' / 'desc' (or { sort, nulls }); the object form is for relations.`
@@ -768,10 +786,10 @@ export function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lat
         if (nestedRel && isRelationOrderByValue(qi, dirValue)) {
             return buildChainedToOneOrderBy(qi, { relName, relDef, alias, correlation }, col, dirValue, params);
         }
-        // columnMap-first resolution (camelToSnake fallback): mirrors the
-        // scalar orderBy path so camelCase-named DB columns resolve here too.
-        const snakeCol = ownLookup(targetMeta.columnMap, col) ?? camelToSnake(col);
-        if (!targetMeta.allColumns.includes(snakeCol)) {
+        // The ONE key-resolution rule ({@link resolveColumnName}), so a target
+        // column resolves here exactly as it does in the top-level orderBy.
+        const snakeCol = resolveColumnName(targetMeta, col);
+        if (snakeCol === undefined) {
             const relationHint = ownLookup(targetMeta.relations, col)
                 ? ` "${col}" is a relation on "${relDef.to}": order by one of ITS columns, e.g. ` +
                     `{ ${relName}: { ${col}: { <column>: 'asc' } } }.`

package/dist/query/utils.d.ts

@@ -59,6 +59,47 @@ export interface ColumnNameSource {
  * name (see {@link ownLookup}).
  */
 export declare function resolveColumnName(meta: ColumnNameSource, key: string): string | undefined;
+/**
+ * Resolve a user-supplied key to a relation's CANONICAL name and definition, or
+ * `undefined` when the key names no relation on the table.
+ *
+ * The relation-name half of the rule {@link resolveColumnName} states for
+ * columns, and deliberately the same shape: the declared name first, else
+ * `snakeToCamel(key)` accepted ONLY when that names a real relation.
+ * `snakeToCamel` is idempotent on an already-camel string, so a canonical key
+ * takes the first branch and this is a no-op for every existing caller.
+ *
+ * WHY IT EXISTS. A relation has one declared name, `ripeningChecks`, while the
+ * DDL anyone reads has only the TABLE name, `ripening_checks`. Writing back
+ * what the schema shows therefore failed with E005 in `with`, E003 in a
+ * relation filter, and E005 in `orderBy`, on names the error text was already
+ * computing correctly ("Did you mean ...?"). A system that can name the
+ * intended relation can accept it.
+ *
+ * NOT A GUESS, for the same reason the column rule is not: the transformed name
+ * is accepted only when it is a real declared relation, so an unknown key still
+ * fails and a typo is still a typo. Exact match wins first, so a schema that
+ * literally declares `ripening_checks` keeps it, even alongside a
+ * `ripeningChecks`.
+ *
+ * The RESULT KEY is the canonical name, not the caller's spelling, matching the
+ * column side (`select: { ledger_handle: true }` already returns
+ * `{ ledgerHandle }`). Resolving here rather than normalizing the args up front
+ * also means both spellings share one SQL-cache entry instead of minting two
+ * templates for one query.
+ *
+ * Prototype-safe via {@link ownLookup}, so `__proto__` cannot name a relation.
+ */
+export declare function resolveRelation<R>(relations: Record<string, R>, key: string): {
+    name: string;
+    def: R;
+} | undefined;
+/**
+ * {@link resolveRelation} when only the definition is wanted: a drop-in for the
+ * `ownLookup(meta.relations, key)` it replaces, with the same signature and the
+ * same `undefined` on a miss.
+ */
+export declare function resolveRelationDef<R>(relations: Record<string, R>, key: string): R | undefined;
 /**
  * THE canonical order for a caller-supplied set of columns: the table's own
  * `allColumns` order, which is the order `omit` and the default projection
@@ -356,6 +397,19 @@ export declare function isTemporalInfinity(value: unknown): boolean;
  * astronomical year (`0044 BC` → -43) the way the driver's own parser does.
  */
 export declare function createUtcDateParser(fallback: (text: string) => unknown): (text: string) => unknown;
+/**
+ * The `date` (OID 1082) parser WITHOUT the fast scan in front of it: the regex
+ * implementation described by {@link createUtcDateParser}, and the reference
+ * side of the differential test.
+ *
+ * Exported so "what the fast path must agree with" is the running code rather
+ * than a transcription of it in a test file. Two hand-synced copies of a
+ * parser is the drift class this repo has been bitten by before; there is one
+ * copy, and the fast path delegates to it.
+ *
+ * @internal
+ */
+export declare function createUtcDateParserGeneral(fallback: (text: string) => unknown): (text: string) => unknown;
 /**
  * Build the driver parser for Postgres `timestamp` (OID 1114) that reads an
  * offset-less date-time as UTC. Also lifted to the `_timestamp` array OID
@@ -376,6 +430,34 @@ export declare function createUtcDateParser(fallback: (text: string) => unknown)
  * `Date`-string parsing did too.
  */
 export declare function createUtcTimestampParser(fallback: (text: string) => unknown): (text: string) => unknown;
+/**
+ * The `timestamp` (OID 1114) parser WITHOUT the fast scan in front of it: the
+ * regex implementation described by {@link createUtcTimestampParser}, and the
+ * reference side of the differential test. Same reasoning as
+ * {@link createUtcDateParserGeneral}.
+ *
+ * @internal
+ */
+export declare function createUtcTimestampParserGeneral(fallback: (text: string) => unknown): (text: string) => unknown;
+/**
+ * Build the driver parser for Postgres `timestamptz` (OID 1184): the ISO wire
+ * shape decoded by {@link scanIsoTemporal}, everything else handed straight to
+ * `fallback`.
+ *
+ * UNLIKE the `date` and `timestamp` parsers beside it, this one changes NO
+ * READING. A `timestamptz` arrives with an explicit offset, so its instant is
+ * unambiguous and both this and `postgres-date` produce the same `Date`; the
+ * only difference is how long it takes. That is also why it is not governed by
+ * a semantic decision the way `utcTimestamps` governs the zone-less types: there
+ * is no second interpretation to choose between.
+ *
+ * `fallback` must be captured with `pg.types.getTypeParser(1184, 'text')`
+ * BEFORE registration, for the same reason as the parsers above: reading it
+ * afterwards hands back this function and recurses forever. It is what keeps
+ * `infinity` / `-infinity`, ` BC`, wide and low years, and every non-ISO
+ * `DateStyle` on `postgres-date`, which already handles them.
+ */
+export declare function createFastTimestamptzParser(fallback: (text: string) => unknown): (text: string) => unknown;
 /**
  * The offset-less-timestamp-as-UTC reading, with no fallback: `text` must be a
  * plain `YYYY-MM-DD HH:MM:SS[.ffffff]`. Used where the input shape is already
@@ -395,8 +477,17 @@ export declare function parseUtcTimestampText(text: string): Date;
  * `pg.types.arrayParser` is a public member of the `pg` module (it is what the
  * driver's own `_text` / `_date` parsers are built from), so this adds no
  * dependency. NULL elements stay `null` and are never handed to `element`.
+ *
+ * The empty-string guard mirrors pg's own `parseDateArray`, which opens
+ * `if (!value) return null`. Turbine's copy did not, and answered `[]` where
+ * the driver answers `null` for the same input. No column produces it (a SQL
+ * NULL never reaches a parser, and an empty array is `{}`), so this is parity
+ * for its own sake rather than a bug report; it matters because these parsers
+ * are registered process-globally over pg's, and a shape where Turbine's
+ * answer differs from the driver's is a difference somebody eventually finds
+ * the hard way.
  */
-export declare function createPgArrayParser(element: (text: string) => unknown): (text: string) => unknown[];
+export declare function createPgArrayParser(element: (text: string) => unknown): (text: string) => unknown[] | null;
 /** Tag `parser` as Turbine's own and return it (see {@link TURBINE_PARSER}). */
 export declare function markTurbineParser<F extends (text: string) => unknown>(parser: F): F;
 /**
@@ -458,8 +549,21 @@ export declare function isDefaultTextParser(oid: number, parser: (text: string)
  */
 export declare function warnParserOverwrite(oid: number, typeName: string): void;
 /**
- * Register the UTC readings of the four zone-less temporal OIDs on the pg
- * module: `timestamp` (1114), `date` (1082) and their array forms (1115, 1182).
+ * Register Turbine's temporal text parsers on the pg module. SIX OIDs, doing
+ * two different jobs:
+ *
+ *   1114 / 1082 / 1115 / 1182   the UTC READING of the zone-less types,
+ *                               `timestamp`, `date` and their array forms.
+ *                               This changes what a column means and is what
+ *                               `utcTimestamps` is named for.
+ *   1184 / 1185                 the fast decode path for `timestamptz` and
+ *                               `timestamptz[]`. This changes NOTHING about
+ *                               what a column means: an offset-carrying value
+ *                               has one instant and this reads the same one.
+ *                               It is here for speed, `timestamptz` being ~88%
+ *                               of the client-side decode cost of a wide row
+ *                               drain, and it DECLINES rather than overwrites
+ *                               (see the comment at the call site).
  *
  * ONE place, because `pg.types.setTypeParser` is process-global and the pairing
  * matters: registering a scalar without its array form, or a `date` without the