@ultimat3/entity 20.2.1 → 22.0.0

package/src/row-observer.ts

@@ -13,7 +13,8 @@
 // the replicator — `@ultimat3/realtime`'s `selectChangeFeed` still decides, and this is never in
 // that decision.
 
-import { expectedQueryLoop } from '@ultimat3/db';
+import { currentWriteOrigin } from '@ultimat3/core';
+import { currentTx, expectedQueryLoop } from '@ultimat3/db';
 import type { EntityCore } from './entity';
 import { MAX_PAGE_SIZE } from './plan';
 import type { Repo, RepoOptions, UpsertArgs } from './repo';
@@ -32,6 +33,13 @@ export interface RowChange {
   readonly op: RowChangeOp;
   readonly before: Readonly<Record<string, unknown>> | null;
   readonly after: Readonly<Record<string, unknown>> | null;
+  /**
+   * The keyed write this change belongs to — `@ultimat3/core`'s `currentWriteOrigin()` at the
+   * moment the repository wrote, i.e. the digest of the idempotency key the request arrived with.
+   * The WAL decoder reads the same fact off the transaction's opening message; absent both ways
+   * for a write no keyed request made.
+   */
+  readonly write?: string;
 }
 
 /**
@@ -176,12 +184,43 @@ const beforeAllOf = async <Row>(
 export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Repo<Row> {
   const name = entity.$name;
 
-  const emit = (op: RowChangeOp, before: unknown, after: unknown): void => {
-    installed?.onChange({ entity: name, op, before: asRecord(before), after: asRecord(after) });
+  /**
+   * Reported at COMMIT. The write may sit in a transaction — the caller's `options.tx`, or the
+   * ambient `withTransaction` a Postgres repository joins — and a change reported before COMMIT
+   * put a row in a live query that a rollback then erased (plan 101, 06 m). Outside a transaction
+   * the write is already durable, so it is reported at once. The write origin is read NOW: it is
+   * the request's, and the commit callback may run outside that request's scope.
+   */
+  const afterCommit = (options: RepoOptions | undefined, report: () => void): void => {
+    const tx: { onCommit?(effect: () => void): void } | undefined = options?.tx ?? currentTx();
+    if (tx?.onCommit === undefined) report();
+    else tx.onCommit(report);
   };
 
-  const bulk = (op: 'delete' | 'update', rows: number): void => {
-    if (rows > 0) installed?.onBulk?.({ entity: name, op, rows });
+  const emit = (
+    op: RowChangeOp,
+    before: unknown,
+    after: unknown,
+    options: RepoOptions | undefined,
+  ): void => {
+    const observer = installed;
+    if (observer === null) return;
+    const write = currentWriteOrigin();
+    const change: RowChange = {
+      entity: name,
+      op,
+      before: asRecord(before),
+      after: asRecord(after),
+      ...(write === undefined ? {} : { write }),
+    };
+    afterCommit(options, () => observer.onChange(change));
+  };
+
+  const bulk = (op: 'delete' | 'update', rows: number, options: RepoOptions | undefined): void => {
+    const observer = installed;
+    if (rows > 0 && observer?.onBulk !== undefined) {
+      afterCommit(options, () => observer.onBulk?.({ entity: name, op, rows }));
+    }
   };
 
   // Spread first, exactly as `examples/dummy`'s own capturing driver does: a repository may carry
@@ -192,13 +231,13 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
 
     insert: async (values: Row, options?: RepoOptions): Promise<Row> => {
       const stored = await repo.insert(values, options);
-      emit('insert', null, stored);
+      emit('insert', null, stored, options);
       return stored;
     },
 
     insertAll: async (rows: readonly Row[], options?: RepoOptions): Promise<readonly Row[]> => {
       const stored = await repo.insertAll(rows, options);
-      for (const row of stored) emit('insert', null, row);
+      for (const row of stored) emit('insert', null, row, options);
       return stored;
     },
 
@@ -217,7 +256,7 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
       for (const row of stored) {
         const id = idOf(row);
         const previous = id === undefined ? null : (before.get(id) ?? null);
-        emit(previous === null ? 'insert' : 'update', previous, row);
+        emit(previous === null ? 'insert' : 'update', previous, row, args);
       }
       return stored;
     },
