turbine-orm 0.71.0 → 0.72.0

package/dist/cjs/query/relation-names.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Caller-supplied RELATION names, normalized to their declared spelling once,
+ * before anything reads them.
+ *
+ * ## The rule
+ *
+ * A relation has one declared name (`ripeningChecks`), while the DDL anyone
+ * reads has only the table name (`ripening_checks`). Writing back what the
+ * schema shows therefore failed: E005 in `with`, E003 in a relation filter,
+ * E005 in `orderBy`, on names the error text was already computing correctly
+ * ("Did you mean ...?"). This accepts the snake_case spelling wherever the
+ * declared name is accepted, by the same resolve-then-validate rule
+ * {@link resolveRelation} states, which is the relation-level twin of
+ * `resolveColumnName`. It is not a guess: `snakeToCamel(key)` is accepted ONLY
+ * when it names a real declared relation, so a typo is still a typo, and an
+ * exact declared name always wins first.
+ *
+ * ## Why this is ONE pass up front and not a fix at each lookup
+ *
+ * The `with` tree is walked by SIX independent functions, each of which decides
+ * for itself which keys name relations: `withFingerprint`, `collectWithParams`,
+ * `buildRelationShapes`, `planFlattenWith`, `buildSelectWithRelations` and the
+ * batched loader, plus the positional row parser. Teaching each of them that a
+ * key has two spellings would make seven places that must agree about it, and
+ * disagreement is not a clean failure: the fingerprint is the SQL-cache key, so
+ * a walker that resolved differently from the builder would serve one query's
+ * template to another, silently. That is the drift class this repo has paid for
+ * repeatedly (the where-clause walkers, the two projection resolvers).
+ *
+ * Normalizing before any walker runs makes all seven correct with no knowledge
+ * of the second spelling, and keeps ONE authority for the rule.
+ *
+ * ## Shape
+ *
+ * Returns the SAME object when nothing needed rewriting, which is every query
+ * that already spells its relations the declared way, so the common path
+ * allocates nothing and is reference-identical to its input.
+ *
+ * An UNRESOLVABLE key is left exactly as written, deliberately. Reporting it is
+ * the builder's job, and it already names the offending key and lists the
+ * available relations; rejecting it here would move that error away from its
+ * context and change which error type callers see.
+ */
+import type { SchemaMetadata } from '../schema.js';
+import type { WithClause } from './types.js';
+/**
+ * `withClause` with every relation key replaced by its declared spelling,
+ * recursively, including the relation names inside a `_count`.
+ *
+ * Returns the input by reference when no key changed.
+ */
+export declare function normalizeWithClause(schema: SchemaMetadata, table: string, withClause: WithClause | undefined, depth?: number): WithClause | undefined;

