turbine-orm 0.49.0 → 0.50.0

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

@@ -0,0 +1,209 @@
+/**
+ * turbine-orm — Query builder utilities
+ *
+ * Standalone utility functions and classes used by the query builder.
+ */
+/**
+ * Quote a SQL identifier (table name, column name) using Postgres double-quote
+ * rules: wrap in double quotes, escape internal double quotes by doubling them.
+ *
+ * @example
+ *   quoteIdent('users')       → '"users"'
+ *   quoteIdent('my"table')    → '"my""table"'
+ *   quoteIdent('user name')   → '"user name"'
+ */
+export declare function quoteIdent(name: string): string;
+/**
+ * Prototype-safe own-property read for the plain metadata maps (columnMap,
+ * 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
+ * cryptic `TypeError` instead of a clean `ValidationError`. Returns `undefined`
+ * unless `key` is an OWN enumerable/non-enumerable property.
+ */
+export declare function ownLookup<T>(map: Record<string, T>, key: string): T | undefined;
+/**
+ * Escape single quotes for use as string keys in json_build_object().
+ * Doubles single quotes per SQL quoting rules.
+ */
+export declare function escSingleQuote(s: string): string;
+/**
+ * Escape LIKE pattern metacharacters: %, _, and \.
+ * Must be used with `ESCAPE '\'` in the LIKE clause.
+ */
+export declare function escapeLike(value: string): string;
+/**
+ * Simple LRU (Least Recently Used) cache with a fixed maximum size.
+ * When the cache exceeds maxSize, the oldest (least recently used) entry is evicted.
+ * Uses Map insertion order for O(1) eviction.
+ */
+export declare class LRUCache<K, V> {
+    private maxSize;
+    private cache;
+    constructor(maxSize: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    get size(): number;
+}
+/** Cached SQL template paired with its prepared-statement name. */
+export interface SqlCacheEntry {
+    sql: string;
+    name: string;
+}
+/**
+ * FNV-1a 64-bit hash returning 16 lowercase hex chars.
+ * Single-loop string iteration. Uses BigInt for 64-bit math.
+ *
+ * @internal Exported for testing only.
+ */
+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).
+ *
+ * @internal Exported for testing only.
+ */
+export declare function sqlToPreparedName(sql: string): string;
+/** 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.
+ * Handles both single-column (string) and multi-column (string[]) foreign keys.
+ *
+ * For single-column: `"alias"."col" = "parent"."col"`
+ * For multi-column:  `"alias"."col_a" = "parent"."ref_a" AND "alias"."col_b" = "parent"."ref_b"`
+ */
+export declare function buildCorrelation(leftRef: string, leftColumns: string | string[], rightRef: string, rightColumns: string | string[]): string;
+/**
+ * Render a JS `Date` as a TIME-OF-DAY literal for a `time` / `timetz` column.
+ *
+ * Which time of day? The **UTC** components of the Date, never the process
+ * local zone. That is what Prisma does (`new Date('1970-01-01T09:00:00Z')`
+ * written to a `@db.Time(6)` column stores `09:00:00`), and the affected
+ * consumers are porting from Prisma, so Prisma is the contract. It is also the
+ * only choice that round-trips: the same Date produces the same literal no
+ * matter where the process runs.
+ *
+ * `timetz` gets an explicit `+00:00`, because the value's zone IS UTC and
+ * omitting it would let Postgres attach the session's `TimeZone` instead.
+ * Fractional seconds are emitted only when non-zero, so an even-second Date
+ * binds the plain `HH:MM:SS` form.
+ */
+export declare function toTimeOfDayLiteral(value: Date, kind: 'time' | 'timetz'): string;
+/** The temporal column shapes that need a bound Date rewritten to a literal. */
+export type TemporalBindKind = 'time' | 'timetz' | 'date' | 'timestamp';
+/**
+ * Render a JS `Date` as a literal for a zone-less `date` / `timestamp` column,
+ * using the value's **UTC** components.
+ *
+ * This is the write-side mirror of `parseDbDate`, which reads an offset-less
+ * database value back as UTC. Without it the driver serializes the Date with
+ * the PROCESS's offset (`prepareValue` → `dateToString`), so a `timestamp`
+ * column is not round-trip stable outside a UTC process: writing
+ * `2026-07-25T00:00Z` from `America/Los_Angeles` stores
+ * `2026-07-24 17:00:00` and reads back as `2026-07-24T17:00Z`. It also matches
+ * the choice {@link toTimeOfDayLiteral} already makes for `time` columns, and
+ * Prisma, which writes UTC components to zone-less columns.
+ *
+ * `timestamptz` is NOT handled here (and must not be): it stores a real
+ * instant, so the driver's local-offset string is already correct.
+ */
+export declare function toLocalDateTimeLiteral(value: Date, kind: 'date' | 'timestamp'): string;
+/**
+ * Classify a column's database type for temporal bind rewriting.
+ *
+ * `utcDateTimes: false` restricts the classification to the time-of-day types,
+ * whose rewrite is a hard-error fix (Postgres rejects an ISO timestamp for a
+ * `time` column outright) rather than a value correction.
+ */
+export declare function temporalBindKind(dbType: string | undefined, utcDateTimes?: boolean): TemporalBindKind | null;
+/**
+ * Rewrite one bound value for a temporal column: a JS `Date` on a `time` /
+ * `timetz` / `date` / `timestamp` column becomes the corresponding UTC literal,
+ * and an array of Dates on such a column is rewritten element-wise (the
+ * 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
+ * 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 —
+ * 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
+ * stores exactly the wall-clock fields you sent.
+ *
+ * Strings that carry an explicit offset (`timestamptz` output) are parsed
+ * as-is.
+ */
+export declare function parseDbDate(value: string): Date;
+/**
+ * Postgres type name → OID, for every type family whose `json_build_object`
+ * rendering is NOT the value the pg driver produces for the same column.
+ *
+ * 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
+ * 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
+ * (and `'auto'` picks the plan from a row-count heuristic, so it could differ
+ * between two runs of one query). Three of these are lossy, not merely
+ * different:
+ *
+ *   type         driver (target)              json_build_object
+ *   ──────────── ──────────────────────────── ─────────────────────────────
+ *   numeric      '1000.50'   (string)         1000.5    (number, LOSSY)
+ *   int8         '9007199254740993'           9007199254740992 (LOSSY)
+ *   bytea        Buffer                       '\xdeadbeef' (string)
+ *   date         Date (local midnight)        Date (UTC midnight, off by tz)
+ *   interval     { days, hours, … }           '1 day 02:03:04' (string)
+ *   point        { x, y }                     '(1,2)'   (string)
+ *   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` /
+ * `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
+ * every `created_at`).
+ *
+ * The fix these OIDs drive: emit the column as `col::text` inside
+ * `json_build_object` so the JSON carries the same wire text the driver would
+ * receive, then run the DRIVER'S OWN parser for that OID over it. Parity is
+ * then by construction rather than by coincidence, and it automatically
+ * honours a caller's `pg.types.setTypeParser` (including the int8 parser
+ * TurbineClient itself registers) instead of second-guessing it.
+ *
+ * Postgres-only: the JSON functions and the divergence set are both
+ * engine-specific, so callers gate this on the postgres dialect.
+ */
+export declare const JSON_WIRE_COERCION_OIDS: Readonly<Record<string, number>>;
+/**
+ * The OID whose driver parser reproduces `pgType`'s driver representation from
+ * its text rendering, or `undefined` when the type's JSON rendering already
+ * matches the driver (the common case: text, uuid, bool, int4, float8, json,
+ * jsonb, arrays of those, …).
+ */
+export declare function jsonWireCoercionOid(pgType: string | undefined): number | undefined;
+/**
+ * Apply the driver's text parser for `oid` to a JSON-sourced wire string.
+ *
+ * Resolved through `pg.types.getTypeParser` on every call rather than
+ * memoized: parser registration is process-global and happens in the
+ * TurbineClient constructor (int8, and `timestamp` under `utcTimestamps`), and
+ * a caller may register their own at any point. A stale memo would silently
+ * reintroduce the very divergence this exists to remove. The lookup is a plain
+ * object index in pg-types, so it is not worth caching.
+ */
+export declare function coerceJsonWireValue(oid: number, value: unknown): unknown;

