@ultimat3/entity 30.3.0 → 30.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "30.3.0",
+  "version": "30.5.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.3.0",
-    "@ultimat3/db": "30.3.0",
-    "@ultimat3/schema": "30.3.0",
-    "@ultimat3/time": "30.3.0"
+    "@ultimat3/core": "30.5.0",
+    "@ultimat3/db": "30.5.0",
+    "@ultimat3/schema": "30.5.0",
+    "@ultimat3/time": "30.5.0"
   }
 }

package/src/columns-data.ts

@@ -33,17 +33,21 @@ const got = (value: unknown): string => `got ${describeValue(value)}`;
  * 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) => {
-    const result = validate(schema, value);
-    if (result.issues === undefined) return result.value;
-    // The ISSUES, never the value: `formatIssues` renders path + message, and a column rejection
-    // reaches the caller and the log line where a value has no key left to redact.
-    return refuseColumn(
-      'json',
-      `does not match the column's schema — ${formatIssues(result.issues).join('; ')}`,
-      'correct the key the cause names, or widen the schema this column was declared with — json(t.object({ seats: t.number })) validates on the way in and on the way back',
-    );
-  });
+  column<T>(
+    'jsonb',
+    (value) => {
+      const result = validate(schema, value);
+      if (result.issues === undefined) return result.value;
+      // The ISSUES, never the value: `formatIssues` renders path + message, and a column rejection
+      // reaches the caller and the log line where a value has no key left to redact.
+      return refuseColumn(
+        'json',
+        `does not match the column's schema — ${formatIssues(result.issues).join('; ')}`,
+        'correct the key the cause names, or widen the schema this column was declared with — json(t.object({ seats: t.number })) validates on the way in and on the way back',
+      );
+    },
+    { schema },
+  );
 
 const DIGITS = /^-?\d+$/;
 

package/src/memory-repo.ts

@@ -27,7 +27,7 @@ import { compareByKind, matchesPredicate } from './memory-match';
 import { observedMemoryRepo } from './memory-observed';
 import { type MemoryTables, sameTenantJudge } from './memory-same-tenant';
 import { afterCursor } from './memory-seek';
-import { uniqueClash, uniqueIndex, uniqueViolation } from './memory-unique';
+import { StoredRows, uniqueIndex, uniqueViolation } from './memory-unique';
 import { judgeUpdate, mergedRow } from './memory-update';
 import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions } from './repo';
@@ -73,7 +73,9 @@ export const memoryRepo = <Row>(
       'declares a sealed column, and memoryRepo(entity, seed) stores seed rows unsealed — pass no seed and write them with insertAll(rows)',
     );
   }
