@ultimat3/entity 27.6.0 → 27.6.1

package/CLAUDE.md

@@ -48,7 +48,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   list or nothing, and a NULL in it emits `(col in (…) or col is null)`; a column the row never NAMED
   is NULL for `eq`/`neq`/`in`.
 - **The Postgres driver is proved against a real Postgres** (`pg-driver.live.test.ts`, skipped without
-  `TEST_DATABASE_URL`). A new operator, column kind or write path is not done until it round-trips.
+  `TEST_DATABASE_URL`). A new operator, kind or write path is not done until it round-trips.
 - **A repository call rejects, never throws synchronously** (`tableFor`'s writes are `async`).
 - **`defaultDriver()`** is the process default; `Driver.reset?()` is optional (memory only), resets
   repositories in place. Test seam only.
@@ -102,7 +102,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `seekFrom(entity, plan)`; **`assertSeekable` runs in `planFor`**, before a statement exists. A
   `timestamptz` sort key is refused when its `<column>$US` alias would pass 63 bytes. A cursor is bound
   to `planScope(plan)` (entity, filters, sort); a bad one is `X_CURSOR_INVALID`, never "from the top".
-- **A NULLABLE sort key orders** `asc nulls last` / `desc nulls first` (written down); the cursor tags
+- **A NULLABLE sort key orders** `asc nulls last` / `desc nulls first`; the cursor tags
   `~` for NULL and `!` for present; the seek reaches NULLs; a nullable key has no row comparison. Only a
   nullable PRIMARY-KEY column is refused. `pg-null-order.live.test.ts`.
 - **A `timestamp` cursor carries MICROSECONDS**: `seekPrecision` projects `(col at time zone
@@ -145,8 +145,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   NAME and the TABLE are different things** — cache tags and policies key on the name; index names are
   the table's.
 - **Invariants run twice and only ONE side is rendered here**: app-side `assertInvariants`, and the
-  CHECK/UNIQUE DDL is `@ultimat3/db`'s `invariant-ddl.ts` reading `$describe()` (`$migration()` and the
-  local renderers are deleted). An untranslatable predicate is `kind: 'assert'`, `sql: null`.
+  CHECK/UNIQUE DDL is `@ultimat3/db`'s `invariant-ddl.ts` reading `$describe()`. An untranslatable predicate is `kind: 'assert'`, `sql: null`.
   **`InvariantDescription.columns` is projected** (`describe-invariant.test.ts`).
 - **The two halves must AGREE, term by term** (`expr.ts`): `matches(/…/i)` is `~*`, other flags are
   refused (`matchOperator`); `minLength` counts code points; `trimmed()` strips U+0020 only (`btrim`);
@@ -175,8 +174,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `scale: null` means a two-column amount (`decodeRow` branches on `$meta.kind === 'money'`).
 - **Timestamps are `timestamptz`.** A naive timestamp stays inexpressible.
 - **A `jsonb` value is bound `::text::jsonb`** (load-bearing); an array is written as a quoted `{…}`
-  literal. **Wide column types are normalised in `$parse`** to one row type per driver (`bigint()` and
-  `decimal()` are strings).
+  literal, read by its DECLARATION (`pg-array-decode.ts`); `column-matrix-fixture.ts` is every kind
+  on both drivers. **Wide types are normalised in `$parse`** (`bigint()`, `decimal()`: strings).
 - **Every framework member on an entity is `$`-prefixed.** Row types are derived, never re-declared.
   **A branded id survives to the signature** (`IdOf<Row>`). `type-pins.ts` enforces all of it.
 - **`$parse` tells absence from `null`** (`raw === undefined ? defaultValue(...) : raw`).

package/README.md

@@ -240,7 +240,7 @@ for a table it was going to create; these are the shapes a table already has, `A
 | `date()` | `date` | `@ultimat3/time`'s `PlainDate` — a calendar date, no time, no zone. `effective_on` is the date a rate applies, and as a `timestamptz` it is a different date on either side of midnight for half the planet |
 | `bigint()` | `bigint` | a decimal `string`. A JS `bigint` is what `JSON.stringify` throws on and a `number` loses digits past 2^53 — which is exactly where a legacy `int8` key lives. Both driver spellings (a string from Bun's `sql`, a `bigint` from PGlite) arrive as one. Bounded at `int8` (−2^63 … 2^63−1): one past either end is refused where Postgres answers `22003` |
 | `bytes()` | `bytea` | a plain `Uint8Array`, normalised: Bun's `sql` returns a `Buffer` and PGlite a `Uint8Array`, and the two do not serialise alike |
-| `arrayOf(column)` | `<element>[]` | `readonly T[]`, each member parsed by the element column it was given. Money and nested arrays are refused — an element is one scalar column |
+| `arrayOf(column)` | `<element>[]` | `readonly T[]`, each member parsed by the element column it was given. Money and nested arrays are refused — an element is one scalar column. Read by the declaration, not by the driver: `Bun.SQL` hands `uuid[]` back as its text literal (`'{…}'`) and PGlite as an `Array`, and both decode to the same row |
 
 ## Adopting an existing table
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "27.6.0",
+  "version": "27.6.1",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -33,9 +33,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.6.0",
-    "@ultimat3/db": "27.6.0",
-    "@ultimat3/schema": "27.6.0",
-    "@ultimat3/time": "27.6.0"
+    "@ultimat3/core": "27.6.1",
+    "@ultimat3/db": "27.6.1",
+    "@ultimat3/schema": "27.6.1",
+    "@ultimat3/time": "27.6.1"
   }
 }

