turbine-orm 0.54.0 → 0.55.0

package/README.md

@@ -429,7 +429,7 @@ const db = turbine({
 });
 ```
 
-> **`utcTimestamps` is a process-wide decision, not a per-client one.** The two halves settle differently. The WRITE half is per client: a `Date` bound to a zone-less `date` / `timestamp` column is rewritten to a UTC literal unless that client opted out. The READ half is a set of pg type parsers on OIDs 1114 (`timestamp`), 1082 (`date`) and their array forms 1115 / 1182, and `pg.types.setTypeParser` installs one parser per OID for the whole pg module, shared by every pool, every raw query, and any other library on the same `pg`. The first client in the process settles it for all the rest. Constructing a second client with the **opposite** value therefore throws `ValidationError` (`TURBINE_E003`) at construction, rather than handing back a client that writes UTC and reads local (or the reverse) and so does not round-trip its own values. The message names both values and the two ways out: give every client in the process the same `utcTimestamps`, or run the odd one out in its own process. Clients built on an external pool (`pool: ...`, `turbineHttp()`) never REGISTER a parser and settle nothing on their own, so a process holding only those keeps whatever parser configuration the caller set up. They are not exempt from the check, though: registration is process-global, so once a Turbine-owned client has installed the parsers an external-pool client reads through them too, and a disagreeing one would write local `date` literals while reading UTC.
+> **`utcTimestamps` is a process-wide decision, not a per-client one.** The two halves settle differently. The WRITE half is per client: a `Date` bound to a zone-less `date` / `timestamp` column is rewritten to a UTC literal unless that client opted out. The READ half is a set of pg type parsers on OIDs 1114 (`timestamp`), 1082 (`date`) and their array forms 1115 / 1182, and `pg.types.setTypeParser` installs one parser per OID for the whole pg module, shared by every pool, every raw query, and any other library on the same `pg`. It is also **retroactive**: there is one parser table and it is read per row at decode time, so registering changes pools **that already exist and are already querying**, not just pools created afterwards. The same `pg.Pool` running the same query returns different values before and after some unrelated module constructs a Turbine client, and with lazy route imports that ordering is not stable between requests. If the OID had already been customized by something else, Turbine emits a one-time dev warning rather than replacing it silently. The first client in the process settles it for all the rest. Constructing a second client with the **opposite** value therefore throws `ValidationError` (`TURBINE_E003`) at construction, rather than handing back a client that writes UTC and reads local (or the reverse) and so does not round-trip its own values. The message names both values and the two ways out: give every client in the process the same `utcTimestamps`, or run the odd one out in its own process. Clients built on an external pool (`pool: ...`, `turbineHttp()`) never REGISTER a parser and settle nothing on their own, so a process holding only those keeps whatever parser configuration the caller set up. They are not exempt from the check, though: registration is process-global, so once a Turbine-owned client has installed the parsers an external-pool client reads through them too, and a disagreeing one would write local `date` literals while reading UTC.
 
 > **Upgrading with `utcTimestamps: false`.** If you already set `false`, this release changes the **stored text** of your writes: the write path now honors the flag where it previously ignored it, so zone-less columns receive local-calendar literals instead of UTC ones. Rows written before the upgrade and rows written after carry two conventions in the same column until you backfill.
 
@@ -454,7 +454,7 @@ const db = turbine({
 
 Where a pg-style alias exists (`max`, `idleTimeoutMillis`, `connectionTimeoutMillis`), the explicit Turbine field wins when both are set.
 
-> **`planCacheMode` (Postgres only, opt-in).** PostgreSQL promotes a **named** prepared statement to a generic plan on its sixth execution, and a generic plan is costed blind to the bound values. On a predicate whose selectivity swings per value (a `tenant_id` equality on a shared table, where one value matches a handful of rows and another matches most of them), the statement can be locked onto a plan chosen for the average value, and it never reverts. `planCacheMode: 'auto' | 'force_custom_plan' | 'force_generic_plan'` pins the backend's choice; `'force_custom_plan'` re-plans every execution and removes the cliff. It is applied as a connection parameter (`options=-c plan_cache_mode=...`) when Turbine opens a connection, so it is in force for that connection's first statement and for every checkout, `$transaction`, stream and pipeline on it, and it cannot race your first query. Leave it unset (the default) and Turbine sends nothing at all. Reach for it when you have measured a statement getting slower after its fifth execution: `count()` on a skewed predicate is the shape that promotes through Turbine, while `findMany` / `findFirst` bind `LIMIT $n` and are much less exposed. Three scope limits: it does nothing on an **external pool** (Turbine never opens those connections, so set the GUC in the driver's own setup; Turbine-owned string `replicas` on that same client DO get it); a Postgres wire-compatible engine without the setting (CockroachDB, YugabyteDB, pre-12 PostgreSQL) refuses the connection parameter itself; and a **connection pooler** may filter startup parameters (PgBouncer's `ignore_startup_parameters`), where `ALTER ROLE ... SET plan_cache_mode = ...` is the way in. Any value outside the three throws `ValidationError` at construction, and a non-Postgres engine throws `UnsupportedFeatureError` (`TURBINE_E017`).
+> **`planCacheMode` (Postgres only, opt-in).** PostgreSQL may promote a **named** prepared statement to a generic plan from its sixth execution onward, and a generic plan is costed blind to the bound values. On a predicate whose selectivity swings per value (a `tenant_id` equality on a shared table, where one value matches a handful of rows and another matches most of them), the statement can be locked onto a plan chosen for the average value, and it never reverts. `planCacheMode: 'auto' | 'force_custom_plan' | 'force_generic_plan'` pins the backend's choice; `'force_custom_plan'` re-plans every execution and removes the cliff. It is applied as a connection parameter (`options=-c plan_cache_mode=...`) when Turbine opens a connection, so it is in force for that connection's first statement and for every checkout, `$transaction`, stream and pipeline on it, and it cannot race your first query. Leave it unset (the default) and Turbine sends nothing at all. Reach for it when you have measured a statement getting slower after its fifth execution. **Correction to the 0.54 text, which said `findMany` / `findFirst` bind `LIMIT $n` and are "much less exposed":** that was false. PostgreSQL does not deny the planner a limit fraction for a bound limit, it substitutes a default of 10% of the child node's own row estimate (clamped at one row), and an unknown `OFFSET` triggers the same substitution even when the limit is a constant, which a paginated Turbine read always has. Two things also need saying about the sentence that opens this note. The sixth execution is a ceiling, not a trigger: `auto` promotes only when the generic plan's **estimated** cost is not worse than the average custom cost, so many statements are never promoted at all, and `pg_prepared_statements.generic_plans` is how you tell. And the shape that gets promoted unprompted is the one with **no limit**, not the limited one: measured on a skewed join predicate, an unlimited `count()`-shaped statement promoted under the default `auto` and ran a nested loop at 430x the buffers of the custom plan, while the same predicate under `LIMIT $n` was never promoted across eight executions (its substituted row count made the generic plan look more expensive). A limited `findMany` gives the planner two unknowns instead of one, which is not the same as more damage. `implicitPkOrdering` is **off by default in core**, so a default `findMany` emits no `ORDER BY`; switching it on adds an ordering a generic plan can walk the whole table in. Measure with `plan_cache_mode = force_generic_plan` against `force_custom_plan` rather than reasoning about which shapes ought to be safe; the fixtures and numbers are on the [relations page](https://turbineorm.dev/relations) and in the 0.55.0 changelog. Three scope limits: it does nothing on an **external pool** (Turbine never opens those connections, so set the GUC in the driver's own setup; Turbine-owned string `replicas` on that same client DO get it); a Postgres wire-compatible engine without the setting (CockroachDB, YugabyteDB, pre-12 PostgreSQL) refuses the connection parameter itself; and a **connection pooler** may filter startup parameters (PgBouncer's `ignore_startup_parameters`), where `ALTER ROLE ... SET plan_cache_mode = ...` is the way in. Any value outside the three throws `ValidationError` at construction, and a non-Postgres engine throws `UnsupportedFeatureError` (`TURBINE_E017`).
 
 > **`preparedStatements` and connection poolers.** With prepared statements on, Turbine submits queries as `{ name, text, values }` so Postgres caches the parse and plan **per backend connection**. That is a real win against a database you connect to directly, and a hazard behind a transaction-pooling proxy (PgBouncer in `transaction` mode, Supabase's pooler port, some serverless poolers): the named statement is prepared on one backend and your next query may land on another, which fails with `prepared statement "..." does not exist`. Turbine defaults it to `true` only for pools it creates itself and `false` for external pools passed via `pool` / `turbineHttp()`, because serverless drivers are the common case there. If you are pointing a Turbine-owned pool at a transaction pooler, set `preparedStatements: false`. The environment variable `TURBINE_DISABLE_PREPARED=1` turns it off globally without a code change.
 
@@ -1097,7 +1097,7 @@ Turbine maps Postgres types to TypeScript:
 | `int8` / `bigint` | `number` | Values > `Number.MAX_SAFE_INTEGER` (2^53 - 1) are returned as `string` at runtime to avoid precision loss. This affects < 0.01% of use cases (auto-increment IDs, counts, etc. are all safe). |
 | `numeric`, `money` | `string` | Arbitrary precision, kept as string to avoid JS float issues |
 | `text`, `varchar`, `uuid`, `citext` | `string` | |
-| `timestamptz`, `timestamp`, `date` | `Date` | `timestamp` (without time zone) **and `date`** are parsed as UTC by default (Prisma/Rails/Django convention), so the same row yields the same instant in every region. Opt out with `utcTimestamps: false`. Since v0.52 the flag also reaches the WRITE side on Postgres: it governs the `Date` values that `create` / `update` / `upsert` and `where` clauses bind to zone-less `date` / `timestamp` columns. Before v0.52 it reached the read path only, so a client that had set `false` was still binding UTC, and those statements (and the text they store) change on upgrade. The two halves settle at different scopes: the write half is per client, the read half is a process-global pg type parser, so every client in one process must agree or construction throws `ValidationError`. Since v0.54 `date` reads at UTC midnight rather than the process's local midnight (its array form too), which moves the **epoch value** of a `date` by your process's UTC offset even though the calendar day it denotes is unchanged: format with `toISOString().slice(0, 10)`, not with local-component helpers like `toLocaleDateString()`. See [Relation loading and wire encoding](#relation-loading-and-wire-encoding). |
+| `timestamptz`, `timestamp`, `date` | `Date` | `timestamp` (without time zone) **and `date`** are parsed as UTC by default (Prisma/Rails/Django convention), so the same row yields the same instant in every region. Opt out with `utcTimestamps: false`. Since v0.52 the flag also reaches the WRITE side on Postgres: it governs the `Date` values that `create` / `update` / `upsert` and `where` clauses bind to zone-less `date` / `timestamp` columns. Before v0.52 it reached the read path only, so a client that had set `false` was still binding UTC, and those statements (and the text they store) change on upgrade. The two halves settle at different scopes: the write half is per client, the read half is a process-global pg type parser, so every client in one process must agree or construction throws `ValidationError`. Since v0.54 `date` reads at UTC midnight rather than the process's local midnight (its array form too), which moves the **epoch value** of a `date` by your process's UTC offset even though the calendar day it denotes is unchanged: format with `toISOString().slice(0, 10)`, not with local-component helpers like `toLocaleDateString()`. Since v0.55 a stored `infinity` / `-infinity` reads as the JS number `Infinity` / `-Infinity` on **every** read strategy (v0.54 gave the number on the top-level and batched paths and an `Invalid Date` through a `with` clause, because `json_build_object` renders the value as the string `"infinity"` that no driver parser sees). There is no JS `Date` for either value, so the reading costs something either way and the default is the one that cannot **lose** a value: the number binds straight back, so `update({ data: { ...row } })` stores `infinity` again, whereas reading it as `null` makes a stored infinity indistinguishable from a stored NULL and that same write silently stores SQL NULL. The price of the default is that the field is declared `Date` and hands back a number, so `.toISOString()` / `.getTime()` throw a `TypeError` on those rows and `JSON.stringify` still renders them `null`. Set `temporalInfinity: 'null'` to read `null` instead, accepting the data loss, the collapse of `groupBy` / `distinct` keys, and `_max` returning `null` on a table with rows. Either way the value stays writable as `'infinity'` / `'-infinity'`, a one-time warning names the field the first time one is read (this one is NOT silenced by `NODE_ENV=production`, and naming either reading silences it), and `where: { col: null }` still means `IS NULL` and does not match those rows. See [Relation loading and wire encoding](#relation-loading-and-wire-encoding). |
 | `boolean` | `boolean` | |
 | `json`, `jsonb` | `unknown` | |
 | `bytea` | `Buffer` | |

package/dist/cjs/client.d.ts

@@ -26,7 +26,7 @@ import { type Dialect } from './dialect.js';
 import { type ErrorMessageMode } from './errors.js';
 import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
-import { type DeferredQuery, type GlobalFilters, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy } from './query/index.js';
+import { type DeferredQuery, type GlobalFilters, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy, type TemporalInfinityReading } from './query/index.js';
 import { type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
 import { TypedSqlQuery } from './typed-sql.js';
@@ -192,11 +192,21 @@ export interface TurbineConfig {
      * rewrite (a bound `Date` on a zone-less `date` / `timestamp` column is then
      * serialized by the driver in the process's zone).
      *
-     * PER PROCESS, NOT PER CLIENT. The read half is a pg type parser, and
-     * `pg.types.setTypeParser` installs one parser per OID for the whole
-     * process. The first client settles it for every later one, so constructing
-     * a second client with the OPPOSITE value throws a `ValidationError` rather
-     * than handing back a client whose writes and reads disagree. Give every
+     * PER PROCESS, NOT PER CLIENT, AND RETROACTIVE. The read half is a pg type
+     * parser, and `pg.types.setTypeParser` installs one parser per OID for the
+     * whole process. There is ONE parser table and it is consulted per row at
+     * decode time, so registration also changes POOLS THAT ALREADY EXIST AND ARE
+     * ALREADY QUERYING: the same `pg.Pool` running the same query returns
+     * different values before and after a Turbine client is constructed
+     * somewhere else in the process. With lazy route imports that ordering is
+     * not stable between requests, so a reporting job on its own pool can return
+     * different days depending on what has been imported yet. When the OID was
+     * still on the driver's default that is the intended trade; when something
+     * else had already customized it, Turbine says so once (dev-only, see
+     * `warnParserOverwrite`). The first client settles it for every later one, so
+     * constructing a second client with the OPPOSITE value throws a
+     * `ValidationError` rather than handing back a client whose writes and reads
+     * disagree. Give every
      * client in the process the same value, or isolate the odd one in its own
      * process. A client on an EXTERNAL pool never REGISTERS a parser (it inherits
      * whatever configuration the caller's driver has, so a process containing
@@ -207,27 +217,80 @@ export interface TurbineConfig {
      * UTC.
      */
     utcTimestamps?: boolean;
+    /**
+     * How a Postgres temporal `infinity` / `-infinity` is handed back:
+     * `'preserve'` (the default, the JS numbers `Infinity` / `-Infinity`) or
+     * `'null'`. See {@link TemporalInfinityReading} for the full trade.
+     *
+     * There is no JS `Date` for either value, so both readings are wrong in some
+     * way and the option is which way. `'preserve'` is LOSSLESS: binding the
+     * number back stores `infinity` again, so a read-modify-write
+     * (`update({ data: { ...row } })`) round-trips. Its cost is a number on a
+     * `Date`-typed field, so `row.validUntil.toISOString()` throws a TypeError on
+     * exactly those rows, and `JSON.stringify` still renders the value `null`.
+     * `'null'` matches what `JSON.stringify` already produced and keeps the
+     * field's declared `Date | null` type honest, at the cost of DATA LOSS: a
+     * stored `infinity` and a stored NULL become indistinguishable, so that same
+     * read-modify-write writes SQL NULL and destroys the value with no error.
+     * The default is the reading that cannot lose a value.
+     *
+     * Unlike 0.54, which returned the number on some read strategies and an
+     * Invalid Date on others, BOTH readings here are identical on every
+     * strategy, every write projection, `groupBy` keys and `_min` / `_max`.
+     *
+     * Leaving the option unset selects `'preserve'` AND enables a one-time
+     * warning (per process, per field, not silenced by `NODE_ENV=production`) the
+     * first time a stored infinity is actually read, describing that reading and
+     * both escapes. Naming either reading explicitly silences it.
+     */
+    temporalInfinity?: TemporalInfinityReading;
     /**
      * Pin `plan_cache_mode` on every connection this client opens, fixing how the
      * PostgreSQL backend chooses between a custom plan (re-planned per parameter
      * set) and a generic plan (planned once, blind to the values).
      *
      * Why it exists: Turbine sends NAMED prepared statements by default on a pool
-     * it owns, and PostgreSQL promotes a named statement to a generic plan after
-     * five executions. A generic plan is planned for the AVERAGE parameter, so a
+     * it owns, and PostgreSQL MAY promote a named statement to a generic plan
+     * after five executions (see the ceiling note below: it promotes only when
+     * the generic plan's estimated cost is not worse than the average custom
+     * cost). A generic plan is planned for the AVERAGE parameter, so a
      * predicate whose selectivity varies wildly per value (the canonical case is a
      * `tenant_id` / `user_id` equality on a shared table, where one value matches
      * a handful of rows and another matches most of them) is planned blind to the
      * value it will actually get, and it never reverts. `'force_custom_plan'`
      * removes that, at the cost of re-planning each execution.
      *
-     * Scope, measured rather than assumed: it applies to the statements Turbine
-     * itself promotes. `count()` on such a predicate is promoted after five
-     * executions and is controlled by this option; `findMany` / `findFirst` bind
-     * `LIMIT $n`, and a parameterized limit denies the planner the limit fraction
-     * that makes a skewed plan look cheap, so those are much less exposed. Treat
-     * the option as a targeted remedy for a plan that is measurably worse after
-     * its fifth execution, not a general speed-up.
+     * Scope. It applies to the statements Turbine itself promotes, which is any
+     * of them: `count()`, `findMany` and `findFirst` alike. CORRECTION TO THE
+     * 0.54.0 TEXT, which claimed `findMany` / `findFirst` were "much less
+     * exposed" because they bind `LIMIT $n`: that was false. PostgreSQL does not
+     * deny the planner a limit fraction for a bound limit, it SUBSTITUTES a
+     * default of 10% of the child node's own row estimate (clamped at one row),
+     * which is simply a different wrong number. An unknown `OFFSET` triggers the
+     * same substitution on its own even when the limit is a constant, and a
+     * paginated Turbine read binds both.
+     *
+     * Two things the sentence above this one glosses over. The sixth execution
+     * is a CEILING, not a trigger: `auto` promotes only when the generic plan's
+     * ESTIMATED cost is not worse than the average custom cost, so plenty of
+     * statements are never promoted at all (`pg_prepared_statements.generic_plans`
+     * is how you tell). And the shape that gets promoted unprompted is the one
+     * with NO limit: measured on a skewed join predicate, the unlimited statement
+     * promoted under the default `auto` and ran a nested loop at 430x the buffers
+     * of the custom plan, while the same predicate under `LIMIT $n` was never
+     * promoted across eight executions, because its substituted row count made
+     * the generic plan look MORE expensive. A limited `findMany` gives the
+     * planner two unknowns instead of one, which is not the same thing as more
+     * damage.
+     *
+     * `implicitPkOrdering` is OFF by default in core, so a default `findMany`
+     * emits no `ORDER BY` at all; switching it on adds an ordering a generic plan
+     * can walk the whole table in.
+     *
+     * Treat the option as a targeted remedy for a plan that is measurably worse
+     * after its fifth execution, not a general speed-up, and measure with
+     * `plan_cache_mode = force_generic_plan` versus `force_custom_plan` rather
+     * than reasoning about which query shapes "should" be safe.
      *
      * Default `undefined`: Turbine issues NOTHING and the backend keeps its own
      * default (`auto`), byte-identical to not setting the option.
@@ -689,6 +752,13 @@ export declare class TurbineClient {
      *     `UnsupportedFeatureError` (E017), in the same style as the other
      *     capability refusals.
      */
+    /**
+     * Validate the `temporalInfinity` reading. A closed two-value enum, checked
+     * at construction so a typo (`'preserved'`, `'raw'`) fails loudly rather than
+     * silently falling back to the default reading the caller was trying to
+     * change.
+     */
+    private static resolveTemporalInfinity;
     private static resolvePlanCacheMode;
     /**
      * Pin `plan_cache_mode` on every connection an OWNED pool opens, by putting

package/dist/cjs/client.js

@@ -109,6 +109,7 @@ const TURBINE_CONFIG_KEYS = {
     defaultLimit: true,
     warnOnUnlimited: true,
     utcTimestamps: true,
+    temporalInfinity: true,
     planCacheMode: true,
     scopedConnect: true,
     relationLoadStrategy: true,
@@ -599,10 +600,11 @@ class TurbineClient {
         // constructor-gated by the static flags, so it happens at most once.
         const ownsAnyPool = !config.pool;
         if (ownsAnyPool && !TurbineClient.int8ParserRegistered) {
-            pg_1.default.types.setTypeParser(20, (val) => {
+            (0, utils_js_1.warnParserOverwrite)(20, 'int8');
+            pg_1.default.types.setTypeParser(20, (0, utils_js_1.markTurbineParser)((val) => {
                 const n = Number(val);
                 return Number.isSafeInteger(n) ? n : val;
-            });
+            }));
             TurbineClient.int8ParserRegistered = true;
         }
         // Parse the zone-less temporal types (`timestamp` OID 1114, `date` OID
@@ -646,6 +648,7 @@ class TurbineClient {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
             utcTimestamps: config.utcTimestamps,
+            temporalInfinity: TurbineClient.resolveTemporalInfinity(config.temporalInfinity),
             scopedConnect: config.scopedConnect,
             relationLoadStrategy: config.relationLoadStrategy,
             stableRelationOrder: config.stableRelationOrder,
@@ -817,6 +820,23 @@ class TurbineClient {
      *     `UnsupportedFeatureError` (E017), in the same style as the other
      *     capability refusals.
      */
+    /**
+     * Validate the `temporalInfinity` reading. A closed two-value enum, checked
+     * at construction so a typo (`'preserved'`, `'raw'`) fails loudly rather than
+     * silently falling back to the default reading the caller was trying to
+     * change.
+     */
+    static resolveTemporalInfinity(value) {
+        if (value === undefined)
+            return undefined;
+        if (value !== 'null' && value !== 'preserve') {
+            throw new errors_js_1.ValidationError(`Invalid temporalInfinity: ${JSON.stringify(value)}. Expected 'preserve' (default: read a Postgres ` +
+                'temporal `infinity` as the JS number `Infinity` / `-Infinity`, which round-trips through a write ' +
+                "but breaks the declared `Date` type) or 'null' (read it as null, which serializes cleanly but " +
+                'makes it indistinguishable from a stored NULL, so a read-modify-write destroys the value).');
+        }
+        return value;
+    }
     static resolvePlanCacheMode(mode, dialect) {
         if (mode === undefined || mode === null)
             return undefined;

package/dist/cjs/index.d.ts

@@ -43,7 +43,7 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export { HttpJsonSink, type HttpJsonSinkOptions, type MetricsFlushBatch, type MetricsFlushRow, type ObserveConfig, type ObserveHandle, type ObserveSink, PgMetricsSink, type PgMetricsSinkOptions, } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TemporalInfinityReading, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, PrismaCompatMap, PrismaModelMap, PrismaRelationMap, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, withDbFieldNames, } from './schema.js';

package/dist/cjs/query/aggregates.js

@@ -353,12 +353,14 @@ function buildGroupBy(qi, args) {
                 }
                 else if (rawKey.startsWith('_min_')) {
                     const j = jsonAgg(rawKey);
-                    minObj[fieldFor(rawKey, rawKey.slice(5))] = j?.numeric && rawValue !== null ? Number(rawValue) : rawValue;
+                    minObj[fieldFor(rawKey, rawKey.slice(5))] =
+                        j?.numeric && rawValue !== null ? Number(rawValue) : temporalAggValue(qi, rawKey.slice(5), rawValue);
                     hasMins = true;
                 }
                 else if (rawKey.startsWith('_max_')) {
                     const j = jsonAgg(rawKey);
-                    maxObj[fieldFor(rawKey, rawKey.slice(5))] = j?.numeric && rawValue !== null ? Number(rawValue) : rawValue;
+                    maxObj[fieldFor(rawKey, rawKey.slice(5))] =
+                        j?.numeric && rawValue !== null ? Number(rawValue) : temporalAggValue(qi, rawKey.slice(5), rawValue);
                     hasMaxs = true;
                 }
             }
@@ -768,6 +770,38 @@ function buildHavingNumericClauses(qi, expr, filter, params) {
     }
     return clauses;
 }
+/**
+ * `_min` / `_max` over a TEMPORAL column, aligned with the row parser.
+ *
+ * These two are the only aggregates that hand back a row's stored cell rather
+ * than something computed across rows, so they are the only ones that can carry
+ * a Postgres `infinity`. They are assembled from the RAW row (a Date must stay
+ * a Date, and `parseRow`'s snake→camel mapping would collide with the `_min_`
+ * alias), so the infinity mapping has to be applied here too. Without it
+ * `aggregate({ _max: { ts: true } })` would return the driver's `Infinity`
+ * while `findMany` returned `null` for the very same value.
+ *
+ * Gated on the column being temporal, so a numeric `_max` is untouched, and on
+ * the client's `temporalInfinity` reading, so it cannot disagree with the rows
+ * `findMany` returns for the same column. An absent reading resolves to the
+ * default, `'preserve'`, exactly as it does in the row parser.
+ *
+ * Note what the opt-in `'null'` reading then means for `_max` on a table that
+ * plainly has rows: `null` is the same value an empty table and an all-NULL
+ * column return, so `_min` can report a real date while `_max` reports
+ * "nothing" (documented, and one of the reasons `'null'` is not the default).
+ */
+function temporalAggValue(qi, col, value) {
+    if (!qi.tableMeta.dateColumns.has(col))
+        return value;
+    if (!(0, utils_js_1.isTemporalInfinity)(value))
+        return value;
+    if (qi.temporalInfinity === 'null')
+        return null;
+    if (typeof value === 'number')
+        return value;
+    return value === '-infinity' ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY;
+}
 function buildAggregate(qi, args) {
     qi.currentSkip = args.skipGlobalFilters;
     const aggWhere = whereMod.mergeGlobalFilter(qi, args.where);
@@ -912,13 +946,13 @@ function buildAggregate(qi, args) {
                 else if (key.startsWith('_min_')) {
                     const col = key.slice(5);
                     const field = qi.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
-                    minObj[field] = val;
+                    minObj[field] = temporalAggValue(qi, col, val);
                     hasMins = true;
                 }
                 else if (key.startsWith('_max_')) {
                     const col = key.slice(5);
                     const field = qi.tableMeta.reverseColumnMap[col] ?? (0, schema_js_1.snakeToCamel)(col);
-                    maxObj[field] = val;
+                    maxObj[field] = temporalAggValue(qi, col, val);
                     hasMaxs = true;
                 }
             }

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

@@ -154,7 +154,7 @@ export declare const AUTO_TO_ONE_JOIN_ROWS_MAX = 100000;
  * it.
  */
 export declare const AUTO_COUNT_BATCH_MIN_PARENT_ROWS = 2;
-export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './deferred.js';
+export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, TemporalInfinityReading, } from './deferred.js';
 import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
@@ -181,6 +181,14 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly warnOnUnlimited;
     private readonly scopedConnect;
     private readonly utcTimestamps;
+    /**
+     * How a Postgres temporal `infinity` / `-infinity` is handed back:
+     * `'preserve'` (default) or `'null'`. See {@link TemporalInfinityReading}
+     * for the trade, and {@link parseRow} for where it is applied.
+     */
+    private readonly temporalInfinity;
+    /** Whether `temporalInfinity` was left unset, i.e. the warning still applies. */
+    private readonly warnTemporalInfinityUnset;
     private readonly preparedStatementsEnabled;
     /**
      * Whether the SQL template cache is active. Set once in the constructor.
@@ -1010,5 +1018,52 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * memoized per table. Used so nested relation rows (camelCase keys) coerce
      * dates the same way top-level rows do.
      */
+    /**
+     * Say ONCE per `table.field` that a stored temporal `infinity` was actually
+     * read, and describe the reading the caller is getting. JavaScript has no
+     * `Date` for either infinity, so BOTH readings cost something and a caller
+     * whose rows carry the value needs to know which cost they are paying.
+     *
+     * Under the default `'preserve'` the value comes back as the JS number
+     * `Infinity` / `-Infinity` on a field the generated types declare as `Date`,
+     * so `.toISOString()` / `.getTime()` throw a TypeError on exactly those rows
+     * and `JSON.stringify` still renders them `null` (JSON has no infinity
+     * literal). That is the price of the reading being LOSSLESS: the number binds
+     * straight back, so a read-modify-write stores `infinity` again. The
+     * alternative, `'null'`, is silently destructive, which is why it is not the
+     * default and why the warning names it as a deliberate choice rather than a
+     * recommendation.
+     *
+     * ONLY WHEN THE OPTION WAS LEFT UNSET. Naming a reading in the config, either
+     * one, is the acknowledgement, and the warning exists to surface an
+     * unacknowledged trade rather than to nag.
+     *
+     * NOT DEV-ONLY, unlike every other warning in this codebase, and deliberately
+     * so. Production is exactly where a destructive write commits and where the
+     * row cannot be recovered afterwards, so a warning that goes quiet under
+     * `NODE_ENV=production` is silent in the only place it matters. The cost is
+     * bounded to the point of irrelevance: once per process per field, and only
+     * on a row that actually held an infinity.
+     *
+     * KEYED ON THE FIELD, not the row key: top-level rows arrive snake_case and
+     * nested `json_build_object` rows arrive camelCase, so keying on the raw key
+     * warned twice for one column.
+     */
+    private warnTemporalInfinity;
+    /**
+     * Apply the configured reading to the infinity elements of a temporal ARRAY
+     * value, returning the original array by identity when there are none (the
+     * overwhelmingly common case, so no per-row allocation on ordinary data).
+     */
+    private mapArrayTemporalInfinity;
+    /**
+     * The configured reading of one infinity value: the JS number (`'preserve'`,
+     * the default) or `null`. Under `'preserve'` the JSON-wire STRING form
+     * (`"infinity"`, what the join and positional strategies see) is normalized
+     * to the number too, so the reading is identical on every strategy; 0.54
+     * shipped the number on some paths and an Invalid Date on others, which is
+     * the bug that made a single reading necessary in the first place.
+     */
+    private readTemporalInfinity;
     private parseRow;
 }

package/dist/cjs/query/builder.js

@@ -377,6 +377,14 @@ class QueryInterface {
     warnOnUnlimited;
     scopedConnect;
     utcTimestamps;
+    /**
+     * How a Postgres temporal `infinity` / `-infinity` is handed back:
+     * `'preserve'` (default) or `'null'`. See {@link TemporalInfinityReading}
+     * for the trade, and {@link parseRow} for where it is applied.
+     */
+    temporalInfinity;
+    /** Whether `temporalInfinity` was left unset, i.e. the warning still applies. */
+    warnTemporalInfinityUnset;
     preparedStatementsEnabled;
     /**
      * Whether the SQL template cache is active. Set once in the constructor.
@@ -523,6 +531,17 @@ class QueryInterface {
                 : warnOpt !== false;
         this.scopedConnect = options?.scopedConnect === true;
         this.utcTimestamps = options?.utcTimestamps !== false;
+        // Unset resolves to `'preserve'`. `'null'` destroys data: it makes a stored
+        // infinity indistinguishable from a stored NULL, so the ordinary
+        // read-modify-write (`update({ data: { ...row } })`) stores SQL NULL over a
+        // nullable temporal column and the infinity is gone with no error, measured
+        // on a live server. A lossy default is the wrong price for a nicer
+        // `JSON.stringify`, so the lossless reading is the default and `'null'`
+        // stays available as an explicit opt-in.
+        this.temporalInfinity = options?.temporalInfinity === 'null' ? 'null' : 'preserve';
+        // The warning exists to surface an UNACKNOWLEDGED trade. Naming either
+        // reading in the config is the acknowledgement, so it stops.
+        this.warnTemporalInfinityUnset = options?.temporalInfinity === undefined;
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
         // SQL template cache capacity. `sqlCacheSize: 0` disables caching entirely
         // (mirrors `sqlCache: false`); any positive integer sets the LRU bound;
@@ -619,6 +638,9 @@ class QueryInterface {
             // building a client whose writes and reads disagree (see
             // `assertUtcTimestampsAgree` in client.ts).
             utcTimestamps: this.utcTimestamps,
+            // Reaches aggregates.ts, where `_min` / `_max` are assembled from the raw
+            // row and so need the same infinity reading as `parseRow`.
+            temporalInfinity: this.temporalInfinity,
             crossSchemaTypeColumns: this.crossSchemaTypeColumns,
             get currentSkip() {
                 return self.currentSkip;
@@ -3055,6 +3077,87 @@ class QueryInterface {
      * memoized per table. Used so nested relation rows (camelCase keys) coerce
      * dates the same way top-level rows do.
      */
+    /**
+     * Say ONCE per `table.field` that a stored temporal `infinity` was actually
+     * read, and describe the reading the caller is getting. JavaScript has no
+     * `Date` for either infinity, so BOTH readings cost something and a caller
+     * whose rows carry the value needs to know which cost they are paying.
+     *
+     * Under the default `'preserve'` the value comes back as the JS number
+     * `Infinity` / `-Infinity` on a field the generated types declare as `Date`,
+     * so `.toISOString()` / `.getTime()` throw a TypeError on exactly those rows
+     * and `JSON.stringify` still renders them `null` (JSON has no infinity
+     * literal). That is the price of the reading being LOSSLESS: the number binds
+     * straight back, so a read-modify-write stores `infinity` again. The
+     * alternative, `'null'`, is silently destructive, which is why it is not the
+     * default and why the warning names it as a deliberate choice rather than a
+     * recommendation.
+     *
+     * ONLY WHEN THE OPTION WAS LEFT UNSET. Naming a reading in the config, either
+     * one, is the acknowledgement, and the warning exists to surface an
+     * unacknowledged trade rather than to nag.
+     *
+     * NOT DEV-ONLY, unlike every other warning in this codebase, and deliberately
+     * so. Production is exactly where a destructive write commits and where the
+     * row cannot be recovered afterwards, so a warning that goes quiet under
+     * `NODE_ENV=production` is silent in the only place it matters. The cost is
+     * bounded to the point of irrelevance: once per process per field, and only
+     * on a row that actually held an infinity.
+     *
+     * KEYED ON THE FIELD, not the row key: top-level rows arrive snake_case and
+     * nested `json_build_object` rows arrive camelCase, so keying on the raw key
+     * warned twice for one column.
+     */
+    warnTemporalInfinity(table, field) {
+        if (!this.warnTemporalInfinityUnset)
+            return;
+        if (!(0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.temporalInfinity, `${table}.${field}`))
+            return;
+        console.warn(`[turbine] ${table}.${field} holds the Postgres value \`infinity\` (or \`-infinity\`). JavaScript has ` +
+            'no Date for it, so it reads as the JS number `Infinity` / `-Infinity` on a field the generated ' +
+            'types declare as `Date`: `.toISOString()` and `.getTime()` throw a TypeError on these rows, and ' +
+            '`JSON.stringify` still renders them null because JSON has no infinity literal. The number is the ' +
+            'lossless reading, though: it binds straight back, so writing a row you just read stores `infinity` ' +
+            'again. Two more things this column can no longer do: `where: { col: null }` still means IS NULL and ' +
+            "does NOT match these rows (filter them with `{ col: 'infinity' }`), and `groupBy` / `distinct` " +
+            "cannot tell infinity, -infinity and NULL apart. Set `temporalInfinity: 'preserve'` to confirm this " +
+            "reading and silence the warning, or `'null'` to read null instead, accepting that a stored " +
+            'infinity then looks exactly like a stored NULL and a read-modify-write over a nullable column ' +
+            'stores SQL NULL, destroying the value with no error.');
+    }
+    /**
+     * Apply the configured reading to the infinity elements of a temporal ARRAY
+     * value, returning the original array by identity when there are none (the
+     * overwhelmingly common case, so no per-row allocation on ordinary data).
+     */
+    mapArrayTemporalInfinity(value, table, field) {
+        let hit = false;
+        for (let i = 0; i < value.length; i++) {
+            if ((0, utils_js_1.isTemporalInfinity)(value[i])) {
+                hit = true;
+                break;
+            }
+        }
+        if (!hit)
+            return value;
+        this.warnTemporalInfinity(table, field);
+        return value.map((el) => ((0, utils_js_1.isTemporalInfinity)(el) ? this.readTemporalInfinity(el) : el));
+    }
+    /**
+     * The configured reading of one infinity value: the JS number (`'preserve'`,
+     * the default) or `null`. Under `'preserve'` the JSON-wire STRING form
+     * (`"infinity"`, what the join and positional strategies see) is normalized
+     * to the number too, so the reading is identical on every strategy; 0.54
+     * shipped the number on some paths and an Invalid Date on others, which is
+     * the bug that made a single reading necessary in the first place.
+     */
+    readTemporalInfinity(value) {
+        if (this.temporalInfinity === 'null')
+            return null;
+        if (typeof value === 'number')
+            return value;
+        return value === '-infinity' ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY;
+    }
     parseRow(row, table) {
         const parsed = {};
         const meta = this.schema.tables[table];
@@ -3071,29 +3174,48 @@ class QueryInterface {
                 const value = row[col];
                 const field = reverseMap[col] ?? col; // fall back to raw col name, not regex
                 // Top-level rows are snake_case (dateCols); nested rows are camelCase (camelDateFields).
-                //
-                // An ARRAY value is excluded: `dateColumns` includes array-of-date
-                // columns (`date[]`, `timestamp[]`, `timestamptz[]`), for which the
-                // driver already hands back a `Date[]`. Coercing it ran
-                // `new Date(String(theArray))` and replaced the whole array with a
-                // single Invalid Date, the column was unreadable on every strategy.
-                // The join strategy's string arrays are handled upstream instead, by
-                // the JSON-wire decode in relations.ts.
-                //
-                // A NUMBER is excluded for the same reason: the driver returns the
-                // JS numbers `Infinity` / `-Infinity` for the Postgres `infinity` /
-                // `-infinity` timestamp values, and re-coercing one ran
-                // `parseDbDate(String(Infinity))` = `parseDbDate('Infinity')`, which
-                // is an Invalid Date that JSON-encodes as null. The array form escaped
-                // this only because it took the branch above.
-                if ((dateCols.has(col) || camelDateFields.has(field)) &&
-                    value !== null &&
-                    !(value instanceof Date) &&
-                    !Array.isArray(value) &&
-                    typeof value !== 'number') {
-                    // Offset-less strings (Postgres `timestamp`, json_agg output) are
-                    // pinned to UTC so results don't depend on the server's time zone.
-                    parsed[field] = this.utcTimestamps ? (0, utils_js_1.parseDbDate)(String(value)) : new Date(value);
+                if ((dateCols.has(col) || camelDateFields.has(field)) && value !== null && !(value instanceof Date)) {
+                    if ((0, utils_js_1.isTemporalInfinity)(value)) {
+                        // Postgres `infinity` / `-infinity`. No JS Date means either, so
+                        // both readings cost something and the default is the one that is
+                        // not lossy. `'preserve'` hands back the JS number, which breaks
+                        // the declared `Date` type at runtime (`.toISOString()` throws) and
+                        // still serializes as null because JSON has no infinity literal,
+                        // but binds straight back, so a read-modify-write stores `infinity`
+                        // again. `'null'` reads nicer and DESTROYS the value on that same
+                        // write, because a stored infinity and a stored NULL become
+                        // indistinguishable. Whichever is configured, it is the SAME on
+                        // every read strategy: the driver hands back the number,
+                        // `json_build_object` hands back the string "infinity", and both
+                        // land here (see `isTemporalInfinity`).
+                        //
+                        // The warning below fires once per column when the option was left
+                        // unset, on a row that actually held an infinity, and describes the
+                        // reading in force rather than gating on which one it is.
+                        this.warnTemporalInfinity(table, field);
+                        parsed[field] = this.readTemporalInfinity(value);
+                    }
+                    else if (Array.isArray(value)) {
+                        // `dateColumns` includes array-of-date columns (`date[]`,
+                        // `timestamp[]`, `timestamptz[]`), for which the driver already
+                        // hands back a `Date[]`. Coercing the array itself ran
+                        // `new Date(String(theArray))` and replaced the whole column with
+                        // one Invalid Date. Its ELEMENTS get the same infinity mapping as a
+                        // scalar (same declared element type, same JSON rendering);
+                        // everything else is passed through by identity.
+                        parsed[field] = this.mapArrayTemporalInfinity(value, table, field);
+                    }
+                    else if (typeof value === 'number') {
+                        // Any other number on a date column is left alone rather than run
+                        // through `parseDbDate(String(n))`, which would produce an Invalid
+                        // Date.
+                        parsed[field] = value;
+                    }
+                    else {
+                        // Offset-less strings (Postgres `timestamp`, json_agg output) are
+                        // pinned to UTC so results don't depend on the server's time zone.
+                        parsed[field] = this.utcTimestamps ? (0, utils_js_1.parseDbDate)(String(value)) : new Date(value);
+                    }
                 }
                 else {
                     parsed[field] = value;