turbine-orm 0.54.0 → 0.55.0

package/dist/cjs/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/cjs/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/cjs/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;
 /**

package/dist/cjs/query/utils.js

@@ -22,10 +22,14 @@ exports.toLocalDateTimeLiteral = toLocalDateTimeLiteral;
 exports.temporalBindKind = temporalBindKind;
 exports.coerceTemporalValue = coerceTemporalValue;
 exports.parseDbDate = parseDbDate;
+exports.isTemporalInfinity = isTemporalInfinity;
 exports.createUtcDateParser = createUtcDateParser;
 exports.createUtcTimestampParser = createUtcTimestampParser;
 exports.parseUtcTimestampText = parseUtcTimestampText;
 exports.createPgArrayParser = createPgArrayParser;
+exports.markTurbineParser = markTurbineParser;
+exports.isDefaultTextParser = isDefaultTextParser;
+exports.warnParserOverwrite = warnParserOverwrite;
 exports.registerUtcTemporalParsers = registerUtcTemporalParsers;
 exports.jsonWireCoercionOid = jsonWireCoercionOid;
 exports.coerceJsonWireValue = coerceJsonWireValue;
@@ -33,6 +37,7 @@ exports.closestName = closestName;
 exports.unknownFieldMessage = unknownFieldMessage;
 const pg_1 = __importDefault(require("pg"));
 const schema_js_1 = require("../schema.js");
+const warn_registry_js_1 = require("./warn-registry.js");
 // ---------------------------------------------------------------------------
 // Identifier quoting, prevents SQL injection via table/column names
 // ---------------------------------------------------------------------------
@@ -349,6 +354,42 @@ function parseDbDate(value) {
     // normalize `YYYY-MM-DD HH:MM:SS` (driver form) to ISO before pinning UTC
     return new Date(`${value.replace(' ', 'T')}Z`);
 }
+/**
+ * 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.
+ */
+function isTemporalInfinity(value) {
+    if (typeof value === 'number')
+        return value === Number.POSITIVE_INFINITY || value === Number.NEGATIVE_INFINITY;
+    return value === 'infinity' || value === '-infinity';
+}
 // ---------------------------------------------------------------------------
 // Driver type parsers for the zone-less temporal OIDs
 // ---------------------------------------------------------------------------
@@ -462,6 +503,126 @@ function createPgArrayParser(element) {
     const arrayParser = pg_1.default.types.arrayParser;
     return (text) => arrayParser.create(text, (entry) => (entry === null || entry === undefined ? null : element(entry))).parse();
 }
