@ultimat3/entity 29.4.0 → 30.1.0

package/src/pg-driver.ts

@@ -2,59 +2,39 @@
 // only difference is where the rows are, which is the point: a test that passes against memory
 // means something about Postgres.
 //
-// It never takes a connection as an argument. `db()` from `@ultimat3/db` returns the open
-// transaction when there is one, so a repository call inside `withTransaction` joins it without
-// being told — which is how `ctx.jobs.enqueue()` lands its outbox row atomically with the write
-// that caused it. `RepoOptions.tx` is the in-memory driver's undo hook and is ignored here.
+// It takes no connection. `db()` from `@ultimat3/db` returns the open transaction, so a repository
+// call inside `withTransaction` joins it unasked, which lands `ctx.jobs.enqueue()`'s outbox row
+// with its write. `RepoOptions.tx` is the in-memory driver's undo hook and is ignored here.
 
 import { pageOf } from '@ultimat3/core';
 import {
   currentTx,
   type DbClient,
   db,
+  refuseAbandoned,
   type SqlFragment,
   withStatementAttribution,
 } from '@ultimat3/db';
-import { aggregateColumnOf, aggregateMinor, assertOneUnit } from './aggregate';
-import { decodeAggregate } from './aggregate-decode';
 import { appendOnlyRepo } from './append-only';
-import {
-  conflictKeys,
-  insertChunks,
-  insertColumns,
-  namedProperties,
-  upsertPlan,
-} from './bulk-write';
+import { conflictKeys, insertColumns, statementColumns, upsertPlan } from './bulk-write';
+import { writeChunks } from './bulk-write-send';
 import { entityNow } from './clock';
 import { coalesceFindById } from './coalesce';
-import { moneyColumns } from './column';
 import { narrowRow } from './columns';
-import { countsFrom, groupColumnOf, groupValue, MAX_GROUPS } from './count-by';
 import { cursorFor, seekFrom, valueAt } from './cursor';
 import type { Driver } from './database';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { notFound, repoClientPinned } from './errors';
+import { stampHistoryActor } from './history-actor';
 import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
 import { forgetPreloaded, tagSiblings } from './jit-preload';
 import { judgedWrite } from './judged-write';
+import { postgresAggregates } from './pg-aggregates';
+import { postgresLocks } from './pg-lock';
 import { bindValues, decodeRow, type PhysicalRow, physicalName, sortPrecision } from './pg-row';
 import { countStatement, type ReadShape, selectStatement } from './pg-sql';
-import {
-  type AggregateRow,
-  aggregateStatement,
-  countByStatement,
-  currenciesStatement,
-  estimateStatement,
-  type GroupRow,
-  type MoneyUnitRow,
-} from './pg-sql-aggregate';
 import { postgresTransactor } from './pg-transactor';
-import {
-  type ConflictTarget,
-  deleteStatement,
-  insertStatement,
-  updateStatement,
-} from './pg-write-sql';
+import { type ConflictTarget, deleteStatement, updateStatement } from './pg-write-sql';
 import { deletePlan, idPlan, readPlan, updatePlan } from './plan';
 import type { FindManyArgs, Repo, UpsertArgs } from './repo';
 import { sealedRepo } from './sealed-repo';
@@ -65,15 +45,13 @@ import { taggedWrite } from './write-tag';
 
 export interface PostgresDriverOptions {
   /**
-   * Pin a client. Left out, every call resolves `db()` — the ambient pool, or the open
-   * transaction when one is in scope. Tests pass `recordingClient()` here or install one
-   * globally with `setDbClient()`.
+   * Pin a client. Left out, every call resolves `db()` — the ambient pool, or the open transaction
+   * in scope. Tests pass `recordingClient()` here or install one with `setDbClient()`.
    */
   readonly client?: DbClient | undefined;
   /**
-   * Preload foreign keys resolved by a page into a request-scoped cache, so the first
-   * `findById` for any one of them resolves that key for the whole page in one statement.
-   * Default: true.
+   * Preload foreign keys resolved by a page into a request-scoped cache, so the first `findById`
+   * for any of them resolves that key for the whole page in one statement. Default: true.
    */
   readonly jitPreload?: boolean | undefined;
 }
