@ultimat3/entity 0.0.1 → 1.1.0

package/src/expr.ts

@@ -0,0 +1,231 @@
+// The invariant expression language. One declaration compiles to two enforcement points: a
+// predicate the app runs on every write, and the SQL predicate the migration emits.
+//
+// Expressions are written against property keys (`c.likeCount`) and resolved to physical names
+// (`like_count`) by `entity()`, because the author never writes a physical name.
+//
+// A JS predicate (`matches(isValidSlug)`, `satisfies(fn, [...])`) cannot be translated to SQL.
+// It still runs in the app, and reports `sql: null` so `x verify` can warn that the database
+// does not know this rule — silently pretending it reached Postgres would be worse.
+
+import { invariantViolated } from './errors';
+
+export type Row = Readonly<Record<string, unknown>>;
+
+/** Property path -> physical column name. */
+export type Resolve = (path: readonly string[]) => string;
+
+export interface Expr {
+  readonly kind: 'check' | 'unique';
+  readonly paths: readonly (readonly string[])[];
+  readonly message: string;
+  /** `null` when the rule is a JS predicate the database cannot be told about. */
+  toSql(resolve: Resolve): string | null;
+  holds(row: Row): boolean;
+}
+
+interface Term {
+  readonly path: readonly string[];
+  readonly label: string;
+  sql(resolve: Resolve): string;
+  read(row: Row): unknown;
+}
+
+export interface ColumnExpr {
+  /** `btrim(...)` in SQL, `.trim()` in the app — the same rule, both sides. */
+  trimmed(): ColumnExpr;
+  minLength(length: number): Expr;
+  contains(value: string): Expr;
+  /** A `RegExp` reaches the database; a function is app-only. */
+  matches(pattern: RegExp | ((value: string) => boolean)): Expr;
+  atLeast(value: number | bigint): Expr;
+  eq(value: string | number | boolean | bigint | ColumnExpr): Expr;
+  isTrue(): Expr;
+  /** Money is two physical columns; these are how a rule names one of them. */
+  readonly minor: ColumnExpr;
+  readonly currency: ColumnExpr;
+}
+
+type RowPredicate = (...values: never[]) => boolean;
+
+export type InvariantColumns = {
+  readonly [column: string]: ColumnExpr;
+} & {
+  /** Decided by the database — a single row cannot see a duplicate. */
+  unique(columns: readonly string[]): Expr;
+  /** Lifts a domain predicate over several columns. App-only by construction. */
+  satisfies(predicate: RowPredicate, columns: readonly string[]): Expr;
+};
+
+const terms = new WeakMap<ColumnExpr, Term>();
+
+const walk = (row: Row, path: readonly string[]): unknown =>
+  path.reduce<unknown>(
+    (value, key) => (typeof value === 'object' && value !== null ? (value as Row)[key] : undefined),
+    row,
+  );
+
+const literal = (value: unknown): string =>
+  typeof value === 'string' ? `'${value.replaceAll("'", "''")}'` : String(value);
+
+const check = (
+  paths: readonly (readonly string[])[],
+  message: string,
+  sql: (resolve: Resolve) => string | null,
+  holds: (row: Row) => boolean,
+): Expr => ({ kind: 'check', paths, message, toSql: sql, holds });
+
+const isColumnExpr = (value: unknown): value is ColumnExpr =>
+  typeof value === 'object' && value !== null && terms.has(value as ColumnExpr);
+
+const expr = (term: Term): ColumnExpr => {
+  const one = (
+    message: string,
+    sql: (resolve: Resolve) => string | null,
+    holds: (value: unknown) => boolean,
+  ): Expr => check([term.path], message, sql, (row) => holds(term.read(row)));
+
+  const built: ColumnExpr = {
+    trimmed: () =>
+      expr({
+        path: term.path,
+        label: `trimmed ${term.label}`,
+        sql: (resolve) => `btrim(${term.sql(resolve)})`,
+        read: (row) => {
+          const value = term.read(row);
+          return typeof value === 'string' ? value.trim() : value;
+        },
+      }),
+
+    minLength: (length) =>
+      one(
+        `${term.label} must be at least ${length} character${length === 1 ? '' : 's'}`,
+        (resolve) => `char_length(${term.sql(resolve)}) >= ${length}`,
+        (value) => typeof value === 'string' && value.length >= length,
+      ),
+
+    contains: (value) =>
+      one(
+        `${term.label} must contain ${literal(value)}`,
+        (resolve) => `position(${literal(value)} in ${term.sql(resolve)}) > 0`,
+        (actual) => typeof actual === 'string' && actual.includes(value),
+      ),
+
+    matches: (pattern) =>
+      one(
+        `${term.label} must match ${pattern instanceof RegExp ? pattern.source : pattern.name || 'the rule'}`,
+        (resolve) =>
+          pattern instanceof RegExp ? `${term.sql(resolve)} ~ ${literal(pattern.source)}` : null,
+        (value) =>
+          typeof value === 'string' &&
+          (pattern instanceof RegExp ? pattern.test(value) : pattern(value)),
+      ),
+
+    atLeast: (bound) =>
+      one(
+        `${term.label} must be at least ${bound}`,
+        (resolve) => `${term.sql(resolve)} >= ${bound}`,
+        (value) => (typeof value === 'number' || typeof value === 'bigint') && value >= bound,
+      ),
+
+    eq: (other) =>
+      isColumnExpr(other)
+        ? sameAs(term, other)
+        : one(
+            `${term.label} must equal ${literal(other)}`,
+            (resolve) => `${term.sql(resolve)} = ${literal(other)}`,
+            (value) => value === other,
+          ),
+
+    isTrue: () =>
+      one(
+        `${term.label} must be true`,
+        (resolve) => term.sql(resolve),
+        (value) => value === true,
+      ),
+
+    get minor() {
+      return part(term, 'minor');
+    },
+    get currency() {
+      return part(term, 'currency');
+    },
+  };
+
+  terms.set(built, term);
+  return built;
+};
+
+const part = (term: Term, key: string): ColumnExpr =>
+  expr({
+    path: [...term.path, key],
+    label: `${term.label}.${key}`,
+    sql: (resolve) => resolve([...term.path, key]),
+    read: (row) => walk(row, [...term.path, key]),
+  });
+
+const sameAs = (left: Term, other: ColumnExpr): Expr => {
+  const right = terms.get(other);
+  if (right === undefined) throw invariantViolated('invariant', 'eq', 'not a column expression');
+  return check(
+    [left.path, right.path],
+    `${left.label} must equal ${right.label}`,
+    (resolve) => `${left.sql(resolve)} = ${right.sql(resolve)}`,
+    (row) => left.read(row) === right.read(row),
+  );
+};
+
+const columnTerm = (property: string): Term => ({
+  path: [property],
+  label: property,
+  sql: (resolve) => resolve([property]),
+  read: (row) => row[property],
+});
+
+const unique = (columns: readonly string[]): Expr => ({
+  kind: 'unique',
+  paths: columns.map((column) => [column]),
+  message: `${columns.join(', ')} must be unique`,
+  toSql: (resolve) => columns.map((column) => resolve([column])).join(', '),
+  // A single row cannot see a duplicate: the unique index is the authority.
+  holds: () => true,
+});
+
+const satisfies = (predicate: RowPredicate, columns: readonly string[]): Expr =>
+  check(
+    columns.map((column) => [column]),
+    `${columns.join(', ')} must satisfy ${predicate.name || 'the rule'}`,
+    () => null,
+    (row) =>
+      Reflect.apply(
+        predicate,
+        undefined,
+        columns.map((column) => row[column]),
+      ) === true,
+  );
+
+/**
+ * The `c` an invariant is written against. A Proxy so a typo in a column name is a
+ * declaration-time error naming the columns that do exist, not `undefined is not a function`.
+ */
+export const invariantColumns = (
+  entity: string,
+  properties: readonly string[],
+): InvariantColumns => {
+  const known = new Set(properties);
+  const helpers = { unique, satisfies };
+  return new Proxy(helpers, {
+    get(target, property) {
+      if (property === 'unique' || property === 'satisfies') return target[property];
+      if (typeof property !== 'string') return undefined;
+      if (!known.has(property)) {
+        throw invariantViolated(
+          entity,
+          'invariant',
+          `no column "${property}"; declared columns are ${properties.join(', ')}`,
+        );
+      }
+      return expr(columnTerm(property));
+    },
+  }) as InvariantColumns;
+};

