@ultimat3/entity 20.2.1 → 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/record-key.ts

@@ -0,0 +1,59 @@
+// A row's record key: its primary-key columns rendered to one string, in DECLARED order, so the
+// client store keys one record once whatever order a row's own properties arrived in. Runs in the
+// browser too (the store keys adopted rows with it), so it imports nothing a page cannot carry.
+
+import { isFixShellSafe, type Row, renderFixShellArg } from '@ultimat3/core';
+import { describeValue } from '@ultimat3/schema';
+import { EntityError } from './entity-error';
+
+/**
+ * A row reached a record key without one of its primary-key columns — a handler built the row by
+ * hand, or a partial row was handed where a whole one was declared. Refused, never keyed as
+ * `undefined`: two keyless rows would be ONE record in the store and overwrite each other.
+ *
+ * The value is described by SHAPE, never echoed: a key is the caller's data, and this cause
+ * reaches the log line.
+ */
+export const recordKeyMissing = (type: string, column: string, value: unknown): EntityError =>
+  new EntityError({
+    code: 'X_RECORD_KEY_MISSING',
+    cause: `a ${type} row reached its record key with primary-key column "${column}" holding ${describeValue(value)}, not a string, number, bigint, boolean or Date`,
+    // Screened, never spliced: an entity NAME is only checked as an identifier when it is also the
+    // table, so a declared name carrying shell syntax degrades to prose rather than a command. The
+    // `renderFixShellArg` inside the safe branch is verbatim there; it is the call
+    // `bun run fix-shell-arg` recognises as the screen.
+    fix: isFixShellSafe(type)
+      ? `x entities describe ${renderFixShellArg(type, 'ENTITY')} --json   # lists the primary key; return the whole row (every primary-key column) from the handler that built this one`
+      : 'x entities list --json   # find this entity, then return the whole row (every primary-key column) from the handler that built this one',
+  });
+
+/** One part of a key. `Object.hasOwn`, never `row[column]` alone: an inherited member is no key. */
+const partOf = (type: string, row: Row, column: string): string => {
+  const value = Object.hasOwn(row, column) ? row[column] : undefined;
+  switch (typeof value) {
+    case 'string':
+      return value;
+    case 'number':
+      if (Number.isFinite(value)) return String(value);
+      break;
+    case 'bigint':
+    case 'boolean':
+      return String(value);
+    default:
+      if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+  }
+  throw recordKeyMissing(type, column, value);
+};
+
+/**
+ * A single key is the value itself, so it is the same string `$tagFor(id)` and every realtime
+ * topic already carry. A composite key percent-encodes each part before joining on `:`, so a part
+ * holding the separator cannot make two different rows one key.
+ */
+export const recordKeyOf =
+  (type: string, primaryKey: readonly string[]) =>
+  (row: Row): string => {
+    const [only, ...rest] = primaryKey;
+    if (only !== undefined && rest.length === 0) return partOf(type, row, only);
+    return primaryKey.map((column) => encodeURIComponent(partOf(type, row, column))).join(':');
+  };

package/src/record-projection.ts

@@ -0,0 +1,88 @@
+// An entity's client projection — record type, record key, row node, persist — and the brand that
+// carries it on the entity's row schema. Value-light on purpose: the browser store imports this,
+// and nothing here may reach the Postgres driver.
+
+import type { Row } from '@ultimat3/core';
+import { isSchemaNode, type SchemaNode } from '@ultimat3/schema';
+import { invariantViolated } from './entity-error';
+import { recordKeyOf } from './record-key';
+
+/**
+ * `Symbol.for`, not `Symbol()`: islands are separate bundles, so a row schema declared in one and
+ * walked in another holds a brand minted by a different copy of this module. Only the registry key
+ * is the same symbol in both.
+ */
+export const ENTITY_BRAND: unique symbol = Symbol.for('ultimate.entity');
+
+export interface RecordProjection {
+  /** The wire name — the entity's name, the framework's key for it everywhere else too. */
+  readonly type: string;
+  /**
+   * The physical relation. A changefeed and a snapshot speak TABLES; `recordTypeForTable` is how
+   * they reach `type`, and this is the same fact read from the other end.
+   */
+  readonly table: string;
+  /** Primary key → string, in declared order. Throws `X_RECORD_KEY_MISSING`. */
+  readonly key: (row: Row) => string;
+  /** The row's schema IR — JSON, so a store can put it on disk beside the rows. */
+  readonly schema: SchemaNode;
+  /**
+   * Whether the client keeps this entity's records on disk — `entity(name, { persist: true })`,
+   * default `false`. Realtime's persister reads it here, never off the declaration.
+   */
+  readonly persist: boolean;
+}
+
+/** What `entity()` hands the projection: everything but the row node, which the schema builds. */
+export interface ProjectionIdentity {
+  readonly name: string;
+  readonly table: string;
+  readonly primaryKey: readonly string[];
+  readonly persist: boolean;
+}
+
+/** Built once per `entity()`, frozen: the brand, `recordProjection` and `rowsOf` share one object. */
+export const createProjection = (
+  { name, table, primaryKey, persist }: ProjectionIdentity,
+  schema: SchemaNode,
+): RecordProjection =>
+  Object.freeze({ type: name, table, key: recordKeyOf(name, primaryKey), schema, persist });
+
+/**
+ * The projection a schema node is branded with, or `undefined`. Own and non-enumerable: an
+ * enumerable symbol would ride every spread and `toEqual` of the IR, and an inherited one would
+ * brand every node built from a branded prototype.
+ */
+export const projectionOf = (node: unknown): RecordProjection | undefined => {
+  if (!isSchemaNode(node) || !Object.hasOwn(node, ENTITY_BRAND)) return undefined;
+  return (node as { readonly [ENTITY_BRAND]?: RecordProjection })[ENTITY_BRAND];
+};
+
+/** Brands `node` in place. Called by the row schema on its own node and on each wrapper's. */
+export const brandNode = (node: SchemaNode, projection: RecordProjection): void => {
+  Object.defineProperty(node, ENTITY_BRAND, { value: projection, enumerable: false });
+};
+
+/** The structural slice of an entity this reads — so it never imports `entity.ts`. */
+export interface ProjectedEntity {
+  readonly $name: string;
+  readonly $schema: { readonly node: SchemaNode };
+}
+
+/**
+ * `recordProjection(posts)` — the one answer to "what is this entity on the client". Read off the
+ * brand rather than rebuilt, so the store, the envelope and `rowsOf` hold the same object.
+ */
+export const recordProjection = (entity: ProjectedEntity): RecordProjection => {
+  const projection = projectionOf(entity.$schema.node);
+  // Every `entity()` brands its row schema, so absence means a hand-built lookalike: the type is
+  // `EntityCore`, and the only way here without a brand is a cast.
+  if (projection === undefined) {
+    throw invariantViolated(
+      entity.$name,
+      '$schema',
+      'carries no record brand; declare it with entity()',
+    );
+  }
+  return projection;
+};