package/src/index.ts

@@ -88,10 +88,12 @@ export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
 export { persistedRecordTypes } from './persisted-types';
-export type { PostgresDriverOptions } from './pg-driver';
-export { postgresDriver, postgresRepo } from './pg-driver';
 // For a change feed holding a table name and raw columns: `entityForTable` + `decodeRow` is the row
 // the app declared, money and all. Exported for `@ultimat3/realtime` (plan 101, 06 i).
+export type { PgArray } from './pg-array-literal';
+export { parsePgArray } from './pg-array-literal';
+export type { PostgresDriverOptions } from './pg-driver';
+export { postgresDriver, postgresRepo } from './pg-driver';
 export { decodeRow } from './pg-row';
 export { postgresTransactor } from './pg-transactor';
 // The two page bounds, beside `N_PLUS_ONE_THRESHOLD` and for the same reason: an app validating

package/src/pg-array-decode.ts

@@ -0,0 +1,82 @@
+// Single responsibility: an `arrayOf()` cell as the driver handed it back -> the JS array its
+// element column can parse. A driver decides PER TYPE OID and PER PROTOCOL what an array cell is,
+// and the repository may not depend on that table:
+//
+//   * `Bun.SQL` parses the array types it knows and hands every other one back as its TEXT
+//     literal — `uuid[]` is `'{01a1…,01a2…}'` (measured, Bun 1.4.2 against Postgres 17 and 18),
+//     which `arrayOf(uuid())` refused as "expected an array, got a string" on every read while
+//     PGlite, which `x dev` and every non-live suite run on, parsed it;
+//   * `Bun.SQL` hands `int4[]` back as an `Int32Array` whenever the statement carries a parameter
+//     (the extended protocol's binary result) and as an `Array` when it carries none.
+//
+// Neither is decided by a type-parser registration: `Bun.SQL` has none, and a table keyed by oid
+// would miss the next type it does not know — a domain or an extension type has a per-database
+// oid. The DECLARED column is the only thing that knows this cell is an array, so the literal is
+// read here, keyed by the declaration and by nothing the driver says.
+
+import { instantMicros } from './instant';
+import { parsePgArray } from './pg-array-literal';
+import type { ColumnKind, ColumnMeta } from './types';
+
+const MICROS_PER_MILLI = 1000n;
+
+/** Floor, so a pre-1970 instant with a sub-millisecond part lands on the millisecond below it. */
+const millisOf = (micros: bigint): number => {
+  const remainder = ((micros % MICROS_PER_MILLI) + MICROS_PER_MILLI) % MICROS_PER_MILLI;
+  return Number((micros - remainder) / MICROS_PER_MILLI);
+};
+
+const WHOLE = /^-?\d+$/;
+
+/**
+ * One element's TEXT -> the value a driver that parsed the array would have handed over, which is
+ * what each column's `$parse` was written against: a `number` for `integer`, a `boolean` for
+ * `boolean`, a `Date` for `timestamptz`, and the text itself for every kind whose row value IS
+ * text (`uuid`, `text`, `numeric`, `bigint`, `date`).
+ *
+ * A text this cannot read is returned AS IT IS, never coerced: the element column refuses it with
+ * its own words, where `Number('abc')` would have stored a `NaN` nobody can find again.
+ */
+const elementOf = (kind: ColumnKind | undefined, raw: string): unknown => {
+  switch (kind) {
+    case 'integer':
+      return WHOLE.test(raw) ? Number(raw) : raw;
+    case 'boolean':
+      return raw === 't' || raw === 'true' ? true : raw === 'f' || raw === 'false' ? false : raw;
+    case 'timestamptz': {
+      // `2026-01-02 03:04:05.123456+00`: Postgres names the offset, so the text is an instant.
+      const micros = instantMicros(raw);
+      return micros === undefined || WHOLE.test(raw) ? raw : new Date(millisOf(micros));
+    }
+    default:
+      return raw;
+  }
+};
+
+/** Every integer and float typed array; a `DataView` is bytes with no elements to list. */
+const isTypedArray = (value: unknown): value is ArrayLike<unknown> =>
+  ArrayBuffer.isView(value) && !(value instanceof DataView);
+
+/** What `arrayFromDriver` answers when the cell is neither an array nor a literal of one. */
+export const NOT_AN_ARRAY = Symbol('not-an-array');
+
+/**
+ * The cell of a column DECLARED `arrayOf()`, as a plain JS array of driver-shaped elements — or
+ * `NOT_AN_ARRAY` when it is none of the three shapes a driver produces. Called for an array column
+ * only: a string in a `text()` column is a string, and nothing here ever asks whether it "looks
+ * like" a literal.
+ *
+ * A nested literal (`{{a,b},{c,d}}`) parses to nested arrays and is refused by the element column
+ * one line later — `arrayOf()` declares one dimension, so a second one is the table disagreeing
+ * with the entity, said by the column that knows its own type.
+ */
+export const arrayFromDriver = (
+  meta: ColumnMeta,
+  value: unknown,
+): readonly unknown[] | typeof NOT_AN_ARRAY => {
+  if (Array.isArray(value)) return value;
+  if (isTypedArray(value)) return Array.from(value);
+  if (typeof value !== 'string') return NOT_AN_ARRAY;
+  const kind = meta.element?.$meta.kind;
+  return parsePgArray(value, (raw) => elementOf(kind, raw)) ?? NOT_AN_ARRAY;
+};