package/dist/cjs/query/utils.js

@@ -4,8 +4,11 @@
  *
  * Standalone utility functions and classes used by the query builder.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPERATOR_KEYS = exports.LRUCache = void 0;
+exports.JSON_WIRE_COERCION_OIDS = exports.OPERATOR_KEYS = exports.LRUCache = void 0;
 exports.quoteIdent = quoteIdent;
 exports.ownLookup = ownLookup;
 exports.escSingleQuote = escSingleQuote;
@@ -13,7 +16,15 @@ exports.escapeLike = escapeLike;
 exports.fnv1a64Hex = fnv1a64Hex;
 exports.sqlToPreparedName = sqlToPreparedName;
 exports.buildCorrelation = buildCorrelation;
+exports.toTimeOfDayLiteral = toTimeOfDayLiteral;
+exports.toLocalDateTimeLiteral = toLocalDateTimeLiteral;
+exports.temporalBindKind = temporalBindKind;
+exports.coerceTemporalValue = coerceTemporalValue;
 exports.parseDbDate = parseDbDate;
+exports.jsonWireCoercionOid = jsonWireCoercionOid;
+exports.coerceJsonWireValue = coerceJsonWireValue;
+const pg_1 = __importDefault(require("pg"));
+const schema_js_1 = require("../schema.js");
 // ---------------------------------------------------------------------------
 // Identifier quoting — prevents SQL injection via table/column names
 // ---------------------------------------------------------------------------
