@ultimat3/entity 21.0.0 → 22.0.0

package/src/pg-sql-aggregate.ts

@@ -0,0 +1,132 @@
+// The aggregate reads compiled to SQL: a grouped count, one aggregate over one column, the
+// distinct currencies a money column holds, and the planner's row estimate. Split from `pg-sql.ts`,
+// which compiles the row reads they share their predicates with — `conditions()` is imported, never
+// restated, so an aggregate counts exactly the rows the matching read would return.
+
+import { identifier, type SqlFragment, sql } from '@ultimat3/db';
+import type { AggregateFn } from './aggregate';
+import { AVG_SCALE } from './aggregate';
+import { kindOf } from './cursor';
+import type { EntityCore } from './entity';
+import { columnRef, conditions, type ReadShape } from './pg-sql';
+import type { QueryPlan } from './tenancy';
+
+/** What a grouped count comes back as. Both names are fixed, so neither can be a column's. */
+export interface GroupRow {
+  readonly group_value: unknown;
+  readonly group_count: unknown;
+}
+
+/**
+ * The grouped count: one row per distinct value of one column, over exactly the rows
+ * `countStatement` would have counted — the same predicates, the same soft-delete filter, one
+ * `group by` more. `limit` bounds the groups, not the rows, which is what turns a whole-table
+ * breakdown into a refusal instead of a result set nobody sized.
+ *
+ * Both output names are aliases and fixed, so they cannot collide with each other whatever the
+ * table declares: an entity is free to have a column called `count`, and the un-aliased form would
+ * then return two outputs of one name.
+ */
+export const countByStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  shape: ReadShape,
+  column: string,
+  limit: number,
+): SqlFragment => {
+  const grouped = columnRef(entity, column);
+  return sql`select ${grouped} as group_value, count(*) as group_count from ${identifier(
+    entity.$table,
+  )} where ${conditions(entity, plan, shape)} group by ${grouped} limit ${limit}`;
+};
+
+/**
+ * One aggregate over exactly the rows `countStatement` would have counted — the same predicates,
+ * the same soft-delete filter, one function more. Four outputs and always the same four names, so
+ * neither driver reads a column an entity could also have declared:
+ *
+ * - `agg_value` — the aggregate itself, as TEXT. `::text` and never a float: `sum(bigint)` is a
+ *   `numeric` Bun would hand back as a string anyway, and pinning it makes `integer` behave the
+ *   same. `aggregate.ts` re-parses it by the column's kind.
+ * - `agg_count` — how many non-null values went in, which is what tells `null` ("no rows") from a
+ *   legitimate zero, and what `avg` divides by.
+ *
+ * `avg` is `round(avg(...), AVG_SCALE)` rather than the server's own scale, because the in-memory
+ * driver has to reach the same digits and "whatever numeric division gives you" is not a rule two
+ * implementations can share.
+ */
+export const aggregateStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  shape: ReadShape,
+  fn: AggregateFn,
+  column: string,
+): SqlFragment => {
+  const target = columnRef(entity, column);
+  const extreme = fn === 'min' ? sql`min(${target})` : sql`max(${target})`;
+  const value =
+    fn === 'sum'
+      ? sql`sum(${target})`
+      : fn === 'avg'
+        ? sql`round(avg(${target}), ${AVG_SCALE})`
+        : // An instant crosses as EPOCH MILLISECONDS, never as the session's own text: `::text`
+          // prints in the session's zone, and `new Date` on that answered NaN for an offset with
+          // seconds (a pre-1937 LMT) and 1999 for year 0099. Not `at time zone 'UTC'` either —
+          // that is an offsetless `timestamp`, which JS reads as LOCAL time.
+          kindOf(entity, column) === 'timestamptz'
+          ? sql`(extract(epoch from ${extreme}) * 1000)`
+          : extreme;
+  return sql`select ${value}::text as agg_value, count(${target}) as agg_count from ${identifier(
+    entity.$table,
+  )} where ${conditions(entity, plan, shape)}`;
+};
+
+/** What an aggregate comes back as. Both names are fixed, so neither can be a column's. */
+export interface AggregateRow {
+  readonly agg_value: unknown;
+  readonly agg_count: unknown;
+}
+
+/**
+ * The distinct currencies among the rows an aggregate is about to cover. A separate statement
+ * rather than a clever one: `sum(minor)` over two currencies is a number in neither, and the only
+ * honest answer is to refuse — which needs the list, not a boolean.
+ *
+ * Bounded at three, because the refusal names them and a caller with three already knows.
+ */
+export const currenciesStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  shape: ReadShape,
+  currencyColumn: string,
+  scaleColumn: string | null,
+): SqlFragment => {
+  const currency = identifier(currencyColumn);
+  // The SCALE is half of what makes two amounts incomparable and it is the half with no symptom:
+  // `{ minor: 5, currency: 'USD' }` is five cents and the same row at `scale: 6` is five millionths
+  // of a dollar. A table with no scale column has one unit per currency by construction.
+  const scale = scaleColumn === null ? sql`null` : identifier(scaleColumn);
+  return sql`select distinct ${currency} as group_value, ${scale} as group_scale from ${identifier(
+    entity.$table,
+  )} where ${conditions(entity, plan, shape)} and ${currency} is not null limit 3`;
+};
+
+/** One `(currency, scale)` pair the rows an aggregate covers actually use. */
+export interface MoneyUnitRow {
+  readonly group_value: unknown;
+  readonly group_scale: unknown;
+}
+
+/**
+ * The planner's own row estimate for a table — `reltuples`, which is what `ANALYZE` last wrote and
+ * what every query plan in the database is already costed against. `count(*)` walks every visible
+ * row (MVCC gives no shortcut), so on a large table it is the read that exceeds a web role's
+ * `statement_timeout`, and no index can make it cheaper: the `fix:` on that timeout tells an author
+ * to add one, and following it changes nothing.
+ *
+ * `to_regclass` rather than a name comparison, so a search_path change cannot silently answer for a
+ * different schema's table of the same name — and `-1` is what Postgres 14+ stores for a table that
+ * has never been analysed, which is an answer, not an estimate.
+ */
+export const estimateStatement = (table: string): SqlFragment =>
+  sql`select reltuples::bigint as estimate from pg_class where oid = to_regclass(${table})`;