@@ -226,7 +265,7 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
       if (installed === null) return await repo.update(id, patch, options);
       const before = await beforeOf(entity, repo, id);
       const after = await repo.update(id, patch, options);
-      emit('update', before, after);
+      emit('update', before, after, options);
       return after;
     },
 
@@ -234,12 +273,12 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
       if (installed === null) return await repo.delete(id, options);
       const before = await beforeOf(entity, repo, id);
       await repo.delete(id, options);
-      emit('delete', before, null);
+      emit('delete', before, null, options);
     },
 
     deleteWhere: async (filter: RowPatch<Row>, options?: RepoOptions): Promise<number> => {
       const rows = await repo.deleteWhere(filter, options);
-      bulk('delete', rows);
+      bulk('delete', rows, options);
       return rows;
     },
 
@@ -249,7 +288,7 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
       options?: RepoOptions,
     ): Promise<number> => {
       const rows = await repo.updateWhere(filter, patch, options);
-      bulk('update', rows);
+      bulk('update', rows, options);
       return rows;
     },
   };

package/src/row-schema.ts

@@ -0,0 +1,63 @@
+// `entity.$schema` — the whole row as a `t`-compatible schema, branded with the entity's record
+// projection. The brand is what lets `rowsOf` find a row inside any output shape, so it has to
+// survive every wrapper a row can be put in: containers keep the child node by reference, and the
+// five methods that COPY a node are re-branded here rather than in `@ultimat3/schema`.
+
+import { renderThrowable } from '@ultimat3/core';
+import { fail, makeSchema, pass, type Schema, type SchemaNode } from '@ultimat3/schema';
+import {
+  brandNode,
+  createProjection,
+  type ProjectionIdentity,
+  type RecordProjection,
+} from './record-projection';
+import type { AnyColumn } from './types';
+import { columnNode } from './view';
+
+/**
+ * Re-brands whatever a copying method returns. `nullable()`, `optional()`, `default()`,
+ * `describe()` and `refine()` each build a fresh node by spreading this one, and a spread drops a
+ * non-enumerable symbol — so without this, `t.nullable(posts.$schema)` would be a row nobody
+ * recognises. `refine()` keeps the brand because it keeps the shape; `.pick()` is not here
+ * because an entity row schema has none, and a `t.object` that does builds an unbranded node.
+ */
+const branded = <In, Out>(
+  schema: Schema<In, Out>,
+  projection: RecordProjection,
+): Schema<In, Out> => {
+  brandNode(schema.node, projection);
+  return {
+    ...schema,
+    optional: () => branded(schema.optional(), projection),
+    nullable: () => branded(schema.nullable(), projection),
+    default: (value) => branded(schema.default(value), projection),
+    describe: (description) => branded(schema.describe(description), projection),
+    refine: (refinement) => branded(schema.refine(refinement), projection),
+  };
+};
+
+/**
+ * The row schema for one entity. Validation IS `$parse` — defaults filled, every column parsed —
+ * so `$schema` and `$parse` can never disagree about what a row is. A refusal is rendered with
+ * `renderThrowable`, never `instanceof`/`String()`: a column parser is app-reachable and may throw
+ * anything, and a second `TypeError` out of a validator is the one outcome a validator may not have.
+ */
+export const rowSchema = <Row>(
+  identity: ProjectionIdentity,
+  columns: readonly (readonly [string, AnyColumn])[],
+  parse: (value: unknown) => Row,
+): Schema<unknown, Row> => {
+  const node: SchemaNode = {
+    kind: 'object',
+    properties: Object.fromEntries(columns.map(([key, column]) => [key, columnNode(column)])),
+  };
+  const projection = createProjection(identity, node);
+  const schema = makeSchema<unknown, Row>(node, (value, path) => {
+    try {
+      return pass(parse(value));
+    } catch (error) {
+      return fail(path, renderThrowable(error));
+    }
+  });
+  return branded(schema, projection);
+};

package/src/rows-of.ts