@@ -153,6 +164,114 @@ function buildCorrelation(leftRef, leftColumns, rightRef, rightColumns) {
         .map((col, i) => `${leftRef}.${quoteIdent(col)} = ${rightRef}.${quoteIdent(rightCols[i])}`)
         .join(' AND ');
 }
+/**
+ * Render a JS `Date` as a TIME-OF-DAY literal for a `time` / `timetz` column.
+ *
+ * Which time of day? The **UTC** components of the Date, never the process
+ * local zone. That is what Prisma does (`new Date('1970-01-01T09:00:00Z')`
+ * written to a `@db.Time(6)` column stores `09:00:00`), and the affected
+ * consumers are porting from Prisma, so Prisma is the contract. It is also the
+ * only choice that round-trips: the same Date produces the same literal no
+ * matter where the process runs.
+ *
+ * `timetz` gets an explicit `+00:00`, because the value's zone IS UTC and
+ * omitting it would let Postgres attach the session's `TimeZone` instead.
+ * Fractional seconds are emitted only when non-zero, so an even-second Date
+ * binds the plain `HH:MM:SS` form.
+ */
+function toTimeOfDayLiteral(value, kind) {
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    const ms = value.getUTCMilliseconds();
+    const literal = `${pad(value.getUTCHours())}:${pad(value.getUTCMinutes())}:${pad(value.getUTCSeconds())}` +
+        (ms === 0 ? '' : `.${pad(ms, 3)}`);
+    return kind === 'timetz' ? `${literal}+00:00` : literal;
+}
+/** Render the UTC calendar date of a `Date` as `YYYY-MM-DD`. */
+function utcDatePart(value) {
+    const year = value.getUTCFullYear();
+    const y = year < 0 ? `-${String(-year).padStart(4, '0')}` : String(year).padStart(4, '0');
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${y}-${pad(value.getUTCMonth() + 1)}-${pad(value.getUTCDate())}`;
+}
+/**
+ * Render a JS `Date` as a literal for a zone-less `date` / `timestamp` column,
+ * using the value's **UTC** components.
+ *
+ * This is the write-side mirror of `parseDbDate`, which reads an offset-less
+ * database value back as UTC. Without it the driver serializes the Date with
+ * the PROCESS's offset (`prepareValue` → `dateToString`), so a `timestamp`
+ * column is not round-trip stable outside a UTC process: writing
+ * `2026-07-25T00:00Z` from `America/Los_Angeles` stores
+ * `2026-07-24 17:00:00` and reads back as `2026-07-24T17:00Z`. It also matches
+ * the choice {@link toTimeOfDayLiteral} already makes for `time` columns, and
+ * Prisma, which writes UTC components to zone-less columns.
+ *
+ * `timestamptz` is NOT handled here (and must not be): it stores a real
+ * instant, so the driver's local-offset string is already correct.
+ */
+function toLocalDateTimeLiteral(value, kind) {
+    const datePart = utcDatePart(value);
+    if (kind === 'date')
+        return datePart;
+    return `${datePart} ${toTimeOfDayLiteral(value, 'time')}`;
+}
+/**
+ * Classify a column's database type for temporal bind rewriting.
+ *
+ * `utcDateTimes: false` restricts the classification to the time-of-day types,
+ * whose rewrite is a hard-error fix (Postgres rejects an ISO timestamp for a
+ * `time` column outright) rather than a value correction.
+ */
+function temporalBindKind(dbType, utcDateTimes = true) {
+    const timeKind = (0, schema_js_1.timeOfDayKind)(dbType);
+    if (timeKind)
+        return timeKind;
+    return utcDateTimes ? (0, schema_js_1.localDateTimeKind)(dbType) : null;
+}
+/**
+ * Rewrite one bound value for a temporal column: a JS `Date` on a `time` /
+ * `timetz` / `date` / `timestamp` column becomes the corresponding UTC literal,
+ * and an array of Dates on such a column is rewritten element-wise (the
+ * 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
+ * no-op outside the shapes above.
+ */
+function coerceTemporalValue(dbType, value, utcDateTimes = true) {
+    const isDate = value instanceof Date;
+    if (!isDate && !Array.isArray(value))
+        return value;
+    if (isDate && Number.isNaN(value.getTime()))
+        return value;
+    // An array value is either an `in`/`notIn` list on a scalar temporal column
+    // (type already the element type) or the value of an array column, whose
+    // introspected type is the `_time` / `_timestamp` array spelling.
+    const kind = temporalBindKind(isDate ? dbType : arrayElementDbType(dbType), utcDateTimes);
+    if (!kind)
+        return value;
+    if (isDate)
+        return renderTemporal(value, kind);
+    // Rewrite only if the list actually holds a Date, so a string list stays
+    // byte-identical (and the same array instance is returned).
+    if (!value.some((v) => v instanceof Date))
+        return value;
+    return value.map((v) => (v instanceof Date && !Number.isNaN(v.getTime()) ? renderTemporal(v, kind) : v));
+}
+/** `_time` → `time`, `time[]` → `time`, anything else unchanged. */
+function arrayElementDbType(dbType) {
+    if (!dbType)
+        return dbType;
+    if (dbType.startsWith('_'))
+        return dbType.slice(1);
+    return dbType.endsWith('[]') ? dbType.slice(0, -2) : dbType;
+}
+function renderTemporal(value, kind) {
+    return kind === 'date' || kind === 'timestamp'
+        ? toLocalDateTimeLiteral(value, kind)
+        : toTimeOfDayLiteral(value, kind);
+}
 /**
  * Matches an explicit timezone suffix on a date-time string: a trailing `Z`
  * or a `±HH`, `±HHMM`, `±HH:MM` offset.
@@ -188,3 +307,91 @@ function parseDbDate(value) {
     // normalize `YYYY-MM-DD HH:MM:SS` (driver form) to ISO before pinning UTC
     return new Date(`${value.replace(' ', 'T')}Z`);
 }
+// ---------------------------------------------------------------------------
+// JSON-wire value coercion (relationLoadStrategy: 'join')
+// ---------------------------------------------------------------------------
+/**
+ * Postgres type name → OID, for every type family whose `json_build_object`
+ * rendering is NOT the value the pg driver produces for the same column.
+ *
+ * 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
+ * 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
+ * (and `'auto'` picks the plan from a row-count heuristic, so it could differ
+ * between two runs of one query). Three of these are lossy, not merely
+ * different:
+ *
+ *   type         driver (target)              json_build_object
+ *   ──────────── ──────────────────────────── ─────────────────────────────
+ *   numeric      '1000.50'   (string)         1000.5    (number, LOSSY)
+ *   int8         '9007199254740993'           9007199254740992 (LOSSY)
+ *   bytea        Buffer                       '\xdeadbeef' (string)
+ *   date         Date (local midnight)        Date (UTC midnight, off by tz)
+ *   interval     { days, hours, … }           '1 day 02:03:04' (string)
+ *   point        { x, y }                     '(1,2)'   (string)
+ *   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` /
+ * `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
+ * every `created_at`).
+ *
+ * The fix these OIDs drive: emit the column as `col::text` inside
+ * `json_build_object` so the JSON carries the same wire text the driver would
+ * receive, then run the DRIVER'S OWN parser for that OID over it. Parity is
+ * then by construction rather than by coincidence, and it automatically
+ * honours a caller's `pg.types.setTypeParser` (including the int8 parser
+ * TurbineClient itself registers) instead of second-guessing it.
+ *
+ * Postgres-only: the JSON functions and the divergence set are both
+ * engine-specific, so callers gate this on the postgres dialect.
+ */
+exports.JSON_WIRE_COERCION_OIDS = {
+    numeric: 1700,
+    int8: 20,
+    bytea: 17,
+    date: 1082,
+    interval: 1186,
+    point: 600,
+    circle: 718,
+    _numeric: 1231,
+    _int8: 1016,
+    _bytea: 1001,
+    _date: 1182,
+    _interval: 1187,
+    _point: 1017,
+    _timestamp: 1115,
+    _timestamptz: 1185,
+};
+/**
+ * The OID whose driver parser reproduces `pgType`'s driver representation from
+ * its text rendering, or `undefined` when the type's JSON rendering already
+ * matches the driver (the common case: text, uuid, bool, int4, float8, json,
+ * jsonb, arrays of those, …).
+ */
+function jsonWireCoercionOid(pgType) {
+    if (!pgType)
+        return undefined;
+    return exports.JSON_WIRE_COERCION_OIDS[pgType];
+}
+/**
+ * Apply the driver's text parser for `oid` to a JSON-sourced wire string.
+ *
+ * Resolved through `pg.types.getTypeParser` on every call rather than
+ * memoized: parser registration is process-global and happens in the
+ * TurbineClient constructor (int8, and `timestamp` under `utcTimestamps`), and
+ * a caller may register their own at any point. A stale memo would silently
+ * reintroduce the very divergence this exists to remove. The lookup is a plain
+ * object index in pg-types, so it is not worth caching.
+ */
+function coerceJsonWireValue(oid, value) {
+    if (typeof value !== 'string')
+        return value;
+    return pg_1.default.types.getTypeParser(oid, 'text')(value);
+}

package/dist/cjs/query/warn-registry.d.ts

@@ -0,0 +1,68 @@
+/**
+ * turbine-orm, process-wide once-per-key dev-warning dedupe registry.
+ *
+ * Several dev-only diagnostics (the missing-FK-index warning in relations.ts,
+ * the `relationLoadStrategy: 'auto'` engagement note, the deep-`with` warning)
+ * must fire AT MOST ONCE per distinct key for the life of the process. A
+ * module-level `Set` almost does this, but it is defeated by the two field
+ * realities this package actually ships into:
+ *
+ *   1. **Dual-package loading.** Turbine ships ESM (`dist/`) AND CJS
+ *      (`dist/cjs/`). A mixed `require`/`import` graph (a compat layer, a tool
+ *      that loads both) instantiates the module twice, giving two independent
+ *      `Set`s that each warn once, a double warning.
+ *   2. **Bundler / HMR re-evaluation.** Under Next.js dev the module is
+ *      re-evaluated per recompile, resetting a module-level `Set` and making the
+ *      warning appear to fire every time.
+ *
+ * Hanging the registry off `globalThis` under a `Symbol.for(...)` key gives every
+ * module copy in the realm ONE shared registry (cross-copy identity without
+ * polluting enumerable globals), and `globalThis` survives webpack recompiles
+ * because the realm persists, which is exactly what fixes the every-recompile
+ * firing in dev servers. Per-process firing (worker threads, separate processes)
+ * is acceptable and stays.
+ *
+ * Bounded: each namespace stops recording AND stops warning once it reaches
+ * {@link WARN_ONCE_CAP} distinct keys. A schema with 500+ distinct unindexed
+ * relations has long since gotten the message, and the cap prevents unbounded
+ * growth if metadata objects are churned dynamically. (Clearing on overflow
+ * would be wrong, it would re-warn.)
+ */
+/** Per-namespace cap on distinct recorded keys (see module doc). */
+export declare const WARN_ONCE_CAP = 500;
+/**
+ * Record `(ns, key)` and report whether THIS call is the first to see it
+ * process-wide. Returns `true` exactly once per distinct key (the caller should
+ * emit its warning then), `false` on every subsequent call for that key, and
+ * `false` once the namespace has recorded {@link WARN_ONCE_CAP} distinct keys
+ * (bounded growth; the warning simply stops rather than re-firing).
+ */
+export declare function shouldWarnOnce(ns: string, key: string): boolean;
+/** True when `(ns, key)` has already been recorded (no mutation). */
+export declare function hasWarnedOnce(ns: string, key: string): boolean;
+/**
+ * @internal Test-only: clear one namespace, or the whole registry when `ns` is
+ * omitted. Lets a single test process verify that a warning fires once and then
+ * re-verify after a reset without spawning a new process.
+ */
+export declare function resetWarnOnce(ns?: string): void;
+/** Namespace constants so callers never typo a bare string. */
+export declare const WARN_NS: {
+    /** Missing-FK-index runtime warning (relations.ts `buildRelationSubquery`). */
+    readonly unindexedRelation: "unindexedRelation";
+    /** `relationLoadStrategy: 'auto'` batched-fallback engagement note. */
+    readonly autoStrategy: "autoStrategy";
+    /** Deep-`with` (depth > 5) advisory (builder.ts `findMany`). */
+    readonly deepWith: "deepWith";
+    /** Non-deterministic page advisory: paginating findMany with no orderBy. */
+    readonly unorderedPage: "unorderedPage";
+    /** PowDB `emitLinks` DDL skips (name/column collision, endpoint drift). */
+    readonly powdbLinks: "powdbLinks";
+    /**
+     * `relationLoadStrategy: 'flatten'` was asked for but a relation stayed on the
+     * correlated-subquery path (relations.ts `planFlattenWith`, builder.ts
+     * `planFlatten`). An explicitly requested strategy that quietly does not
+     * engage is indistinguishable from one that does nothing, so say so once.
+     */
+    readonly flattenFallback: "flattenFallback";
+};

package/dist/cjs/query/warn-registry.js

@@ -95,6 +95,15 @@ exports.WARN_NS = {
     autoStrategy: 'autoStrategy',
     /** Deep-`with` (depth > 5) advisory (builder.ts `findMany`). */
     deepWith: 'deepWith',
+    /** Non-deterministic page advisory: paginating findMany with no orderBy. */
+    unorderedPage: 'unorderedPage',
     /** PowDB `emitLinks` DDL skips (name/column collision, endpoint drift). */
     powdbLinks: 'powdbLinks',
+    /**
+     * `relationLoadStrategy: 'flatten'` was asked for but a relation stayed on the
+     * correlated-subquery path (relations.ts `planFlattenWith`, builder.ts
+     * `planFlatten`). An explicitly requested strategy that quietly does not
+     * engage is indistinguishable from one that does nothing, so say so once.
+     */
+    flattenFallback: 'flattenFallback',
 };

package/dist/cjs/query/where-compile.d.ts

@@ -0,0 +1,139 @@
+/**
+ * turbine-orm: Shared WHERE-clause walk
+ *
+ * The SQL template cache requires three code paths over a table-scoped WHERE
+ * object to stay in perfect lockstep:
+ *   - `fingerprintWhere`   : the value-invariant cache KEY,
+ *   - `buildWhereClause`   : the SQL text + `$N` params on a cache MISS,
+ *   - `collectWhereParams` : the params ONLY on a cache HIT (no SQL rebuild).
+ *
+ * If any two of them enumerate the WHERE keys in a different order, or classify
+ * a key's value into a different filter shape, the cached SQL's `$N`
+ * placeholders bind the wrong values: a silent cross-value (and, with tenant
+ * columns, cross-tenant) leak. That drift shipped twice historically (permuted
+ * where-key order; an orderBy fingerprint collision).
+ *
+ * This module removes the drift BY CONSTRUCTION:
+ *   - {@link walkWhere} is the ONE enumeration. It sorts keys canonically,
+ *     skips `undefined`, dispatches the `OR`/`AND`/`NOT` combinators and
+ *     relation filters, and yields a flat, ordered {@link WhereEvent} stream.
+ *     All three consumers iterate this same stream, so their key order and
+ *     combinator structure can never diverge again.
+ *   - {@link classifyScalarForSql} is the ONE scalar-shape decision the SQL
+ *     paths use. `buildWhereClause` and `collectWhereParams` BOTH call it with
+ *     the same `(rawColumn, value)`, so they always take the same branch and
+ *     therefore push params in the same order.
+ *   - {@link fingerprintScalarToken} is the fingerprint's own (deliberately
+ *     column-blind) scalar token. It over-distinguishes relative to the SQL
+ *     classifier (which is always safe), so a fingerprint match still implies
+ *     an identical SQL shape.
+ *
+ * The dev-mode / sampled-production cross-check in `builder.ts` stays as the
+ * tripwire: with this shared walk it should never fire, but it remains the
+ * last-line guard against a future leaf builder / collect mirror falling out of
+ * step.
+ */
+import type { RelationDef, TableMetadata } from '../schema.js';
+/** A table-scoped WHERE object (or an `OR`/`AND`/`NOT` branch of one). */
+export type WhereRecord = Record<string, unknown>;
+/**
+ * Everything the shared walk needs from the owning {@link QueryInterface}. Bound
+ * once per instance (see `QueryInterface`'s `whereHost` field) so the walk stays
+ * a pure function of the instance's schema state without widening the class's
+ * public surface.
+ */
+export interface WhereHost {
+    readonly tableMeta: TableMetadata;
+    /** Wrap a bare belongsTo/hasOne relation filter in `{ is: … }`. */
+    normalizeRelationFilter(relDef: RelationDef, filterObj: WhereRecord): WhereRecord;
+    /** Resolve a column's Postgres type token (defaults to `text`). */
+    getColumnPgType(column: string): string;
+    /** True for `json` / `jsonb` column types. */
+    isJsonColumnType(colType: string): boolean;
+}
+/**
+ * The SQL-relevant classification of a scalar WHERE value, decided column-aware
+ * in the SAME linear fall-through order the SQL builder has always used
+ * (null → vector → json → array → text-search → operator → equality). Shared by
+ * the build and collect paths so their branch choice (and thus param order)
+ * is identical by construction. The `*Throw` variants preserve the build path's
+ * strict-validation errors for a JSON/array operator on a non-JSON/array column.
+ */
+export type ScalarSqlClass = {
+    kind: 'null';
+} | {
+    kind: 'vector';
+} | {
+    kind: 'json';
+} | {
+    kind: 'jsonThrow';
+    jsonKey: string;
+} | {
+    kind: 'array';
+    colType: string;
+} | {
+    kind: 'arrayThrow';
+    arrayKey: string;
+} | {
+    kind: 'textsearch';
+} | {
+    kind: 'operator';
+} | {
+    kind: 'equality';
+};
+/**
+ * One node of the canonical WHERE walk. `scalar` carries only `key` + `value`;
+ * each consumer resolves the column/shape itself (the SQL paths via
+ * {@link classifyScalarForSql}, the fingerprint via
+ * {@link fingerprintScalarToken}) so the fingerprint stays column-blind exactly
+ * as before.
+ */
+export type WhereEvent = {
+    kind: 'or';
+    conditions: WhereRecord[];
+} | {
+    kind: 'and';
+    conditions: WhereRecord[];
+} | {
+    kind: 'not';
+    condition: WhereRecord;
+} | {
+    kind: 'relation';
+    key: string;
+    relDef: RelationDef;
+    filterObj: WhereRecord;
+} | {
+    kind: 'scalar';
+    key: string;
+    value: unknown;
+};
+/**
+ * THE canonical WHERE enumeration. Yields events in sorted-key order (skipping
+ * `undefined`), dispatching combinators and relation filters, so every consumer
+ * (fingerprint, SQL build, param collect) walks identically.
+ *
+ * Combinator SKIP rules match the historical code exactly: an `OR`/`AND` whose
+ * value is a non-array or an empty array is skipped entirely (it contributes
+ * neither SQL, params, nor a fingerprint token); `NOT` is always emitted.
+ * A key that names a relation but whose value is not a `{ some/every/none/is/
+ * isNot }` filter falls through to the scalar path, exactly as before.
+ */
+export declare function walkWhere(host: WhereHost, where: WhereRecord): WhereEvent[];
+/**
+ * Column-aware SQL classification of a scalar WHERE value. Reproduces the SQL
+ * builder's linear fall-through: a JSON/array-shaped value on a non-JSON/array
+ * column falls THROUGH to the next shape (and ultimately equality) unless it
+ * carries a shape-unique key, in which case the build path reports a typed
+ * error (`*Throw`). Both the build and collect paths call this, so they can
+ * never classify the same value differently.
+ */
+export declare function classifyScalarForSql(host: WhereHost, rawColumn: string, value: unknown): ScalarSqlClass;
+/**
+ * The fingerprint's scalar token: deliberately COLUMN-BLIND and in the
+ * historical fingerprint precedence (operator before vector/json/array), so a
+ * value that both looks like an operator and a JSON filter (`equals`/`contains`
+ * overlap) tokenizes as an operator exactly as it did before. Column-blindness
+ * only ever over-distinguishes versus {@link classifyScalarForSql}, which is
+ * safe: it can cause an extra cache MISS, never a wrong-value HIT.
+ */
+export declare function fingerprintScalarToken(value: unknown): string;