turbine-orm 0.71.0 → 0.72.0

package/dist/cjs/query/utils.js

@@ -12,6 +12,8 @@ exports.JSON_WIRE_COERCION_OIDS = exports.OPERATOR_KEYS = exports.LRUCache = exp
 exports.quoteIdent = quoteIdent;
 exports.ownLookup = ownLookup;
 exports.resolveColumnName = resolveColumnName;
+exports.resolveRelation = resolveRelation;
+exports.resolveRelationDef = resolveRelationDef;
 exports.canonicalColumnOrder = canonicalColumnOrder;
 exports.canonicalWriteEntries = canonicalWriteEntries;
 exports.markInternalCombinator = markInternalCombinator;
@@ -28,7 +30,10 @@ exports.coerceTemporalValue = coerceTemporalValue;
 exports.parseDbDate = parseDbDate;
 exports.isTemporalInfinity = isTemporalInfinity;
 exports.createUtcDateParser = createUtcDateParser;
+exports.createUtcDateParserGeneral = createUtcDateParserGeneral;
 exports.createUtcTimestampParser = createUtcTimestampParser;
+exports.createUtcTimestampParserGeneral = createUtcTimestampParserGeneral;
+exports.createFastTimestamptzParser = createFastTimestamptzParser;
 exports.parseUtcTimestampText = parseUtcTimestampText;
 exports.createPgArrayParser = createPgArrayParser;
 exports.markTurbineParser = markTurbineParser;