@@ -0,0 +1,132 @@
+// Which values in an output are entity rows — read off the output SCHEMA, never declared beside it
+// (axiom 2). `hasEntityRows` answers statically and is memoised per node; `rowsOf` walks only the
+// branches that can hold a row, so an output with none costs one WeakMap read per call.
+
+import type { Row } from '@ultimat3/core';
+import { isSchemaNode, nodeOf, type SchemaNode } from '@ultimat3/schema';
+import { projectionOf, type RecordProjection } from './record-projection';
+
+/** Children in the IR that can hold a value: object fields, array items, record values, arms. */
+const childrenOf = (node: SchemaNode): readonly SchemaNode[] => [
+  ...Object.values(node.properties ?? {}),
+  ...(node.items === undefined ? [] : [node.items]),
+  ...(node.valueNode === undefined ? [] : [node.valueNode]),
+  ...(node.anyOf ?? []),
+];
+
+const holdsRows = new WeakMap<SchemaNode, boolean>();
+
+const containsBrand = (node: SchemaNode): boolean => {
+  const known = holdsRows.get(node);
+  if (known !== undefined) return known;
+  // Seeded `false` before recursing, so a node reachable from itself ends rather than overflows.
+  holdsRows.set(node, false);
+  const answer = projectionOf(node) !== undefined || childrenOf(node).some(containsBrand);
+  holdsRows.set(node, answer);
+  return answer;
+};
+
+/** A schema object (anything carrying `node`) or a bare node; anything else has no rows. */
+const rootOf = (schema: unknown): SchemaNode | undefined =>
+  nodeOf(schema) ?? (isSchemaNode(schema) ? schema : undefined);
+
+/** Does this output schema reference any entity row, at any depth? Static — no value needed. */
+export const hasEntityRows = (schema: unknown): boolean => {
+  const root = rootOf(schema);
+  return root !== undefined && containsBrand(root);
+};
+
+/**
+ * Every entity projection an output schema can carry, one per record type, in first-seen order.
+ * Static, like `hasEntityRows`: a branded node is a row and its columns are never walked. What a
+ * caller needing the ENTITIES rather than the rows reads — `@ultimat3/action`'s mutator clock check.
+ */
+export const projectionsIn = (schema: unknown): readonly RecordProjection[] => {
+  const root = rootOf(schema);
+  if (root === undefined) return [];
+  const found = new Map<string, RecordProjection>();
+  const seen = new Set<SchemaNode>();
+  const visit = (node: SchemaNode): void => {
+    if (seen.has(node) || !containsBrand(node)) return;
+    seen.add(node);
+    const projection = projectionOf(node);
+    if (projection !== undefined) {
+      if (!found.has(projection.type)) found.set(projection.type, projection);
+      return;
+    }
+    for (const child of childrenOf(node)) visit(child);
+  };
+  visit(root);
+  return [...found.values()];
+};
+
+const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Inside a union the IR cannot say which arm a value took, so a branded arm claims the value only
+ * when it carries every column of that row as an OWN key — `$parse` writes every column, `null`
+ * included, so a real row always does. Outside a union the output schema already validated the
+ * value, and it is taken as the row it was declared to be.
+ */
+const fits = (projection: RecordProjection, value: Readonly<Record<string, unknown>>): boolean =>
+  Object.keys(projection.schema.properties ?? {}).every((column) => Object.hasOwn(value, column));
+
+type Found = Map<string, Map<string, Row>>;
+
+const collect = (found: Found, projection: RecordProjection, row: Row): void => {
+  const byKey = found.get(projection.type) ?? new Map<string, Row>();
+  found.set(projection.type, byKey);
+  const key = projection.key(row);
+  // First sighting wins: one record shown twice in a response is one record, not two writes.
+  if (!byKey.has(key)) byKey.set(key, row);
+};
+
+const walk = (node: SchemaNode, value: unknown, found: Found, inUnion: boolean): void => {
+  if (value === null || value === undefined || !containsBrand(node)) return;
+  const projection = projectionOf(node);
+  if (projection !== undefined) {
+    // A row's own columns are never walked: a column node carries no brand, and a `json()` value
+    // shaped like a row is data, not a record.
+    if (isObject(value) && (!inUnion || fits(projection, value))) collect(found, projection, value);
+    return;
+  }
+  if (node.kind === 'array' && node.items !== undefined && Array.isArray(value)) {
+    for (const item of value) walk(node.items, item, found, inUnion);
+  } else if (node.kind === 'object' && node.properties !== undefined && isObject(value)) {
+    for (const [key, child] of Object.entries(node.properties)) {
+      if (Object.hasOwn(value, key)) walk(child, value[key], found, inUnion);
+    }
+  } else if (node.kind === 'record' && node.valueNode !== undefined && isObject(value)) {
+    for (const entry of Object.values(value)) walk(node.valueNode, entry, found, inUnion);
+  } else if (node.kind === 'union') {
+    for (const arm of node.anyOf ?? []) walk(arm, value, found, true);
+  }
+};
+
+/** Keyed by record key, null-prototype: a key is data, and `'__proto__'` must stay a key. */
+export type RecordsByKey = Readonly<Record<string, Row>>;
+
+/** Keyed by record type, then by record key — the shape the record envelope carries on the wire. */
+export type RecordsByType = Readonly<Record<string, RecordsByKey>>;
+
+const nullProto = <V>(entries: Iterable<readonly [string, V]>): Readonly<Record<string, V>> => {
+  const out = Object.create(null) as Record<string, V>;
+  for (const [key, value] of entries) out[key] = value;
+  return out;
+};
+
+/**
+ * Every entity row in `value`, grouped by record type and keyed by record key — `{}` when the
+ * schema references none. The KEY travels because the browser cannot compute it: it would have to
+ * import the app's `entity()` declarations. The rows are the SAME objects the handler returned,
+ * one per key; a row with no key is `X_RECORD_KEY_MISSING`, because a keyless record would
+ * overwrite every other keyless one.
+ */
+export const rowsOf = (schema: unknown, value: unknown): RecordsByType => {
+  const root = rootOf(schema);
+  if (root === undefined || !containsBrand(root)) return nullProto([]);
+  const found: Found = new Map();
+  walk(root, value, found, false);
+  return nullProto([...found].map(([type, byKey]) => [type, nullProto(byKey)] as const));
+};

