@ultimat3/entity 11.3.0 → 13.0.0

package/src/tenancy.ts

@@ -13,6 +13,18 @@ import {
 } from './errors';
 import type { ColumnMap } from './types';
 
+/**
+ * The predicate vocabulary, closed. The last four are the CONTAINMENT half, added 2026-08-24: a
+ * `json()` or `arrayOf()` column was declared, written and then unfilterable — the ten operators
+ * before them could compare a column to a scalar and nothing else — so an app storing either had
+ * to leave the query language for hand-written SQL, which is the one read path in this framework
+ * with no tenancy guard on it. Their meaning is Postgres', written once in `containment.ts` and
+ * read by both drivers.
+ *
+ * There is deliberately no jsonpath EXPRESSION operator beside them: `contains` already matches
+ * nested structure (`data @> '{"a":{"b":1}}'`), and a path language inside the query language
+ * would be a second way to ask one question.
+ */
 export type Operator =
   | 'eq'
   | 'neq'
@@ -23,7 +35,16 @@ export type Operator =
   | 'lte'
   | 'like'
   | 'is-null'
-  | 'is-not-null';
+  | 'is-not-null'
+  | 'contains'
+  | 'contained-by'
+  | 'overlaps'
+  | 'has-key'
+  // The FULL-TEXT half, added 2026-08-24. `column` is not a column: it is `SEARCH_PROPERTY`, and
+  // both drivers branch on the OPERATOR and read the entity's own `$search` — a `tsvector` is a
+  // physical column no row carries, so resolving it as a property would be a lie in two places.
+  // The operand is a search TERM, always bound, never parsed as tsquery syntax.
+  | 'matches';
 
 export interface Predicate {
   readonly column: string;
@@ -195,7 +216,7 @@ const verifyScope = (
  * every repository operation through `readPlan`, so both drivers and every read, write and count
  * pass through this one derivation.
  *
- * Runtime only. There is no build-time tenancy step in `x verify` — its 17 steps check none — and
+ * Runtime only. There is no build-time tenancy step in `x verify` — its 20 steps check none — and
  * there cannot usefully be one: the tenant is a request-time value, so a compiler could only prove
  * that some argument was passed, which is exactly the thing that was never a guarantee. That is
  * why this is the seam every plan is built through rather than a lint.

package/src/transition.ts

@@ -0,0 +1,119 @@
+// One atomic move of one row through its column's state machine: the legality question answered
+// from the declaration, the move made by a single conditional statement, and the diagnosis of a
+// statement that matched nothing. Split from `query.ts` for the line ceiling and because this is
+// the one write whose refusal is a READ — see `diagnose`.
+
+import { columnFor } from './column';
+import type { EntityCore } from './entity';
+import { notFound } from './errors';
+import type { IllegalTransition } from './feature-errors';
+import { stateConflict, stateTransitionIllegal, stateUndeclared } from './feature-errors';
+import type { Repo, RepoOptions } from './repo';
+import { canMove, isState, isTerminal, movesFrom, type StateMachine } from './state-machine';
+import type { ColumnMap, IdOf, RowPatch } from './types';
+
+/** What a caller names: the state it believes the row is in, and the one it wants. */
+export interface Move<S extends string = string> {
+  readonly from: S;
+  readonly to: S;
+}
+
+/** Every property whose column declares a machine — what `X_STATE_UNDECLARED` lists back. */
+export const machineColumns = <Row, C extends ColumnMap>(
+  entity: EntityCore<Row, C>,
+): readonly string[] =>
+  Object.entries(entity.$columns)
+    .filter(([, column]) => column.$meta.machine !== undefined)
+    .map(([property]) => property);
+
+/**
+ * The machine on a named column, or the refusal. `columnFor` and not `$columns[property]`: the name
+ * is caller data on this path, and a plain read answers an `Object.prototype` member.
+ */
+export const machineFor = <Row, C extends ColumnMap>(
+  entity: EntityCore<Row, C>,
+  property: string,
+): StateMachine => {
+  const machine = columnFor(entity.$columns, property)?.$meta.machine;
+  if (machine === undefined) {
+    throw stateUndeclared(entity.$name, property, machineColumns(entity));
+  }
+  return machine;
+};
+
+/**
+ * Why the statement matched no row, asked only once it already has.
+ *
+ * A read AFTER the decision, never before one: the conditional update is what refused, and this
+ * exists so the refusal carries the state the row is really in instead of "0 rows". It is
+ * tenant-scoped like every other read, so a row belonging to another org reads as absent and the
+ * caller is told `X_NOT_FOUND` — which is the truth available to them, and the only answer that
+ * does not confirm the row exists somewhere.
+ */
+const diagnose = async <Row>(
+  entity: EntityCore<Row>,
+  repo: Repo<Row>,
+  property: string,
+  id: IdOf<Row>,
+  move: Move,
+  options: RepoOptions | undefined,
+): Promise<Error> => {
+  const row = await repo.findById(id, options);
+  if (row === null) return notFound(entity.$name, String(id));
+  const actual = (row as Readonly<Record<string, unknown>>)[property];
+  return stateConflict(entity.$name, property, String(id), move.from, String(actual));
+};
+
+const whyNot = (machine: StateMachine, move: Move): IllegalTransition => {
+  if (!isState(machine, move.from)) return { reason: 'unknown-state', states: machine.states };
+  if (isTerminal(machine, move.from)) return { reason: 'terminal' };
+  return { reason: 'not-declared', legal: movesFrom(machine, move.from) };
+};
+
+/**
+ * The move, made by ONE statement.
+ *
+ * The predicate carries the state the caller expects, so the state that was OBSERVED and the state
+ * that was WRITTEN are one decision the database made under its own row lock. A read-then-check-
+ * then-write is the same code with a window in it: two callers both read `pending`, both find the
+ * move legal, and both write — and the second write is a transition out of a state the row had
+ * already left. Here the second statement's `status = 'pending'` matches nothing, and no rows is
+ * the refusal.
+ *
+ * The legality question is answered before the statement rather than inside it, because the
+ * transition table is not in the database and does not belong there: it is a property of the
+ * declaration, so an illegal move is refused without a round trip and without touching the row.
+ *
+ * The row is READ BACK afterwards rather than returned by the statement. `updateWhere` answers a
+ * count in both drivers, and a second read is honest about what it is — the row as it stands now,
+ * which is the row this call moved unless something moved it again, and something moving it again
+ * is exactly what this design permits and reports.
+ */
+export const transitionRow = async <Row, C extends ColumnMap>(
+  entity: EntityCore<Row, C>,
+  repo: Repo<Row>,
+  property: string,
+  id: IdOf<Row>,
+  move: Move,
+  patch: (values: RowPatch<Row>) => RowPatch<Row>,
+  options: RepoOptions | undefined,
+): Promise<Row> => {
+  const machine = machineFor(entity, property);
+  if (!canMove(machine, move.from, move.to)) {
+    // Asked in this order and no other: an unknown state is terminal-looking (no outgoing moves)
+    // and a terminal state is legal-list-looking (an empty list), so a check that skipped either
+    // one would answer a true sentence about the wrong thing.
+    throw stateTransitionIllegal(entity.$name, property, move.from, move.to, whyNot(machine, move));
+  }
+  // `as unknown as`, and the double step is the honest one: `RowPatch<Row>` is a mapped type over
+  // 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>;
+  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);
+  const row = await repo.findById(id, options);
+  if (row === null) throw notFound(entity.$name, String(id));
+  return row;
+};

package/src/types.ts

@@ -6,6 +6,8 @@
 // A column carries its TypeScript type in `$parse`, which is what lets the row type be derived
 // from the column set instead of being written a second time as a hand-maintained schema.
 
+import type { IndexMethod } from '@ultimat3/db';
+
 /**
  * Postgres types the builders emit. `money` expands to `bigint` + `char(3)` (+ a nullable
  * `integer` scale); `array` expands to its element's type with `[]` after it.
@@ -46,6 +48,13 @@ export type ColumnDefault =
 
 export type OnDelete = 'cascade' | 'restrict' | 'set null';
 
+/**
+ * A source column's contribution to the entity's search vector — Postgres' own four labels, which
+ * `ts_rank` weights `{D, C, B, A}` = `{0.1, 0.2, 0.4, 1.0}` by default. `D` is what an unweighted
+ * `to_tsvector` produces, so it is the default here too.
+ */
+export type SearchWeight = 'A' | 'B' | 'C' | 'D';
+
 export interface ReferenceOptions {
   readonly onDelete?: OnDelete;
 }
@@ -61,6 +70,7 @@ export interface ReferenceOptions {
  * `t.money` — the schema node that becomes the OpenAPI contract — rejected the framework's own row.
  */
 import type { MoneyValue } from '@ultimat3/schema';
+import type { StateMachine, TransitionTable } from './state-machine';
 
 export type { MoneyValue };
 
@@ -131,6 +141,20 @@ export interface ColumnMeta {
   /** A thunk: schema modules reference each other in a cycle. */
   readonly references?: () => AnyColumn;
   readonly onDelete?: OnDelete;
+  /**
+   * Presence is what puts this column in the entity's generated `tsvector`, and the value is its
+   * weight. A modifier and not a column of its own: the vector is derived from every searchable
+   * column at once (`search.ts`), so declaring it per column would be one vector per column and
+   * one GIN index per column.
+   */
+  readonly searchable?: SearchWeight;
+  /**
+   * The state machine this column's values move through, when one was declared. Built once at
+   * declaration (`stateMachineOf`) so an illegal table is a refusal where it was written, and held
+   * as the built machine rather than the literal table because the literal is an object a caller
+   * indexes by a data key.
+   */
+  readonly machine?: StateMachine;
 }
 
 /**
@@ -157,6 +181,34 @@ export interface Column<T, Optional extends boolean = false> {
    * override it to keep theirs, and nothing else has any.
    */
   column(name: string): Column<T, Optional>;
+  /**
+   * Adds this column to the entity's one generated `tsvector`, at `weight` (default `D`). Text
+   * only — every other kind is refused here, where the chain was written.
+   */
+  searchable(weight?: SearchWeight): Column<T, Optional>;
+}
+
+/**
+ * `enumerated()`'s own column: the one that may declare a state machine, because it is the one
+ * that already declares a closed set of values for the machine to move through.
+ *
+ * The links below are overridden for the reason `UuidColumn`'s and `TimestampColumn`'s are — the
+ * generic chain answers the general `Column`, so `enumerated(S).default('draft')` would lose
+ * `transitions` and `enumerated(S).transitions(T).column('c')` would lose the machine's own type.
+ */
+export interface EnumeratedColumn<V extends readonly string[], Optional extends boolean = false>
+  extends Column<V[number], Optional> {
+  /**
+   * Declares which values may follow which. The states are `V` — this column's own — so the
+   * framework never names one: a missing state, an unknown key and an unknown target are each a
+   * compile error against the set the app already wrote.
+   *
+   * A state machine column may not be nullable: NULL is not a state, so nothing could say what it
+   * may move to.
+   */
+  transitions(table: TransitionTable<V[number]>): EnumeratedColumn<V, Optional>;
+  default(value: V[number]): EnumeratedColumn<V, true>;
+  column(name: string): EnumeratedColumn<V, Optional>;
 }
 
 /**
@@ -268,4 +320,12 @@ export interface IndexDef {
   readonly order?: 'asc' | 'desc';
   /** Partial index predicate — a soft-deleted row is excluded with this. */
   readonly where?: string;
+  /**
+   * The access method. Absent is `btree`, which is Postgres' own default and what every index
+   * declared before this field existed is — so an entity that names none emits the statement it
+   * always emitted, byte for byte, and no app's sidecar regenerates. `@ultimat3/db` owns the
+   * closed set (`INDEX_METHODS`); redeclaring the union here would be the second declaration of
+   * one fact that this release exists to stop.
+   */
+  readonly using?: IndexMethod;
 }