package/dist/cjs/query/relation-names.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Caller-supplied RELATION names, normalized to their declared spelling once,
+ * before anything reads them.
+ *
+ * ## The rule
+ *
+ * A relation has one declared name (`ripeningChecks`), while the DDL anyone
+ * reads has only the table name (`ripening_checks`). Writing back what the
+ * schema shows therefore failed: E005 in `with`, E003 in a relation filter,
+ * E005 in `orderBy`, on names the error text was already computing correctly
+ * ("Did you mean ...?"). This accepts the snake_case spelling wherever the
+ * declared name is accepted, by the same resolve-then-validate rule
+ * {@link resolveRelation} states, which is the relation-level twin of
+ * `resolveColumnName`. It is not a guess: `snakeToCamel(key)` is accepted ONLY
+ * when it names a real declared relation, so a typo is still a typo, and an
+ * exact declared name always wins first.
+ *
+ * ## Why this is ONE pass up front and not a fix at each lookup
+ *
+ * The `with` tree is walked by SIX independent functions, each of which decides
+ * for itself which keys name relations: `withFingerprint`, `collectWithParams`,
+ * `buildRelationShapes`, `planFlattenWith`, `buildSelectWithRelations` and the
+ * batched loader, plus the positional row parser. Teaching each of them that a
+ * key has two spellings would make seven places that must agree about it, and
+ * disagreement is not a clean failure: the fingerprint is the SQL-cache key, so
+ * a walker that resolved differently from the builder would serve one query's
+ * template to another, silently. That is the drift class this repo has paid for
+ * repeatedly (the where-clause walkers, the two projection resolvers).
+ *
+ * Normalizing before any walker runs makes all seven correct with no knowledge
+ * of the second spelling, and keeps ONE authority for the rule.
+ *
+ * ## Shape
+ *
+ * Returns the SAME object when nothing needed rewriting, which is every query
+ * that already spells its relations the declared way, so the common path
+ * allocates nothing and is reference-identical to its input.
+ *
+ * An UNRESOLVABLE key is left exactly as written, deliberately. Reporting it is
+ * the builder's job, and it already names the offending key and lists the
+ * available relations; rejecting it here would move that error away from its
+ * context and change which error type callers see.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWithClause = normalizeWithClause;
+const utils_js_1 = require("./utils.js");
+/** Depth cap mirroring the builder's own, so a cyclic `with` cannot spin here. */
+const MAX_DEPTH = 12;
+/**
+ * `withClause` with every relation key replaced by its declared spelling,
+ * recursively, including the relation names inside a `_count`.
+ *
+ * Returns the input by reference when no key changed.
+ */
+function normalizeWithClause(schema, table, withClause, depth = 0) {
+    if (!withClause || typeof withClause !== 'object' || depth > MAX_DEPTH)
+        return withClause;
+    const meta = schema.tables[table];
+    if (!meta)
+        return withClause;
+    let changed = false;
+    const out = {};
+    for (const [key, spec] of Object.entries(withClause)) {
+        if (key === '_count') {
+            const nextCount = normalizeCount(meta, spec);
+            if (nextCount !== spec)
+                changed = true;
+            out[key] = nextCount;
+            continue;
+        }
+        const resolved = (0, utils_js_1.resolveRelation)(meta.relations, key);
+        // Unknown key: keep it verbatim and let the builder raise E005 by name.
+        const name = resolved?.name ?? key;
+        if (name !== key)
+            changed = true;
+        const nextSpec = resolved ? normalizeSpec(schema, resolved.def.to, spec, depth) : spec;
+        if (nextSpec !== spec)
+            changed = true;
+        out[name] = nextSpec;
+    }
+    return changed ? out : withClause;
+}
+/** A relation's `with` options, normalizing its nested `with` against the TARGET table. */
+function normalizeSpec(schema, target, spec, depth) {
+    if (spec === true || spec === false || spec === null || typeof spec !== 'object')
+        return spec;
+    const opts = spec;
+    if (!opts.with)
+        return spec;
+    const nested = normalizeWithClause(schema, target, opts.with, depth + 1);
+    return nested === opts.with ? spec : { ...opts, with: nested };
+}
+/**
+ * `_count` names relations too. `true` means every relation and has nothing to
+ * rename; the record form has one key per counted relation.
+ */
+function normalizeCount(meta, count) {
+    if (!count || typeof count !== 'object')
+        return count;
+    let changed = false;
+    const out = {};
+    for (const [key, value] of Object.entries(count)) {
+        const name = (0, utils_js_1.resolveRelation)(meta.relations, key)?.name ?? key;
+        if (name !== key)
+            changed = true;
+        out[name] = value;
+    }
+    return changed ? out : count;
+}
+/*
+ * NOTE for the next person: there are deliberately no `declaredRelationName` /
+ * `namesRelation` wrappers here. The argument positions where a relation key
+ * sits INTERLEAVED with column keys (`where`'s some/every/none, `orderBy`'s
+ * relation targets, the simple-where fast path) cannot be normalized up front
+ * the way `with` can, so they call `resolveRelation` / `resolveRelationDef`
+ * from query/utils.ts directly at their branch point. Each of those branches is
+ * already a documented single authority; wrapping them here would add a second
+ * name for the same rule without removing a caller.
+ */

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

