@ultimat3/entity 11.3.0 → 13.0.0

package/src/feature-errors.ts

@@ -0,0 +1,121 @@
+// The refusals the two DECLARED capabilities raise at call time — full-text search and a state
+// machine. Split from `errors.ts` at the 500-line ceiling; the codes and their titles stay there,
+// because a registry with two homes is a registry that disagrees with itself.
+
+import { EntityError } from './errors';
+
+/**
+ * A `matches` predicate on an entity whose columns declare no `.searchable()`.
+ *
+ * Raised where the STATEMENT would be built, not where the chain was written, because both drivers
+ * reach it: an entity's search vector is derived from its columns, so there is nothing else the
+ * predicate could name and no vector to guess at.
+ */
+export const searchUndeclared = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_SEARCH_UNDECLARED',
+    cause: `${entityName} has no searchable column, so there is no tsvector to match against`,
+    fix: `add .searchable() to a text() column of ${entityName}, then: x db gen "search ${entityName}"`,
+  });
+
+/**
+ * A full-text match asked of `memoryDriver()`. REFUSED rather than emulated, and that is the whole
+ * decision: `to_tsvector` stems, drops stop words and applies a language's own rules, and
+ * `websearch_to_tsquery` parses quoted phrases and `-`negation — a JS token comparison is a
+ * DIFFERENT question with the same shape, so it would answer green in a unit test and differently
+ * in production, which is the one outcome the two-driver split exists to prevent.
+ */
+export const searchInMemory = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_SEARCH_IN_MEMORY',
+    cause: `memoryDriver() cannot stem, weight or rank a tsvector, so a search of ${entityName} has no answer it could give that Postgres would agree with`,
+    fix: `move this read into a <name>.live.test.ts and run it with TEST_DATABASE_URL set — bun test packages/entity/src/pg-search.live.test.ts is the model`,
+  });
+
+/**
+ * `transition()` on a column that declares no `.transitions()`.
+ *
+ * A declaration bug and not a caller's, which is why it lists the columns that DO declare one: the
+ * repair is naming a different column or writing the table, and both are edits to source.
+ */
+export const stateUndeclared = (
+  entityName: string,
+  column: string,
+  machines: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_STATE_UNDECLARED',
+    cause: `${entityName}.${column} declares no state machine, so there is no transition to check`,
+    fix:
+      machines.length === 0
+        ? `add .transitions(…) to ${entityName}.${column} — it must be an enumerated() column, and every value that set declares needs an entry`
+        : `${entityName} declares a machine on: ${machines.join(', ')}`,
+  });
+
+/**
+ * Why a move is not in the machine. THREE conditions and one code, because they share one repair —
+ * the move is not in the table — and each states its own fact, because they are not the same
+ * mistake and the fix line differs.
+ *
+ * `unknown-state` is separate from `terminal` for a reason a test found: an unknown state has no
+ * outgoing moves either, so a single "no legal moves" branch reported a typo as "the row is
+ * terminal in <typo>" — a sentence about a state that does not exist. Reachable from JS, and from
+ * a `from` that came out of parsed JSON.
+ *
+ * `terminal` is separate from the ordinary case because "no legal moves" reads like a missing
+ * declaration and is not one: an empty list is how a terminal state is written.
+ */
+export type IllegalTransition =
+  | { readonly reason: 'unknown-state'; readonly states: readonly string[] }
+  | { readonly reason: 'terminal' }
+  | { readonly reason: 'not-declared'; readonly legal: readonly string[] };
+
+export const stateTransitionIllegal = (
+  entityName: string,
+  column: string,
+  from: string,
+  to: string,
+  detail: IllegalTransition,
+): EntityError => {
+  const subject = `${entityName}.${column}`;
+  if (detail.reason === 'unknown-state') {
+    return new EntityError({
+      code: 'X_STATE_TRANSITION_ILLEGAL',
+      cause: `"${from}" is not a state of ${subject} — it declares: ${detail.states.join(' | ')}`,
+      fix: `${entityName}.transition('${column}', id, { from: '${detail.states[0] ?? from}', to: '${to}' })   # name a state the enumerated() set declares`,
+    });
+  }
+  if (detail.reason === 'terminal') {
+    return new EntityError({
+      code: 'X_STATE_TRANSITION_ILLEGAL',
+      cause: `${subject} is terminal in "${from}": the machine declares no move out of it, so "${to}" is not one`,
+      fix: `move the row before it reaches "${from}", or add "${to}" to the "${from}" entry of the transitions() table`,
+    });
+  }
+  return new EntityError({
+    code: 'X_STATE_TRANSITION_ILLEGAL',
+    cause: `${subject} has no move from "${from}" to "${to}" — from "${from}" it may go to: ${detail.legal.join(', ')}`,
+    fix: `${entityName}.transition('${column}', id, { from: '${from}', to: '${detail.legal[0]}' })   # or add "${to}" to the "${from}" entry of the transitions() table`,
+  });
+};
+
+/**
+ * The conditional update matched no row, and the row is in a different state than the caller named.
+ *
+ * This is the lost update, caught: two callers both read "pending", both found the move legal, and
+ * the second one's statement carried `status = 'pending'` in its predicate and matched nothing. The
+ * state in the cause is READ BACK after the refusal, so it is a diagnosis and never the decision —
+ * the decision was the statement, and it was atomic.
+ */
+export const stateConflict = (
+  entityName: string,
+  column: string,
+  id: string,
+  expected: string,
+  actual: string,
+): EntityError =>
+  new EntityError({
+    code: 'X_STATE_CONFLICT',
+    cause: `${entityName}.${column} named "${expected}" for row ${id}, which is in "${actual}" — something moved it first`,
+    fix: `re-read the row and decide again against "${actual}": ${entityName}.findById(id) — a transition names the state it expects, so a stale read is refused rather than overwritten`,
+  });

