turbine-orm 0.49.0 → 0.50.0

package/dist/query/types.d.ts

@@ -38,7 +38,7 @@ export type OrderDirection = 'asc' | 'desc';
  * PowDB's own existing default (loaders / nested projections); it never selects
  * a distinct PowQL code path.
  */
-export type RelationLoadStrategy = 'join' | 'batched' | 'auto';
+export type RelationLoadStrategy = 'join' | 'batched' | 'auto' | 'flatten';
 /**
  * Reference to ANOTHER COLUMN of the same table inside a where operator,
  * enabling column-to-column comparison:
@@ -100,34 +100,79 @@ export interface WhereOperator<V = unknown, F extends string = string> {
  * - A vector distance filter object ({ distance: { to, metric, lt } }) for pgvector columns
  */
 export type WhereValue<V = unknown, F extends string = string> = (V extends Array<infer U> ? TypedRelationFilter<U> : V extends Date ? V : V extends object ? V | TypedToOneFilter<V> | WhereClause<V> : V) | WhereOperator<V, F> | JsonFilter | ArrayFilter | TextSearchFilter | VectorFilter | null;
-/** Relation filter on a to-many relation property. */
-export interface TypedRelationFilter<U> {
-    some?: WhereClause<U>;
-    every?: WhereClause<U>;
-    none?: WhereClause<U>;
+/**
+ * Relation filter on a to-many relation property.
+ *
+ * `UR` is the target entity's own relations map, so a nested relation filter
+ * (`posts: { some: { comments: { some: ... } } }`) stays key-checked at depth.
+ * It defaults to `{}` so the legacy single-generic spelling still works.
+ */
+export interface TypedRelationFilter<U, UR extends object = {}> {
+    some?: WhereClause<U, UR>;
+    every?: WhereClause<U, UR>;
+    none?: WhereClause<U, UR>;
 }
 /**
  * Relation filter on a to-one relation property. A bare object on a to-one
  * relation key is also accepted at runtime (implicit `is`, Prisma-compatible).
+ *
+ * `VR` is the target entity's own relations map (see {@link TypedRelationFilter}).
  */
-export interface TypedToOneFilter<V> {
-    is?: WhereClause<V>;
-    isNot?: WhereClause<V>;
+export interface TypedToOneFilter<V, VR extends object = {}> {
+    is?: WhereClause<V, VR>;
+    isNot?: WhereClause<V, VR>;
 }
+/**
+ * The where-value accepted on a RELATION key, derived from the generated
+ * {@link RelationDescriptor} brand: to-many relations take `some`/`every`/`none`,
+ * 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
+ * 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;
 /**
  * Where clause type: each field can be a plain value, null, or operator object.
- * Special keys: OR for disjunctive conditions.
- * Relation names can be used with some/every/none sub-filters.
+ * Special keys: OR / AND / NOT.
+ *
+ * **Key checking.** Historically this type carried a
+ * `[relationName: string]: unknown` index signature so relation filters
+ * (`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.
+ *
+ * Passing `R` (the generated `*Relations` map, which every typed client
+ * already threads through `QueryInterface<T, R>`) removes the need for the
+ * index signature: the relation keys become real, explicitly enumerated
+ * properties, so a misspelled column OR relation is a compile error at the
+ * offending key while every legitimate filter shape still typechecks.
+ *
+ * When `R` is omitted / `{}` (the untyped escape hatch, `defineSchema`-only
+ * clients, and any call site that does not thread the relations map) the type
+ * degrades to exactly its historical permissive form.
  */
-export type WhereClause<T> = {
+export type WhereClause<T, R extends object = {}> = [keyof R] extends [never] ? LooseWhereClause<T> : StrictWhereClause<T, R>;
+/** The historical, index-signature-carrying where clause. See {@link WhereClause}. */
+export type LooseWhereClause<T> = {
     [K in keyof T]?: WhereValue<T[K], Extract<keyof T, string>>;
 } & {
-    OR?: WhereClause<T>[];
-    AND?: WhereClause<T>[];
-    NOT?: WhereClause<T>;
+    OR?: LooseWhereClause<T>[];
+    AND?: LooseWhereClause<T>[];
+    NOT?: LooseWhereClause<T>;
     /** 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. */
+type StrictWhereClause<T, R extends object> = {
+    [K in keyof T]?: WhereValue<T[K], Extract<keyof T, string>>;
+} & {
+    [K in keyof R]?: RelationWhereValue<R[K]>;
+} & {
+    OR?: WhereClause<T, R>[];
+    AND?: WhereClause<T, R>[];
+    NOT?: WhereClause<T, R>;
+};
 /**
  * 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
@@ -178,7 +223,7 @@ export interface WithClause {
  * `WithResult` inference.
  */
 export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ? WithClause : {
-    [K in keyof R]?: true | WithOptions<RelationRelations<R[K]> & object>;
+    [K in keyof R]?: true | WithOptions<RelationRelations<R[K]> & object, RelationTarget<R[K]>>;
 } & {
     /** Reserved: correlated relation counts. `true` counts all to-many relations. */
     _count?: true | {
@@ -200,9 +245,19 @@ export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ?
  * {@link WithOptions.orderBy} is `WithOrderByObject[]`.
  */
 export type WithOrderByObject = Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy | RelationOrderBy>;
-export interface WithOptions<NestedR extends object = {}> {
+/**
+ * The `where` accepted inside a relation `with` block. When the relation
+ * target entity is known (a typed client, via the {@link RelationDescriptor}
+ * brand the generator emits) this is a key-checked {@link WhereClause} over the
+ * TARGET entity and its own relations, so `with: { posts: { where: { titel } } }`
+ * is a compile error. When the target is unknown (the untyped
+ * {@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>;
+export interface WithOptions<NestedR extends object = {}, NestedT = unknown> {
     with?: TypedWithClause<NestedR>;
-    where?: Record<string, unknown>;
+    /** Filter the related rows. Keys are checked against the relation target when it is known (see {@link WithWhere}). */
+    where?: WithWhere<NestedT, NestedR>;
     /**
      * Order the related rows. Accepts a single object (`{ a: 'asc', b: 'desc' }`)
      * or a Prisma-style array of objects (`[{ a: 'asc' }, { b: 'desc' }]`, whose
@@ -316,6 +371,28 @@ type WithRelationAdditions<T, R extends object, W> = [keyof W & keyof R] extends
 type CountResult<C> = C extends true ? Record<string, number> : C extends object ? {
     [K in keyof C]: number;
 } : Record<string, number>;
+/**
+ * Key-validating companion for an inferred `select` / `omit` flag map.
+ *
+ * `select?: S` alone can never reject a typo: `S` is inferred FROM the object
+ * literal, so `{ emial: true }` simply becomes the inferred type and a
+ * misspelled column silently narrows the result to `Pick<T, never>`. Writing
+ * the property as `S & FieldFlags<T, S>` keeps `S` inferred exactly as before
+ * (the naked `S` member is still the inference site, so literal `true` values
+ * and the `TrueKeys` result narrowing are unchanged) while the mapped member
+ * maps every key that is NOT a field of `T` to `never`, which makes the
+ * supplied `true` unassignable and reports the typo at the offending key.
+ *
+ * A key that IS a field of `T` maps to plain `boolean`, so every legitimate
+ * flag map (`{ id: true }`, `{ id: true, email: false }`, `{}`) is unaffected.
+ *
+ * An OPEN flag map (`Record<string, boolean>`, which is what the internal
+ * pass-through signatures instantiate `S` with) has nothing to validate: it is
+ * returned unchanged so those instantiations stay assignable to each other.
+ */
+export type FieldFlags<T, S> = S extends object ? string extends keyof S ? S : {
+    [K in keyof S]: K extends keyof T ? boolean : never;
+} : S;
 /** Extract keys from a boolean record where the value is `true`. */
 type TrueKeys<S extends Record<string, boolean>> = {
     [K in keyof S]: S[K] extends true ? K : never;
@@ -339,9 +416,12 @@ export type FieldResult<T, S extends Record<string, boolean> | undefined, O exte
  */
 export type QueryResult<T, R extends object, W, S extends Record<string, boolean> | undefined, O extends Record<string, boolean> | undefined> = S extends undefined ? O extends undefined ? WithResult<T, R, W> : O extends Record<string, boolean> ? Omit<WithResult<T, R, W>, Exclude<Extract<keyof T, TrueKeys<O>>, keyof W>> : WithResult<T, R, W> : S extends Record<string, boolean> ? Pick<WithResult<T, R, W>, Extract<keyof T, TrueKeys<S>> | Exclude<keyof WithResult<T, R, W>, keyof T> | Extract<keyof W, keyof WithResult<T, R, W>>> : WithResult<T, R, W>;
 export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
-    where: WhereClause<T>;
-    select?: S;
-    omit?: O;
+    /** Row selector. Keys are checked against `T` and `R` (see {@link WhereClause}). */
+    where: WhereClause<T, R>;
+    /** Only return these fields. Keys are checked against `T` (see {@link FieldFlags}). */
+    select?: S & FieldFlags<T, S>;
+    /** Exclude these fields. Keys are checked against `T` (see {@link FieldFlags}). */
+    omit?: O & FieldFlags<T, O>;
     with?: W;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
@@ -355,9 +435,12 @@ export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithCla
     includePii?: boolean;
 }
 export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
-    where?: WhereClause<T>;
-    select?: S;
-    omit?: O;
+    /** Row filter. Keys are checked against `T` and `R` (see {@link WhereClause}). */
+    where?: WhereClause<T, R>;
+    /** Only return these fields. Keys are checked against `T` (see {@link FieldFlags}). */
+    select?: S & FieldFlags<T, S>;
+    /** Exclude these fields. Keys are checked against `T` (see {@link FieldFlags}). */
+    omit?: O & FieldFlags<T, O>;
     orderBy?: OrderByClause;
     limit?: number;
     offset?: number;
@@ -465,7 +548,8 @@ export type UpdateInput<T> = {
     [K in keyof T]?: T[K] | UpdateOperatorInput<T[K]>;
 };
 export interface UpdateArgs<T, R extends object = {}> {
-    where: WhereClause<T>;
+    /** Row selector. Keys are checked against `T` and `R` (see {@link WhereClause}). */
+    where: WhereClause<T, R>;
     /**
      * Update data. On typed clients, relation names additionally accept nested
      * write ops ({@link NestedUpdateOp}): `create` / `connect` / `connectOrCreate`
@@ -506,8 +590,8 @@ export interface UpdateArgs<T, R extends object = {}> {
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
-export interface UpdateManyArgs<T> {
-    where: WhereClause<T>;
+export interface UpdateManyArgs<T, R extends object = {}> {
+    where: WhereClause<T, R>;
     data: UpdateInput<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
@@ -516,8 +600,8 @@ export interface UpdateManyArgs<T> {
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
-export interface DeleteArgs<T> {
-    where: WhereClause<T>;
+export interface DeleteArgs<T, R extends object = {}> {
+    where: WhereClause<T, R>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
@@ -525,8 +609,8 @@ export interface DeleteArgs<T> {
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
-export interface DeleteManyArgs<T> {
-    where: WhereClause<T>;
+export interface DeleteManyArgs<T, R extends object = {}> {
+    where: WhereClause<T, R>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
@@ -534,8 +618,8 @@ export interface DeleteManyArgs<T> {
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
-export interface UpsertArgs<T> {
-    where: WhereClause<T>;
+export interface UpsertArgs<T, R extends object = {}> {
+    where: WhereClause<T, R>;
     create: Partial<T>;
     update: Partial<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
@@ -594,8 +678,8 @@ export type CreateDataInput<T, R extends object = {}> = [keyof R] extends [never
 export type UpdateDataInput<T, R extends object = {}> = [keyof R] extends [never] ? UpdateInput<T> : UpdateInput<T> & {
     [K in keyof R]?: NestedUpdateOp<RelationTarget<R[K]> & object, RelationRelations<R[K]> & object>;
 };
-export interface CountArgs<T> {
-    where?: WhereClause<T>;
+export interface CountArgs<T, R extends object = {}> {
+    where?: WhereClause<T, R>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
@@ -751,10 +835,10 @@ export interface GroupByOrderBy {
     /** A by-column field name or JSON group-key alias → direction or sort spec. */
     [key: string]: OrderDirection | OrderBySpec | GroupByAggregateOrderBy | undefined;
 }
-export interface GroupByArgs<T> {
+export interface GroupByArgs<T, R extends object = {}> {
     /** Group keys: plain column field names and/or JSON-path keys ({@link JsonPathGroupKey}). */
     by: ((keyof T & string) | JsonPathGroupKey)[];
-    where?: WhereClause<T>;
+    where?: WhereClause<T, R>;
     /**
      * PostgreSQL only: group over one representative row per column combination
      * (`SELECT DISTINCT ON … ORDER BY …` row source). See {@link GroupByDistinctOn}.
@@ -883,8 +967,8 @@ type GroupByCountPart<A> = A extends {
     _count: number;
 };
 /** Arguments for the standalone aggregate method */
-export interface AggregateArgs<T> {
-    where?: WhereClause<T>;
+export interface AggregateArgs<T, R extends object = {}> {
+    where?: WhereClause<T, R>;
     /**
      * Count rows. `true` → `_count: number` (COUNT(*)). The record form counts per
      * selection: the reserved `_all: true` key → COUNT(*), and each entity field

package/dist/query/utils.d.ts

@@ -75,6 +75,61 @@ export declare const OPERATOR_KEYS: Set<string>;
  * 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.
  *
@@ -91,3 +146,64 @@ export declare function buildCorrelation(leftRef: string, leftColumns: string |
  * 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/query/utils.js

@@ -3,6 +3,8 @@
  *
  * 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
 // ---------------------------------------------------------------------------
@@ -141,6 +143,114 @@ export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export function temporalBindKind(dbType, utcDateTimes = true) {
+    const timeKind = timeOfDayKind(dbType);
+    if (timeKind)
+        return timeKind;
+    return utcDateTimes ? 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.
+ */
+export 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.
@@ -176,3 +286,91 @@ export 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.
+ */
+export const 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, …).
+ */
+export function jsonWireCoercionOid(pgType) {
+    if (!pgType)
+        return undefined;
+    return 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.
+ */
+export function coerceJsonWireValue(oid, value) {
+    if (typeof value !== 'string')
+        return value;
+    return pg.types.getTypeParser(oid, 'text')(value);
+}

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

@@ -54,6 +54,15 @@ export declare const WARN_NS: {
     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/query/warn-registry.js

@@ -89,6 +89,15 @@ export const 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',
 };