@ultimat3/entity 7.0.0 → 8.0.0

package/CLAUDE.md

@@ -753,6 +753,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `types.ts` | `Column`, `RowOf`, `Insertable`, `IdOf` — the type derivation. `COLUMN_KINDS` is the runtime array `ColumnKind` DERIVES from (the shape core's `PRIMITIVE_KINDS` uses), so a package answering "one case per kind" reads a real list rather than spelling its own |
 | `column.ts` / `columns.ts` | the chain + property-key binding; the blessed builders; `columnName`/`moneyColumns`, the ONE physical-name resolver; `narrowMoney`, the one write-side narrowing both drivers run |
 | `columns-data.ts` | the wide vocabulary an existing schema needs: `json`, `decimal`, `date`, `bigint`, `bytes`, `arrayOf` |
+| `array-element.ts` | which element kinds `arrayOf()` refuses, and the one-line edit that repairs each |
 | `expr.ts` / `invariants.ts` | the `invariants: (c) => …` rule language; bind + `toSql()` DDL |
 | `entity.ts` / `describe.ts` | `entity()`, `$row`; the `EntityDescription` projection |
 | `view.ts` | `$view(keys)` — the row projection an action names as its `output` |

package/package.json

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

package/src/array-element.ts

@@ -0,0 +1,67 @@
+// Which element kinds `arrayOf()` refuses, and the one-line edit that repairs each. Split from
+// `columns-data.ts`, which parses columns: a refusal POLICY and four repair strings are a second
+// responsibility, and the file was 250 lines with both in it.
+
+import { EntityError } from './errors';
+
+/** The element kinds `arrayElement` (`pg-row.ts`) has no literal for, and why each one is refused. */
+const ARRAY_ELEMENT_REFUSED = ['money', 'array', 'jsonb', 'bytea'] as const;
+
+export type RefusedElement = (typeof ARRAY_ELEMENT_REFUSED)[number];
+
+export const isRefusedElement = (kind: string): kind is RefusedElement =>
+  (ARRAY_ELEMENT_REFUSED as readonly string[]).includes(kind);
+
+/**
+ * One column per refused element kind: the shape that holds the same list and can be written.
+ * `Object.freeze<Record<K, V>>` and never `Readonly<Record<K, V>> = Object.freeze({…})`, which
+ * infers the key set from the literal and would accept a fifth key in silence.
+ *
+ * Each value is a MECHANICAL edit with nothing for the reader to supply — the placeholder form
+ * `json(t.array(<element schema>))` was the defect: a `fix:` a reader has to complete is one they
+ * can complete wrongly, and `<element schema>` pasted verbatim is a syntax error. The two that
+ * need a second table name it (`amounts`, `blobs`) rather than saying "a child table", so every
+ * line is text that runs.
+ */
+const ARRAY_ELEMENT_FIXES = Object.freeze<Record<RefusedElement, string>>({
+  money:
+    'move the list to its own entity and relate it — ' +
+    "entity('amounts', { columns: { amount: money() } }) — then drop this column: an array column " +
+    'is ONE column and money() is three (minor, currency, scale)',
+  array:
+    'rewrite arrayOf(arrayOf(x)) as arrayOf(x) if the nesting carries no meaning, or move the ' +
+    "inner list to its own entity and relate it — entity('items', { columns: { value: text() } })",
+  jsonb:
+    'rewrite arrayOf(json(S)) as json(t.array(S)) with S unchanged — one jsonb column holds the ' +
+    'whole list and t.array still validates every member',
+  bytea:
+    'move the list to its own entity and relate it — ' +
+    "entity('blobs', { columns: { data: bytes() } }) — then drop this column: one row per blob, " +
+    'and bytea has no array literal that survives the driver',
+});
+
+/**
+ * An element the Postgres array literal cannot carry, refused where the schema is still being
+ * written. Two different reasons, one code — the situation is a single one, "this list needs a
+ * different column" — so only the cause and the fix branch.
+ *
+ * `money` and `array` are not ONE column: three physical columns for an amount, and a nested array
+ * has no unambiguous literal form. `jsonb` and `bytea` are one column each and were the silent
+ * half: `arrayElement` renders any object as `""`, so two objects bound as `{"",""}` and one blob
+ * as `{""}` (measured), while `memoryRepo` kept the value — a loss no test in this tree could see
+ * and only a table could show.
+ *
+ * Not `reject()`: a declaration is repaired by an EDIT, and `reject`'s
+ * `x entities describe column --json` is `X_DECLARATION_UNKNOWN` — no entity is named `column`, and
+ * there is no entity at all yet. So each fix is the edit that holds the list instead.
+ */
+export const arrayElementRefused = (kind: RefusedElement): EntityError => {
+  const singleColumn = kind === 'money' || kind === 'array';
+  return new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: singleColumn
+      ? `arrayOf(${kind}) has no single column behind it — an array element is one scalar column, and ${kind === 'money' ? 'money is three (minor, currency, scale)' : 'a nested array has no unambiguous literal form'}`
+      : `arrayOf(${kind}) has no array literal form — every element would cross to Postgres as an empty string while memoryRepo kept the value, so the loss is invisible until the row is read back`,
+    fix: ARRAY_ELEMENT_FIXES[kind],
+  });
+};