@@ -108,6 +113,55 @@ function resolveColumnName(meta, key) {
         return snake;
     return 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.
+ */
+function resolveRelation(relations, key) {
+    const direct = ownLookup(relations, key);
+    if (direct !== undefined)
+        return { name: key, def: direct };
+    const camel = (0, schema_js_1.snakeToCamel)(key);
+    if (camel === key)
+        return undefined;
+    const mapped = ownLookup(relations, camel);
+    return mapped === undefined ? undefined : { name: camel, def: mapped };
+}
+/**
+ * {@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.
+ */
+function resolveRelationDef(relations, key) {
+    return resolveRelation(relations, key)?.def;
+}
 // ---------------------------------------------------------------------------
 // Caller-controlled key ORDER, canonicalized
 // ---------------------------------------------------------------------------
@@ -572,6 +626,211 @@ function isTemporalInfinity(value) {
 // ---------------------------------------------------------------------------
 // Driver type parsers for the zone-less temporal OIDs
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// The fast temporal scan
+//
+// Every temporal parser below is a two-stage function: a hand-written
+// character scan that claims the ONE wire shape a busy application actually
+// produces, and behind it the general parser, which is where every other shape
+// (and every shape a future server adds) still goes.
+//
+// WHY IT EXISTS, stated as a measurement rather than an intuition. Draining
+// 50,000 rows of the benchmark `comments` fixture spends ~23.5 ms in
+// client-side type decoding, and `timestamptz` alone is 20.7 ms of it (88%).
+// The remaining types are not worth touching: `text`, `numeric`, `uuid` and
+// `bool` cost nothing at all, because pg registers no parser for them. Two
+// hard bounds were verified in node-postgres' source before any of this was
+// written, and they say what a decoder rewrite can and cannot reach: every
+// cell is materialised as a JS string by `reader.string(len)` before any
+// parser is consulted, so the `utf8Slice` half is unreachable; and the binary
+// protocol is not an escape hatch, the parser constructor throws
+// `Binary mode not supported yet`. The type-PARSING half is the whole budget,
+// and this is a claim on it.
+//
+// THE RULE, and it is the only thing that makes a fast path acceptable here:
+// **the scan must return exactly what the parser it replaces returned, or
+// return `null` and not claim the value at all.** It never guesses, never
+// "handles" a shape approximately, and never widens what it accepts to cover
+// one more case. Every refusal costs a few charCode compares and is repaid by
+// the general parser being correct.
+//
+// Two traps are baked into the refusals rather than into corrections, because
+// a throwaway version of this decoder wrote during the ceiling measurement got
+// 3 of 15 edge values wrong while believing it had delegated the hard ones:
+//
+//   1. `Date.UTC` maps years 0-99 onto 1900-1999, so `0044-03-15` decodes as
+//      1944 and `0001-01-01` as 1901. The obvious repair, build the Date then
+//      `setUTCFullYear`, is ALSO wrong: year 0 is a leap year in the proleptic
+//      Gregorian calendar and 1900 is not, so `0000-02-29` built that way
+//      lands on March 1st. The scan refuses `year < 100` and lets the general
+//      parser's `new Date(0)` + `setUTCFullYear(y, m, d)` assembly (which sets
+//      all three fields against the right year's calendar) answer it.
+//   2. An offset parse that runs to end-of-string silently EATS a trailing
+//      ` BC`: `4713-01-01 00:00:00+00 BC` decodes as AD 4713, off by 9,424
+//      years with no error. The scan requires end-of-string after the offset.
+//
+// Differential coverage: src/test/fast-temporal-decode.test.ts compares the
+// scan against the parser it replaces value for value, and
+// src/test/fast-temporal-decode.integration.test.ts does the same against a
+// live server with `DateStyle` and `TimeZone` varied, because the wire shape
+// is a server setting and a decoder tuned to one `DateStyle` is a latent
+// corruption bug.
+// ---------------------------------------------------------------------------
+// Wire shape the scan is reading. Plain module constants rather than an enum:
+// this repo's lint config rejects `const enum` (it does not survive
+// `isolatedModules`), and a plain `enum` emits a runtime object, so every
+// `Shape.Date` in the scan below would become a property load in the hottest
+// loop in the library. These are values, never serialized, never persisted.
+/** `YYYY-MM-DD` (OID 1082). */
+const SHAPE_DATE = 0;
+/** `YYYY-MM-DD[ T]HH:MM:SS[.f…]` (OID 1114), never an offset. */
+const SHAPE_TIMESTAMP = 1;
+/** `YYYY-MM-DD HH:MM:SS[.f…](Z|±HH[:MM[:SS]])` (OID 1184), offset REQUIRED. */
+const SHAPE_TIMESTAMPTZ = 2;
+const CH_HYPHEN = 45;
+const CH_COLON = 58;
+const CH_DOT = 46;
+const CH_SPACE = 32;
+const CH_T = 84;
+const CH_Z = 90;
+const CH_PLUS = 43;
+/** Same code point as {@link CH_HYPHEN}; named separately because the two read
+ * as different things (a date separator, an offset sign) at their use sites. */
+const CH_MINUS = 45;
+/**
+ * Two ASCII digits at `i` as a number, or `-1` if either character is not a
+ * digit. `charCodeAt` past the end returns `NaN`, and `NaN - 48` is `NaN`,
+ * which fails both range tests, so this needs no separate length check.
+ */
+function twoDigitsAt(text, i) {
+    const hi = text.charCodeAt(i) - 48;
+    const lo = text.charCodeAt(i + 1) - 48;
+    return hi >= 0 && hi <= 9 && lo >= 0 && lo <= 9 ? hi * 10 + lo : -1;
+}
+/**
+ * Decode `text` if it is exactly the canonical ISO wire shape for `shape`, or
+ * return `null` to say "not mine" (see the rule in the block comment above).
+ *
+ * Deliberately NOT accepted, each because the parser it replaces would answer
+ * differently:
+ *
+ *   - a year that is not exactly four digits. A 5-digit year is a real
+ *     PostgreSQL output and the general parser handles it; a fast path that
+ *     matched a variable-width year would have to re-find every later field.
+ *   - a year below 100 (trap 1 above).
+ *   - a `T` separator for `SHAPE_TIMESTAMPTZ`. `postgres-date`'s
+ *     own date-time regex requires a literal SPACE, so it returns `null` for
+ *     `2024-01-01T00:00:00+00`; a scan that accepted `T` there would invent a
+ *     Date where the driver hands back null. `timestamp` (1114) does accept it
+ *     because the general parser it replaces does.
+ *   - a missing offset for `SHAPE_TIMESTAMPTZ`. `postgres-date` reads an
+ *     offset-less value in the process's LOCAL zone, which is not what this
+ *     scan computes.
+ *   - a colon-less offset (`+0530`), an alphabetic zone (` UTC`), or anything
+ *     at all after the offset, including ` BC` (trap 2 above).
+ *   - a bare `.` with no fractional digits.
+ *
+ * Field-value overflow (`2024-13-45`, `25:70:99`) IS accepted, because
+ * `Date.UTC` rolls those over exactly as the general parser's `setUTCFullYear`
+ * / `setUTCHours` do. PostgreSQL never emits them; agreeing on them is free.
+ */
+function scanIsoTemporal(text, shape) {
+    const len = text.length;
+    if (len < 10)
+        return null;
+    if (text.charCodeAt(4) !== CH_HYPHEN || text.charCodeAt(7) !== CH_HYPHEN)
+        return null;
+    const yearHi = twoDigitsAt(text, 0);
+    const yearLo = twoDigitsAt(text, 2);
+    if (yearHi < 0 || yearLo < 0)
+        return null;
+    const year = yearHi * 100 + yearLo;
+    if (year < 100)
+        return null;
+    const month = twoDigitsAt(text, 5);
+    const day = twoDigitsAt(text, 8);
+    if (month < 0 || day < 0)
+        return null;
+    if (shape === SHAPE_DATE) {
+        return len === 10 ? new Date(Date.UTC(year, month - 1, day)) : null;
+    }
+    if (len < 19)
+        return null;
+    const sep = text.charCodeAt(10);
+    if (shape === SHAPE_TIMESTAMP ? sep !== CH_SPACE && sep !== CH_T : sep !== CH_SPACE)
+        return null;
+    if (text.charCodeAt(13) !== CH_COLON || text.charCodeAt(16) !== CH_COLON)
+        return null;
+    const hour = twoDigitsAt(text, 11);
+    const minute = twoDigitsAt(text, 14);
+    const second = twoDigitsAt(text, 17);
+    if (hour < 0 || minute < 0 || second < 0)
+        return null;
+    let i = 19;
+    let ms = 0;
+    if (text.charCodeAt(i) === CH_DOT) {
+        i++;
+        let digits = 0;
+        for (;;) {
+            const d = text.charCodeAt(i) - 48;
+            if (!(d >= 0 && d <= 9))
+                break;
+            // Only the first three digits survive: PostgreSQL emits up to six and a
+            // JS Date holds milliseconds. `postgres-date` gets the same answer by a
+            // different route (`1000 * parseFloat('.476603')`, truncated by
+            // `Date.UTC`), and the two agree on every 1-to-6-digit fraction.
+            if (digits < 3)
+                ms = ms * 10 + d;
+            digits++;
+            i++;
+        }
+        if (digits === 0)
+            return null;
+        if (digits === 1)
+            ms *= 100;
+        else if (digits === 2)
+            ms *= 10;
+    }
+    if (shape === SHAPE_TIMESTAMP) {
+        return i === len ? new Date(Date.UTC(year, month - 1, day, hour, minute, second, ms)) : null;
+    }
+    let offsetMs = 0;
+    const signCode = text.charCodeAt(i);
+    if (signCode === CH_Z) {
+        i++;
+    }
+    else if (signCode === CH_PLUS || signCode === CH_MINUS) {
+        i++;
+        const offsetHours = twoDigitsAt(text, i);
+        if (offsetHours < 0)
+            return null;
+        i += 2;
+        let offsetMinutes = 0;
+        let offsetSeconds = 0;
+        if (text.charCodeAt(i) === CH_COLON) {
+            offsetMinutes = twoDigitsAt(text, i + 1);
+            if (offsetMinutes < 0)
+                return null;
+            i += 3;
+            // A zone whose historical LMT offset was not a whole minute emits
+            // seconds too (`1850-01-01 00:00:00+00:19:32`).
+            if (text.charCodeAt(i) === CH_COLON) {
+                offsetSeconds = twoDigitsAt(text, i + 1);
+                if (offsetSeconds < 0)
+                    return null;
+                i += 3;
+            }
+        }
+        offsetMs =
+            (offsetHours * 3_600_000 + offsetMinutes * 60_000 + offsetSeconds * 1000) * (signCode === CH_MINUS ? -1 : 1);
+    }
+    else {
+        return null;
+    }
+    if (i !== len)
+        return null;
+    return new Date(Date.UTC(year, month - 1, day, hour, minute, second, ms) - offsetMs);
+}
 /**
  * A Postgres `date` wire value: `YYYY-MM-DD`, optionally with more than four
  * year digits, optionally suffixed ` BC`. Anything else (`infinity`,
@@ -605,6 +864,22 @@ const PG_DATE_TEXT_RE = /^(\d{4,})-(\d{2})-(\d{2})( BC)?$/;
  * astronomical year (`0044 BC` → -43) the way the driver's own parser does.
  */
 function createUtcDateParser(fallback) {
+    const general = createUtcDateParserGeneral(fallback);
+    return (text) => scanIsoTemporal(text, SHAPE_DATE) ?? general(text);
+}
+/**
+ * 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
+ */
+function createUtcDateParserGeneral(fallback) {
     return (text) => {
         const m = PG_DATE_TEXT_RE.exec(text);
         if (!m)
@@ -644,6 +919,18 @@ const PG_TIMESTAMP_TEXT_RE = /^(\d{4,})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2
  * `Date`-string parsing did too.
  */
 function createUtcTimestampParser(fallback) {
+    const general = createUtcTimestampParserGeneral(fallback);
+    return (text) => scanIsoTemporal(text, SHAPE_TIMESTAMP) ?? general(text);
+}
+/**
+ * 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
+ */
+function createUtcTimestampParserGeneral(fallback) {
     return (text) => {
         const m = PG_TIMESTAMP_TEXT_RE.exec(text);
         if (!m)
@@ -656,6 +943,27 @@ function createUtcTimestampParser(fallback) {
         return date;
     };
 }
+/**
+ * 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.
+ */
+function createFastTimestamptzParser(fallback) {
+    return (text) => scanIsoTemporal(text, SHAPE_TIMESTAMPTZ) ?? fallback(text);
+}
 /**
  * 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
@@ -677,10 +985,21 @@ function parseUtcTimestampText(text) {
  * `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.
  */
 function createPgArrayParser(element) {
     const arrayParser = pg_1.default.types.arrayParser;
-    return (text) => arrayParser.create(text, (entry) => (entry === null || entry === undefined ? null : element(entry))).parse();
+    return (text) => text
+        ? arrayParser.create(text, (entry) => (entry === null || entry === undefined ? null : element(entry))).parse()
+        : null;
 }
 /**
  * A canonical wire value per OID, plus the JS value pg's OWN default text
@@ -699,6 +1018,13 @@ const DEFAULT_PARSER_PROBES = {
     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)] },
+    // The `timestamptz` pair carries an explicit offset, so unlike the four
+    // above its expectation is NOT computed from local components: pg's default
+    // and Turbine's fast scan produce the same instant in every zone. These two
+    // probes are consulted by {@link registerFastTemporalParserIfDefault}, which
+    // DECLINES to install rather than warning-and-overwriting.
+    1184: { text: '2020-01-02 03:04:05+00', expected: () => new Date(Date.UTC(2020, 0, 2, 3, 4, 5)) },
+    1185: { text: '{"2020-01-02 03:04:05+00"}', expected: () => [new Date(Date.UTC(2020, 0, 2, 3, 4, 5))] },
 };
 /**
  * Marks a text parser as one TURBINE installed, so a later registration in the
@@ -708,8 +1034,15 @@ const DEFAULT_PARSER_PROBES = {
  * 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]);
+/**
+ * The OIDs the `utcTimestamps` flag governs, and so the ones it can opt out of.
+ *
+ * 1184 / 1185 are in the set because the flag gates their registration too,
+ * but they are there for a different reason from the other four: those four
+ * change a READING (local zone to UTC), while the `timestamptz` pair changes
+ * only decode SPEED. See {@link registerUtcTemporalParsers}.
+ */
+const TEMPORAL_PARSER_OIDS = new Set([1114, 1082, 1115, 1182, 1184, 1185]);
 /** Tag `parser` as Turbine's own and return it (see {@link TURBINE_PARSER}). */
 function markTurbineParser(parser) {
     parser[TURBINE_PARSER] = true;
@@ -802,11 +1135,14 @@ function warnParserOverwrite(oid, typeName) {
         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.
+    // The `utcTimestamps: false` opt-out only governs the six 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.
+    // (1184 / 1185 never reach this warning at all: they DECLINE over a
+    // non-default parser instead of overwriting it. They are named in the
+    // sentence because it describes what the flag leaves alone.)
     const remedy = TEMPORAL_PARSER_OIDS.has(oid)
-        ? ' `utcTimestamps: false` leaves the four temporal OIDs (1114, 1082, 1115, 1182) alone entirely.'
+        ? ' `utcTimestamps: false` leaves the six temporal OIDs (1114, 1082, 1115, 1182, 1184, 1185) 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 ' +
@@ -817,8 +1153,21 @@ function warnParserOverwrite(oid, typeName) {
         'in production from import order alone.');
 }
 /**
- * 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
@@ -856,6 +1205,58 @@ function registerUtcTemporalParsers() {
     // beside them returned UTC ones.
     setParser(1182, markTurbineParser(createPgArrayParser(parseDate)));
     setParser(1115, markTurbineParser(createPgArrayParser(parseTimestamp)));
+    // `timestamptz` (1184) and `timestamptz[]` (1185). SPEED ONLY: an offset-
+    // carrying value has exactly one instant, and this reads it as the same
+    // instant `postgres-date` does, so nothing here changes what a column means.
+    //
+    // Two things about it are deliberate and neither is obvious.
+    //
+    // It is gated behind `utcTimestamps` along with the other four, even though
+    // that flag is about a READING and this is not. The alternative was a second
+    // registration site outside this function, and one process-global parser
+    // table with two places that write to it is the exact shape the "ONE place"
+    // rule above exists to prevent. So the flag reads as "leave pg's temporal
+    // parser table alone", and `utcTimestamps: false` costs the optimisation as
+    // well as the UTC reading. That is a documented cost, not an oversight.
+    //
+    // And it DECLINES rather than overwrites (see
+    // {@link registerFastTemporalParserIfDefault}), which is the opposite of what
+    // the four above do. They MUST overwrite: they exist to replace a reading,
+    // and a process where half the temporal columns read local and half read UTC
+    // is broken. This one exists only to be faster, so a caller who installed
+    // their own `timestamptz` parser (to get strings, or Luxon objects, or a
+    // Temporal instant) keeps it. Overwriting them would trade their correctness
+    // for our speed, which is never the right trade, and Turbine has never
+    // touched 1184 before now, so declining is also what preserves that.
+    const parseTimestamptz = registerFastTemporalParserIfDefault(1184, createFastTimestamptzParser);
+    if (parseTimestamptz) {
+        registerFastTemporalParserIfDefault(1185, () => createPgArrayParser(parseTimestamptz));
+    }
+}
+/**
+ * Install a SPEED-ONLY parser for `oid`, but only over pg's own default (or
+ * over a parser Turbine itself installed earlier in this process).
+ *
+ * Returns the installed parser, or `undefined` when it declined, so a caller
+ * can hold a scalar and its array form to the same decision: registering the
+ * array half over a caller's customized scalar half would make the two
+ * disagree, which is worse than leaving both slow.
+ *
+ * `build` receives the parser being replaced, which becomes the fast path's
+ * fallback. That is only sound because the parser being replaced is known to
+ * be pg's default (or Turbine's own wrapper around it); the check below is
+ * what makes it so, and is not an optimisation of it.
+ */
+function registerFastTemporalParserIfDefault(oid, build) {
+    const getParser = pg_1.default.types.getTypeParser;
+    const setParser = pg_1.default.types.setTypeParser;
+    const current = getParser(oid, 'text');
+    const isTurbines = current[TURBINE_PARSER] === true;
+    if (!isTurbines && !isDefaultTextParser(oid, current))
+        return undefined;
+    const parser = markTurbineParser(build(current));
+    setParser(oid, parser);
+    return parser;
 }
 // ---------------------------------------------------------------------------
 // JSON-wire value coercion (relationLoadStrategy: 'join')

package/dist/cjs/query/where-compile.js

@@ -120,11 +120,16 @@ function walkWhere(host, where) {
             events.push({ kind: 'not', condition: value });
             continue;
         }
-        const relDef = (0, utils_js_1.ownLookup)(host.tableMeta.relations, key);
-        if (relDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
-            const filterObj = host.normalizeRelationFilter(relDef, value);
+        // Resolved rather than looked up, so a relation filter accepts the
+        // snake_case spelling of the relation exactly as `with` does. This is the
+        // ONE branch authority (build, fingerprint and param-collect all consume
+        // these events), so resolving here cannot drift between them; the emitted
+        // event carries the DECLARED name, which is what reaches the fingerprint.
+        const resolvedRel = (0, utils_js_1.resolveRelation)(host.tableMeta.relations, key);
+        if (resolvedRel && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            const filterObj = host.normalizeRelationFilter(resolvedRel.def, value);
             if (isRelationFilterObj(filterObj)) {
-                events.push({ kind: 'relation', key, relDef, filterObj });
+                events.push({ kind: 'relation', key: resolvedRel.name, relDef: resolvedRel.def, filterObj });
                 continue;
             }
         }

package/dist/cjs/query/where.js

@@ -812,8 +812,8 @@ function buildScopedWhere(qi, scope, where, params, depth = 0) {
  */
 function buildScopedScalarClause(qi, scope, field, value, params, clauses) {
     const meta = scope.meta;
-    const col = (0, utils_js_1.ownLookup)(meta.columnMap, field) ?? (0, schema_js_1.camelToSnake)(field);
-    if (!meta.allColumns.includes(col))
+    const col = (0, utils_js_1.resolveColumnName)(meta, field);
+    if (col === undefined)
         throw scope.unknownColumn(field);
     const qCol = `${scope.qualifier}${qi.q(col)}`;
     if (value === null) {
@@ -891,7 +891,11 @@ function collectScopedScalarParams(qi, scope, field, value, params) {
     if (value === null)
         return;
     const meta = scope.meta;
-    const col = (0, utils_js_1.ownLookup)(meta.columnMap, field) ?? (0, schema_js_1.camelToSnake)(field);
+    // Unvalidated on purpose: this is the cache-HIT mirror, and a key that does
+    // not resolve could never have produced the entry being served. It still
+    // goes through the one authority, so the column it binds against cannot
+    // differ from the one the build path emitted.
+    const col = (0, utils_js_1.resolveColumnName)(meta, field) ?? (0, schema_js_1.camelToSnake)(field);
     if (typeof value === 'object' && !Array.isArray(value) && (0, filters_js_1.isJsonFilter)(value)) {
         const colType = pgTypeForColumn(qi, meta, col);
         if (isJsonColumnType(qi, colType)) {
@@ -1231,8 +1235,8 @@ function resolveColumnRef(_qi, ref, ctx, mode) {
             `Case-insensitive column-to-column comparison is not supported: use client.sql\`...\` ` +
             `for lower(a) = lower(b).`);
     }
-    const col = (0, utils_js_1.ownLookup)(ctx.meta.columnMap, ref.col) ?? (0, schema_js_1.camelToSnake)(ref.col);
-    if (!ctx.meta.allColumns.includes(col)) {
+    const col = (0, utils_js_1.resolveColumnName)(ctx.meta, ref.col);
+    if (col === undefined) {
         throw new errors_js_1.ValidationError(`[turbine] Unknown field "${ref.col}" referenced by { col } in where on table "${ctx.table}". ` +
             `Known fields: ${Object.keys(ctx.meta.columnMap).join(', ') || '(none)'}.`);
     }

package/dist/client.d.ts

@@ -800,24 +800,6 @@ export declare class TurbineClient {
      * (`ALTER ROLE ... SET plan_cache_mode = ...`).
      */
     private static withPlanCacheMode;
-    /**
-     * `connectionString` with `setting` appended to its existing `options` query
-     * parameter, or `null` when it carries no `options` (in which case the caller
-     * should use the `options` pool field, which is not overridden).
-     *
-     * Only the query string is rewritten, never the userinfo or host, so a
-     * percent-encoded password cannot be mangled by a round trip through `URL`.
-     * The split is on the first `?`, which is also where pg's own parser puts the
-     * query-string boundary: a connection string with an unencoded `?` inside the
-     * password is not parseable by pg either, so there is no shape this handles
-     * differently from the driver.
-     *
-     * A twin of this lives in `src/connection-url.ts`, which `turbine doctor`
-     * uses for `statement_timeout`. Unifying them is the obvious refactor and it
-     * is deliberately NOT done; the reason (a c8 merge artifact that costs almost
-     * all of the coverage gate's headroom) is written up over there.
-     */
-    private static mergeConnectionStringOptions;
     /**
      * Refuse a `utcTimestamps` value that contradicts the one an earlier client
      * in this process settled the zone-less temporal read parsers (OIDs 1114,

package/dist/client.js

@@ -22,6 +22,7 @@
  * ```
  */
 import pg from 'pg';
+import { mergeConnectionStringOptions } from './connection-url.js';
 import { postgresDialect } from './dialect.js';
 import { ConnectionError, errorMessageModesDiverged, registerClientErrorMessageMode, runWithErrorMessageMode, setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 import { ObserveEngine } from './observe.js';
@@ -1138,7 +1139,7 @@ export class TurbineClient {
         // cannot be a bind parameter.
         const setting = `-c plan_cache_mode=${mode}`;
         const merged = poolConfig.connectionString
-            ? TurbineClient.mergeConnectionStringOptions(poolConfig.connectionString, setting)
+            ? mergeConnectionStringOptions(poolConfig.connectionString, setting)
             : null;
         if (merged)
             return { ...poolConfig, connectionString: merged };
@@ -1148,34 +1149,6 @@ export class TurbineClient {
         const existing = poolConfig.options || (typeof process !== 'undefined' ? process.env?.PGOPTIONS : undefined);
         return { ...poolConfig, options: existing ? `${existing} ${setting}` : setting };
     }
-    /**
-     * `connectionString` with `setting` appended to its existing `options` query
-     * parameter, or `null` when it carries no `options` (in which case the caller
-     * should use the `options` pool field, which is not overridden).
-     *
-     * Only the query string is rewritten, never the userinfo or host, so a
-     * percent-encoded password cannot be mangled by a round trip through `URL`.
-     * The split is on the first `?`, which is also where pg's own parser puts the
-     * query-string boundary: a connection string with an unencoded `?` inside the
-     * password is not parseable by pg either, so there is no shape this handles
-     * differently from the driver.
-     *
-     * A twin of this lives in `src/connection-url.ts`, which `turbine doctor`
-     * uses for `statement_timeout`. Unifying them is the obvious refactor and it
-     * is deliberately NOT done; the reason (a c8 merge artifact that costs almost
-     * all of the coverage gate's headroom) is written up over there.
-     */
-    static mergeConnectionStringOptions(connectionString, setting) {
-        const q = connectionString.indexOf('?');
-        if (q === -1)
-            return null;
-        const params = new URLSearchParams(connectionString.slice(q + 1));
-        const existing = params.get('options');
-        if (existing === null)
-            return null;
-        params.set('options', `${existing} ${setting}`);
-        return connectionString.slice(0, q + 1) + params.toString();
-    }
     /**
      * Refuse a `utcTimestamps` value that contradicts the one an earlier client
      * in this process settled the zone-less temporal read parsers (OIDs 1114,