@ultimat3/entity 30.1.0 → 30.3.0

package/package.json

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

package/src/append-only.ts

@@ -4,6 +4,7 @@
 // alike — and before any statement exists, so memory and Postgres answer the same code.
 
 import { appendOnlyColumnRefused, appendOnlyRefused } from './append-only-errors';
+import { readOnlyRefused } from './read-only';
 import type { Repo, UpsertArgs } from './repo';
 import type { AnyColumn } from './types';
 import { readOnlyRepo } from './view-repo';
@@ -14,6 +15,8 @@ export interface AppendOnlySource {
   readonly $appendOnly: boolean;
   /** `entity({ view })`: every write refused. Optional so a hand-built source still passes. */
   readonly $viewQuery?: unknown;
+  /** `entity({ readOnly })`'s reason: every write refused. Optional, as `$viewQuery` is. */
+  readonly $readOnly?: string | null;
 }
 
 /**
@@ -62,6 +65,12 @@ export const appendOnlyRepo = <Row, R extends Repo<Row>>(entity: AppendOnlySourc
   if (entity.$viewQuery !== undefined && entity.$viewQuery !== null) {
     return readOnlyRepo<Row, R>(entity.$name, repo);
   }
+  const reason = entity.$readOnly;
+  if (typeof reason === 'string') {
+    return readOnlyRepo<Row, R>(entity.$name, repo, (operation) =>
+      readOnlyRefused(entity.$name, operation, reason),
+    );
+  }
   if (!entity.$appendOnly) return repo;
   const name = entity.$name;
   const refusing: Pick<

package/src/describe.ts

@@ -42,6 +42,8 @@ export interface DescribeInput<Row> {
   readonly shared?: string | undefined;
   /** `entity({ scan: '<why>' })` — projected only when declared. */
   readonly scan?: string | undefined;
+  /** `entity({ readOnly: '<why>' })` — projected only when declared. */
+  readonly readOnly?: string | undefined;
   /** `entity({ view })` — projected only when declared. */
   readonly view?: ViewQuery | null | undefined;
   /** `retain`, `history`, `countedIn` counters — each projected only when declared (`lifecycle.ts`). */
@@ -372,6 +374,7 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
     // Absent unless declared, like `appendOnly`: no entity that never said it moves the hash.
     ...(input.shared === undefined ? {} : { shared: input.shared }),
     ...(input.scan === undefined ? {} : { scan: input.scan }),
