turbine-orm 0.50.0 → 0.51.0

package/dist/query/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Query builder types
+ * turbine-orm, Query builder types
  *
  * All exported type and interface definitions for the query builder module.
  */
@@ -128,7 +128,7 @@ export interface TypedToOneFilter<V, VR extends object = {}> {
  * to-one relations take `is`/`isNot` or a bare sub-where (implicit `is`).
  *
  * Legacy generated shapes (`posts: Post[]`, `profile: Profile | null`) carry no
- * brand, so they degrade to `unknown` — the key is still recognised (no typo
+ * brand, so they degrade to `unknown`, the key is still recognised (no typo
  * false-positive) but its value is not checked.
  */
 type RelationWhereValue<Rel> = Rel extends RelationDescriptor<infer Target, infer Cardinality, infer TR> ? Cardinality extends 'many' ? TypedRelationFilter<Target, TR & object> : TypedToOneFilter<Target, TR & object> | WhereClause<Target, TR & object> : unknown;
@@ -138,7 +138,7 @@ type RelationWhereValue<Rel> = Rel extends RelationDescriptor<infer Target, infe
  *
  * **Key checking.** Historically this type carried a
  * `[relationName: string]: unknown` index signature so relation filters
- * (`where: { posts: { some: ... } }`) would typecheck — the relation names are
+ * (`where: { posts: { some: ... } }`) would typecheck, the relation names are
  * NOT keys of the entity `T`. That index signature also annihilated
  * excess-property checking, so `where: { emial: 'x' }` compiled silently.
  *
@@ -160,7 +160,7 @@ export type LooseWhereClause<T> = {
     OR?: LooseWhereClause<T>[];
     AND?: LooseWhereClause<T>[];
     NOT?: LooseWhereClause<T>;
-    /** Relation filters — keyed by relation name, value is { some, every, none } */
+    /** Relation filters, keyed by relation name, value is { some, every, none } */
     [relationName: string]: unknown;
 };
 /** Key-checked where clause: column keys from `T`, relation keys from `R`, no index signature. */
@@ -177,7 +177,7 @@ type StrictWhereClause<T, R extends object> = {
  * Client-level automatic WHERE filters, keyed by table accessor (the name used
  * in `db[name]` / `client.table(name)`). Each value is AND-merged into the
  * compiled WHERE of every read and mutation on that table, and into every
- * relation subquery that targets it — the mechanism behind soft-delete and
+ * relation subquery that targets it, the mechanism behind soft-delete and
  * multi-tenancy. A function value is evaluated at query-build time (per query),
  * so a closure over per-request state (e.g. the current tenant id) enables
  * request-scoped filters. `create`/`createMany` are never filtered.
@@ -190,7 +190,7 @@ export type GlobalFilters = {
  * global filter on the query's own table AND on every relation target it
  * touches; an array skips only the named table accessors (own table and/or
  * relation targets). Global filters never satisfy the empty-`where` guard for
- * `update`/`delete` — that guard always checks the user-supplied `where`.
+ * `update`/`delete`, that guard always checks the user-supplied `where`.
  */
 export type SkipGlobalFilters = true | readonly string[];
 /**
@@ -201,7 +201,7 @@ export type SkipGlobalFilters = true | readonly string[];
  */
 export type WithCount = true | Record<string, true>;
 /**
- * Unparameterized with clause — accepts any relation name.
+ * Unparameterized with clause, accepts any relation name.
  * Used internally by the query builder at runtime.
  *
  * The reserved `_count` key (see {@link WithCount}) is also accepted at runtime;
@@ -219,7 +219,7 @@ export interface WithClause {
  *
  * For typed maps, each relation accepts either `true` (default include) or a
  * {@link WithOptions} object whose nested `with` is keyed against the relation
- * target's own relations interface — this is what enables deep
+ * target's own relations interface, this is what enables deep
  * `WithResult` inference.
  */
 export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ? WithClause : {
@@ -233,7 +233,7 @@ export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ?
 /**
  * Options for an included relation.
  *
- * Generic over `NestedR` — the relations interface of the *target* entity —
+ * Generic over `NestedR`, the relations interface of the *target* entity -
  * so the nested `with` clause is autocompleted with the correct relation keys
  * and so {@link WithResult} can recursively infer the return type. Defaults to
  * `{}` (no relation suggestions) for callers that use the unparameterized
@@ -254,6 +254,38 @@ export type WithOrderByObject = Record<string, OrderDirection | OrderBySpec | Js
  * {@link WithClause} escape hatch) it degrades to the historical open record.
  */
 export type WithWhere<NestedT, NestedR extends object> = [unknown] extends [NestedT] ? Record<string, unknown> : WhereClause<NestedT & object, NestedR>;
+/**
+ * A key-checked orderBy object over an entity and its relations.
+ *
+ * A column key takes a direction, an {@link OrderBySpec}, a JSON-path ordering
+ * or a vector KNN ordering; a RELATION key takes a {@link RelationOrderBy}
+ * (`_count`, or a target column) or a pick-row ordering. Written as an
+ * intersection of two mapped types so an object literal with a key in neither
+ * set is an excess property, which is what turns `orderBy: { titel: 'asc' }`
+ * into a compile error instead of a runtime E003.
+ *
+ * Degrades to the open {@link OrderByObject} when the entity is untyped, so
+ * `db.table(name)` and dynamically built clauses keep working. A value typed
+ * `Record<string, OrderDirection>` still assigns, because an index signature
+ * satisfies each optional target key.
+ */
+export type TypedOrderByObject<T, R extends object> = [unknown] extends [T] ? OrderByObject : [
+    keyof R
+] extends [never] ? OrderByObject : {
+    [K in keyof T]?: OrderDirection | OrderBySpec | JsonPathOrderBy | VectorOrderBy;
+} & {
+    [K in keyof R]?: RelationOrderBy | RelationPickOrderBy;
+};
+/** {@link TypedOrderByObject}, single or Prisma-style array. */
+export type TypedOrderByClause<T, R extends object> = TypedOrderByObject<T, R> | TypedOrderByObject<T, R>[];
+/**
+ * `select` / `omit` inside a relation `with` block, key-checked against the
+ * relation TARGET when it is known, and the historical open record when it is
+ * not (the untyped {@link WithClause} escape hatch).
+ */
+export type WithFieldFlags<NestedT> = [unknown] extends [NestedT] ? Record<string, boolean> : {
+    [K in keyof NestedT]?: boolean;
+};
 export interface WithOptions<NestedR extends object = {}, NestedT = unknown> {
     with?: TypedWithClause<NestedR>;
     /** Filter the related rows. Keys are checked against the relation target when it is known (see {@link WithWhere}). */
@@ -263,21 +295,21 @@ export interface WithOptions<NestedR extends object = {}, NestedT = unknown> {
      * or a Prisma-style array of objects (`[{ a: 'asc' }, { b: 'desc' }]`, whose
      * element order is the authoritative multi-key sort precedence).
      */
-    orderBy?: WithOrderByObject | WithOrderByObject[];
+    orderBy?: TypedOrderByClause<NestedT, NestedR>;
     limit?: number;
-    /** Only include these fields from the relation */
-    select?: Record<string, boolean>;
-    /** Exclude these fields from the relation */
-    omit?: Record<string, boolean>;
+    /** Only include these fields from the relation. Key-checked against the target when it is known. */
+    select?: WithFieldFlags<NestedT>;
+    /** Exclude these fields from the relation. Key-checked against the target when it is known. */
+    omit?: WithFieldFlags<NestedT>;
 }
 /**
  * A relation descriptor used by generated `*Relations` interfaces to make deep
  * `with` clause inference work. It bundles three pieces of information that
  * `WithResult` needs to recurse through nested relations:
  *
- *  - `__target`     — the target entity type (e.g. `Post`)
- *  - `__cardinality`— `'many'` for hasMany, `'one'` for belongsTo / hasOne
- *  - `__relations`  — the target entity's relations interface (for further recursion)
+ *  - `__target`    , the target entity type (e.g. `Post`)
+ *  - `__cardinality`, `'many'` for hasMany, `'one'` for belongsTo / hasOne
+ *  - `__relations` , the target entity's relations interface (for further recursion)
  *
  * **Generator contract (Track 3):** the code generator emits `*Relations`
  * interfaces in the following shape so that `WithResult` can walk arbitrary
@@ -290,14 +322,14 @@ export interface WithOptions<NestedR extends object = {}, NestedT = unknown> {
  * }
  * ```
  *
- * The brand fields are phantom — they exist only for type inference and have
+ * The brand fields are phantom, they exist only for type inference and have
  * no runtime representation. The runtime always sees the parsed entity values
- * (arrays for hasMany, single object or null for belongsTo / hasOne) — see the
+ * (arrays for hasMany, single object or null for belongsTo / hasOne), see the
  * cardinality projection inside {@link WithResult}.
  *
  * **Backward compatibility:** legacy generated code emitted bare types
  * (`posts: Post[]`, `profile: Profile | null`). `WithResult` still accepts that
- * shape via a fallback branch — it just cannot recurse into nested `with` for
+ * shape via a fallback branch, it just cannot recurse into nested `with` for
  * those relations until the generator is updated.
  *
  * @typeParam Target      - The entity type the relation points at.
@@ -331,7 +363,7 @@ type ApplyCardinality<Rel, Resolved> = Rel extends RelationDescriptor<infer _T,
  *     deep nesting.
  *
  * **When `R` is `{}` (the default):** the recursion short-circuits and the
- * function returns plain `T` — preserving the existing untyped escape hatch
+ * function returns plain `T`, preserving the existing untyped escape hatch
  * for callers that have not generated typed clients.
  *
  * **When `R` does not contain the requested relations:** the unknown keys are
@@ -348,7 +380,7 @@ type ApplyCardinality<Rel, Resolved> = Rel extends RelationDescriptor<infer _T,
  */
 export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : W extends object ? W extends {
     _count: infer C;
-} ? // `_count` requested — add the typed count object alongside any relations.
+} ? // `_count` requested, add the typed count object alongside any relations.
 WithRelationAdditions<T, R, W> & {
     _count: CountResult<C>;
 } : WithRelationAdditions<T, R, W> : T;
@@ -402,7 +434,7 @@ export type SelectResult<T, S extends Record<string, boolean> | undefined> = S e
 /** Omit the fields from T that are marked (value = true) in O. */
 export type OmitResult<T, O extends Record<string, boolean> | undefined> = O extends Record<string, boolean> ? Omit<T, Extract<keyof T, TrueKeys<O>>> : T;
 /**
- * Apply select or omit field narrowing to a base type. Select takes priority —
+ * Apply select or omit field narrowing to a base type. Select takes priority -
  * when both are provided, only select is applied (matching runtime behavior).
  */
 export type FieldResult<T, S extends Record<string, boolean> | undefined, O extends Record<string, boolean> | undefined> = S extends Record<string, boolean> ? SelectResult<T, S> : OmitResult<T, O>;
@@ -441,7 +473,7 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     select?: S & FieldFlags<T, S>;
     /** Exclude these fields. Keys are checked against `T` (see {@link FieldFlags}). */
     omit?: O & FieldFlags<T, O>;
-    orderBy?: OrderByClause;
+    orderBy?: TypedOrderByClause<T, R>;
     limit?: number;
     offset?: number;
     with?: W;
@@ -523,7 +555,7 @@ export interface CreateManyArgs<T> {
  * `set` works on any type; `increment`, `decrement`, `multiply`, and `divide`
  * are only valid on numeric fields. They generate SQL like
  * `col = col + $n` (and the corresponding `-`, `*`, `/` variants) instead of
- * plain absolute assignments, so they are safe against concurrent writers —
+ * plain absolute assignments, so they are safe against concurrent writers -
  * the database performs the math atomically.
  *
  * @example
@@ -541,7 +573,7 @@ export type UpdateOperatorInput<V> = {
     divide: number;
 } : never);
 /**
- * Update data — each field can be a plain value or an atomic operator object.
+ * Update data, each field can be a plain value or an atomic operator object.
  * Back-compatible with `Partial<T>`: plain values still typecheck unchanged.
  */
 export type UpdateInput<T> = {
@@ -560,14 +592,14 @@ export interface UpdateArgs<T, R extends object = {}> {
     timeout?: number;
     /**
      * Opt in to running this mutation when `where` resolves to an empty
-     * predicate (e.g. `{}` or `{ id: undefined }`). Default `false` — an
+     * predicate (e.g. `{}` or `{ id: undefined }`). Default `false`, an
      * empty predicate throws `ValidationError` to catch the common case of
      * a filter value accidentally being `undefined`. Set this to `true` only
      * when an unconditional mutation is the intended behaviour.
      */
     allowFullTableScan?: boolean;
     /**
-     * Optimistic locking — prevents lost updates in concurrent scenarios.
+     * Optimistic locking, prevents lost updates in concurrent scenarios.
      * Specify the version field and its expected value. The update adds a
      * WHERE check on the version and auto-increments it. If the row was
      * modified by another transaction, throws `OptimisticLockError`.
@@ -663,7 +695,7 @@ export interface NestedUpdateOp<T, TR extends object = {}> {
 /**
  * `create()` data input. When the relations map `R` is known (typed clients),
  * each relation name additionally accepts a {@link NestedCreateOp} for the
- * relation's target entity — recursively, via the target's own relations map.
+ * relation's target entity, recursively, via the target's own relations map.
  * When `R` is `{}` (untyped escape hatch) this collapses to plain `Partial<T>`.
  */
 export type CreateDataInput<T, R extends object = {}> = [keyof R] extends [never] ? Partial<T> : Partial<T> & {
@@ -718,14 +750,14 @@ export interface HavingAggregateFilter {
     _count?: HavingFilter;
 }
 /**
- * HAVING clause for `groupBy` — filters whole groups by their aggregate values
+ * HAVING clause for `groupBy`, filters whole groups by their aggregate values
  * (the SQL `HAVING` clause). Follows Prisma's shape: each aggregable field maps
  * to a {@link HavingAggregateFilter} (`field → aggregate → operator → value`),
  * and the special top-level `_count` key (no field) filters on `COUNT(*)`.
  *
  * Implemented as a mapped type so the special `_count` key can carry a
  * {@link HavingFilter} while every entity field carries a
- * {@link HavingAggregateFilter} — without the index-signature conflict an
+ * {@link HavingAggregateFilter}, without the index-signature conflict an
  * intersection type would produce when `T` is a broad `Record<string, unknown>`.
  *
  * @example
@@ -1050,7 +1082,7 @@ export interface JsonFilter {
     hasKey?: string;
     /**
      * Greater-than comparison of the value at `path` (required). Numbers cast
-     * the extracted text to numeric — `(col #>> path)::numeric > $n` — while
+     * the extracted text to numeric, `(col #>> path)::numeric > $n`, while
      * strings compare as text.
      */
     gt?: number | string;
@@ -1060,6 +1092,25 @@ export interface JsonFilter {
     lt?: number | string;
     /** Less-than-or-equal comparison of the value at `path` (required). See {@link JsonFilter.gt}. */
     lte?: number | string;
+    /**
+     * Substring match against the TEXT at `path` (required): `col #>> path LIKE
+     * '%value%'`. This is Prisma's `string_contains`.
+     *
+     * Deliberately not spelled `contains`, which on a JSON column already means
+     * whole-document containment (`@>`) and means something entirely different.
+     * The operand is LIKE-escaped, so `%` and `_` match literally.
+     */
+    stringContains?: string;
+    /** Prefix match against the text at `path` (required). Prisma's `string_starts_with`. See {@link JsonFilter.stringContains}. */
+    stringStartsWith?: string;
+    /** Suffix match against the text at `path` (required). Prisma's `string_ends_with`. See {@link JsonFilter.stringContains}. */
+    stringEndsWith?: string;
+    /**
+     * Case-insensitive matching for the substring operators above (ILIKE on
+     * PostgreSQL, the dialect's equivalent elsewhere). Has no effect on
+     * `equals` / `contains` / `hasKey` / the range operators.
+     */
+    mode?: 'default' | 'insensitive';
 }
 /** Array query operators for where clauses */
 export interface ArrayFilter {
@@ -1086,7 +1137,7 @@ export interface TextSearchFilter {
  *  - `'cosine'` → `<=>` (cosine distance)
  *  - `'ip'`     → `<#>` (negative inner product)
  *
- * This is a fixed allow-list — a value outside it is rejected with a
+ * This is a fixed allow-list, a value outside it is rejected with a
  * `ValidationError` so a user-supplied string can never become a SQL operator.
  */
 export type VectorMetric = 'l2' | 'cosine' | 'ip';
@@ -1189,9 +1240,9 @@ export interface JsonPathOrderBy {
 /**
  * Ordering by a relation, keyed by the relation name in an {@link OrderByClause}:
  *
- *  - to-many (hasMany / manyToMany): `{ posts: { _count: 'desc' } }` — orders by
+ *  - to-many (hasMany / manyToMany): `{ posts: { _count: 'desc' } }`, orders by
  *    a correlated `COUNT(*)` of the related rows.
- *  - to-one (belongsTo / hasOne): `{ author: { name: 'asc' } }` — orders by a
+ *  - to-one (belongsTo / hasOne): `{ author: { name: 'asc' } }`, orders by a
  *    correlated scalar subquery on the target column (an {@link OrderBySpec} with
  *    `nulls` is accepted too).
  */

package/dist/query/types.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Query builder types
+ * turbine-orm, Query builder types
  *
  * All exported type and interface definitions for the query builder module.
  */

package/dist/query/utils.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Query builder utilities
+ * turbine-orm, Query builder utilities
  *
  * Standalone utility functions and classes used by the query builder.
  */
@@ -18,7 +18,7 @@ export declare function quoteIdent(name: string): string;
  * relations, reverseColumnMap). These are constructed as plain objects, so a
  * bare `map[key]` for a user-supplied field name like "constructor",
  * "toString", or "__proto__" returns an inherited member from
- * `Object.prototype` — a truthy value that slips past validation and produces a
+ * `Object.prototype`, a truthy value that slips past validation and produces a
  * cryptic `TypeError` instead of a clean `ValidationError`. Returns `undefined`
  * unless `key` is an OWN enumerable/non-enumerable property.
  */
@@ -60,12 +60,12 @@ export interface SqlCacheEntry {
 export declare function fnv1a64Hex(s: string): string;
 /**
  * Derive a prepared-statement name from a SQL string.
- * Format: `t_<16hex>` — always 18 chars, well under NAMEDATALEN (63).
+ * Format: `t_<16hex>`, always 18 chars, well under NAMEDATALEN (63).
  *
  * @internal Exported for testing only.
  */
 export declare function sqlToPreparedName(sql: string): string;
-/** Known operator keys — used to detect operator objects vs plain values */
+/** Known operator keys, used to detect operator objects vs plain values */
 export declare const OPERATOR_KEYS: Set<string>;
 /**
  * Build a correlation clause joining columns between two table references.
@@ -125,21 +125,21 @@ export declare function temporalBindKind(dbType: string | undefined, utcDateTime
  * per-element rewrite is what a `time[]` column needs, and matches the scalar
  * case rather than silently binding an ISO timestamp).
  *
- * Everything else — every non-Date, every non-temporal column, and every
- * `timestamptz` column — is returned by IDENTITY, so this is a byte-for-byte
+ * Everything else, every non-Date, every non-temporal column, and every
+ * `timestamptz` column, is returned by IDENTITY, so this is a byte-for-byte
  * no-op outside the shapes above.
  */
 export declare function coerceTemporalValue(dbType: string | undefined, value: unknown, utcDateTimes?: boolean): unknown;
 /**
  * Parse a database date-time string deterministically.
  *
- * Postgres `timestamp` (without time zone) values arrive with no offset —
+ * Postgres `timestamp` (without time zone) values arrive with no offset -
  * both from the driver and from `json_agg`/`json_build_object` subquery JSON
  * (`2026-07-07T17:15:41.896`). JavaScript's `new Date()` interprets such
  * strings in the SERVER'S LOCAL TIME ZONE, so the same row parses to a
  * different instant depending on where the code runs. The universal ORM
  * convention (Prisma, Rails, Django) is to treat offset-less timestamps as
- * UTC — that is also the only interpretation that round-trips: Postgres
+ * UTC, that is also the only interpretation that round-trips: Postgres
  * stores exactly the wall-clock fields you sent.
  *
  * Strings that carry an explicit offset (`timestamptz` output) are parsed
@@ -153,7 +153,7 @@ export declare function parseDbDate(value: string): Date;
  * Why this table exists: the `'join'` strategy reads a relation through
  * `json_agg(json_build_object(...))`, so its values are whatever
  * `JSON.parse` makes of Postgres's JSON rendering. Every other read path in
- * the library — a top-level row, `'batched'`, `'flatten'` — reads the column
+ * the library, a top-level row, `'batched'`, `'flatten'`, reads the column
  * through the driver and gets the driver's representation. Measured against
  * PostgreSQL 17, those two disagree for exactly the families below, which
  * made the SAME query return a different JS type depending on which plan ran
@@ -172,7 +172,7 @@ export declare function parseDbDate(value: string): Date;
  *   circle       { x, y, radius }             '<(1,2),3>' (string)
  *
  * The array forms diverge the same way, plus `_timestamp`/`_timestamptz`
- * (driver: `Date[]`; JSON: `string[]`) — the scalar `timestamp` /
+ * (driver: `Date[]`; JSON: `string[]`), the scalar `timestamp` /
  * `timestamptz` are deliberately ABSENT because the existing `dateColumns`
  * coercion in `parseRow` already lands them on the driver's value, and they
  * are the hottest column type in a typical schema (no reason to add a cast to
@@ -207,3 +207,20 @@ export declare function jsonWireCoercionOid(pgType: string | undefined): number
  * object index in pg-types, so it is not worth caching.
  */
 export declare function coerceJsonWireValue(oid: number, value: unknown): unknown;
+/** The closest name in `candidates` to `input`, or null when none is close. */
+export declare function closestName(input: string, candidates: Iterable<string>): string | null;
+/**
+ * The "unknown field" error text, listing RELATIONS as well as columns.
+ *
+ * The message used to read `Known fields: id, name.` and nothing else. That is
+ * actively misleading when the key was a relation name: relation filters ARE
+ * valid in a `where`, so a user who guessed the wrong relation name concluded
+ * from this message that turbine cannot filter by relations at all. Relation
+ * names are frequently guessed wrong because introspection derives them, and
+ * two foreign keys to one table produce names (`msgsBySender`) that no one
+ * would predict.
+ */
+export declare function unknownFieldMessage(table: string, field: string, meta: {
+    columnMap: Record<string, string>;
+    relations?: Record<string, unknown>;
+}): string;

package/dist/query/utils.js

@@ -1,12 +1,12 @@
 /**
- * turbine-orm — Query builder utilities
+ * turbine-orm, Query builder utilities
  *
  * Standalone utility functions and classes used by the query builder.
  */
 import pg from 'pg';
 import { localDateTimeKind, timeOfDayKind } from '../schema.js';
 // ---------------------------------------------------------------------------
-// Identifier quoting — prevents SQL injection via table/column names
+// Identifier quoting, prevents SQL injection via table/column names
 // ---------------------------------------------------------------------------
 /**
  * Quote a SQL identifier (table name, column name) using Postgres double-quote
@@ -25,7 +25,7 @@ export function quoteIdent(name) {
  * relations, reverseColumnMap). These are constructed as plain objects, so a
  * bare `map[key]` for a user-supplied field name like "constructor",
  * "toString", or "__proto__" returns an inherited member from
- * `Object.prototype` — a truthy value that slips past validation and produces a
+ * `Object.prototype`, a truthy value that slips past validation and produces a
  * cryptic `TypeError` instead of a clean `ValidationError`. Returns `undefined`
  * unless `key` is an OWN enumerable/non-enumerable property.
  */
@@ -47,7 +47,7 @@ export function escapeLike(value) {
     return value.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
 }
 // ---------------------------------------------------------------------------
-// LRU cache — bounded SQL template cache to prevent memory leaks
+// LRU cache, bounded SQL template cache to prevent memory leaks
 // ---------------------------------------------------------------------------
 /**
  * Simple LRU (Least Recently Used) cache with a fixed maximum size.
@@ -104,14 +104,14 @@ export function fnv1a64Hex(s) {
 }
 /**
  * Derive a prepared-statement name from a SQL string.
- * Format: `t_<16hex>` — always 18 chars, well under NAMEDATALEN (63).
+ * Format: `t_<16hex>`, always 18 chars, well under NAMEDATALEN (63).
  *
  * @internal Exported for testing only.
  */
 export function sqlToPreparedName(sql) {
     return `t_${fnv1a64Hex(sql)}`;
 }
-/** Known operator keys — used to detect operator objects vs plain values */
+/** Known operator keys, used to detect operator objects vs plain values */
 export const OPERATOR_KEYS = new Set([
     'equals',
     'gt',
@@ -214,8 +214,8 @@ export function temporalBindKind(dbType, utcDateTimes = true) {
  * per-element rewrite is what a `time[]` column needs, and matches the scalar
  * case rather than silently binding an ISO timestamp).
  *
- * Everything else — every non-Date, every non-temporal column, and every
- * `timestamptz` column — is returned by IDENTITY, so this is a byte-for-byte
+ * Everything else, every non-Date, every non-temporal column, and every
+ * `timestamptz` column, is returned by IDENTITY, so this is a byte-for-byte
  * no-op outside the shapes above.
  */
 export function coerceTemporalValue(dbType, value, utcDateTimes = true) {
@@ -259,13 +259,13 @@ const TZ_SUFFIX_RE = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/;
 /**
  * Parse a database date-time string deterministically.
  *
- * Postgres `timestamp` (without time zone) values arrive with no offset —
+ * Postgres `timestamp` (without time zone) values arrive with no offset -
  * both from the driver and from `json_agg`/`json_build_object` subquery JSON
  * (`2026-07-07T17:15:41.896`). JavaScript's `new Date()` interprets such
  * strings in the SERVER'S LOCAL TIME ZONE, so the same row parses to a
  * different instant depending on where the code runs. The universal ORM
  * convention (Prisma, Rails, Django) is to treat offset-less timestamps as
- * UTC — that is also the only interpretation that round-trips: Postgres
+ * UTC, that is also the only interpretation that round-trips: Postgres
  * stores exactly the wall-clock fields you sent.
  *
  * Strings that carry an explicit offset (`timestamptz` output) are parsed
@@ -273,12 +273,12 @@ const TZ_SUFFIX_RE = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/;
  */
 export function parseDbDate(value) {
     // Date-only values (`2026-07-07`, from `date` columns in json_agg output)
-    // have no time to zone-pin — and their `-07` tail must not be read as an
+    // have no time to zone-pin, and their `-07` tail must not be read as an
     // offset. JS parses bare ISO dates as UTC midnight already.
     if (!value.includes(':'))
         return new Date(value);
     if (TZ_SUFFIX_RE.test(value)) {
-        // JS Date can't parse colon-less (`-0430`) or bare-hour (`+02`) offsets —
+        // JS Date can't parse colon-less (`-0430`) or bare-hour (`+02`) offsets -
         // normalize both to `±HH:MM`. Postgres emits the bare-hour form for
         // whole-hour zones in some text outputs.
         return new Date(value.replace(/([+-]\d{2})(\d{2})$/, '$1:$2').replace(/([+-]\d{2})$/, '$1:00'));
@@ -296,7 +296,7 @@ export function parseDbDate(value) {
  * Why this table exists: the `'join'` strategy reads a relation through
  * `json_agg(json_build_object(...))`, so its values are whatever
  * `JSON.parse` makes of Postgres's JSON rendering. Every other read path in
- * the library — a top-level row, `'batched'`, `'flatten'` — reads the column
+ * the library, a top-level row, `'batched'`, `'flatten'`, reads the column
  * through the driver and gets the driver's representation. Measured against
  * PostgreSQL 17, those two disagree for exactly the families below, which
  * made the SAME query return a different JS type depending on which plan ran
@@ -315,7 +315,7 @@ export function parseDbDate(value) {
  *   circle       { x, y, radius }             '<(1,2),3>' (string)
  *
  * The array forms diverge the same way, plus `_timestamp`/`_timestamptz`
- * (driver: `Date[]`; JSON: `string[]`) — the scalar `timestamp` /
+ * (driver: `Date[]`; JSON: `string[]`), the scalar `timestamp` /
  * `timestamptz` are deliberately ABSENT because the existing `dateColumns`
  * coercion in `parseRow` already lands them on the driver's value, and they
  * are the hottest column type in a typical schema (no reason to add a cast to
@@ -374,3 +374,73 @@ export function coerceJsonWireValue(oid, value) {
         return value;
     return pg.types.getTypeParser(oid, 'text')(value);
 }
+// ---------------------------------------------------------------------------
+// Unknown-field diagnostics
+// ---------------------------------------------------------------------------
+/**
+ * Case-insensitive closeness of `candidate` to `input`, higher is better,
+ * 0 meaning "not worth suggesting". Deliberately tiny: this runs only on the
+ * error path, and its whole job is to turn a guessed name into the real one.
+ *
+ * Substring containment is scored ABOVE edit distance because the real-world
+ * miss is a longer, more descriptive guess than the actual name (`modelVersions`
+ * for a relation turbine derived as `versions`), where the edit distance is
+ * large but the containment is exact.
+ */
+function nameCloseness(input, candidate) {
+    const a = input.toLowerCase();
+    const b = candidate.toLowerCase();
+    if (a === b)
+        return 1000;
+    if (a.includes(b) || b.includes(a))
+        return 500 + Math.min(a.length, b.length);
+    // Levenshtein, bounded: only near-misses are worth suggesting.
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, j) => j);
+    for (let i = 1; i < rows; i++) {
+        const cur = [i];
+        for (let j = 1; j < cols; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    const distance = prev[cols - 1];
+    const limit = Math.max(2, Math.floor(Math.max(a.length, b.length) / 3));
+    return distance <= limit ? 100 - distance : 0;
+}
+/** The closest name in `candidates` to `input`, or null when none is close. */
+export function closestName(input, candidates) {
+    let best = null;
+    let bestScore = 0;
+    for (const c of candidates) {
+        const score = nameCloseness(input, c);
+        if (score > bestScore) {
+            bestScore = score;
+            best = c;
+        }
+    }
+    return best;
+}
+/**
+ * The "unknown field" error text, listing RELATIONS as well as columns.
+ *
+ * The message used to read `Known fields: id, name.` and nothing else. That is
+ * actively misleading when the key was a relation name: relation filters ARE
+ * valid in a `where`, so a user who guessed the wrong relation name concluded
+ * from this message that turbine cannot filter by relations at all. Relation
+ * names are frequently guessed wrong because introspection derives them, and
+ * two foreign keys to one table produce names (`msgsBySender`) that no one
+ * would predict.
+ */
+export function unknownFieldMessage(table, field, meta) {
+    const columns = Object.keys(meta.columnMap);
+    const relations = Object.keys(meta.relations ?? {});
+    const suggestion = closestName(field, [...columns, ...relations]);
+    const didYouMean = suggestion
+        ? ` Did you mean "${suggestion}"${relations.includes(suggestion) ? ' (a relation)' : ''}?`
+        : '';
+    return (`[turbine] Unknown field "${field}" on table "${table}".${didYouMean}` +
+        ` Known columns: ${columns.join(', ') || '(none)'}.` +
+        (relations.length ? ` Known relations (valid in \`where\` and \`with\`): ${relations.join(', ')}.` : ''));
+}