package/src/columns-data.ts

@@ -10,6 +10,7 @@
 
 import { describeValue, formatIssues, type StandardSchemaV1, validate } from '@ultimat3/schema';
 import { isPlainDate, type PlainDate, plainDateUtc } from '@ultimat3/time';
+import { arrayElementRefused, isRefusedElement } from './array-element';
 import { column } from './column';
 import { invariantViolated } from './errors';
 import type { AnyColumn, Column, ColumnMeta } from './types';
@@ -27,9 +28,13 @@ const got = (value: unknown): string => `got ${describeValue(value)}`;
  * place for one — the value arrives from the DATABASE as often as from a caller, so the row type
  * would be a claim nothing ever checked.
  *
- * The object is bound as an object, never as a string: a JSON string parameter is stored as a JSON
- * *string* by Postgres (measured — `'{"a":1}'` comes back as the text, not the object), so
- * stringifying here would change the value's type in the table.
+ * The value crosses to Postgres as TEXT and is cast back — `bindValues` calls `JSON.stringify` and
+ * `cellCast` (`pg-sql.ts`) writes `::text::jsonb` — and both halves are load-bearing. The driver
+ * seam refuses a plain object as a parameter (`X_SQL_UNSAFE`), so the object cannot cross as
+ * itself; and under a bare `$1::jsonb` the server describes the parameter as `jsonb`, Bun's `sql`
+ * JSON-ENCODES the string it was handed, and `{"a":1}` lands as a JSON *string* — `jsonb_typeof`
+ * answers `string` (measured, Postgres 17.10). Pinning the parameter to `text` first is what makes
+ * the server parse the characters, so neither half may be changed without the other.
  */
 export const json = <T>(schema: StandardSchemaV1<unknown, T>): Column<T> =>
   column<T>('jsonb', (value) => {
@@ -180,17 +185,11 @@ export const bytes = (): Column<Uint8Array> =>
  * `$parse` decides every member: `arrayOf(text({ max: 40 }))` refuses a 41-character tag exactly
  * where a `text()` column would.
  *
- * Money and arrays of arrays are refused rather than approximated: money is three physical columns
- * and cannot be one array element, and a nested array has no unambiguous literal form.
+ * Four element kinds are refused rather than approximated — see `arrayElementRefused`.
  */
 export const arrayOf = <T>(element: Column<T>): Column<readonly T[]> => {
   const kind = element.$meta.kind;
-  if (kind === 'money' || kind === 'array') {
-    reject(
-      'array',
-      `arrayOf(${kind}) has no single column behind it — an array element is one scalar column`,
-    );
-  }
+  if (isRefusedElement(kind)) throw arrayElementRefused(kind);
   return column<readonly T[]>(
     'array',
     (value) => {

package/src/describe.ts

@@ -67,9 +67,13 @@ export const sqlTypeOf = (meta: ColumnMeta): string => {
   }
   if (meta.kind === 'array') {
     const element = meta.element?.$meta;
-    // `arrayOf` refuses an element that is not one scalar column, so this is total in practice;
-    // `text[]` is the answer that keeps a description renderable rather than throwing inside a
-    // projection, which is the one place an error has no caller to instruct.
+    // The element KIND is bounded by `arrayOf`, which refuses money, a nested array, `jsonb` and
+    // `bytea` at declaration — it refused only the first two until 2026-08, so this line emitted a
+    // real `jsonb[]`/`bytea[]` for a column `bindValues` wrote as `{"",""}`: a DDL type for a value
+    // that could not survive the trip. What is NOT bounded is `element` itself, which is absent on
+    // any `ColumnMeta` nobody built through `arrayOf()`; `text[]` keeps such a description
+    // renderable rather than throwing inside a projection, the one place an error has no caller to
+    // instruct.
     return `${element === undefined ? 'text' : sqlTypeOf(element)}[]`;
   }
   return meta.kind;

package/src/memory-match.ts

@@ -31,6 +31,9 @@ import type { ColumnKind } from './types';
  */
 const DECIMAL_TEXT: ReadonlySet<ColumnKind> = new Set<ColumnKind>(['bigint', 'numeric']);
 
+/** Absent and NULL are one thing to a predicate: a column the projection left out is not a value. */
+const isNull = (value: unknown): boolean => value === null || value === undefined;
+
 const sign = <T extends number | bigint | string>(left: T, right: T): number =>
   left < right ? -1 : left > right ? 1 : 0;
 
@@ -139,6 +142,13 @@ export const matchesPredicate = <Row>(
   const kind = kindOf(entity, predicate.column);
   const actual = valueAt(row, predicate.column);
   const same = (candidate: unknown): boolean => sameValueOfKind(kind, actual, candidate);
+  // `col > NULL` is UNKNOWN in SQL and UNKNOWN is not a match, so a NULL on EITHER side matches no
+  // row here either — `predicateSql` emits a bare `"col" > $1` and Postgres returns nothing. Without
+  // this the fall-through compared `String(null)` as the text `"null"`, which sorts after `"5"` and
+  // before `"z"`: `gt(seats, 5)` answered the null row in memory and never in production, and
+  // `lt(seats, null)` answered every row. The guard is HERE and not in `compareByKind`, which also
+  // orders a page — a sort puts NULLs last (`asc nulls last`) rather than dropping them.
+  const unknown = (): boolean => isNull(actual) || isNull(predicate.value);
   const order = (): number => compareByKind(kind, actual, predicate.value);
   switch (predicate.op) {
     case 'eq':
@@ -150,20 +160,20 @@ export const matchesPredicate = <Row>(
     case 'in':
       return Array.isArray(predicate.value) && predicate.value.some(same);
     case 'gt':
-      return order() > 0;
+      return !unknown() && order() > 0;
     case 'gte':
-      return order() >= 0;
+      return !unknown() && order() >= 0;
     case 'lt':
-      return order() < 0;
+      return !unknown() && order() < 0;
     case 'lte':
-      return order() <= 0;
+      return !unknown() && order() <= 0;
     // Real LIKE semantics, so `'draft%'` means "starts with" here exactly as it does in Postgres.
     // Treating the pattern as a substring would make the two drivers disagree.
     case 'like':
-      return likePattern(entity.$name, String(predicate.value)).test(String(actual));
+      return !unknown() && likePattern(entity.$name, String(predicate.value)).test(String(actual));
     case 'is-null':
-      return actual === null || actual === undefined;
+      return isNull(actual);
     case 'is-not-null':
-      return actual !== null && actual !== undefined;
+      return !isNull(actual);
   }
 };

package/src/pg-row.ts

@@ -102,6 +102,12 @@ export const bindValues = <Row>(
  * One array element, as a Postgres array literal spells it. Quoted always: an unquoted element
  * containing a comma, a brace or a backslash is a different array, and an empty string unquoted
  * is nothing at all.
+ *
+ * The `object` branch is the LAST resort and never a declared column's value: `arrayOf()` refuses
+ * `jsonb`, `bytea`, `money` and a nested array at declaration (`columns-data.ts`) precisely because
+ * this line has no literal for them and rendered every one as `""` — silently, and only against a
+ * real table, since `memoryRepo` stores the value it was handed. A `Date` is the one object shape
+ * with a literal, so it is named above.
  */
 const arrayElement = (value: unknown): string => {
   if (value === null || value === undefined) return 'NULL';