package/src/record-table.ts

@@ -0,0 +1,46 @@
+// Table → record type, over the registered entities. A changefeed and a snapshot name the
+// physical relation; the client store keys records by entity name, and this is the one bridge —
+// memoised against the registry's generation, so a per-change lookup is one `Map` read.
+
+import { invariantViolated } from './entity-error';
+import type { RecordProjection } from './record-projection';
+import type { RegistryEntry } from './registry';
+import { registeredEntities, registryGeneration } from './registry';
+
+let cached: {
+  readonly generation: number;
+  readonly byTable: ReadonlyMap<string, RegistryEntry>;
+} | null = null;
+
+const tableIndex = (): ReadonlyMap<string, RegistryEntry> => {
+  const generation = registryGeneration();
+  if (cached !== null && cached.generation === generation) return cached.byTable;
+  const byTable = new Map<string, RegistryEntry>();
+  for (const entry of registeredEntities()) {
+    const other = byTable.get(entry.tableName);
+    // Two entities over one relation (`table:` lets an app adopt a table twice) leave a changed
+    // row with no single record type; refused rather than guessed, since the wrong guess writes
+    // one entity's row into another's records.
+    if (other !== undefined) {
+      throw invariantViolated(
+        entry.name,
+        'table',
+        `shares table "${entry.tableName}" with entity "${other.name}", so a change on it has no one record type — give one of them its own table, or stop streaming it`,
+      );
+    }
+    byTable.set(entry.tableName, entry);
+  }
+  cached = { generation, byTable };
+  return byTable;
+};
+
+/** The record type (entity name) a table's rows belong to, or `undefined` for an unknown table. */
+export const recordTypeForTable = (table: string): string | undefined =>
+  tableIndex().get(table)?.name;
+
+/**
+ * The whole client projection a table's rows belong to — type, key, row schema, `persist` — or
+ * `undefined` for an unknown table. Same index as `recordTypeForTable`, so the two never disagree.
+ */
+export const recordProjectionForTable = (table: string): RecordProjection | undefined =>
+  tableIndex().get(table)?.projection;

package/src/record.ts

@@ -0,0 +1,10 @@
+// `@ultimat3/entity/record` — the entity's client projection, and nothing that reaches a driver.
+// The package barrel re-exports the same bindings for server code; a BROWSER module imports them
+// from here, because the barrel retains ~1 MB of SQL rendering (`pg-sql.ts`, `@ultimat3/db`) a page
+// never runs — measured in `record-bundle.test.ts`, which fails if this entry ever grows it back.
+
+export type { ProjectedEntity, RecordProjection } from './record-projection';
+export { ENTITY_BRAND, recordProjection } from './record-projection';
+export { recordProjectionForTable, recordTypeForTable } from './record-table';
+export type { RecordsByKey, RecordsByType } from './rows-of';
+export { hasEntityRows, rowsOf } from './rows-of';

package/src/registry.ts

@@ -4,8 +4,10 @@
 // than a silent last-one-wins.
 
 import type { IndexMethod } from '@ultimat3/db';
-import { entityDuplicate } from './errors';
+import type { EntityCore } from './entity';
+import { entityDuplicate } from './entity-error';
 import type { InvariantKind } from './invariants';
+import type { RecordProjection } from './record-projection';
 import type { ColumnDefault, OnDelete } from './types';
 
 export interface ColumnDescription {
@@ -128,6 +130,12 @@ export interface EntityDescription {
 export interface RegistryEntry {
   readonly name: string;
   readonly tableName: string;
+  /** `entity(name, { persist: true })` — the client keeps this type on disk. Absent = `false`. */
+  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:
@@ -152,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 {