@@ -117,12 +117,17 @@ export declare function isRelationOrderByValue(_qi: BuilderCtx, value: unknown):
  */
 export declare function nullsSuffix(qi: BuilderCtx, nulls: 'first' | 'last' | undefined): string;
 /**
- * Resolve an orderBy key to its snake_case column via the table's columnMap
- * (camelToSnake fallback), throwing the SAME unknown-field E003 the top-level
- * where path uses. Shared by top-level JSON-path ordering and every nested
- * relation orderBy path so nested orderBy accepts exactly what top-level
- * accepts (the 0.30.x bug: nested orderBy skipped the columnMap and rejected
- * camelCase-named DB columns like "sortOrder").
+ * Resolve an orderBy key to its snake_case column via {@link resolveColumnName},
+ * throwing the SAME unknown-field E003 the top-level where path uses. Shared by
+ * top-level JSON-path ordering and every nested relation orderBy path so nested
+ * orderBy accepts exactly what top-level accepts (the 0.30.x bug: nested orderBy
+ * skipped the columnMap and rejected camelCase-named DB columns like
+ * "sortOrder").
+ *
+ * The rule is REACHED here, never restated: this used to inline
+ * `columnMap ?? camelToSnake` + an `allColumns` check, which agreed with
+ * `resolveColumnName` while the top-level scalar path a few lines up disagreed
+ * with both.
  */
 export declare function resolveOrderByColumn(_qi: BuilderCtx, table: string, meta: TableMetadata, key: string): string;
 /**

package/dist/cjs/query/relations.js

@@ -117,7 +117,10 @@ function projectionColumn(table, meta, field, clause) {
     // A relation named in a projection is a habit, not a typo, so it gets its own
     // message pointing at `with`. Checked BEFORE the generic throw because the
     // generic one degrades into "Did you mean <exactly what you typed>?".
-    if ((0, utils_js_1.ownLookup)(meta.relations, field))
+    // Resolved, so `select: { ripening_checks: true }` gets the "that is a
+    // relation, use `with`" message rather than degrading to an unknown-field
+    // suggestion that names the relation back at the caller.
+    if ((0, utils_js_1.resolveRelationDef)(meta.relations, field))
         throw new errors_js_1.ValidationError((0, utils_js_1.relationInProjectionMessage)(table, field, clause));
     throw new errors_js_1.ValidationError((0, utils_js_1.unknownFieldMessage)(table, field, meta));
 }
@@ -541,10 +544,8 @@ function buildOrderBy(qi, orderBy, params, lateralSink) {
         .map(([key, value]) => {
         // Vector KNN ordering: { distance: { to, metric, direction? } }
         if ((0, filters_js_1.isVectorOrderBy)(value)) {
-            if (meta && !(key in meta.columnMap)) {
-                throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${qi.table}". ` +
-                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
-            }
+            if (meta)
+                resolveOrderByColumn(qi, qi.table, meta, key);
             if (!params) {
                 throw new errors_js_1.ValidationError(`[turbine] Vector distance ordering on "${key}" is only supported in a top-level findMany orderBy.`);
             }
@@ -567,10 +568,13 @@ function buildOrderBy(qi, orderBy, params, lateralSink) {
             return buildRelationOrderBy(qi, key, value, `ord${relOrdCounter++}`, params, undefined, lateralSink);
         }
         // Scalar column ordering, a plain direction or an OrderBySpec (nulls).
-        if (meta && !(key in meta.columnMap)) {
-            throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${qi.table}". ` +
-                `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
-        }
+        // Through `resolveOrderByColumn`, which is the same resolve-or-E003 the
+        // nested orderBy paths below already used and emits the same message
+        // this used to inline. It used to test `key in meta.columnMap`, which
+        // knows only the FIELD spelling, and so rejected the snake_case COLUMN
+        // name that `where` / `select` / `distinct` accept on the same table.
+        if (meta)
+            resolveOrderByColumn(qi, qi.table, meta, key);
         // Refuse a direction that is neither asc nor desc. normalizeOrderBy is
         // `=== 'desc' ? DESC : ASC`, so without this every typo sorted ASCENDING
         // and returned a correct-looking page in the reverse order.
@@ -608,16 +612,21 @@ function nullsSuffix(qi, nulls) {
     return nulls === 'first' ? ' NULLS FIRST' : ' NULLS LAST';
 }
 /**
- * Resolve an orderBy key to its snake_case column via the table's columnMap
- * (camelToSnake fallback), throwing the SAME unknown-field E003 the top-level
- * where path uses. Shared by top-level JSON-path ordering and every nested
- * relation orderBy path so nested orderBy accepts exactly what top-level
- * accepts (the 0.30.x bug: nested orderBy skipped the columnMap and rejected
- * camelCase-named DB columns like "sortOrder").
+ * Resolve an orderBy key to its snake_case column via {@link resolveColumnName},
+ * throwing the SAME unknown-field E003 the top-level where path uses. Shared by
+ * top-level JSON-path ordering and every nested relation orderBy path so nested
+ * orderBy accepts exactly what top-level accepts (the 0.30.x bug: nested orderBy
+ * skipped the columnMap and rejected camelCase-named DB columns like
+ * "sortOrder").
+ *
+ * The rule is REACHED here, never restated: this used to inline
+ * `columnMap ?? camelToSnake` + an `allColumns` check, which agreed with
+ * `resolveColumnName` while the top-level scalar path a few lines up disagreed
+ * with both.
  */
 function resolveOrderByColumn(_qi, table, meta, key) {
-    const col = (0, utils_js_1.ownLookup)(meta.columnMap, key) ?? (0, schema_js_1.camelToSnake)(key);
-    if (!meta.allColumns.includes(col)) {
+    const col = (0, utils_js_1.resolveColumnName)(meta, key);
+    if (col === undefined) {
         throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${table}". ` +
             `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
     }
@@ -746,14 +755,18 @@ function buildChainedToOneOrderBy(qi, head, nextRelName, nextValue, params) {
                 `(got: ${entries.map(([k]) => k).join(', ') || '(empty)'}).`);
         }
         const [key, entryValue] = entries[0];
-        if ((0, utils_js_1.ownLookup)(currentMeta.relations, key) && isRelationOrderByValue(qi, entryValue)) {
-            relName = key;
+        // Resolved, so a chained orderBy descends through the snake_case spelling
+        // of a relation exactly as `with` does; `relName` carries the DECLARED
+        // name onward so the path reported in errors is the canonical one.
+        const chained = (0, utils_js_1.resolveRelation)(currentMeta.relations, key);
+        if (chained && isRelationOrderByValue(qi, entryValue)) {
+            relName = chained.name;
             value = entryValue;
             continue;
         }
         // Terminal: a column on the last table in the chain.
-        const snakeCol = (0, utils_js_1.ownLookup)(currentMeta.columnMap, key) ?? (0, schema_js_1.camelToSnake)(key);
-        if (!currentMeta.allColumns.includes(snakeCol)) {
+        const snakeCol = (0, utils_js_1.resolveColumnName)(currentMeta, key);
+        if (snakeCol === undefined) {
             throw new errors_js_1.ValidationError(`[turbine] Unknown column "${key}" in orderBy on relation "${path.join('.')}" (table "${currentMeta.name}").`);
         }
         (0, types_js_1.assertOrderDirection)(entryValue, `orderBy on relation path "${path.join('.')}"`);
@@ -788,7 +801,12 @@ function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lateralSin
     const ownerMeta = ctx?.meta ?? qi.tableMeta;
     const ownerTable = ctx?.table ?? qi.table;
     const parentRef = ctx?.parentRef ?? qi.table;
-    const relDef = (0, utils_js_1.ownLookup)(ownerMeta.relations, relName);
+    // Resolved, then `relName` is rebound to the declared spelling so the alias
+    // and every message below use one name.
+    const resolvedOwner = (0, utils_js_1.resolveRelation)(ownerMeta.relations, relName);
+    if (resolvedOwner)
+        relName = resolvedOwner.name;
+    const relDef = resolvedOwner?.def;
     if (!relDef) {
         // A table with no relations at all would otherwise render a dangling
         // "Available: " and read as a broken message; and the most likely cause of
@@ -796,7 +814,7 @@ function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lateralSin
         // scalar column, which deserves to be named rather than reported as a
         // missing relation.
         const known = Object.keys(ownerMeta.relations);
-        const isColumn = Object.hasOwn(ownerMeta.columnMap, relName) || ownerMeta.allColumns.includes(relName);
+        const isColumn = (0, utils_js_1.resolveColumnName)(ownerMeta, relName) !== undefined;
         throw new errors_js_1.RelationError(isColumn
             ? `[turbine] orderBy on "${ownerTable}.${relName}" got a relation-shaped value, but "${relName}" is a ` +
                 `column. Order a column with 'asc' / 'desc' (or { sort, nulls }); the object form is for relations.`
@@ -847,10 +865,10 @@ function buildRelationOrderBy(qi, relName, value, alias, params, ctx, lateralSin
         if (nestedRel && isRelationOrderByValue(qi, dirValue)) {
             return buildChainedToOneOrderBy(qi, { relName, relDef, alias, correlation }, col, dirValue, params);
         }
-        // columnMap-first resolution (camelToSnake fallback): mirrors the
-        // scalar orderBy path so camelCase-named DB columns resolve here too.
-        const snakeCol = (0, utils_js_1.ownLookup)(targetMeta.columnMap, col) ?? (0, schema_js_1.camelToSnake)(col);
-        if (!targetMeta.allColumns.includes(snakeCol)) {
+        // The ONE key-resolution rule ({@link resolveColumnName}), so a target
+        // column resolves here exactly as it does in the top-level orderBy.
+        const snakeCol = (0, utils_js_1.resolveColumnName)(targetMeta, col);
+        if (snakeCol === undefined) {
             const relationHint = (0, utils_js_1.ownLookup)(targetMeta.relations, col)
                 ? ` "${col}" is a relation on "${relDef.to}": order by one of ITS columns, e.g. ` +
                     `{ ${relName}: { ${col}: { <column>: 'asc' } } }.`

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

@@ -59,6 +59,47 @@ export interface ColumnNameSource {
  * name (see {@link ownLookup}).
  */
 export declare function resolveColumnName(meta: ColumnNameSource, key: string): string | undefined;
+/**
+ * Resolve a user-supplied key to a relation's CANONICAL name and definition, or
+ * `undefined` when the key names no relation on the table.
+ *
+ * The relation-name half of the rule {@link resolveColumnName} states for
+ * columns, and deliberately the same shape: the declared name first, else
+ * `snakeToCamel(key)` accepted ONLY when that names a real relation.
+ * `snakeToCamel` is idempotent on an already-camel string, so a canonical key
+ * takes the first branch and this is a no-op for every existing caller.
+ *
+ * WHY IT EXISTS. A relation has one declared name, `ripeningChecks`, while the
+ * DDL anyone reads has only the TABLE name, `ripening_checks`. Writing back
+ * what the schema shows therefore failed with E005 in `with`, E003 in a
+ * relation filter, and E005 in `orderBy`, on names the error text was already
+ * computing correctly ("Did you mean ...?"). A system that can name the
+ * intended relation can accept it.
+ *
+ * NOT A GUESS, for the same reason the column rule is not: the transformed name
+ * is accepted only when it is a real declared relation, so an unknown key still
+ * fails and a typo is still a typo. Exact match wins first, so a schema that
+ * literally declares `ripening_checks` keeps it, even alongside a
+ * `ripeningChecks`.
+ *
+ * The RESULT KEY is the canonical name, not the caller's spelling, matching the
+ * column side (`select: { ledger_handle: true }` already returns
+ * `{ ledgerHandle }`). Resolving here rather than normalizing the args up front
+ * also means both spellings share one SQL-cache entry instead of minting two
+ * templates for one query.
+ *
+ * Prototype-safe via {@link ownLookup}, so `__proto__` cannot name a relation.
+ */
+export declare function resolveRelation<R>(relations: Record<string, R>, key: string): {
+    name: string;
+    def: R;
+} | undefined;
+/**
+ * {@link resolveRelation} when only the definition is wanted: a drop-in for the
+ * `ownLookup(meta.relations, key)` it replaces, with the same signature and the
+ * same `undefined` on a miss.
+ */
+export declare function resolveRelationDef<R>(relations: Record<string, R>, key: string): R | undefined;
 /**
  * THE canonical order for a caller-supplied set of columns: the table's own
  * `allColumns` order, which is the order `omit` and the default projection
@@ -356,6 +397,19 @@ export declare function isTemporalInfinity(value: unknown): boolean;
  * astronomical year (`0044 BC` → -43) the way the driver's own parser does.
  */
 export declare function createUtcDateParser(fallback: (text: string) => unknown): (text: string) => unknown;
+/**
+ * The `date` (OID 1082) parser WITHOUT the fast scan in front of it: the regex
+ * implementation described by {@link createUtcDateParser}, and the reference
+ * side of the differential test.
+ *
+ * Exported so "what the fast path must agree with" is the running code rather
+ * than a transcription of it in a test file. Two hand-synced copies of a
+ * parser is the drift class this repo has been bitten by before; there is one
+ * copy, and the fast path delegates to it.
+ *
+ * @internal
+ */
+export declare function createUtcDateParserGeneral(fallback: (text: string) => unknown): (text: string) => unknown;
 /**
  * Build the driver parser for Postgres `timestamp` (OID 1114) that reads an
  * offset-less date-time as UTC. Also lifted to the `_timestamp` array OID
@@ -376,6 +430,34 @@ export declare function createUtcDateParser(fallback: (text: string) => unknown)
  * `Date`-string parsing did too.
  */
 export declare function createUtcTimestampParser(fallback: (text: string) => unknown): (text: string) => unknown;
+/**
+ * The `timestamp` (OID 1114) parser WITHOUT the fast scan in front of it: the
+ * regex implementation described by {@link createUtcTimestampParser}, and the
+ * reference side of the differential test. Same reasoning as
+ * {@link createUtcDateParserGeneral}.
+ *
+ * @internal
+ */
+export declare function createUtcTimestampParserGeneral(fallback: (text: string) => unknown): (text: string) => unknown;
+/**
+ * Build the driver parser for Postgres `timestamptz` (OID 1184): the ISO wire
+ * shape decoded by {@link scanIsoTemporal}, everything else handed straight to
+ * `fallback`.
+ *
+ * UNLIKE the `date` and `timestamp` parsers beside it, this one changes NO
+ * READING. A `timestamptz` arrives with an explicit offset, so its instant is
+ * unambiguous and both this and `postgres-date` produce the same `Date`; the
+ * only difference is how long it takes. That is also why it is not governed by
+ * a semantic decision the way `utcTimestamps` governs the zone-less types: there
+ * is no second interpretation to choose between.
+ *
+ * `fallback` must be captured with `pg.types.getTypeParser(1184, 'text')`
+ * BEFORE registration, for the same reason as the parsers above: reading it
+ * afterwards hands back this function and recurses forever. It is what keeps
+ * `infinity` / `-infinity`, ` BC`, wide and low years, and every non-ISO
+ * `DateStyle` on `postgres-date`, which already handles them.
+ */
+export declare function createFastTimestamptzParser(fallback: (text: string) => unknown): (text: string) => unknown;
 /**
  * The offset-less-timestamp-as-UTC reading, with no fallback: `text` must be a
  * plain `YYYY-MM-DD HH:MM:SS[.ffffff]`. Used where the input shape is already
@@ -395,8 +477,17 @@ export declare function parseUtcTimestampText(text: string): Date;
  * `pg.types.arrayParser` is a public member of the `pg` module (it is what the
  * driver's own `_text` / `_date` parsers are built from), so this adds no
  * dependency. NULL elements stay `null` and are never handed to `element`.
+ *
+ * The empty-string guard mirrors pg's own `parseDateArray`, which opens
+ * `if (!value) return null`. Turbine's copy did not, and answered `[]` where
+ * the driver answers `null` for the same input. No column produces it (a SQL
+ * NULL never reaches a parser, and an empty array is `{}`), so this is parity
+ * for its own sake rather than a bug report; it matters because these parsers
+ * are registered process-globally over pg's, and a shape where Turbine's
+ * answer differs from the driver's is a difference somebody eventually finds
+ * the hard way.
  */
-export declare function createPgArrayParser(element: (text: string) => unknown): (text: string) => unknown[];
+export declare function createPgArrayParser(element: (text: string) => unknown): (text: string) => unknown[] | null;
 /** 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;
 /**
@@ -458,8 +549,21 @@ export declare function isDefaultTextParser(oid: number, parser: (text: string)
  */
 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).
+ * Register Turbine's temporal text parsers on the pg module. SIX OIDs, doing
+ * two different jobs:
+ *
+ *   1114 / 1082 / 1115 / 1182   the UTC READING of the zone-less types,
+ *                               `timestamp`, `date` and their array forms.
+ *                               This changes what a column means and is what
+ *                               `utcTimestamps` is named for.
+ *   1184 / 1185                 the fast decode path for `timestamptz` and
+ *                               `timestamptz[]`. This changes NOTHING about
+ *                               what a column means: an offset-carrying value
+ *                               has one instant and this reads the same one.
+ *                               It is here for speed, `timestamptz` being ~88%
+ *                               of the client-side decode cost of a wide row
+ *                               drain, and it DECLINES rather than overwrites
+ *                               (see the comment at the call site).
  *
  * ONE place, because `pg.types.setTypeParser` is process-global and the pairing
  * matters: registering a scalar without its array form, or a `date` without the