+    ...(input.readOnly === undefined ? {} : { readOnly: input.readOnly }),
     // Absent on every table, so no entity that never said `view` moves the hash.
     ...(input.view === null || input.view === undefined
       ? {}

package/src/entity-error.ts

@@ -48,6 +48,7 @@ export const ENTITY_ERROR_CODES = [
   'X_ENTITY_VIEW_READ_ONLY',
   'X_ENTITY_RETAIN_UNINDEXED',
   'X_ENTITY_COUNTS_INVALID',
+  'X_ENTITY_READ_ONLY',
 ] as const;
 
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
@@ -91,6 +92,7 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_RETAIN_UNINDEXED: 'entity({ retain }) names a column no index leads with',
   X_ENTITY_COUNTS_INVALID:
     'references(…, { countedIn }) names no integer of its parent, or is no key to its primary key',
+  X_ENTITY_READ_ONLY: 'a read-only entity was asked to write a row',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the

package/src/entity.ts

@@ -26,6 +26,7 @@ import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
 import { describeLifecycle, lifecycleHistory } from './lifecycle';
+import { assertReadOnly } from './read-only';
 import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
@@ -72,6 +73,11 @@ export interface EntityInit<C extends ColumnMap> {
    * and a reference column no index leads with; blank is refused.
    */
   readonly scan?: string;
+  /**
+   * Why the app never writes this table — legacy history a trigger closed, a table another system
+   * owns. Every write is `X_ENTITY_READ_ONLY` and `x exercise` seeds no row of it; blank is refused.
+   */
+  readonly readOnly?: string;
   /** Composite keys only — a single key is `uuid().primaryKey()` on the column itself. */
   readonly primaryKey?: readonly (keyof C & string)[];
   /**
@@ -149,6 +155,8 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   readonly $historyOf: string | null;
   /** `entity({ view })`: the query a view is derived by, `null` on a table. Writes are refused. */
   readonly $viewQuery: ViewQuery | null;
+  /** `entity({ readOnly })`'s reason, `null` on a table the app writes. Writes are refused. */
+  readonly $readOnly: string | null;
   /** Property key of the tenant column, or `null`. Presence is what turns tenancy on. */
   readonly $tenantColumn: string | null;
   /**
@@ -230,6 +238,7 @@ export const entity = <const C extends ColumnMap>(
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const appendOnly = init.appendOnly === true;
   if (appendOnly) assertAppendOnlyColumns(name, entries, SOFT_DELETE_COLUMN);
+  const readOnly = assertReadOnly(name, init.readOnly, { appendOnly, view: init.view != null });
 
   const searchSources: readonly SearchSource[] = entries.flatMap(([property, column]) => {
     const weight = column.$meta.searchable;
@@ -412,6 +421,7 @@ export const entity = <const C extends ColumnMap>(
       retired: init.retired,
       shared: init.shared,
       scan: init.scan,
+      readOnly: init.readOnly,
       view: viewQuery,
       lifecycle: describeLifecycle(core as EntityCore, retain, init.historyOf),
     });
@@ -438,6 +448,7 @@ export const entity = <const C extends ColumnMap>(
     $softDelete: softDelete,
     $appendOnly: appendOnly || init.historyOf !== undefined,
     $viewQuery: viewQuery,
+    $readOnly: readOnly,
     $tenantColumn: tenantColumn,
     $search: search,
     $schema: schema,

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, uniqueViolation } from './memory-unique';
+import { uniqueClash, 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';
@@ -143,8 +143,8 @@ export const memoryRepo = <Row>(
     batch.map((row) => narrowRow<Row>(entity.$columns, row));
 
   /**
-   * Lazy: a batch asks this once a row, and an entity with no unique never iterates it. Re-iterable
-   * and not a generator: `uniqueClash` walks it once per constraint.
+   * 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]() {
@@ -162,6 +162,8 @@ export const memoryRepo = <Row>(
     options: RepoOptions | undefined,
     operation: string,
     from?: string,
+    /** `insertAll` judged every unique key of its batch already, against one index. */
+    uniquesJudged = false,
   ): Row => {
     // `MoneyInput` lets a writer hand a `bigint`; a stored row holds the value type. The Postgres
     // driver narrows at the same position — its write methods' entry — so without this an
@@ -176,7 +178,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 = uniqueClash(entity, row, storedExcept(from));
+    const clash = uniquesJudged ? undefined : uniqueClash(entity, row, storedExcept(from));
     if (clash !== undefined) throw uniqueViolation(entity, clash);
     const moved = from !== undefined && from !== key ? rows.get(from) : undefined;
     const previous = rows.get(key);
@@ -265,14 +267,11 @@ 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);
-      const earlier = (position: number): Iterable<Row> => ({
-        *[Symbol.iterator]() {
-          yield* rows.values();
-          for (let at = 0; at < position; at += 1) yield batch[at] as Row;
-        },
-      });
+      // 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());
       const seen = new Set<string>();
-      for (const [position, row] of batch.entries()) {
+      for (const row of batch) {
         assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);
         entity.$assert(row);
         judgeReferences(row, batch);
@@ -282,10 +281,11 @@ export const memoryRepo = <Row>(
           throw uniqueViolation(entity, `${entity.$table}_pkey`);
         }
         seen.add(key);
-        const clash = uniqueClash(entity, row, earlier(position));
+        const clash = taken.clash(row);
         if (clash !== undefined) throw uniqueViolation(entity, clash);
+        taken.add(row);
       }
-      return batch.map((row) => write(row, options, 'insertAll'));
+      return batch.map((row) => write(row, options, 'insertAll', undefined, true));
     }),
 
     upsertAll: writing(async (given, args) => {

package/src/memory-unique.ts

@@ -39,6 +39,54 @@ const kindsOf = <Row>(entity: EntityCore<Row>): ReadonlyMap<string, string> =>
       .map(([property, column]) => [columnName(property, column.$meta), column.$meta.kind]),
   );
 
+/** Each unique constraint's key for a row, in declaration order; `undefined` where a part is NULL. */
+const keysOf = <Row>(entity: EntityCore<Row>) => {
+  const unique = uniqueConstraints(entity);
+  const kinds = kindsOf(entity);
+  return {
+    unique,
+    keys: (row: Row): readonly (string | undefined)[] => {
+      const bound = bindValues(entity, row as unknown as RowPatch<Row>);
+      return unique.map((index) => {
+        const parts = index.columns.map((name) => cellOf(kinds.get(name), bound.get(name)));
+        return parts.some((part) => part === undefined) ? undefined : JSON.stringify(parts);
+      });
+    },
+  };
+};
+
+/**
+ * Every unique key a set of rows holds, one `Set` 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.
+ */
+export interface UniqueIndex<Row> {
+  /** The first constraint, in declaration order, `row` collides on — or `undefined`. */
+  clash(row: Row): string | undefined;
+  add(row: Row): void;
+}
+
+export function uniqueIndex<Row>(entity: EntityCore<Row>, rows: Iterable<Row>): UniqueIndex<Row> {
+  const { unique, keys } = keysOf(entity);
+  const taken = unique.map(() => new Set<string>());
+  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);
+      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);
+      });
+    },
+  };
+  for (const row of rows) index.add(row);
+  return index;
+}
+
 /**
  * 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
@@ -48,20 +96,5 @@ export const uniqueClash = <Row>(
   entity: EntityCore<Row>,
   candidate: Row,
   others: Iterable<Row>,
-): string | undefined => {
-  const unique = uniqueConstraints(entity);
-  if (unique.length === 0) return undefined;
-  const bound = (row: Row) => bindValues(entity, row as unknown as RowPatch<Row>);
-  const incoming = bound(candidate);
-  const kinds = kindsOf(entity);
-  for (const index of unique) {
-    const key = index.columns.map((name) => cellOf(kinds.get(name), incoming.get(name)));
-    if (key.some((part) => part === undefined)) continue;
-    for (const other of others) {
-      const stored = bound(other);
-      if (index.columns.every((name, at) => cellOf(kinds.get(name), stored.get(name)) === key[at]))
-        return index.name();
-    }
-  }
-  return undefined;
-};
+): string | undefined =>
+  uniqueConstraints(entity).length === 0 ? undefined : uniqueIndex(entity, others).clash(candidate);

package/src/read-only.ts

@@ -0,0 +1,53 @@
+// `entity({ readOnly: '<why>' })`: a table the app reads and never writes — legacy history behind a
+// trigger that refuses every INSERT, a table another system owns. A reason, like `shared` and
+// `scan`: blank is no reason. The repository refuses every write (`view-repo.ts`'s seam), and the
+// exercise pass's seed graph leaves the table empty, as it does a view.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { EntityError } from './entity-error';
+
+/**
+ * Refused at declaration: a blank reason, and a second spelling of a narrower rule — a view
+ * already refuses every write, and `appendOnly` admits the inserts this refuses.
+ */
+export const assertReadOnly = (
+  entityName: string,
+  readOnly: string | undefined,
+  also: { readonly appendOnly: boolean; readonly view: boolean },
+): string | null => {
+  if (readOnly === undefined) return null;
+  const refuse = (why: string, fix: string): never => {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entityName} declares readOnly ${why}`,
+      fix,
+    });
+  };
+  if (readOnly.trim() === '') {
+    refuse(
+      'with no reason: a blank reason says nothing about why the app never writes the table',
+      `entity('${entityName}', { readOnly: '<why the app never writes it, e.g. legacy history a trigger closed>' }) — or drop readOnly`,
+    );
+  }
+  if (also.view) {
+    refuse(
+      'and is a view: a view refuses every write already',
+      `entity('${entityName}', { view }) — with the readOnly option removed`,
+    );
+  }
+  if (also.appendOnly) {
+    refuse(
+      'and appendOnly: appendOnly admits the inserts readOnly refuses',
+      `entity('${entityName}', { readOnly: '<why>' }) — with appendOnly removed, or appendOnly alone when the app appends`,
+    );
+  }
+  return readOnly;
+};
+
+/** `X_ENTITY_READ_ONLY`: the write, the entity, and the reason its declaration gave. */
+export const readOnlyRefused = (entityName: string, operation: string, reason: string) =>
+  new EntityError({
+    code: 'X_ENTITY_READ_ONLY',
+    cause: `${entityName}.${operation}() — ${entityName} is declared readOnly (${reason}), so the app never writes a row of it`,
+    fix: `x entities show ${renderFixShellArg(entityName, '<entity>')} --json   # write the table the app owns; drop readOnly from entity('<entity>', { … }) only once the table takes writes again`,
+  });