package/src/pg-array-literal.ts

@@ -0,0 +1,106 @@
+// Single responsibility: the Postgres array TEXT literal — `{a,b}`, `{"a,b",NULL}`,
+// `{{1,2},{3,4}}` — read into a JS array. The one grammar in the framework: the repository reads a
+// literal a driver left unparsed (`pg-array-decode.ts`) and `@ultimat3/realtime` reads the one the
+// WAL carries, and two readers of one grammar are how a quoted `"NULL"` becomes a null in one of
+// them. The element decoder arrives as a parameter, so this file knows no type.
+//
+// The writer is `arrayLiteral` in `pg-row.ts`; `pg-array-literal.test.ts` holds the two to each
+// other, so what this package writes is what it can read.
+
+/** Where the scan is, so every branch below advances one cursor rather than slicing the text. */
+interface Scan {
+  readonly text: string;
+  at: number;
+}
+
+/**
+ * One array literal -> a nested JS array, or `null` when the text is not one this grammar
+ * describes. `null` is not an error: a dimension prefix (`[0:2]={…}`), a `DateStyle` this decoder
+ * does not read, or a corrupted literal all mean the same thing to the caller — keep the text it
+ * arrived as rather than deliver an array that is missing a member.
+ *
+ * `decode` is the ELEMENT decoder. It never sees a quoted element's quotes or its backslash
+ * escapes: an unquoted `NULL` is the null value and a quoted `"NULL"` is the four-character
+ * string, which is the one distinction the quoting exists to carry.
+ */
+export function parsePgArray<T>(text: string, decode: (raw: string) => T): PgArray<T> | null {
+  const scan: Scan = { text, at: 0 };
+  const parsed = readArray(scan, decode);
+  // Trailing content means the literal was not what this grammar accepted, whatever it parsed.
+  return parsed === null || scan.at !== text.length ? null : parsed;
+}
+
+/** A member is a decoded value, the null member, or — for a multidimensional array — a row of them. */
+export type PgArray<T> = (T | null | PgArray<T>)[];
+
+function readArray<T>(scan: Scan, decode: (raw: string) => T): PgArray<T> | null {
+  if (scan.text[scan.at] !== '{') return null;
+  scan.at += 1;
+  const out: PgArray<T> = [];
+  if (scan.text[scan.at] === '}') {
+    scan.at += 1;
+    return out;
+  }
+  for (;;) {
+    const member = readMember(scan, decode);
+    if (member === FAILED) return null;
+    out.push(member);
+    const next = scan.text[scan.at];
+    scan.at += 1;
+    if (next === '}') return out;
+    if (next !== ',') return null;
+  }
+}
+
+/** A sentinel, because `null` is a legal member and `undefined` would be a second spelling of it. */
+const FAILED = Symbol('pg-array-failed');
+
+function readMember<T>(
+  scan: Scan,
+  decode: (raw: string) => T,
+): T | null | PgArray<T> | typeof FAILED {
+  const head = scan.text[scan.at];
+  if (head === '{') {
+    const nested = readArray(scan, decode);
+    return nested === null ? FAILED : nested;
+  }
+  if (head === '"') {
+    const quoted = readQuoted(scan);
+    return quoted === null ? FAILED : decode(quoted);
+  }
+  const start = scan.at;
+  while (scan.at < scan.text.length) {
+    const char = scan.text[scan.at];
+    if (char === ',' || char === '}') break;
+    // A brace or a quote inside a bare element is a literal this grammar does not describe.
+    if (char === '{' || char === '"') return FAILED;
+    scan.at += 1;
+  }
+  if (scan.at === scan.text.length) return FAILED;
+  const raw = scan.text.slice(start, scan.at);
+  // Unquoted and case-insensitive is the ONLY spelling of the null member; `"NULL"` is a string.
+  return raw.toUpperCase() === 'NULL' ? null : decode(raw);
+}
+
+/** The text between one pair of quotes, with `\\` and `\"` unescaped. `null` if it never closes. */
+function readQuoted(scan: Scan): string | null {
+  scan.at += 1;
+  let out = '';
+  while (scan.at < scan.text.length) {
+    const char = scan.text[scan.at];
+    if (char === '"') {
+      scan.at += 1;
+      return out;
+    }
+    if (char === '\\') {
+      const escaped = scan.text[scan.at + 1];
+      if (escaped === undefined) return null;
+      out += escaped;
+      scan.at += 2;
+      continue;
+    }
+    out += char ?? '';
+    scan.at += 1;
+  }
+  return null;
+}

