@ultimat3/entity 30.8.0 → 30.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "30.8.0",
+  "version": "30.9.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "keywords": [
     "ultimate",
@@ -43,9 +43,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.8.0",
-    "@ultimat3/db": "30.8.0",
-    "@ultimat3/schema": "30.8.0",
-    "@ultimat3/time": "30.8.0"
+    "@ultimat3/core": "30.9.0",
+    "@ultimat3/db": "30.9.0",
+    "@ultimat3/schema": "30.9.0",
+    "@ultimat3/time": "30.9.0"
   }
 }

package/src/entity-parse.ts

@@ -6,6 +6,7 @@ import { describeValue } from '@ultimat3/schema';
 import { entityNow } from './clock';
 import { newId } from './columns';
 import { invariantViolated } from './errors';
+import { holdsJsonNull } from './json-null';
 import { sealedMissing } from './sealed-errors';
 import type { AnyColumn, ColumnMeta } from './types';
 
@@ -41,7 +42,7 @@ export const rowParsers = <Row, Wire>(
       // spread of an omitted optional key produces and is the shape every existing caller has.
       const raw = input[property];
       const given = raw === undefined ? defaultValue(column.$meta) : raw;
-      if (given === undefined || given === null) {
+      if (given === undefined || (given === null && !holdsJsonNull(column.$meta))) {
         if (column.$meta.notNull) {
           // A required sealed column ABSENT from a row is nearly always a spread of a repository
           // row, which does not enumerate it — so the refusal names that, and the rewrite.
@@ -72,7 +73,7 @@ export const rowParsers = <Row, Wire>(
     for (const [property, column] of wireEntries) {
       const raw = input[property];
       const given = raw === undefined ? defaultValue(column.$meta) : raw;
-      if (given === undefined || given === null) {
+      if (given === undefined || (given === null && !holdsJsonNull(column.$meta))) {
         if (column.$meta.notNull) {
           throw invariantViolated(name, property, 'is required and has no default');
         }

package/src/entity-patch.ts

@@ -3,6 +3,7 @@
 // would rewrite every column it did not name.
 
 import { invariantViolated } from './errors';
+import { holdsJsonNull } from './json-null';
 import { copyRow } from './sealed';
 import type { AnyColumn } from './types';
 
@@ -24,7 +25,8 @@ export const parseEntityPatch = <Patch>(
     const column = Object.hasOwn(columns, property) ? columns[property] : undefined;
     const value: unknown = descriptor.get === undefined ? descriptor.value : descriptor.get();
     if (column === undefined || value === undefined) continue;
-    if (value === null) {
+    // A NOT NULL `jsonb` column's `null` is the JSON value, judged by its schema below.
+    if (value === null && !holdsJsonNull(column.$meta)) {
       if (column.$meta.notNull) {
         throw invariantViolated(name, property, 'is required and has no default');
       }

package/src/json-null.ts

@@ -0,0 +1,13 @@
+// Single responsibility: when a `null` handed to a column is the JSON VALUE `null` rather than SQL
+// NULL. One rule, read by the parsers, the Postgres binder and decoder, and the memory matcher —
+// a copy in any one of them is a row the two drivers spell differently.
+
+import type { ColumnMeta } from './types';
+
+/**
+ * A NOT NULL `jsonb` column: the table holds no SQL NULL, so a `null` reaching it can only be the
+ * JSON literal, judged by the column's schema like any other JSON value and stored as
+ * `'null'::jsonb`. A NULLABLE `jsonb` column keeps `null` as SQL NULL — the clear every other
+ * nullable column means by it, and what `is null` answers in both drivers.
+ */
+export const holdsJsonNull = (meta: ColumnMeta): boolean => meta.kind === 'jsonb' && meta.notNull;

package/src/memory-match.ts

@@ -5,6 +5,7 @@
 // deciding by `typeof` is answering a different question.
 
 import { keyOf } from './batch-read';
+import { columnFor } from './column';
 import { arrayContains, arrayOverlaps, jsonContains, jsonHasKey } from './containment';
 import { kindOf, valueAt } from './cursor';
 import type { EntityCore } from './entity';
@@ -12,6 +13,7 @@ import { EntityError } from './errors';
 import { searchInMemory } from './feature-errors';
 import { instantMicros } from './instant';
 import { isNullish as isNull } from './is-null';
+import { holdsJsonNull } from './json-null';
 import { likeMatches } from './like';
 import { DECIMAL_TEXT, numericOrder } from './numeric-compare';
 import { operatorUnknown } from './operator';
@@ -111,6 +113,10 @@ export const matchesPredicate = <Row>(
   // predicate and a money sort key both name.
   const kind = kindOf(entity, predicate.column);
   const actual = valueAt(row, predicate.column);
+  // The row side of every NULL test. A NOT NULL `jsonb` column holding `null` holds the JSON
+  // literal (`json-null.ts`), which Postgres' `is null` never matches and its `@>` compares.
+  const held = columnFor(entity.$columns, predicate.column);
+  const rowIsNull = isNull(actual) && !(held !== undefined && holdsJsonNull(held.$meta));
   /**
    * `col = <value>`, with SQL's three-valued logic on both sides: a NULL is never EQUAL to
    * anything, the other NULL included, so `equals` answers false the moment either side is one
@@ -124,34 +130,32 @@ export const matchesPredicate = <Row>(
    * `valueAt(row, 'price.minor')` has nothing to read.
    */
   const equals = (candidate: unknown): boolean =>
-    !isNull(actual) && !isNull(candidate) && sameValueOfKind(kind, actual, candidate);
+    !rowIsNull && !isNull(candidate) && 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 unknown = (): boolean => rowIsNull || isNull(predicate.value);
   const order = (): number => compareByKind(kind, actual, predicate.value);
   switch (predicate.op) {
     // `predicateSql` compiles a null operand to `"col" is null` rather than binding it, so this
     // is the same predicate, not a widening of it.
     case 'eq':
-      return predicate.value === null ? isNull(actual) : equals(predicate.value);
+      return predicate.value === null ? rowIsNull : equals(predicate.value);
     // `is distinct from` reads a NULL as a value on BOTH sides: TRUE where one side is null and
     // the other is not, FALSE where both are. A bound `undefined` is a NULL parameter there, so
     // the operand side reads through `isNull` and the two spellings mean one thing.
     case 'neq':
-      return isNull(predicate.value) ? !isNull(actual) : !equals(predicate.value);
+      return isNull(predicate.value) ? !rowIsNull : !equals(predicate.value);
     // `in` reads a LIST or nothing: an operand that is not an array matches no row, which is what
     // `predicateSql` now compiles it to and what `@ultimat3/query` answers for the same operand.
     // A NULL inside the list is asked as `is null` beside the list there, for the same reason.
     case 'in':
       return (
         Array.isArray(predicate.value) &&
-        predicate.value.some((candidate) =>
-          isNull(candidate) ? isNull(actual) : equals(candidate),
-        )
+        predicate.value.some((candidate) => (isNull(candidate) ? rowIsNull : equals(candidate)))
       );
     case 'gt':
       return !unknown() && order() > 0;
@@ -166,22 +170,22 @@ export const matchesPredicate = <Row>(
     case 'like':
       return !unknown() && likeMatches(entity.$name, String(predicate.value), String(actual));
     case 'is-null':
-      return isNull(actual);
+      return rowIsNull;
     case 'is-not-null':
-      return !isNull(actual);
+      return !rowIsNull;
     // The containment half, decided by the column's DECLARED kind exactly as everything above it
     // is: `@>` on a `jsonb` is recursive structural containment and `@>` on an array is plain
     // element containment, and those are two different operators that happen to share a symbol.
     // A NULL column value matches nothing, which is what the SQL answers too.
     case 'contains':
-      return !isNull(actual) && containsBy(kind, actual, predicate.value);
+      return !rowIsNull && containsBy(kind, actual, predicate.value);
     case 'contained-by':
-      return !isNull(actual) && containsBy(kind, predicate.value, actual);
+      return !rowIsNull && containsBy(kind, predicate.value, actual);
     // `&&` is arrays only. A `jsonb` column reaching it is refused rather than guessed at: there
     // is no `jsonb && jsonb` in Postgres, so any answer here would be one no statement can make.
     case 'overlaps':
       return (
-        !isNull(actual) &&
+        !rowIsNull &&
         arrayOverlaps(
           asArray(entity, predicate, actual),
           asArray(entity, predicate, predicate.value),

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 { holdsJsonNull } from './json-null';
 import { arrayFromDriver, NOT_AN_ARRAY } from './pg-array-decode';
 import type { SortKey } from './tenancy';
 import type { AnyColumn, MoneyValue, RowPatch } from './types';
@@ -142,6 +143,9 @@ export const arrayLiteral = (value: unknown): string =>
   `{${(Array.isArray(value) ? value : [value]).map(arrayElement).join(',')}}`;
 
 const bindable = (column: AnyColumn, value: unknown): unknown => {
+  // A NOT NULL `jsonb` column's `null` is the JSON literal, `'null'` cast back by the cell — bound
+  // as SQL NULL it was refused `23502` by the very column whose schema had just accepted it.
+  if (value === null && holdsJsonNull(column.$meta)) return JSON.stringify(null);
   if (value === null || value === undefined) return null;
   // A plain object is not a bindable parameter (`X_SQL_UNSAFE`), so a `jsonb` value crosses as its
   // TEXT and `pg-sql.ts`'s cell casts it back — see `cellCast` for why the cast is `::text::jsonb`.
@@ -232,7 +236,9 @@ export const decodeRow = <Row>(entity: EntityCore<Row>, source: PhysicalRow): Ro
       column.$meta.kind === 'money' && currency !== undefined
         ? moneyOf(source, head, currency, scale)
         : source[head];
-    if (value !== null && value !== undefined) {
+    // `holdsJsonNull`: what the driver hands back for a stored `'null'::jsonb` is a JS `null`, and
+    // in a NOT NULL `jsonb` column that is the JSON value — its schema judges it, as it judged it in.
+    if (value !== undefined && (value !== null || holdsJsonNull(column.$meta))) {
       // 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.

package/src/view.ts

@@ -11,6 +11,7 @@ import {
 } from '@ultimat3/schema';
 import { viewKeyUnknown } from './entity-error';
 import { invariantViolated } from './errors';
+import { holdsJsonNull } from './json-null';
 import type { AnyColumn, ColumnMap } from './types';
 import { columnIssue, missingIssue } from './view-issue';
 
@@ -151,7 +152,7 @@ export const viewFor = <Row, K extends keyof Row & string>(
     const issues: StandardIssue[] = [];
     for (const [key, column] of picked) {
       const given = input[key];
-      if (given === undefined || given === null) {
+      if (given === undefined || (given === null && !holdsJsonNull(column.$meta))) {
         // No default is filled in: a view projects a row that already exists, so an absent
         // required column is missing data, never a value the projection may invent.
         if (column.$meta.notNull) issues.push(missingIssue(key));