package/src/pg-sql.ts

@@ -4,8 +4,6 @@
 // declared. That is the whole reason this file exists instead of a template literal per method.
 
 import { identifier, join, raw, type SqlFragment, sql } from '@ultimat3/db';
-import type { AggregateFn } from './aggregate';
-import { AVG_SCALE } from './aggregate';
 import { columnFor } from './column';
 import { isNullableKey, kindOf } from './cursor';
 import type { EntityCore } from './entity';
@@ -26,7 +24,7 @@ export interface ReadShape {
   readonly seek?: readonly unknown[] | undefined;
 }
 
-const columnRef = <Row>(entity: EntityCore<Row>, path: string): SqlFragment =>
+export const columnRef = <Row>(entity: EntityCore<Row>, path: string): SqlFragment =>
   identifier(physicalName(entity, path));
 
 /**
@@ -379,118 +377,3 @@ export const countStatement = <Row>(
   shape: ReadShape,
 ): SqlFragment =>
   sql`select count(*) as count from ${identifier(entity.$table)} where ${conditions(entity, plan, shape)}`;
-
-/** What a grouped count comes back as. Both names are fixed, so neither can be a column's. */
-export interface GroupRow {
-  readonly group_value: unknown;
-  readonly group_count: unknown;
-}
-
-/**
- * The grouped count: one row per distinct value of one column, over exactly the rows
- * `countStatement` would have counted — the same predicates, the same soft-delete filter, one
- * `group by` more. `limit` bounds the groups, not the rows, which is what turns a whole-table
- * breakdown into a refusal instead of a result set nobody sized.
- *
- * Both output names are aliases and fixed, so they cannot collide with each other whatever the
- * table declares: an entity is free to have a column called `count`, and the un-aliased form would
- * then return two outputs of one name.
- */
-export const countByStatement = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  shape: ReadShape,
-  column: string,
-  limit: number,
-): SqlFragment => {
-  const grouped = columnRef(entity, column);
-  return sql`select ${grouped} as group_value, count(*) as group_count from ${identifier(
-    entity.$table,
-  )} where ${conditions(entity, plan, shape)} group by ${grouped} limit ${limit}`;
-};
-
-/**
- * One aggregate over exactly the rows `countStatement` would have counted — the same predicates,
- * the same soft-delete filter, one function more. Four outputs and always the same four names, so
- * neither driver reads a column an entity could also have declared:
- *
- * - `agg_value` — the aggregate itself, as TEXT. `::text` and never a float: `sum(bigint)` is a
- *   `numeric` Bun would hand back as a string anyway, and pinning it makes `integer` behave the
- *   same. `aggregate.ts` re-parses it by the column's kind.
- * - `agg_count` — how many non-null values went in, which is what tells `null` ("no rows") from a
- *   legitimate zero, and what `avg` divides by.
- *
- * `avg` is `round(avg(...), AVG_SCALE)` rather than the server's own scale, because the in-memory
- * driver has to reach the same digits and "whatever numeric division gives you" is not a rule two
- * implementations can share.
- */
-export const aggregateStatement = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  shape: ReadShape,
-  fn: AggregateFn,
-  column: string,
-): SqlFragment => {
-  const target = columnRef(entity, column);
-  const value =
-    fn === 'sum'
-      ? sql`sum(${target})`
-      : fn === 'avg'
-        ? sql`round(avg(${target}), ${AVG_SCALE})`
-        : fn === 'min'
-          ? sql`min(${target})`
-          : sql`max(${target})`;
-  return sql`select ${value}::text as agg_value, count(${target}) as agg_count from ${identifier(
-    entity.$table,
-  )} where ${conditions(entity, plan, shape)}`;
-};
-
-/** What an aggregate comes back as. Both names are fixed, so neither can be a column's. */
-export interface AggregateRow {
-  readonly agg_value: unknown;
-  readonly agg_count: unknown;
-}
-
-/**
- * The distinct currencies among the rows an aggregate is about to cover. A separate statement
- * rather than a clever one: `sum(minor)` over two currencies is a number in neither, and the only
- * honest answer is to refuse — which needs the list, not a boolean.
- *
- * Bounded at three, because the refusal names them and a caller with three already knows.
- */
-export const currenciesStatement = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  shape: ReadShape,
-  currencyColumn: string,
-  scaleColumn: string | null,
-): SqlFragment => {
-  const currency = identifier(currencyColumn);
-  // The SCALE is half of what makes two amounts incomparable and it is the half with no symptom:
-  // `{ minor: 5, currency: 'USD' }` is five cents and the same row at `scale: 6` is five millionths
-  // of a dollar. A table with no scale column has one unit per currency by construction.
-  const scale = scaleColumn === null ? sql`null` : identifier(scaleColumn);
-  return sql`select distinct ${currency} as group_value, ${scale} as group_scale from ${identifier(
-    entity.$table,
-  )} where ${conditions(entity, plan, shape)} and ${currency} is not null limit 3`;
-};
-
-/** One `(currency, scale)` pair the rows an aggregate covers actually use. */
-export interface MoneyUnitRow {
-  readonly group_value: unknown;
-  readonly group_scale: unknown;
-}
-
-/**
- * The planner's own row estimate for a table — `reltuples`, which is what `ANALYZE` last wrote and
- * what every query plan in the database is already costed against. `count(*)` walks every visible
- * row (MVCC gives no shortcut), so on a large table it is the read that exceeds a web role's
- * `statement_timeout`, and no index can make it cheaper: the `fix:` on that timeout tells an author
- * to add one, and following it changes nothing.
- *
- * `to_regclass` rather than a name comparison, so a search_path change cannot silently answer for a
- * different schema's table of the same name — and `-1` is what Postgres 14+ stores for a table that
- * has never been analysed, which is an answer, not an estimate.
- */
-export const estimateStatement = (table: string): SqlFragment =>
-  sql`select reltuples::bigint as estimate from pg_class where oid = to_regclass(${table})`;