+/**
+ * A canonical wire value per OID, plus the JS value pg's OWN default text
+ * parser produces from it, used to tell "still on the driver default" from
+ * "somebody else already customized this OID" (see
+ * {@link isDefaultTextParser}).
+ *
+ * The expected values are computed from LOCAL date components on purpose: pg's
+ * default for the zone-less temporal OIDs builds its `Date` in the process's
+ * zone (that is the reading `utcTimestamps` exists to replace), so the
+ * expectation has to be computed the same way in whatever zone the process runs.
+ */
+const DEFAULT_PARSER_PROBES = {
+    20: { text: '9007199254740993', expected: () => '9007199254740993' },
+    1082: { text: '2020-01-02', expected: () => new Date(2020, 0, 2) },
+    1114: { text: '2020-01-02 03:04:05', expected: () => new Date(2020, 0, 2, 3, 4, 5) },
+    1115: { text: '{"2020-01-02 03:04:05"}', expected: () => [new Date(2020, 0, 2, 3, 4, 5)] },
+    1182: { text: '{2020-01-02}', expected: () => [new Date(2020, 0, 2)] },
+};
+/**
+ * Marks a text parser as one TURBINE installed, so a later registration in the
+ * same process (a client plus `turbine studio`, ESM plus CJS copies of this
+ * module) does not report Turbine's own parser as "somebody else's". A
+ * `Symbol.for` key, for the same cross-copy-identity reason the warn registry
+ * uses one.
+ */
+const TURBINE_PARSER = Symbol.for('turbine.typeParser');
+/** The OIDs the `utcTimestamps` flag governs, and so the ones it can opt out of. */
+const TEMPORAL_PARSER_OIDS = new Set([1114, 1082, 1115, 1182]);
+/** Tag `parser` as Turbine's own and return it (see {@link TURBINE_PARSER}). */
+function markTurbineParser(parser) {
+    parser[TURBINE_PARSER] = true;
+    return parser;
+}
+/** Comparable rendering of a parser result (Date by instant, array by element). */
+function parserResultSignature(value) {
+    if (value === null || value === undefined)
+        return String(value);
+    if (value instanceof Date)
+        return `date:${value.getTime()}`;
+    if (Array.isArray(value))
+        return `[${value.map(parserResultSignature).join(',')}]`;
+    return `${typeof value}:${String(value)}`;
+}
+/**
+ * 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.
+ */
+function isDefaultTextParser(oid, parser) {
+    const probe = DEFAULT_PARSER_PROBES[oid];
+    if (!probe)
+        return true;
+    try {
+        return parserResultSignature(parser(probe.text)) === parserResultSignature(probe.expected());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+function warnParserOverwrite(oid, typeName) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    const getParser = pg_1.default.types.getTypeParser;
+    const current = getParser(oid, 'text');
+    // Turbine's own earlier registration is not a third party's expectation.
+    if (current[TURBINE_PARSER])
+        return;
+    if (isDefaultTextParser(oid, current))
+        return;
+    if (!(0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.parserOverwrite, String(oid)))
+        return;
+    // The `utcTimestamps: false` opt-out only governs the four TEMPORAL OIDs.
+    // Offering it as the remedy for int8 (20) would name a setting that does
+    // nothing for the OID being warned about; that registration has no opt-out.
+    const remedy = TEMPORAL_PARSER_OIDS.has(oid)
+        ? ' `utcTimestamps: false` leaves the four temporal OIDs (1114, 1082, 1115, 1182) alone entirely.'
+        : ' There is no opt-out for this OID: Turbine registers it so bigint values come back as numbers.';
+    console.warn(`[turbine] pg type parser for OID ${oid} (${typeName}) was already customized by something else in this ` +
+        'process, and Turbine is replacing it. `pg.types.setTypeParser` is process-global and takes effect ' +
+        'immediately for EVERY pg.Pool in the process, including pools that already exist and are already ' +
+        'querying, so whatever set that parser will now read this column differently. If yours should win, ' +
+        `register it AFTER constructing the client.${remedy} Dev-only: silent under \`NODE_ENV=production\`.`);
+}
 /**
  * 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).
@@ -477,6 +638,11 @@ function createPgArrayParser(element) {
  * 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.
  */
 function registerUtcTemporalParsers() {
     // pg-types declares get/setTypeParser over its own OID enum, which lists the
@@ -484,15 +650,19 @@ function registerUtcTemporalParsers() {
     // retyped over a plain number rather than the incomplete enum.
     const getParser = pg_1.default.types.getTypeParser;
     const setParser = pg_1.default.types.setTypeParser;
+    warnParserOverwrite(1114, 'timestamp');
+    warnParserOverwrite(1082, 'date');
+    warnParserOverwrite(1115, 'timestamp[]');
+    warnParserOverwrite(1182, 'date[]');
     const parseDate = createUtcDateParser(getParser(1082, 'text'));
     const parseTimestamp = createUtcTimestampParser(getParser(1114, 'text'));
-    setParser(1114, parseTimestamp);
-    setParser(1082, parseDate);
+    setParser(1114, markTurbineParser(parseTimestamp));
+    setParser(1082, markTurbineParser(parseDate));
     // Array OIDs do not inherit their element parser, so `date[]` / `timestamp[]`
     // would otherwise keep returning local-zone Dates while the scalar columns
     // beside them returned UTC ones.
-    setParser(1182, createPgArrayParser(parseDate));
-    setParser(1115, createPgArrayParser(parseTimestamp));
+    setParser(1182, markTurbineParser(createPgArrayParser(parseDate)));
+    setParser(1115, markTurbineParser(createPgArrayParser(parseTimestamp)));
 }
 // ---------------------------------------------------------------------------
 // JSON-wire value coercion (relationLoadStrategy: 'join')

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

@@ -82,6 +82,20 @@ export declare const WARN_NS: {
      * the offenders, not one per column. The namespace name is historical.
      */
     readonly untypedDateColumn: "untypedDateColumn";
+    /**
+     * A stored temporal `infinity` / `-infinity` was actually read, and
+     * `temporalInfinity` was left unset, so the row parser describes the reading
+     * in force (builder.ts `warnTemporalInfinity`). Keyed on `table.column`, so a
+     * table with two such columns says it once for each and a million rows say it
+     * once in total.
+     */
+    readonly temporalInfinity: "temporalInfinity";
+    /**
+     * Turbine replaced a pg text parser that was NOT on the driver default, i.e.
+     * something else in the process had already customized that OID (utils.ts
+     * `warnParserOverwrite`). Keyed on the OID.
+     */
+    readonly parserOverwrite: "parserOverwrite";
     /**
      * `planCacheMode` was set on a client given an EXTERNAL pool, where Turbine
      * runs no connection setup, so the option is a no-op (client.ts constructor).

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

@@ -123,6 +123,20 @@ exports.WARN_NS = {
      * the offenders, not one per column. The namespace name is historical.
      */
     untypedDateColumn: 'untypedDateColumn',
+    /**
+     * A stored temporal `infinity` / `-infinity` was actually read, and
+     * `temporalInfinity` was left unset, so the row parser describes the reading
+     * in force (builder.ts `warnTemporalInfinity`). Keyed on `table.column`, so a
+     * table with two such columns says it once for each and a million rows say it
+     * once in total.
+     */
+    temporalInfinity: 'temporalInfinity',
+    /**
+     * Turbine replaced a pg text parser that was NOT on the driver default, i.e.
+     * something else in the process had already customized that OID (utils.ts
+     * `warnParserOverwrite`). Keyed on the OID.
+     */
+    parserOverwrite: 'parserOverwrite',
     /**
      * `planCacheMode` was set on a client given an EXTERNAL pool, where Turbine
      * runs no connection setup, so the option is a no-op (client.ts constructor).

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

@@ -14,6 +14,7 @@ import type pg from 'pg';
 import type { Dialect } from '../dialect.js';
 import { ValidationError } from '../errors.js';
 import type { RelationDef, SchemaMetadata, TableMetadata } from '../schema.js';
+import type { TemporalInfinityReading } from './deferred.js';
 import type { ArrayFilter, ColumnRef, GlobalFilters, JsonFilter, JsonPathOrderBy, SkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
 import { type SqlCacheEntry } from './utils.js';
 import { type WhereHost, type WhereRecord } from './where-compile.js';
@@ -43,6 +44,13 @@ export interface BuilderCtx {
      * `timestamp` columns (see `coerceWriteValue` in writes.ts).
      */
     readonly utcTimestamps?: boolean;
+    /**
+     * The client's `temporalInfinity` reading (`'preserve'` default, `'null'`).
+     * Read by aggregates.ts, where `_min` / `_max` are assembled from the raw row
+     * and so cannot go through `parseRow`. Optional so a hand-built ctx keeps the
+     * default.
+     */
+    readonly temporalInfinity?: TemporalInfinityReading;
     readonly crossSchemaTypeColumns: Set<string>;
     /**
      * The active query's `skipGlobalFilters` opt-out. A live getter/setter over

package/dist/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