package/src/index-name.ts

@@ -0,0 +1,83 @@
+// What an index is CALLED. Split out of `entity.ts` at the 500-line ceiling, and it is one job:
+// two indexes that differ only in their predicate, their direction or their access method must not
+// share a name, and no name may cross the 63 bytes Postgres silently truncates at.
+
+import type { IndexMethod } from '@ultimat3/db';
+import { invariantViolated } from './errors';
+
+/**
+ * What separates two indexes on the SAME columns: the predicate, the direction and the ACCESS
+ * METHOD. Eight hex characters of sha256 over all three — deterministic across processes, so a
+ * name is a property of the declaration and never of the run that generated it.
+ *
+ * The method belongs here for exactly the reason `where` does. A btree on an `arrayOf()` column
+ * answers `=` and an ordering; a GIN on the same column answers `@>` / `<@` / `&&`. They are two
+ * distinct indexes, and without the method in the name both are `<table>_<cols>_idx` — where the
+ * dedup below drops one in silence (the defect this discriminator was added for) or, since that
+ * dedup is now on the whole definition, two `create index` statements share one name and the
+ * migration is `42P07`.
+ */
+const indexDiscriminator = (
+  order: string | undefined,
+  where: string | null,
+  using: string | undefined,
+): string =>
+  new Bun.CryptoHasher('sha256')
+    // The method is APPENDED only when one was declared, never as an empty field: every name this
+    // function has ever minted for a partial or ordered index is therefore unchanged by the method
+    // existing, and an index that declares no method is byte-identical to the one it was.
+    .update(`${order ?? ''}|${where ?? ''}${using === undefined ? '' : `|${using}`}`)
+    .digest('hex')
+    .slice(0, 8);
+
+/**
+ * `<table>_<columns>_idx`, plus a discriminator when — and only when — the index carries a
+ * predicate, a direction or a non-default access method.
+ *
+ * Only then, because the plain name is load-bearing in two places: `unique()` on a column is an
+ * inline column clause and Postgres names the index it creates exactly `<table>_<column>_key`, so
+ * a discriminator there would make the generator emit a second `create unique index` for an index
+ * that already exists (`42P07`); and a foreign key's own index is deduped against a hand-declared
+ * one by this name.
+ *
+ * Without it, two DIFFERENT partial indexes on one column were one name — `posts_author_id_idx`
+ * for both `where status = 'published'` and `where status = 'draft'` — and the dedup below dropped
+ * the second with no error, no warning and no drift finding, since a declared index is matched by
+ * name.
+ */
+/**
+ * `NAMEDATALEN - 1`. Postgres truncates a longer identifier and says NOTHING, so two index names
+ * sharing their first 63 bytes become one index on the server — the same silent collapse the
+ * discriminator above exists to prevent, one layer down, and invisible to a drift check comparing
+ * DECLARED names because those still differ. Bytes and not characters: 63 is what the server
+ * counts, and `.length` would stop seeing the truncation the moment a name is not ASCII.
+ */
+const MAX_IDENTIFIER_BYTES = 63;
+
+const byteLength = (value: string): number => new TextEncoder().encode(value).length;
+
+export const indexName = (
+  entityName: string,
+  table: string,
+  columns: readonly string[],
+  unique: boolean,
+  order?: string | undefined,
+  where: string | null = null,
+  using?: IndexMethod | undefined,
+): string => {
+  const suffix = unique ? 'key' : 'idx';
+  const base = `${table}_${columns.join('_')}`;
+  const plain = order === undefined && where === null && using === undefined;
+  const name = plain
+    ? `${base}_${suffix}`
+    : `${base}_${indexDiscriminator(order, where, using)}_${suffix}`;
+  const bytes = byteLength(name);
+  if (bytes <= MAX_IDENTIFIER_BYTES) return name;
+  throw invariantViolated(
+    entityName,
+    'index',
+    `the index on (${columns.join(', ')}) is named "${name}", which is ${bytes} bytes — ` +
+      `Postgres truncates an identifier at ${MAX_IDENTIFIER_BYTES} and does not say so, ` +
+      'so two indexes can silently become one',
+  );
+};