package/src/pg-transactor.ts

@@ -0,0 +1,23 @@
+// The Postgres half of `Transactor`: one real transaction per `run`, the `Tx` a token. Split from
+// `pg-driver.ts`, which is the repositories — the two meet only through `db()`, never an import.
+
+import { type TransactionOptions, withTransaction } from '@ultimat3/db';
+import type { Transactor } from './repo';
+
+/**
+ * A real Postgres transaction behind the same `Transactor` the in-memory one implements. The
+ * `Tx` handed to the callback is a token: repositories find the transaction through `db()`, so
+ * nothing has to thread a connection through the call stack.
+ */
+export const postgresTransactor = (options: TransactionOptions = {}): Transactor => ({
+  run: (work) =>
+    withTransaction(
+      (tx) =>
+        work({
+          id: tx.id,
+          onRollback: (undo: () => void) => tx.onRollback(undo),
+          onCommit: (effect: () => void) => tx.onCommit(effect),
+        }),
+      options,
+    ),
+});

package/src/registry.ts

@@ -4,6 +4,7 @@
 // than a silent last-one-wins.
 
 import type { IndexMethod } from '@ultimat3/db';
+import type { EntityCore } from './entity';
 import { entityDuplicate } from './entity-error';
 import type { InvariantKind } from './invariants';
 import type { RecordProjection } from './record-projection';