package/src/registry.ts

@@ -162,6 +162,8 @@ export interface EntityDescription {
   readonly shared?: string | undefined;
   /** `entity({ scan: '<why>' })`: why the plan sweep may see this table scanned. */
   readonly scan?: string | undefined;
+  /** `entity({ readOnly: '<why>' })`: why the app never writes the table; every write refused. */
+  readonly readOnly?: string | undefined;
   /**
    * `entity({ view: { sql } })`: a relation Postgres derives. Absent on a table. `x db gen` emits
    * it (`@ultimat3/db`'s `generate-view.ts`), admin lists it read-only.

package/src/view-repo.ts

@@ -1,6 +1,6 @@
-// Single responsibility: the repository seam of a view entity — every write rejects with
-// `X_ENTITY_VIEW_READ_ONLY` before any statement exists, in both drivers, because both return
-// through `appendOnlyRepo`. Reads pass through untouched; a spread keeps `MemoryRepo.reset()`.
+// Single responsibility: the repository seam of an entity no row of which is written — a view
+// (`X_ENTITY_VIEW_READ_ONLY`), a `readOnly` table (`X_ENTITY_READ_ONLY`) — every write rejecting
+// before any statement exists, in both drivers, because both return through `appendOnlyRepo`. Reads pass through untouched; a spread keeps `MemoryRepo.reset()`.
 
 import { renderFixShellArg } from '@ultimat3/core';
 import { EntityError } from './entity-error';
@@ -24,12 +24,17 @@ export const viewReadOnly = (entityName: string, operation: string): EntityError
     fix: `x entities show ${renderFixShellArg(entityName, '<entity>')} --json   # write the table its view.sql reads; the view answers on the next read (materialized: after its refreshView job runs)`,
   });
 
-export const readOnlyRepo = <Row, R extends Repo<Row>>(entityName: string, repo: R): R => {
+/** `repo` with every write rejecting `refusal(operation)` — a view's code unless told otherwise. */
+export const readOnlyRepo = <Row, R extends Repo<Row>>(
+  entityName: string,
+  repo: R,
+  refusal: (operation: string) => EntityError = (operation) => viewReadOnly(entityName, operation),
+): R => {
   const refusing = Object.fromEntries(
     WRITES.map((operation) => [
       operation,
       async () => {
-        throw viewReadOnly(entityName, operation);
+        throw refusal(operation);
       },
     ]),
   );