package/src/index.ts

@@ -3,6 +3,8 @@
 /** Re-exported so an `entity` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
+export type { AggregateFn } from './aggregate';
+export { AVG_SCALE } from './aggregate';
 export type { BatchIterator } from './batch';
 export type { MoneyColumns } from './column';
 export { columnName, moneyColumns, snake } from './column';
@@ -20,9 +22,6 @@ export {
   url,
   uuid,
 } from './columns';
-// The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
-// are decisions this framework made for a table it was going to create, and these are the shapes
-// a table already has (`docs`: Entities-And-Migrations, "Adopting an existing database").
 export type { DecimalOptions } from './columns-data';
 export { arrayOf, bigint, bytes, date, decimal, json } from './columns-data';
 // `crossTenantReason` stays internal: an app that could read the flag would have a second way to
@@ -34,6 +33,9 @@ export type { DescribeInput } from './describe';
 export { sqlTypeOf } from './describe';
 export type { Entity, EntityCore, EntityInit, IndexInit } from './entity';
 export { entity, SOFT_DELETE_COLUMN } from './entity';
+// The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
+// are decisions this framework made for a table it was going to create, and these are the shapes
+// a table already has (`docs`: Entities-And-Migrations, "Adopting an existing database").
 export type {
   EntityErrorCode,
   PreloadCandidate,
@@ -63,6 +65,15 @@ export {
   writeUnfiltered,
 } from './errors';
 export type { ColumnExpr, Expr, InvariantColumns, Resolve } from './expr';
+/** The two DECLARED capabilities' refusals — a third-party driver raises the same ones. */
+export type { IllegalTransition } from './feature-errors';
+export {
+  searchInMemory,
+  searchUndeclared,
+  stateConflict,
+  stateTransitionIllegal,
+  stateUndeclared,
+} from './feature-errors';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
 export {
   assertInvariants,
@@ -72,6 +83,7 @@ export {
   MAX_ASSERTED_ROWS,
   toSql,
 } from './invariants';
+export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
 export type { PostgresDriverOptions } from './pg-driver';
@@ -111,9 +123,22 @@ export type {
   Tx,
   UpsertArgs,
 } from './repo';
-export { memoryRepo, memoryTransactor } from './repo';
 export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-observer';
 export { observedRepo, rowObserver, setRowObserver } from './row-observer';
+// Full-text search. The LANGUAGE set and the weights are values an app reads to build a form;
+// `SEARCH_PROPERTY` is what a `matches` predicate names, which a hand-built `QueryPlan` needs.
+export type { SearchInit, SearchLanguage, SearchSource, SearchVector } from './search';
+export {
+  DEFAULT_SEARCH_COLUMN,
+  DEFAULT_SEARCH_LANGUAGE,
+  DEFAULT_SEARCH_WEIGHT,
+  isSearchLanguage,
+  isSearchWeight,
+  SEARCH_LANGUAGES,
+  SEARCH_PROPERTY,
+  SEARCH_WEIGHTS,
+  searchExpression,
+} from './search';
 export type {
   Seed,
   SeedContext,
@@ -126,6 +151,16 @@ export type {
   SeedWrite,
 } from './seed';
 export { defineSeed, isSeed, SEED_TIERS, seedId, seedTiersFor } from './seed';
+// A state machine over a column. The MECHANISM only: the table, the refusal, the terminal concept.
+// The states are the app's `enumerated()` set and nothing here names one.
+export type { StateMachine, TransitionTable } from './state-machine';
+export {
+  canMove,
+  isState,
+  isTerminal,
+  movesFrom,
+  stateMachineOf,
+} from './state-machine';
 export type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
 export {
   assertRowTenant,
@@ -139,6 +174,7 @@ export {
   scopedPlan,
   tenantColumnOf,
 } from './tenancy';
+export type { Move } from './transition';
 export type {
   AnyColumn,
   Column,
@@ -146,6 +182,7 @@ export type {
   ColumnKind,
   ColumnMap,
   ColumnMeta,
+  EnumeratedColumn,
   IdOf,
   IndexDef,
   Insertable,
@@ -156,6 +193,7 @@ export type {
   ReferenceOptions,
   RowOf,
   RowPatch,
+  SearchWeight,
   TimestampColumn,
   TypeOf,
   UuidColumn,

package/src/instant.ts

@@ -0,0 +1,93 @@
+// Single responsibility: a `timestamptz` value at the precision the COLUMN stores it, rather than
+// the precision a JS `Date` holds. The column keeps microseconds and a `Date` keeps milliseconds,
+// so a page position minted from a decoded row ranks rows differently from the `order by` that
+// produced them. Microseconds since the epoch is the one form both sides can be exact in, and this
+// file is the only place the two representations meet.
+
+/** A `Date` is exactly this much coarser than the column it came out of. */
+const MICROS_PER_MILLI = 1000n;
+
+const MICROS_PER_SECOND = 1_000_000n;
+
+const FRACTION_DIGITS = 6;
+
+/**
+ * What `(col at time zone 'UTC')::text` prints: `2026-01-01 00:00:00.123456`, with the fraction
+ * omitted entirely when every digit of it is zero and TRUNCATED when the trailing ones are —
+ * `.1` is a tenth of a second, not one microsecond, which is why the fraction is padded on the
+ * right and never on the left.
+ *
+ * The year is `\d{4,}` because Postgres prints one wider than four digits unpadded; a `BC` suffix
+ * matches nothing here on purpose, and an unmatched text falls back to the decoded `Date`.
+ */
+const PG_INSTANT_TEXT = /^(\d{4,})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?$/;
+
+/**
+ * `Date.UTC` maps years 0–99 into the 1900s, so the epoch is built by assignment instead. Whole
+ * seconds only: the fraction is added in the microsecond domain, where it is exact.
+ */
+const utcSecondMillis = (parts: readonly number[]): number => {
+  const [year = 0, month = 1, day = 1, hour = 0, minute = 0, second = 0] = parts;
+  const at = new Date(0);
+  at.setUTCFullYear(year, month - 1, day);
+  at.setUTCHours(hour, minute, second, 0);
+  return at.getTime();
+};
+
+/** Floor division: `-1n / 2n` truncates toward zero, which would place a pre-1970 instant late. */
+const floorDiv = (value: bigint, by: bigint): bigint => {
+  const remainder = ((value % by) + by) % by;
+  return (value - remainder) / by;
+};
+
+/**
+ * The exact microsecond epoch of a `timestamptz` Postgres rendered as text, or `undefined` when
+ * the text is not one — a caller with nothing to read falls back to the decoded `Date`, which is
+ * the position it always had.
+ */
+export const pgInstantMicros = (text: unknown): bigint | undefined => {
+  if (typeof text !== 'string') return undefined;
+  const match = PG_INSTANT_TEXT.exec(text);
+  if (match === null) return undefined;
+  const [, year = '', month = '', day = '', hour = '', minute = '', second = '', fraction] = match;
+  const millis = utcSecondMillis([year, month, day, hour, minute, second].map(Number));
+  if (!Number.isFinite(millis)) return undefined;
+  // The fraction is always forward in time, so it ADDS even when the second boundary is negative.
+  return BigInt(millis) * MICROS_PER_MILLI + BigInt((fraction ?? '').padEnd(FRACTION_DIGITS, '0'));
+};
+
+/**
+ * The microsecond epoch of whatever a sort key is holding: a decoded row's `Date` (milliseconds,
+ * so the last three digits are zero), a value already counted in microseconds, or the decimal a
+ * cursor carries. `undefined` for anything else, so a caller decides rather than guessing at `0`.
+ */
+export const instantMicros = (value: unknown): bigint | undefined => {
+  if (typeof value === 'bigint') return value;
+  if (value instanceof Date) {
+    const millis = value.getTime();
+    return Number.isNaN(millis) ? undefined : BigInt(millis) * MICROS_PER_MILLI;
+  }
+  if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
+  return undefined;
+};
+
+/**
+ * The instant a seek binds, spelled so Postgres parses it back to the same microsecond. ISO 8601
+ * in UTC with all six fraction digits — `toISOString()` alone is milliseconds, which is the whole
+ * defect this file exists to close, so the fraction is written here rather than read off the
+ * `Date`.
+ */
+export const microsToIso = (micros: bigint): string => {
+  const second = floorDiv(micros, MICROS_PER_SECOND);
+  const fraction = micros - second * MICROS_PER_SECOND;
+  const whole = new Date(Number(second) * 1000).toISOString();
+  return `${whole.slice(0, whole.indexOf('.'))}.${String(fraction).padStart(FRACTION_DIGITS, '0')}Z`;
+};
+
+/**
+ * The output name the microsecond half of a sort key comes back under. Every physical column name
+ * in this framework is lower case — `columnName` is either `snake(property)`, which lower-cases,
+ * or a `.column()` name `assertColumnName` refuses unless it matches `[a-z_][a-z0-9_$]*` — so an
+ * UPPER-CASE suffix is a name no entity can declare and this alias can never shadow a column.
+ */
+export const seekAlias = (physicalColumn: string): string => `${physicalColumn}$US`;

package/src/memory-match.ts

@@ -6,9 +6,12 @@
 
 import { compareDecimalText } from '@ultimat3/core';
 import { keyOf } from './batch-read';
+import { arrayContains, arrayOverlaps, jsonContains, jsonHasKey } from './containment';
 import { kindOf, valueAt } from './cursor';
 import type { EntityCore } from './entity';
 import { EntityError } from './errors';
+import { searchInMemory } from './feature-errors';
+import { instantMicros } from './instant';
 import type { Predicate } from './tenancy';
 import type { ColumnKind } from './types';
 
@@ -46,6 +49,25 @@ export const compareByKind = (
   left: unknown,
   right: unknown,
 ): number => {
+  // NULL is the LARGEST value, which is what `order by` means in Postgres and what `nulls last`
+  // ascending / `nulls first` descending spell out (`pg-sql.ts`'s `orderSql`, `@ultimat3/query`'s
+  // `compareValues`). Two absences are equal, so the next sort key decides — without this rule a
+  // NULL fell through to `String(left) < String(right)` and sorted as the four characters `null`,
+  // somewhere in the middle of the alphabet, which is a different listing from the one the
+  // database returns and a page boundary cut where the server cuts none.
+  if (isNull(left) || isNull(right)) {
+    return isNull(left) && isNull(right) ? 0 : isNull(left) ? 1 : -1;
+  }
+  // A `timestamptz` is compared in MICROSECONDS, which is what the column holds and what a cursor
+  // now carries (`cursor.ts`). The two sides are not the same shape and that is the point: a
+  // stored row here is a `Date` and a keyset position is a microsecond count, so a `Date`/`Date`
+  // test alone would fall through to `String(left) < String(right)` and order a page by the text
+  // of an ISO string against a decimal.
+  if (kind === 'timestamptz') {
+    const before = instantMicros(left);
+    const after = instantMicros(right);
+    if (before !== undefined && after !== undefined) return sign(before, after);
+  }
   if (left instanceof Date && right instanceof Date) return sign(left.getTime(), right.getTime());
   if (kind !== undefined && DECIMAL_TEXT.has(kind)) {
     // `undefined` when either side is not a plain decimal — that pair is not a numeric comparison,
@@ -137,6 +159,10 @@ export const matchesPredicate = <Row>(
   row: unknown,
   predicate: Predicate,
 ): boolean => {
+  // BEFORE anything is read off the row. A full-text match has no in-memory meaning — see
+  // `searchInMemory` — and `valueAt(row, '$search')` would answer `undefined`, which every
+  // comparison below reads as NULL and silently turns into "no rows".
+  if (predicate.op === 'matches') throw searchInMemory(entity.$name);
   // The column's declared kind, resolved once — `price.minor` included, which is the path a money
   // predicate and a money sort key both name.
   const kind = kindOf(entity, predicate.column);
@@ -199,5 +225,51 @@ export const matchesPredicate = <Row>(
       return isNull(actual);
     case 'is-not-null':
       return !isNull(actual);
+    // The containment half, decided by the column's DECLARED kind exactly as everything above it
+    // is: `@>` on a `jsonb` is recursive structural containment and `@>` on an array is plain
+    // element containment, and those are two different operators that happen to share a symbol.
+    // A NULL column value matches nothing, which is what the SQL answers too.
+    case 'contains':
+      return !isNull(actual) && containsBy(kind, actual, predicate.value);
+    case 'contained-by':
+      return !isNull(actual) && containsBy(kind, predicate.value, actual);
+    // `&&` is arrays only. A `jsonb` column reaching it is refused rather than guessed at: there
+    // is no `jsonb && jsonb` in Postgres, so any answer here would be one no statement can make.
+    case 'overlaps':
+      return (
+        !isNull(actual) &&
+        arrayOverlaps(
+          asArray(entity, predicate, actual),
+          asArray(entity, predicate, predicate.value),
+        )
+      );
+    case 'has-key':
+      return jsonHasKey(actual, predicate.value);
+  }
+};
+
+/** `left @> right`, under the rule the LEFT column's kind decides. */
+const containsBy = (kind: ColumnKind | undefined, left: unknown, right: unknown): boolean =>
+  kind === 'jsonb'
+    ? jsonContains(left, right)
+    : arrayContains(Array.isArray(left) ? left : [left], Array.isArray(right) ? right : [right]);
+
+/**
+ * The operand of an array-only operator. A `jsonb` column here is the caller asking for an
+ * operator Postgres does not have on that type, so it is refused where they wrote it rather than
+ * answered with something the database never would.
+ */
+const asArray = <Row>(
+  entity: EntityCore<Row>,
+  predicate: Predicate,
+  value: unknown,
+): readonly unknown[] => {
+  if (kindOf(entity, predicate.column) === 'jsonb') {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entity.$name}.${predicate.column} is jsonb, and Postgres has no && (overlaps) operator for jsonb`,
+      fix: `${entity.$name}.andWhere('${predicate.column}', 'contains', <value>)   # @> matches nested structure; && is for arrayOf() columns`,
+    });
   }
+  return Array.isArray(value) ? value : [value];
 };