@@ -133,6 +134,8 @@ export interface RegistryEntry {
   readonly persist?: boolean;
   /** The entity's client projection — what a changefeed's table maps to on the client. */
   readonly projection?: RecordProjection;
+  /** The entity itself, for `entityForTable` — what decodes a raw row of this table. */
+  readonly core?: EntityCore<unknown>;
   describe(): EntityDescription;
   /**
    * The foreign keys this entity declares, resolved. This is how a relation reaches query time:
@@ -157,6 +160,16 @@ export const registerEntity = <E extends RegistryEntry>(entry: E): E => {
 
 export const getEntity = (name: string): RegistryEntry | undefined => entities.get(name);
 
+/**
+ * The entity declared on a PHYSICAL table, or `undefined`. What a change feed has in hand is a
+ * table name and raw columns; with this and `decodeRow` it gets the row the app declared, money
+ * and all — where `@ultimat3/realtime` had to guess money columns from their names.
+ */
+export const entityForTable = (table: string): EntityCore<unknown> | undefined => {
+  for (const entry of entities.values()) if (entry.tableName === table) return entry.core;
+  return undefined;
+};
+
 export const entityNames = (): readonly string[] => [...entities.keys()].sort();
 
 /**

package/src/repo.ts

@@ -15,6 +15,11 @@ export interface Tx {
   readonly id: string;
   /** Registered by drivers so a failed transaction can undo in-memory effects. */
   onRollback(undo: () => void): void;
+  /**
+   * Run once the transaction COMMITS, never on rollback. Optional so a hand-written `Tx` still
+   * satisfies the type; without it, work registered here runs immediately (the pre-22 behaviour).
+   */
+  onCommit?(effect: () => void): void;
 }
 
 export interface RepoOptions {

package/src/row-observer.ts

@@ -14,7 +14,7 @@
 // that decision.
 
 import { currentWriteOrigin } from '@ultimat3/core';
-import { expectedQueryLoop } from '@ultimat3/db';
+import { currentTx, expectedQueryLoop } from '@ultimat3/db';
 import type { EntityCore } from './entity';
 import { MAX_PAGE_SIZE } from './plan';
 import type { Repo, RepoOptions, UpsertArgs } from './repo';
@@ -184,20 +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 => {
-    if (installed === null) return;
+  /**
+   * 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 emit = (
+    op: RowChangeOp,
+    before: unknown,
+    after: unknown,
+    options: RepoOptions | undefined,
+  ): void => {
+    const observer = installed;
+    if (observer === null) return;
     const write = currentWriteOrigin();
-    installed.onChange({
+    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): void => {
-    if (rows > 0) installed?.onBulk?.({ entity: name, op, rows });
+  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
@@ -208,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;
     },
 
@@ -233,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;
     },
@@ -242,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;
     },
 
@@ -250,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;
     },
 
@@ -265,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/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);