package/src/seed.ts

@@ -291,8 +291,14 @@ export const defineSeed = (
           const found = await repo.findMany({ where: equalityPredicates(where), limit: 1 });
           const stored = found.rows[0];
           const preserve: readonly string[] = key.preserve ?? [CREATED_AT_COLUMN];
+          // Only what the CALLER named, and never a key the table generates: `$parse` fills a
+          // fresh uuid and a `defaultNow()` into `row`, which no stored row can equal — so a
+          // re-run reported every row `'updated'` and never once `'skipped'`.
           const compared = Object.keys(row as Record<string, unknown>).filter(
-            (property) => !preserve.includes(property),
+            (property) =>
+              !preserve.includes(property) &&
+              Object.hasOwn(values, property) &&
+              (!entity.$primaryKey.includes(property) || key.by.includes(property as never)),
           );
           if (
             stored !== undefined &&

package/src/transition.ts

@@ -8,6 +8,7 @@ import type { EntityCore } from './entity';
 import { notFound } from './errors';
 import type { IllegalTransition } from './feature-errors';
 import { stateConflict, stateTransitionIllegal, stateUndeclared } from './feature-errors';
+import { singleKeyOf } from './plan';
 import type { Repo, RepoOptions } from './repo';
 import { canMove, isState, isTerminal, movesFrom, type StateMachine } from './state-machine';
 import type { ColumnMap, IdOf, RowPatch } from './types';
@@ -109,7 +110,11 @@ export const transitionRow = async <Row, C extends ColumnMap>(
   // an UNRESOLVED `Row`, so it never reduces and no object literal is ever assignable to it — the
   // same reason `expr.ts` and `@ultimat3/query`'s `paginate` spell theirs the same way. The column
   // name came from `machineFor`, which resolved it against the entity, so the shape is a real one.
-  const filter = { id, [property]: move.from } as unknown as RowPatch<Row>;
+  // Keyed on the entity's OWN primary key, never the literal `id`: a `code`-keyed entity has no
+  // `id` column, so the filter matched nothing in memory (a false `X_STATE_CONFLICT`) and named a
+  // column Postgres does not have (`X_INVARIANT_VIOLATED`).
+  const key = singleKeyOf(entity, 'transition');
+  const filter = { [key]: id, [property]: move.from } as unknown as RowPatch<Row>;
   const values = { [property]: move.to } as unknown as RowPatch<Row>;
   const written = await repo.updateWhere(filter, patch(values), options);
   if (written === 0) throw await diagnose(entity, repo, property, id, move, options);

package/src/write-tag.ts

@@ -0,0 +1,75 @@
+// A keyed write names itself in the write-ahead log. The Postgres driver opens the transaction a
+// keyed request's write lands in with `pg_logical_emit_message(true, WRITE_ORIGIN_WAL_PREFIX,
+// <digest>)`, and `@ultimat3/realtime`'s replication stream names every change after it with that
+// digest — which is how a `records` frame produced by the replicator, in another process, still
+// tells the page that wrote it that this is its own echo. The in-process row observer reads the
+// same fact off the request scope and needs none of this.
+
+import { currentWriteOrigin, WRITE_ORIGIN_WAL_PREFIX } from '@ultimat3/core';
+import { currentTx, type DbClient, type DbTx, db, sql, withTransaction } from '@ultimat3/db';
+
+/** Transactions this process already opened with the message: one per transaction is enough. */
+const tagged = new WeakSet<DbTx>();
+
+/**
+ * Whether this database lets the app's role emit the message. Asked once per process and
+ * remembered only once answered: a role without `EXECUTE` (a managed service may revoke it) must
+ * cost the page its echo match, never the write — so the answer is read BEFORE the first emit
+ * rather than learned from a failed one, which would already have aborted the caller's transaction.
+ */
+let emits: Promise<boolean> | undefined;
+
+/**
+ * By name, across overloads: Postgres 17 added a fourth parameter (`flush`, defaulted), so a probe
+ * naming the three-argument signature answered "no such function" there while the call below works
+ * on every version from 14 up. Measured on 17-alpine.
+ */
+const CAN_EMIT = sql`select exists (select 1 from pg_catalog.pg_proc where proname = 'pg_logical_emit_message' and has_function_privilege(oid, 'execute')) as "ok"`;
+
+function canEmit(client: DbClient): Promise<boolean> {
+  if (emits === undefined) {
+    const asked = client.one<{ ok: unknown }>(CAN_EMIT).then((row) => row?.ok === true);
+    emits = asked;
+    // A probe that FAILED answered nothing: the next write asks again.
+    asked.catch(() => {
+      if (emits === asked) emits = undefined;
+    });
+  }
+  return emits.catch(() => false);
+}
+
+const emit = (client: DbClient, digest: string): Promise<unknown> =>
+  client.query(
+    sql`select pg_logical_emit_message(true, ${WRITE_ORIGIN_WAL_PREFIX}::text, ${digest}::text)`,
+  );
+
+/**
+ * Send `write` so the WAL names the keyed write it belongs to. Outside a keyed request, or on a
+ * repository pinned to its own client (which may not join a transaction — `X_REPO_CLIENT_PINNED`),
+ * it is `write()` unchanged. Inside an open transaction the message goes first, once. Outside one,
+ * the write is wrapped in a transaction of its own, because a message in another transaction names
+ * nothing: three more round trips per keyed write, and only for a write a page is waiting on.
+ */
+export async function taggedWrite<T>(pinned: boolean, write: () => Promise<T>): Promise<T> {
+  const digest = currentWriteOrigin();
+  if (digest === undefined || pinned) return write();
+  const open = currentTx();
+  if (!(await canEmit(open ?? db()))) return write();
+  if (open !== undefined) {
+    if (!tagged.has(open)) {
+      await emit(open, digest);
+      tagged.add(open);
+    }
+    return write();
+  }
+  return withTransaction(async (tx) => {
+    await emit(tx, digest);
+    tagged.add(tx);
+    return write();
+  });
+}
+
+/** Forget the capability answer. Tests only: a process asks one database once. */
+export function resetWriteTag(): void {
+  emits = undefined;
+}