package/src/index.ts

@@ -1,26 +1,26 @@
 // The public surface of @ultimat3/entity. Explicit, never `export *`.
 
-export type { MoneyColumns } from './columns';
+/** 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 { TextOptions } from './columns';
 export {
   boolean,
-  id,
+  enumerated,
   integer,
-  jsonb,
   locale,
   money,
   newId,
-  nullable,
-  orgId,
-  references,
-  slug,
-  softDelete,
-  table,
   text,
-  timestamps,
+  timestamp,
   tz,
+  url,
+  uuid,
 } from './columns';
-export type { Entity, EntityInit, EntitySchema } from './entity';
-export { entity } from './entity';
+export type { Database, DatabaseOptions, Driver, EntitySet } from './database';
+export { database, memoryDriver } from './database';
+export type { Entity, EntityCore, EntityInit, IndexInit } from './entity';
+export { entity, SOFT_DELETE_COLUMN } from './entity';
 export type { EntityErrorCode } from './errors';
 export {
   dbDrift,
@@ -32,15 +32,19 @@ export {
   notFound,
   tenancyUnscoped,
 } from './errors';
-export type { CheckInit, Invariant, InvariantKind, UniqueInit } from './invariants';
+export type { ColumnExpr, Expr, InvariantColumns, Resolve } from './expr';
+export type { Invariant, InvariantDef, InvariantKind } from './invariants';
 export {
   assertInvariants,
   constraintName,
   invariant,
   invariantsToSql,
   toSql,
-  unique,
 } from './invariants';
+export type { PostgresDriverOptions } from './pg-driver';
+export { postgresDriver, postgresRepo, postgresTransactor } from './pg-driver';
+export type { ReadBuilder, Table } from './query';
+export { tableFor } from './query';
 export type {
   ColumnDescription,
   EntityDescription,
@@ -55,8 +59,10 @@ export {
   registerEntity,
 } from './registry';
 export type { FindManyArgs, Page, Repo, RepoOptions, Transactor, Tx } from './repo';
-export { decodeCursor, encodeCursor, memoryRepo, memoryTransactor } from './repo';
-export type { Operator, Predicate, QueryPlan, SortDirection } from './tenancy';
+export { memoryRepo, memoryTransactor } from './repo';
+export type { Seed, SeedContext, SeedOptions } from './seed';
+export { defineSeed, seedId } from './seed';
+export type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
 export {
   assertScoped,
   describePlan,
@@ -65,15 +71,25 @@ export {
   isOrgScoped,
   ORG_COLUMN,
   orgScoped,
+  tenantColumnOf,
 } from './tenancy';
 export type {
-  ColumnDef,
+  AnyColumn,
+  Column,
   ColumnDefault,
   ColumnKind,
   ColumnMap,
+  ColumnMeta,
   IndexDef,
-  ReferenceDef,
+  Insertable,
+  MoneyInput,
+  MoneyValue,
+  OnDelete,
+  ReferenceOptions,
   RowOf,
-  TableDef,
+  TimestampColumn,
+  TypeOf,
+  UuidColumn,
 } from './types';
-export { columnNames, hasColumn } from './types';
+// `viewFor` stays internal: a view is reached through the entity, as `posts.$view([...])`.
+export type { EntityView } from './view';

package/src/invariants.ts

@@ -1,10 +1,16 @@
-// A domain invariant is written once and enforced twice: in the app on every write,
-// and in Postgres as a CHECK or UNIQUE constraint emitted into the migration. The
-// database can therefore never disagree with the code — a bulk import, a psql
-// session or a second service all hit the same rule.
+// A domain invariant is written once and enforced twice: in the app on every write, and in
+// Postgres as a CHECK or a unique index emitted into the migration. The database can therefore
+// never disagree with the code — a bulk import, a psql session or a second service all hit the
+// same rule.
+//
+// `invariant()` is unbound on purpose: it is written next to the columns, and `entity()` binds
+// it to their physical names. That is what keeps a physical name from being typed twice.
+
 import { invariantViolated } from './errors';
+import type { Expr, InvariantColumns, Resolve, Row } from './expr';
 
-export type InvariantKind = 'check' | 'unique';
+/** `assert` is a rule only the app can run — a JS predicate with no SQL translation. */
+export type InvariantKind = 'check' | 'unique' | 'assert';
 
 export interface Invariant<T> {
   /** Becomes the constraint name: `<table>_<name>_check`. Keep it snake_case. */
@@ -12,64 +18,60 @@ export interface Invariant<T> {
   readonly kind: InvariantKind;
   /** Safe to log and useful to an agent: says what was expected, not what leaked. */
   readonly message: string;
-  /** SQL predicate for `check`, or the column list for `unique`. */
-  readonly sql: string;
+  /** SQL predicate for `check`, the column list for `unique`, `null` for `assert`. */
+  readonly sql: string | null;
+  /** Physical column names the rule reads. */
   readonly columns: readonly string[];
   /** Partial-constraint predicate, e.g. `deleted_at is null`. */
   readonly where?: string;
   readonly holds: (row: T) => boolean;
 }
 
-export interface CheckInit<T> {
-  readonly message: string;
-  /** Postgres predicate over physical column names. */
-  readonly sql: string;
-  readonly holds: (row: T) => boolean;
-  readonly columns?: readonly string[];
-  readonly where?: string;
+/** What `invariant()` returns: a rule that does not yet know its physical column names. */
+export interface InvariantDef {
+  readonly name: string;
+  readonly build: (columns: InvariantColumns) => Expr;
 }
 
-/** `invariant('price_positive', { sql: 'price_minor > 0', holds: (p) => p.priceMinor > 0n })` */
-export const invariant = <T>(name: string, init: CheckInit<T>): Invariant<T> => ({
-  name,
-  kind: 'check',
-  message: init.message,
-  sql: init.sql,
-  columns: init.columns ?? [],
-  ...(init.where === undefined ? {} : { where: init.where }),
-  holds: init.holds,
-});
+/** `invariant('post_like_count_non_negative', (c) => c.likeCount.atLeast(0))` */
+export const invariant = (
+  name: string,
+  build: (columns: InvariantColumns) => Expr,
+): InvariantDef => ({ name, build });
 
-export interface UniqueInit<T> {
-  readonly message: string;
-  readonly columns: readonly string[];
-  /** In-app duplicate detection needs the store, so the app check defaults to true. */
-  readonly holds?: (row: T) => boolean;
-  readonly where?: string;
-}
+const asRow = (value: unknown): Row =>
+  typeof value === 'object' && value !== null ? (value as Row) : {};
 
-/**
- * Uniqueness cannot be decided from a single row, so the app-side check is a no-op
- * by default and the database is the authority. The unique index is still declared
- * here so it lives next to the rule it implements.
- */
-export const unique = <T>(name: string, init: UniqueInit<T>): Invariant<T> => ({
-  name,
-  kind: 'unique',
-  message: init.message,
-  sql: init.columns.join(', '),
-  columns: init.columns,
-  ...(init.where === undefined ? {} : { where: init.where }),
-  holds: init.holds ?? (() => true),
-});
+/** Called by `entity()`: resolves property paths to physical names and freezes the rule. */
+export const bindInvariant = <T>(
+  def: InvariantDef,
+  columns: InvariantColumns,
+  resolve: Resolve,
+  partialWhere: string | undefined,
+): Invariant<T> => {
+  const expr = def.build(columns);
+  const sql = expr.toSql(resolve);
+  const kind: InvariantKind = expr.kind === 'unique' ? 'unique' : sql === null ? 'assert' : 'check';
+  return {
+    name: def.name,
+    kind,
+    message: expr.message,
+    sql,
+    columns: expr.paths.map(resolve),
+    // A soft-deleted row must not keep a slug reserved, so uniqueness is partial there.
+    ...(kind === 'unique' && partialWhere !== undefined ? { where: partialWhere } : {}),
+    holds: (row) => expr.holds(asRow(row)),
+  };
+};
 
 export const constraintName = (
   table: string,
   inv: { readonly name: string; readonly kind: InvariantKind },
-): string => `${table}_${inv.name}_${inv.kind === 'check' ? 'check' : 'key'}`;
+): string => `${table}_${inv.name}_${inv.kind === 'unique' ? 'key' : 'check'}`;
 
 /** The DDL the migration emits. One statement, terminated, ready to diff. */
-export const toSql = <T>(table: string, inv: Invariant<T>): string => {
+export const toSql = <T>(table: string, inv: Invariant<T>): string | null => {
+  if (inv.sql === null) return null;
   const name = constraintName(table, inv);
   if (inv.kind === 'check') {
     return `ALTER TABLE "${table}" ADD CONSTRAINT "${name}" CHECK (${inv.sql});`;
@@ -80,7 +82,10 @@ export const toSql = <T>(table: string, inv: Invariant<T>): string => {
 };
 
 export const invariantsToSql = <T>(table: string, invariants: readonly Invariant<T>[]): string =>
-  invariants.map((inv) => toSql(table, inv)).join('\n');
+  invariants
+    .map((inv) => toSql(table, inv))
+    .filter((statement): statement is string => statement !== null)
+    .join('\n');
 
 /** Runs on every write. Reports every violation at once so one round trip fixes all. */
 export const assertInvariants = <T>(
@@ -89,7 +94,6 @@ export const assertInvariants = <T>(
   row: T,
 ): void => {
   const failed = invariants.filter((inv) => !inv.holds(row));
-  if (failed.length === 0) return;
   const first = failed[0];
   if (first === undefined) return;
   throw invariantViolated(entityName, first.name, failed.map((inv) => inv.message).join('; '));

package/src/pg-driver.ts

@@ -0,0 +1,154 @@
+// The production driver. Same `Repo` contract as `memoryRepo`, same plans, same cursor — the
+// 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.
+
+import { type DbClient, db, type TransactionOptions, withTransaction } from '@ultimat3/db';
+import { snake } from './column';
+import { cursorFor, seekFrom, valueAt } from './cursor';
+import type { Driver } from './database';
+import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
+import { notFound } from './errors';
+import { bindValues, decodeRow, type PhysicalRow } from './pg-row';
+import {
+  countStatement,
+  deleteStatement,
+  insertStatement,
+  type ReadShape,
+  selectStatement,
+  updateStatement,
+} from './pg-sql';
+import { idPlan, readPlan } from './plan';
+import type { FindManyArgs, Repo, Transactor } from './repo';
+import type { QueryPlan } from './tenancy';
+
+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 `createRecordingClient()` here or install one
+   * globally with `setDbClient()`.
+   */
+  readonly client?: DbClient | undefined;
+}
+
+const shapeOf = (args: FindManyArgs, seek?: readonly unknown[]): ReadShape => ({
+  includeDeleted: args.includeDeleted === true,
+  ...(seek === undefined ? {} : { seek }),
+});
+
+export const postgresRepo = <Row>(
+  entity: EntityCore<Row>,
+  config: PostgresDriverOptions = {},
+): Repo<Row> => {
+  const client = (): DbClient => config.client ?? db();
+  const idOf = (row: Row): string =>
+    entity.$primaryKey.map((property) => String(valueAt(row, property))).join('');
+
+  const one = async (plan: QueryPlan, args: FindManyArgs): Promise<Row | null> => {
+    const [found] = await client().query<PhysicalRow>(
+      selectStatement(entity, plan, shapeOf(args), 1),
+    );
+    return found === undefined ? null : decodeRow(entity, found);
+  };
+
+  return {
+    async findById(id, options) {
+      const plan = idPlan(entity, id, options, 'findById');
+      return one(plan, options ?? {});
+    },
+
+    async findMany(args = {}) {
+      const plan = readPlan(entity, args, 'findMany');
+      // One row past the page: the presence of that row is what says there is a next cursor,
+      // and it costs one row instead of a second `count(*)` over the same predicate.
+      const found = await client().query<PhysicalRow>(
+        selectStatement(entity, plan, shapeOf(args, seekFrom(entity, plan)), plan.limit + 1),
+      );
+      const rows = found.slice(0, plan.limit).map((row) => decodeRow(entity, row));
+      const last = rows.at(-1);
+      return {
+        rows,
+        nextCursor:
+          found.length > plan.limit && last !== undefined
+            ? cursorFor(entity, plan, last, idOf(last))
+            : null,
+      };
+    },
+
+    async insert(values) {
+      entity.$assert(values);
+      const written = await client().one<PhysicalRow>(
+        insertStatement(entity, bindValues(entity, values)),
+      );
+      // `returning *` is the row Postgres actually stored, defaults included.
+      return written === null ? values : decodeRow(entity, written);
+    },
+
+    async update(id, patch, options) {
+      const plan = idPlan(entity, id, options, 'update');
+      const values = bindValues(entity, patch);
+      if (values.size === 0) {
+        const current = await one(plan, options ?? {});
+        if (current === null) throw notFound(entity.$name, id);
+        return current;
+      }
+      const written = await client().one<PhysicalRow>(
+        updateStatement(entity, plan, values, shapeOf(options ?? {})),
+      );
+      if (written === null) throw notFound(entity.$name, id);
+      const after = decodeRow(entity, written);
+      // SQL-expressible invariants are CHECK constraints, so Postgres already rejected the
+      // statement. A JS-only one (`kind: 'assert'`, `sql: null`) can only be judged on the
+      // result — inside `withTransaction` the throw takes the row with it.
+      entity.$assert(after);
+      return after;
+    },
+
+    async delete(id, options) {
+      const plan = idPlan(entity, id, options, 'delete');
+      // Soft delete hides the row without losing it; the column's presence is the switch.
+      const statement = entity.$softDelete
+        ? updateStatement(
+            entity,
+            plan,
+            new Map([[snake(SOFT_DELETE_COLUMN), new Date()]]),
+            shapeOf({}),
+          )
+        : deleteStatement(entity, plan);
+      if ((await client().execute(statement)) === 0) throw notFound(entity.$name, id);
+    },
+
+    async count(args = {}) {
+      const plan = readPlan(entity, args, 'count');
+      const row = await client().one<{ count: unknown }>(
+        countStatement(entity, plan, shapeOf(args)),
+      );
+      return Number(row?.count ?? 0);
+    },
+  };
+};
+
+/**
+ * `database(entities, { driver: postgresDriver() })` — the one line that moves an app off the
+ * in-memory default. Repos are stateless, so there is nothing to memoise.
+ */
+export const postgresDriver = (config: PostgresDriverOptions = {}): Driver => ({
+  repo: <Row>(entity: EntityCore<Row>) => postgresRepo(entity, config),
+});
+
+/**
+ * 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) }),
+      options,
+    ),
+});