package/src/pg-row.ts

@@ -10,6 +10,7 @@ import { kindOf } from './cursor';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
 import { pgInstantMicros, seekAlias } from './instant';
+import { arrayFromDriver, NOT_AN_ARRAY } from './pg-array-decode';
 import type { SortKey } from './tenancy';
 import type { AnyColumn, MoneyValue, RowPatch } from './types';
 
@@ -168,6 +169,26 @@ const moneyOf = (
   };
 };
 
+/**
+ * What a column's `$parse` is handed. Every kind but one takes the driver's value as it is; an
+ * `arrayOf()` cell is first made the JS array its declaration says it is, because a driver hands
+ * one back three ways (`pg-array-decode.ts`) and only one of them is an `Array`.
+ *
+ * A cell that is none of the three is the table no longer matching the entity, and it is said
+ * here — `arrayOf`'s own refusal is written for a WRITE ("wrap it — [value]"), which instructs
+ * nobody about a value Postgres returned.
+ */
+const cellOf = (entityName: string, property: string, column: AnyColumn, value: unknown) => {
+  if (column.$meta.kind !== 'array') return value;
+  const members = arrayFromDriver(column.$meta, value);
+  if (members !== NOT_AN_ARRAY) return members;
+  throw invariantViolated(
+    entityName,
+    property,
+    `the database returned ${typeof value === 'string' ? `text that is not a Postgres array literal (${value.length} characters)` : `a ${typeof value}`} for an arrayOf() column — the table no longer matches the entity`,
+  );
+};
+
 /**
  * Physical row -> entity row. A column the projection left out is left out here too, so a
  * `select` narrows the object as well as the statement.
@@ -188,7 +209,10 @@ export const decodeRow = <Row>(entity: EntityCore<Row>, source: PhysicalRow): Ro
       // A sealed column's stored value is not the author's to parse: it goes up as it is, and the
       // sealing seam opens it — so a row somebody left in the clear is `X_SEAL_INVALID` there
       // rather than whatever the plaintext parser thinks of its length here.
-      row[property] = column.$meta.sealed === undefined ? column.$parse(value) : value;
+      row[property] =
+        column.$meta.sealed === undefined
+          ? column.$parse(cellOf(entity.$name, property, column, value))
+          : value;
       continue;
     }
     if (column.$meta.notNull) {