@@ -165,19 +143,59 @@ export const postgresRepo = <Row>(
    * Every write goes out through here: the ONE place the request's preloaded rows are dropped (a
    * row this statement changes must not be served afterwards from a page read before it — so
    * before the statement, not after), and where a keyed request's write names itself in the WAL
-   * (`write-tag.ts`).
+   * (`write-tag.ts`). The one funnel for an autocommit repository write, so it is also where a scope
+   * whose caller was already answered stops: the pool does not refuse, and must not (`runOn`).
    */
-  const writing = <T>(send: () => Promise<T>): Promise<T> => {
-    forgetPreloaded(entity.$name);
+  const writing = async <T>(send: () => Promise<T>): Promise<T> => {
+    refuseAbandoned();
+    forgetPreloaded();
+    await stampHistoryActor(entity, config.client !== undefined);
     return taggedWrite(config.client !== undefined, send);
   };
 
+  /**
+   * Only an entity with a JS-only rule comes here: rows ARE needed, so how many is a memory bound.
+   * Counted BEFORE the write, because a refusal after `returning *` has already allocated what it
+   * refuses; a concurrent writer can drift the count, which moves a bound, never a decision.
+   */
+  const judgedRows = async (
+    op: string,
+    plan: QueryPlan,
+    values: ReadonlyMap<string, unknown>,
+    shape: ReadShape,
+  ): Promise<number> => {
+    const matched = await attributed(op, () =>
+      client().one<{ count: unknown }>(countStatement(entity, plan, shape)),
+    );
+    const rows = Number(matched?.count ?? 0);
+    if (rows > MAX_ASSERTED_ROWS) throw assertedRowsTooMany(entity.$name, op, rows);
+    const statement = updateStatement(entity, plan, values, shape, true);
+    return judged(async (send) => {
+      const written = await attributed(op, () => writing(() => send.query<PhysicalRow>(statement)));
+      for (const row of written) entity.$assert(decodeRow(entity, row));
+      return written.length;
+    });
+  };
+
+  /**
+   * `delete` and `deleteWhere`. A soft delete is an update, so an app-only rule judges the stamped
+   * rows, as `memoryRepo`'s `write` does; everything else is one statement and a count.
+   */
+  const removed = (op: string, plan: QueryPlan): Promise<number> =>
+    entity.$softDelete && hasJsOnlyInvariant(entity.$invariants)
+      ? judgedRows(
+          op,
+          plan,
+          new Map([[physicalName(entity, SOFT_DELETE_COLUMN), entityNow()]]),
+          shapeOf({}),
+        )
+      : attributed(op, () => writing(() => client().execute(removal(plan))));
+
   /**
    * The one insert path, for one row or ten thousand: the batch's own column list, split into as
    * many statements as Postgres's bind count allows, and the rows the server stored. `insert(row)`
-   * comes through here too, so there is no second builder for the two to drift apart in — and a
-   * batch wide enough to split is several statements, which is why an all-or-nothing caller wraps
-   * the call in `withTransaction` rather than trusting one statement's atomicity.
+   * comes through here too, so there is no second builder for the two to drift apart in. All or
+   * nothing however many statements it takes (`bulk-write-send.ts`).
    */
   const writeRows = async (
     op: string,
@@ -193,25 +211,17 @@ export const postgresRepo = <Row>(
       assertRowTenant(entity.$name, entity.$tenantColumn, op, row);
       entity.$assert(row);
     }
-    const columns = insertColumns(entity, namedProperties(entity, batch));
     const bound = batch.map((row) => bindValues(entity, row));
-    const shape = { columns, ...(conflict === undefined ? {} : { conflict }) };
-    const written: Row[] = [];
+    const shape = {
+      columns: statementColumns(entity, batch),
+      ...(conflict === undefined ? {} : { conflict }),
+    };
     // Attributed here rather than in each of the three callers: a batch wide enough to split is
-    // several statements sent inside this loop, and every one of them belongs to the call that
+    // several statements sent inside this call, and every one of them belongs to the call that
     // asked for it — `insert`, `insertAll` or `upsertAll`, which is why the op is a parameter.
-    await attributed(op, () =>
-      writing(async () => {
-        for (const chunk of insertChunks(bound, columns.length)) {
-          for (const row of await client().query<PhysicalRow>(
-            insertStatement(entity, chunk, shape),
-          )) {
-            written.push(decodeRow(entity, row));
-          }
-        }
-      }),
+    return attributed(op, () =>
+      writing(() => writeChunks(entity, bound, shape, client(), config.client)),
     );
-    return written;
   };
 
   const repo: Repo<Row> = {
@@ -280,7 +290,8 @@ export const postgresRepo = <Row>(
 
     async upsertAll(batch, args: UpsertArgs<Row>) {
       const rows = narrowed(batch);
-      const plan = upsertPlan(entity, rows, args.onConflict, args.onMatch ?? 'update');
+      const { onConflict, onMatch = 'update', overwrites } = args;
+      const plan = upsertPlan(entity, rows, onConflict, onMatch, overwrites);
       // Refused here, not by the server: a batch that repeats a conflict target is `21000` in
       // Postgres and a silent overwrite in memory, and the two drivers have to mean one thing.
       conflictKeys(entity, plan, rows);
@@ -290,7 +301,9 @@ export const postgresRepo = <Row>(
       });
     },
 
-    async update(id, patch, options) {
+    async update(id, given, options) {
+      // Here and in `memory-repo.ts`, the one door: a value `insert` refuses, a fragment included.
+      const patch = entity.$parsePatch(given);
       const op = 'update';
       const plan = idPlan(entity, id, options, op);
       // The plan bounds WHICH row is written; the patch decides what it becomes, and a patch
@@ -321,7 +334,7 @@ export const postgresRepo = <Row>(
     async delete(id, options) {
       const op = 'delete';
       const plan = idPlan(entity, id, options, op);
-      if ((await attributed(op, () => writing(() => client().execute(removal(plan))))) === 0) {
+      if ((await removed(op, plan)) === 0) {
         throw notFound(entity.$name, id);
       }
     },
@@ -338,10 +351,11 @@ export const postgresRepo = <Row>(
       const op = 'deleteWhere';
       // The plan is built before the write is announced: a refused filter never happened.
       const plan = deletePlan(entity, filter, options, op);
-      return attributed(op, () => writing(() => client().execute(removal(plan))));
+      return removed(op, plan);
     },
 
-    async updateWhere(filter, patch, options) {
+    async updateWhere(filter, given, options) {
+      const patch = entity.$parsePatch(given);
       const op = 'updateWhere';
       const plan = updatePlan(entity, filter, patch, options, op);
       // The same move, filtered: one statement can hand away every row it matches.
@@ -361,24 +375,7 @@ export const postgresRepo = <Row>(
         const statement = updateStatement(entity, plan, values, shape, false);
         return attributed(op, () => writing(() => client().execute(statement)));
       }
-      // Rows ARE needed, so how many is a memory bound rather than a detail — this is the one
-      // statement in the driver whose result size is the caller's filter and not a page. Counted
-      // BEFORE the write, because a refusal after `returning *` has already allocated the thing it
-      // is refusing; the count can drift by whatever a concurrent writer adds between the two,
-      // which moves a bound, never a decision.
-      const matched = await attributed(op, () =>
-        client().one<{ count: unknown }>(countStatement(entity, plan, shape)),
-      );
-      const rows = Number(matched?.count ?? 0);
-      if (rows > MAX_ASSERTED_ROWS) throw assertedRowsTooMany(entity.$name, op, rows);
-      const statement = updateStatement(entity, plan, values, shape, true);
-      return judged(async (send) => {
-        const written = await attributed(op, () =>
-          writing(() => send.query<PhysicalRow>(statement)),
-        );
-        for (const row of written) entity.$assert(decodeRow(entity, row));
-        return written.length;
-      });
+      return judgedRows(op, plan, values, shape);
     },
 
     async count(args = {}) {
@@ -390,92 +387,8 @@ export const postgresRepo = <Row>(
       return Number(row?.count ?? 0);
     },
 
-    async countBy(column, args = {}) {
-      const op = 'countBy';
-      const grouped = groupColumnOf(entity, column, op);
-      const plan = readPlan(entity, args, op);
-      // One group past the bound, for the same reason a page reads one row past its limit: the
-      // presence of that group is what says the answer was never going to fit, and `countsFrom`
-      // refuses it rather than hand back a breakdown missing its tail.
-      const rows = await attributed(op, () =>
-        client().query<GroupRow>(
-          countByStatement(entity, plan, shapeOf(args), column, MAX_GROUPS + 1),
-        ),
-      );
-      return countsFrom(
-        entity,
-        column,
-        op,
-        rows.map((row) => [groupValue(grouped, row.group_value), Number(row.group_count)] as const),
-      );
-    },
-
-    async aggregate(fn, column, args = {}) {
-      const op = fn;
-      const declared = aggregateColumnOf(entity, fn, column);
-      const plan = readPlan(entity, args, op);
-      const shape = shapeOf(args);
-      const money = declared.$meta.kind === 'money' ? moneyColumns(column, declared.$meta) : null;
-      // Money is judged BEFORE the aggregate is asked for, in its own statement: `sum(minor)` over
-      // two currencies is a number in neither, and the refusal has to name them.
-      const unit =
-        money === null
-          ? undefined
-          : assertOneUnit(
-              entity,
-              fn,
-              column,
-              (
-                await attributed(op, () =>
-                  client().query<MoneyUnitRow>(
-                    currenciesStatement(entity, plan, shape, money.currency, money.scale),
-                  ),
-                )
-              ).map((row) => ({
-                currency: String(row.group_value ?? '').trim(),
-                scale:
-                  row.group_scale === null || row.group_scale === undefined
-                    ? null
-                    : Number(row.group_scale),
-              })),
-            );
-      const row = await attributed(op, () =>
-        client().one<AggregateRow>(
-          aggregateStatement(entity, plan, shape, fn, money === null ? column : `${column}.minor`),
-        ),
-      );
-      const text = row?.agg_value;
-      if (text === null || text === undefined) return null;
-      if (money === null) return decodeAggregate(fn, declared.$meta.kind, String(text));
-      if (unit === undefined) return null;
-      return {
-        minor: aggregateMinor(entity, fn, column, String(text)),
-        currency: unit.currency,
-        ...(unit.scale === null ? {} : { scale: unit.scale }),
-      };
-    },
-
-    /**
-     * `reltuples`, the planner's own estimate — one row out of `pg_class`, constant time, and the
-     * only answer that stays constant time as the table grows. `count(*)` walks every visible row
-     * because MVCC gives it no shortcut, so past a few million it is the read that trips a web
-     * role's `statement_timeout`, and no index can help: `X_DB_STATEMENT_TIMEOUT`'s fix names one
-     * anyway, and following it changes nothing.
-     */
-    async approximateCount(args = {}) {
-      const op = 'approximateCount';
-      // Built and therefore GUARDED: tenancy still applies, and a filtered chain is refused here
-      // rather than answered with the whole table's estimate.
-      readPlan(entity, args, op);
-      const row = await attributed(op, () =>
-        client().one<{ estimate: unknown }>(estimateStatement(entity.$table)),
-      );
-      const estimate = Number(row?.estimate ?? -1);
-      // `-1` is what Postgres 14+ stores for a table nobody has analysed. That is an absence of an
-      // estimate, not an estimate of zero, and answering `0` would read exactly like an empty
-      // table to every caller.
-      return Number.isFinite(estimate) && estimate >= 0 ? estimate : null;
-    },
+    ...postgresAggregates(entity, client),
+    ...postgresLocks(entity, config.client, client),
   };
   // The one sealing seam, shared with `memoryRepo()`: sealed on the way in, opened on the way out.
   // Append-only outermost, as there: a refused rewrite seals nothing and sends no statement.

package/src/pg-lock.ts

@@ -0,0 +1,50 @@
+// Single responsibility: `lock` and `lockKey` on Postgres. A transaction, through the driver's own
+// transactor, so nested in `withTransaction` it is a savepoint and the lock lives to the root COMMIT.
+// No wait option: the bound is the role's `statement_timeout`, and a deadlock the server breaks is
+// `X_DB_SERIALIZATION_FAILURE` through the funnel like any other statement.
+
+import { type DbClient, type SqlFragment, sql, withStatementAttribution } from '@ultimat3/db';
+import type { EntityCore } from './entity';
+import { notFound } from './errors';
+import { lockKeyInput } from './lock-key';
+import { decodeRow, type PhysicalRow } from './pg-row';
+import { selectStatement } from './pg-sql';
+import { postgresTransactor } from './pg-transactor';
+import { idPlan } from './plan';
+import type { Repo } from './repo';
+
+/** The read path's own statement, so tenant and soft delete are its own, `for update` after it. */
+const lockedRow = <Row>(entity: EntityCore<Row>, plan: ReturnType<typeof idPlan>): SqlFragment =>
+  sql`${selectStatement(entity, plan, { includeDeleted: false }, 1)} for update`;
+
+/** Scoped to the transaction: COMMIT and ROLLBACK release it, and a dropped connection does too. */
+const advisoryLock = (input: string): SqlFragment =>
+  sql`select pg_advisory_xact_lock(hashtextextended(${input}::text, 0))`;
+
+export const postgresLocks = <Row>(
+  entity: EntityCore<Row>,
+  pinned: DbClient | undefined,
+  client: () => DbClient,
+): Required<Pick<Repo<Row>, 'lock' | 'lockKey'>> => ({
+  async lock(id, fn, options) {
+    const plan = idPlan(entity, id, options, 'lock');
+    return postgresTransactor(pinned === undefined ? {} : { client: pinned }).run(async (tx) => {
+      const found = await withStatementAttribution(entity.$name, 'lock', () =>
+        client().query<PhysicalRow>(lockedRow(entity, plan)),
+      );
+      const [row] = found;
+      if (row === undefined) throw notFound(entity.$name, id);
+      return fn(decodeRow(entity, row), tx);
+    });
+  },
+
+  async lockKey(key, fn, options) {
+    const input = lockKeyInput(entity, key, options);
+    return postgresTransactor(pinned === undefined ? {} : { client: pinned }).run(async (tx) => {
+      await withStatementAttribution(entity.$name, 'lockKey', () =>
+        client().query(advisoryLock(input)),
+      );
+      return fn(tx);
+    });
+  },
+});

package/src/pg-row.ts

@@ -189,14 +189,41 @@ const cellOf = (entityName: string, property: string, column: AnyColumn, value:
   );
 };
 
+/** One column as the decoder reads it: the property, its column, and its physical names. */
+type DecodeStep = readonly [
+  property: string,
+  column: AnyColumn,
+  head: string | undefined,
+  currency: string | undefined,
+  scale: string | undefined,
+];
+
+/**
+ * The physical names, derived once per column map. Column names never change after `entity()`,
+ * and deriving them per row was most of a list's CPU: `snake` is a regex replace, and it ran once
+ * per column per row (measured 2026-11-06: 35.6% self time of a 100-row list). Weak, so a test's
+ * throwaway entity is not held by it.
+ */
+const DECODE_PLANS = new WeakMap<object, readonly DecodeStep[]>();
+
+const decodePlan = (columns: EntityCore<unknown>['$columns']): readonly DecodeStep[] => {
+  const known = DECODE_PLANS.get(columns);
+  if (known !== undefined) return known;
+  const steps = Object.entries(columns).map(([property, column]): DecodeStep => {
+    const [head, currency, scale] = columnsOf(property, column);
+    return [property, column, head, currency, scale];
+  });
+  DECODE_PLANS.set(columns, steps);
+  return steps;
+};
+
 /**
  * Physical row -> entity row. A column the projection left out is left out here too, so a
  * `select` narrows the object as well as the statement.
  */
 export const decodeRow = <Row>(entity: EntityCore<Row>, source: PhysicalRow): Row => {
   const row: Record<string, unknown> = {};
-  for (const [property, column] of Object.entries(entity.$columns)) {
-    const [head, currency, scale] = columnsOf(property, column);
+  for (const [property, column, head, currency, scale] of decodePlan(entity.$columns)) {
     if (head === undefined || !(head in source)) continue;
     // Decided by the column's KIND and never by how many names came back: a money column whose
     // table has no scale column projects two names, and reading that as a non-money column handed

package/src/pg-sql-aggregate.ts

@@ -130,3 +130,34 @@ export interface MoneyUnitRow {
  */
 export const estimateStatement = (table: string): SqlFragment =>
   sql`select reltuples::bigint as estimate from pg_class where oid = to_regclass(${table})`;
+
+/** What a series comes back as. Every name is fixed, so none can be a column's. */
+export interface SeriesRow {
+  readonly bucket_ms: unknown;
+  readonly bucket_count: unknown;
+  readonly bucket_value: unknown;
+}
+
+/**
+ * One row per bucket over exactly the rows `countStatement` would have counted with an instant in
+ * `on`: the three-argument `date_trunc`, with the unit AND the zone bound — a two-argument one
+ * truncates in the session's zone, which is the bug this statement exists to make unwritable. The
+ * bucket crosses as epoch milliseconds, as `min`/`max` over an instant does, never as session text
+ * — and as a `numeric`, not its text, so `group by 1 order by 1` orders instants, not strings.
+ * `limit` bounds the buckets, so a refusal costs one row more than the ceiling.
+ */
+export const seriesStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  shape: ReadShape,
+  series: { readonly on: string; readonly unit: string; readonly timeZone: string },
+  sumColumn: string | null,
+  limit: number,
+): SqlFragment => {
+  const on = columnRef(entity, series.on);
+  const bucket = sql`date_trunc(${series.unit}::text, ${on}, ${series.timeZone}::text)`;
+  const value = sumColumn === null ? sql`null` : sql`sum(${columnRef(entity, sumColumn)})::text`;
+  return sql`select extract(epoch from ${bucket}) * 1000 as bucket_ms, count(*) as bucket_count, ${value} as bucket_value from ${identifier(
+    entity.$table,
+  )} where ${conditions(entity, plan, shape)} and ${on} is not null group by 1 order by 1 limit ${limit}`;
+};

package/src/pg-sql.ts

@@ -56,11 +56,27 @@ const searchSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFragm
   return sql`${column} @@ websearch_to_tsquery(${raw(`'${vector.language}'`)}, ${String(term)})`;
 };
 
+/**
+ * The path a predicate's column resolves through. A NULL test on a whole money property asks about
+ * its amount, the one thing that is NULL when the money is: memory answers it off the property, and
+ * resolving the property here refused it. An amount compared whole stays refused: no single column
+ * holds one, so naming a part is the caller's to do.
+ */
+const nullTestPath = <Row>(entity: EntityCore<Row>, predicate: Predicate): string => {
+  const asksNull =
+    predicate.op === 'is-null' ||
+    predicate.op === 'is-not-null' ||
+    ((predicate.op === 'eq' || predicate.op === 'neq') && predicate.value === null);
+  return asksNull && columnFor(entity.$columns, predicate.column)?.$meta.kind === 'money'
+    ? `${predicate.column}.minor`
+    : predicate.column;
+};
+
 const predicateSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFragment => {
   // BEFORE the column is resolved: a `matches` predicate names `SEARCH_PROPERTY`, which is not a
   // column and must never be looked up as one.
   if (predicate.op === 'matches') return searchSql(entity, predicate);
-  const column = columnRef(entity, predicate.column);
+  const column = columnRef(entity, nullTestPath(entity, predicate));
   const value = predicate.value;
   switch (predicate.op) {
     case 'eq':