-  const rows = new Map<string, Row>(seed.map((row) => [storeKey(row), row]));
+  // Every unique key kept as rows move, so a single write is judged by its own keys, never a scan.
+  const rows = new StoredRows<Row>(entity);
+  for (const row of seed) rows.set(storeKey(row), row);
   tables.set(entity.$name, {
     entity: entity as EntityCore,
     // By the primary key when that is what is asked, which is nearly every reference.
@@ -142,16 +144,6 @@ export const memoryRepo = <Row>(
   const narrowed = (batch: readonly RowWrite<Row>[]): readonly Row[] =>
     batch.map((row) => narrowRow<Row>(entity.$columns, row));
 
-  /**
-   * Lazy: one write asks it once, and an entity with no unique never iterates it. A batch judges
-   * against `uniqueIndex` instead, built once.
-   */
-  const storedExcept = (from: string | undefined): Iterable<Row> => ({
-    *[Symbol.iterator]() {
-      for (const [stored, other] of rows) if (stored !== from) yield other;
-    },
-  });
-
   /**
    * `from` is the key the row is stored under NOW, or `undefined` for a new row. A new row may not
    * land on a stored key, and a moved one may not land on another row's — Postgres answers both
@@ -178,7 +170,7 @@ export const memoryRepo = <Row>(
     judgeReferences(row);
     const key = storeKey(row);
     if (key !== from && rows.has(key)) throw uniqueViolation(entity, `${entity.$table}_pkey`);
-    const clash = uniquesJudged ? undefined : uniqueClash(entity, row, storedExcept(from));
+    const clash = uniquesJudged ? undefined : rows.clash(row, from);
     if (clash !== undefined) throw uniqueViolation(entity, clash);
     const moved = from !== undefined && from !== key ? rows.get(from) : undefined;
     const previous = rows.get(key);
@@ -267,9 +259,9 @@ export const memoryRepo = <Row>(
       // Narrowed FIRST, so what this loop judges is what `write` will store: `$assert` was handed
       // the caller's `bigint` minor unit here and the narrowed `number` one call later.
       const batch = narrowed(given);
-      // The stored rows' keys once, then each batch row's as it is judged: a row collides with
-      // what is stored and with the rows before it, never after — the same first refusal.
-      const taken = uniqueIndex(entity, rows.values());
+      // Layered over the stored rows' index, each batch row's keys added as it is judged: a row
+      // collides with what is stored and with the rows before it, never after.
+      const taken = uniqueIndex(entity, [], rows);
       const seen = new Set<string>();
       for (const row of batch) {
         assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);

package/src/memory-unique.ts

@@ -55,10 +55,28 @@ const keysOf = <Row>(entity: EntityCore<Row>) => {
   };
 };
 
+/** One constraint's keys, counted: a seed or a trigger's raw write may hold one key twice. */
+type Taken = Map<string, number>;
+
+const holds = (taken: readonly Taken[], i: number, key: string | undefined): number =>
+  key === undefined ? 0 : (taken[i]?.get(key) ?? 0);
+
+const move = (taken: readonly Taken[], keys: readonly (string | undefined)[], by: 1 | -1): void =>
+  keys.forEach((key, i) => {
+    const at = taken[i];
+    if (key === undefined || at === undefined) return;
+    const left = (at.get(key) ?? 0) + by;
+    if (left > 0) at.set(key, left);
+    else at.delete(key);
+  });
+
 /**
- * Every unique key a set of rows holds, one `Set` per constraint: a batch is judged against it row
+ * Every unique key a set of rows holds, one count per constraint: a batch is judged against it row
  * by row, each row bound once. A scan of every other row per row — rebound per constraint — made a
  * 1,000-row `insertAll` take tens of seconds.
+ *
+ * `under` is a second index this one is layered over: a key either holds is taken. `insertAll`
+ * judges its batch over the stored rows' index this way, so a batch never copies the table.
  */
 export interface UniqueIndex<Row> {
   /** The first constraint, in declaration order, `row` collides on — or `undefined`. */
@@ -66,21 +84,24 @@ export interface UniqueIndex<Row> {
   add(row: Row): void;
 }
 
-export function uniqueIndex<Row>(entity: EntityCore<Row>, rows: Iterable<Row>): UniqueIndex<Row> {
+export function uniqueIndex<Row>(
+  entity: EntityCore<Row>,
+  rows: Iterable<Row>,
+  under?: StoredRows<Row>,
+): UniqueIndex<Row> {
   const { unique, keys } = keysOf(entity);
-  const taken = unique.map(() => new Set<string>());
+  const taken: Taken[] = unique.map(() => new Map());
   const index: UniqueIndex<Row> = {
     clash(row) {
       if (unique.length === 0) return undefined;
       const mine = keys(row);
-      const at = mine.findIndex((key, i) => key !== undefined && taken[i]?.has(key) === true);
+      const at = mine.findIndex(
+        (key, i) => holds(taken, i, key) > 0 || (under?.holds(i, key) ?? false),
+      );
       return at === -1 ? undefined : unique[at]?.name();
     },
     add(row) {
-      if (unique.length === 0) return;
-      keys(row).forEach((key, i) => {
-        if (key !== undefined) taken[i]?.add(key);
-      });
+      if (unique.length > 0) move(taken, keys(row), 1);
     },
   };
   for (const row of rows) index.add(row);
@@ -88,13 +109,72 @@ export function uniqueIndex<Row>(entity: EntityCore<Row>, rows: Iterable<Row>):
 }
 
 /**
- * The first unique constraint `candidate` collides with among `others`, or `undefined`. Partial
- * ones are skipped: their predicate is SQL this driver cannot evaluate, and a guess would refuse
- * rows Postgres accepts — the one direction that must never happen.
+ * The memory driver's table: a `Map` from store key to row that keeps every non-partial unique's
+ * keys as rows come and go. Every way a row moves — a write, a delete, a trigger's raw write, an
+ * undo run by a rollback, a reset — is a `set`, `delete` or `clear` on this map, so the index
+ * cannot miss one. Rebuilt per write, it made N single inserts cost N² (1,100 rows: ~14 s).
+ *
+ * A row's keys are recorded as it lands and removed by that record, so removal never rebinds.
  */
-export const uniqueClash = <Row>(
-  entity: EntityCore<Row>,
-  candidate: Row,
-  others: Iterable<Row>,
-): string | undefined =>
-  uniqueConstraints(entity).length === 0 ? undefined : uniqueIndex(entity, others).clash(candidate);
+export class StoredRows<Row> extends Map<string, Row> {
+  readonly #unique;
+  readonly #keys;
+  readonly #taken: Taken[];
+  readonly #held = new Map<string, readonly (string | undefined)[]>();
+
+  constructor(entity: EntityCore<Row>) {
+    super();
+    const { unique, keys } = keysOf(entity);
+    this.#unique = unique;
+    this.#keys = keys;
+    this.#taken = unique.map(() => new Map());
+  }
+
+  override set(key: string, row: Row): this {
+    if (this.#unique.length > 0) {
+      this.#release(key);
+      const keys = this.#keys(row);
+      move(this.#taken, keys, 1);
+      this.#held.set(key, keys);
+    }
+    return super.set(key, row);
+  }
+
+  override delete(key: string): boolean {
+    this.#release(key);
+    return super.delete(key);
+  }
+
+  override clear(): void {
+    for (const taken of this.#taken) taken.clear();
+    this.#held.clear();
+    super.clear();
+  }
+
+  /** Whether constraint `i` holds `key` — for an index layered over this one. */
+  holds(i: number, key: string | undefined): boolean {
+    return holds(this.#taken, i, key) > 0;
+  }
+
+  /**
+   * The first constraint, in declaration order, `row` collides on among the stored rows — the row
+   * stored under `from` excepted: it is the one `row` replaces. Partial uniques are not in the list:
+   * their predicate is SQL this driver cannot evaluate, and a guess would refuse rows Postgres
+   * accepts — the one direction that must never happen.
+   */
+  clash(row: Row, from?: string): string | undefined {
+    if (this.#unique.length === 0) return undefined;
+    const own = from === undefined ? undefined : this.#held.get(from);
+    const at = this.#keys(row).findIndex(
+      (key, i) => holds(this.#taken, i, key) - (key !== undefined && own?.[i] === key ? 1 : 0) > 0,
+    );
+    return at === -1 ? undefined : this.#unique[at]?.name();
+  }
+
+  #release(key: string): void {
+    const keys = this.#held.get(key);
+    if (keys === undefined) return;
+    move(this.#taken, keys, -1);
+    this.#held.delete(key);
+  }
+}

package/src/memory-update.ts

@@ -9,7 +9,7 @@
 
 import { narrowRow } from './columns';
 import type { EntityCore } from './entity';
-import { uniqueClash, uniqueViolation } from './memory-unique';
+import { uniqueIndex, uniqueViolation } from './memory-unique';
 import { assertRowTenant } from './tenancy';
 
 /**
@@ -55,6 +55,8 @@ export const judgeUpdate = <Row>(
   const judged: Row[] = [];
   const judgedKeys = new Set<string>();
   const untouchedKeys = new Set(untouched.map((row) => key(row)));
+  // Built once and grown by each result: rebuilt per matched row, a sweep cost matched x stored.
+  const taken = uniqueIndex(entity, untouched);
   for (const row of matched) {
     const result = mergedRow(entity, row, patch);
     // The same four judgements `write` makes, in the same order — on the merged row rather than
@@ -70,8 +72,9 @@ export const judgeUpdate = <Row>(
     }
     // The unique constraints, against the same two sets. The rows this batch matched are not in
     // either: each of them is replaced by its own result, which is judged here instead.
-    const clash = uniqueClash(entity, result, [...untouched, ...judged]);
+    const clash = taken.clash(result);
     if (clash !== undefined) throw uniqueViolation(entity, clash);
+    taken.add(result);
     judged.push(result);
     judgedKeys.add(resultKey);
   }

package/src/types.ts

@@ -82,7 +82,7 @@ export interface ReferenceOptions {
  * on a bigint, so returning a row with a money column from an action crashed the response, and
  * `t.money` — the schema node that becomes the OpenAPI contract — rejected the framework's own row.
  */
-import type { MoneyValue } from '@ultimat3/schema';
+import type { MoneyValue, StandardSchemaV1 } from '@ultimat3/schema';
 import type { StateMachine, TransitionTable } from './state-machine';
 
 export type { MoneyValue };
@@ -181,6 +181,12 @@ export interface ColumnMeta {
    * database keeps equal to the number of rows pointing there. `counter.ts` reads it.
    */
   readonly countedIn?: () => AnyColumn;
+  /**
+   * `json(schema)`'s schema, beside the `$parse` that validates through it, so a reader that must
+   * PRODUCE a storable value (`@ultimat3/testing`'s seed values) draws from the declaration rather
+   * than guess. Not on `$describe()`: the DDL is `jsonb` whatever it holds, so no hash moves.
+   */
+  readonly schema?: StandardSchemaV1<unknown, unknown>;
 }
 
 /** What `.sealed(options)` declared, resolved. */