turbine-orm 0.54.0 → 0.55.0

package/dist/client.js

@@ -27,7 +27,7 @@ import { setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationE
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
-import { closestName, quoteIdent, registerUtcTemporalParsers } from './query/utils.js';
+import { closestName, markTurbineParser, quoteIdent, registerUtcTemporalParsers, warnParserOverwrite, } from './query/utils.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { createSubscription, validateChannel, } from './realtime.js';
 import { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
@@ -102,6 +102,7 @@ const TURBINE_CONFIG_KEYS = {
     defaultLimit: true,
     warnOnUnlimited: true,
     utcTimestamps: true,
+    temporalInfinity: true,
     planCacheMode: true,
     scopedConnect: true,
     relationLoadStrategy: true,
@@ -591,10 +592,11 @@ export class TurbineClient {
         // constructor-gated by the static flags, so it happens at most once.
         const ownsAnyPool = !config.pool;
         if (ownsAnyPool && !TurbineClient.int8ParserRegistered) {
-            pg.types.setTypeParser(20, (val) => {
+            warnParserOverwrite(20, 'int8');
+            pg.types.setTypeParser(20, 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
@@ -638,6 +640,7 @@ export 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,
@@ -809,6 +812,23 @@ export 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 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/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/query/aggregates.js

@@ -11,7 +11,7 @@
 import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
 import { isJsonPathOrderBy, isUnmatchedPlainObject, isVectorOrderBy, isWhereOperator, normalizeOrderBy, orderByEntries, } from './filters.js';
-import { ownLookup } from './utils.js';
+import { isTemporalInfinity, ownLookup } from './utils.js';
 import * as whereMod from './where.js';
 /**
  * Enforce the PII contract on the aggregate surface. A PII-tagged
@@ -310,12 +310,14 @@ export 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;
                 }
             }
@@ -725,6 +727,38 @@ export 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 (!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;
+}
 export function buildAggregate(qi, args) {
     qi.currentSkip = args.skipGlobalFilters;
     const aggWhere = whereMod.mergeGlobalFilter(qi, args.where);
@@ -869,13 +903,13 @@ export function buildAggregate(qi, args) {
                 else if (key.startsWith('_min_')) {
                     const col = key.slice(5);
                     const field = qi.tableMeta.reverseColumnMap[col] ?? 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] ?? snakeToCamel(col);
-                    maxObj[field] = val;
+                    maxObj[field] = temporalAggValue(qi, col, val);
                     hasMaxs = true;
                 }
             }

package/dist/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/query/builder.js

@@ -20,7 +20,7 @@ import { defaultProjectionFields, includeKeysForBatching, loadRelationsBatched,
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import * as relationsMod from './relations.js';
-import { LRUCache, ownLookup, parseDbDate, resolveColumnName, sqlToPreparedName, unknownFieldMessage, } from './utils.js';
+import { isTemporalInfinity, LRUCache, ownLookup, parseDbDate, resolveColumnName, sqlToPreparedName, unknownFieldMessage, } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -341,6 +341,14 @@ export 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.
@@ -487,6 +495,17 @@ export 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;
@@ -583,6 +602,9 @@ export 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;
@@ -3019,6 +3041,87 @@ export 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 (!shouldWarnOnce(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 (isTemporalInfinity(value[i])) {
+                hit = true;
+                break;
+            }
+        }
+        if (!hit)
+            return value;
+        this.warnTemporalInfinity(table, field);
+        return value.map((el) => (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];
@@ -3035,29 +3138,48 @@ export 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 ? parseDbDate(String(value)) : new Date(value);
+                if ((dateCols.has(col) || camelDateFields.has(field)) && value !== null && !(value instanceof Date)) {
+                    if (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 ? parseDbDate(String(value)) : new Date(value);
+                    }
                 }
                 else {
                     parsed[field] = value;

package/dist/query/deferred.d.ts

@@ -35,6 +35,36 @@ export interface DeferredQuery<T> {
      */
     reselect?: (exec: ReselectExecutor) => Promise<pg.QueryResult>;
 }
+/**
+ * How the ORM hands back a Postgres temporal `infinity` / `-infinity`.
+ *
+ * JavaScript has no `Date` for either value, so every available reading is
+ * wrong in some way and the choice is which way:
+ *
+ *   `'preserve'`  the default. The JS numbers `Infinity` / `-Infinity`,
+ *                 normalized to the same value on EVERY read strategy (the
+ *                 join and positional paths see the JSON string `"infinity"`
+ *                 and are mapped to the number, which is what 0.54 got wrong).
+ *                 LOSSLESS: binding the number back to a temporal column
+ *                 stores `infinity` again, so `update({ data: { ...row } })`
+ *                 round-trips. THE COST: the field's declared type is `Date`,
+ *                 so `row.validUntil.toISOString()` throws a TypeError on
+ *                 those rows, and `JSON.stringify` still renders the value
+ *                 `null`.
+ *   `'null'`      opt-in. Matches what a caller serializing the row already
+ *                 saw (`JSON.stringify` renders every other candidate as null
+ *                 too) and is permitted by the declared type of a nullable
+ *                 column, so no method call throws. THE COST is data loss: a
+ *                 stored `infinity` and a stored NULL become
+ *                 indistinguishable, so a read-modify-write over a nullable
+ *                 column (`update({ data: { ...row } })`) writes SQL NULL and
+ *                 the infinity is gone, with no error.
+ *
+ * The default is the reading that cannot lose a value. Pick `'null'` when the
+ * declared type contract matters more than the stored value, knowing that rows
+ * read under it must not be written back.
+ */
+export type TemporalInfinityReading = 'null' | 'preserve';
 /** Middleware function type, imported from client to avoid circular deps */
 export type MiddlewareFn = (params: {
     model: string;
@@ -142,6 +172,11 @@ export interface QueryInterfaceOptions {
      * the pre-0.26 behavior (JS local-time interpretation).
      */
     utcTimestamps?: boolean;
+    /**
+     * How a Postgres temporal `infinity` / `-infinity` is handed back. See
+     * {@link TemporalInfinityReading}. Default `'preserve'`.
+     */
+    temporalInfinity?: TemporalInfinityReading;
     /**
      * Client-level default relation-loading strategy for `with` clauses; a
      * per-query `relationLoadStrategy` arg overrides it. On SQL engines the default

package/dist/query/index.d.ts

@@ -10,5 +10,5 @@ export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, C
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
-export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './builder.js';
+export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, TemporalInfinityReading, } from './builder.js';
 export { 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, QueryInterface, } from './builder.js';

package/dist/query/utils.d.ts

@@ -176,6 +176,38 @@ export declare function coerceTemporalValue(dbType: string | undefined, value: u
  * as-is.
  */
 export declare function parseDbDate(value: string): Date;
+/**
+ * Is `value` one of the two representations a Postgres temporal `infinity` /
+ * `-infinity` reaches the ORM row parser in?
+ *
+ * TWO representations, because a temporal column is read two different ways
+ * and they disagree on the wire:
+ *
+ *   driver          the pg text parser for `timestamp` / `date` does not
+ *                   recognise the word, so it falls through to the driver's own
+ *                   parser, which returns the JS NUMBERS `Infinity` /
+ *                   `-Infinity`. This is what a top-level row, the batched and
+ *                   flatten strategies, a write `RETURNING` projection and a
+ *                   `groupBy` key all see.
+ *   JSON wire       `json_build_object` renders the same value as the STRING
+ *                   `"infinity"`, and scalar `timestamp` / `timestamptz` are
+ *                   deliberately absent from {@link JSON_WIRE_COERCION_OIDS},
+ *                   so no driver parser runs over it. This is what the `'join'`
+ *                   strategy and the positional encoding see.
+ *
+ * Both are normalized in one place ({@link QueryInterface}'s row parser), to
+ * whichever reading `temporalInfinity` selects (the JS number by default, or
+ * `null`), so the same stored value cannot read differently depending on which
+ * plan the query happened to take. The string form is only ever consulted for a column
+ * the schema says is temporal, so a `text` column holding the word "infinity"
+ * is untouched.
+ *
+ * Not dialect-gated. Postgres is the only engine with an infinite temporal
+ * value, but the row parser is engine-shared and the alternative reading on the
+ * other engines (a stray `'infinity'` string becoming an Invalid Date) is not
+ * one worth preserving.
+ */
+export declare function isTemporalInfinity(value: unknown): boolean;
 /**
  * Build the driver parser for Postgres `date` (OID 1082) that reads a
  * zone-less calendar day as **UTC midnight**.
@@ -243,6 +275,52 @@ export declare function parseUtcTimestampText(text: string): Date;
  * dependency. NULL elements stay `null` and are never handed to `element`.
  */
 export declare function createPgArrayParser(element: (text: string) => unknown): (text: string) => unknown[];
+/** Tag `parser` as Turbine's own and return it (see {@link TURBINE_PARSER}). */
+export declare function markTurbineParser<F extends (text: string) => unknown>(parser: F): F;
+/**
+ * Is the parser currently registered for `oid` still pg's own default?
+ *
+ * DETECTED BY BEHAVIOUR, NOT BY IDENTITY, and deliberately so. `pg-types` keeps
+ * its default parser table private: `getTypeParser` hands back whatever is
+ * registered NOW, and there is no exported way to ask what the default WAS, so
+ * a function-identity comparison would need a deep import of a file the package
+ * does not publish as an entry point. Instead this runs the registered parser
+ * over a canonical wire value and compares the result with what pg's default
+ * produces for it.
+ *
+ * What that buys and what it costs, stated honestly:
+ *   - Every parser that behaves OBSERVABLY differently on the probe value is
+ *     detected, which is the case worth warning about (someone else's reading
+ *     is about to be replaced by Turbine's).
+ *   - A replacement that is observably EQUIVALENT on the probe is reported as
+ *     the default and draws no warning. That is a false negative, and an
+ *     acceptable one: if it agrees with the default here it is not a reading
+ *     anybody would notice Turbine overwriting.
+ *   - A parser that THROWS on the probe is reported as non-default; pg's own
+ *     never throws on a valid value of its type.
+ *   - An OID with no probe entry is reported as default (never warn on a guess).
+ *
+ * The registered parser is invoked once, on a synthetic value, at client
+ * construction. A decode parser with side effects would be surprising, and pg's
+ * own have none.
+ */
+export declare function isDefaultTextParser(oid: number, parser: (text: string) => unknown): boolean;
+/**
+ * Warn ONCE per OID when Turbine is about to replace a text parser that is not
+ * pg's default, i.e. when some other module in the process has already
+ * customized it.
+ *
+ * `pg.types.setTypeParser` is process-global and retroactive: it changes how
+ * every `pg.Pool` in the process decodes that OID, including pools that were
+ * constructed and were already querying before the Turbine client existed. When
+ * the OID was still on pg's default that is the documented, intended trade (the
+ * whole point of `utcTimestamps`). When somebody else had already installed
+ * their own reading, Turbine is silently rewriting an expectation it cannot see
+ * the origin of, and the resulting bug is order-dependent: which reading wins
+ * depends on module evaluation order, which lazy route imports make unstable
+ * between requests. So say it out loud, once.
+ */
+export declare function warnParserOverwrite(oid: number, typeName: string): void;
 /**
  * Register the UTC readings of the four zone-less temporal OIDs on the pg
  * module: `timestamp` (1114), `date` (1082) and their array forms (1115, 1182).
@@ -258,6 +336,11 @@ export declare function createPgArrayParser(element: (text: string) => unknown):
  * Each fallback is read BEFORE its parser is installed, so an unrecognised wire
  * value (`infinity`, and whatever a future server adds) still reaches the
  * driver's own parser.
+ *
+ * Registration is RETROACTIVE for the whole process, pools included that were
+ * created and are already querying (there is one parser table, and it is read
+ * per row at decode time, not captured per pool). If any of the four OIDs is
+ * already on a NON-default parser, {@link warnParserOverwrite} says so once.
  */
 export declare function registerUtcTemporalParsers(): void;
 /**