@ultimat3/entity 1.2.0 → 3.0.0

package/src/database.ts

@@ -2,6 +2,7 @@
 // writes a repository class per entity, and nobody can reach a table that is not in the set.
 
 import type { EntityCore } from './entity';
+import type { RelatedTables } from './preload';
 import type { Table } from './query';
 import { tableFor } from './query';
 import type { Repo } from './repo';
@@ -16,6 +17,13 @@ export type Database<E extends EntitySet> = {
 /** Where rows actually live. Postgres in production, memory in tests and before migrations. */
 export interface Driver {
   repo<Row>(entity: EntityCore<Row>): Repo<Row>;
+  /**
+   * TEST SEAM, optional on purpose. Empties everything this driver holds, so one test's rows are
+   * not the next test's fixtures. `memoryDriver()` implements it; `postgresDriver()` leaves it
+   * undefined, because the rows there are an app's and a framework that could truncate them from a
+   * `reset()` eventually would. A harness therefore asks and does not assume: `driver.reset?.()`.
+   */
+  reset?(): void;
 }
 
 export interface DatabaseOptions {
@@ -28,6 +36,9 @@ export interface DatabaseOptions {
  */
 export const memoryDriver = (): Driver => {
   const repos = new Map<string, unknown>();
+  // Held separately from `repos` so the reset is a call on the repository the tables already
+  // resolved, never a replacement of it.
+  const resets: (() => void)[] = [];
   return {
     repo<Row>(entity: EntityCore<Row>): Repo<Row> {
       const existing = repos.get(entity.$name);
@@ -36,14 +47,27 @@ export const memoryDriver = (): Driver => {
       if (existing !== undefined) return existing as Repo<Row>;
       const created = memoryRepo<Row>(entity);
       repos.set(entity.$name, created);
+      resets.push(() => created.reset());
       return created;
     },
+    reset() {
+      for (const reset of resets) reset();
+    },
   };
 };
 
 let shared: Driver | undefined;
 
-const defaultDriver = (): Driver => {
+/**
+ * The driver `database()` uses when a call names none — one per process, created on first use.
+ *
+ * Exported for ONE reason: a test harness needs the same object the app reads through, so it can
+ * seed it before a test and `reset?.()` it after. Without a handle on it, a preload could only
+ * build a driver of its own, and rows written into that one are invisible to every `database()`
+ * call the app already made. Application code names its driver in `database(entities, { driver })`
+ * or takes this one implicitly; it never asks for it by hand.
+ */
+export const defaultDriver = (): Driver => {
   shared ??= memoryDriver();
   return shared;
 };
@@ -53,9 +77,18 @@ export const database = <E extends EntitySet>(
   options: DatabaseOptions = {},
 ): Database<E> => {
   const driver = options.driver ?? defaultDriver();
+  // Keyed by entity name, which is what a relation names — the object key is the caller's spelling
+  // of it. This handle is the whole of what a preload can reach: a table reads the entities its own
+  // `database()` call named, through the driver that call was given, so a preload against memory
+  // means what a preload against Postgres means.
+  const declared = new Map(Object.values(entities).map((entity) => [entity.$name, entity]));
+  const related: RelatedTables = (entityName) => {
+    const entity = declared.get(entityName);
+    return entity === undefined ? undefined : { entity, repo: driver.repo(entity) };
+  };
   const tables: Record<string, unknown> = {};
   for (const [key, entity] of Object.entries(entities)) {
-    tables[key] = tableFor(entity, driver.repo(entity));
+    tables[key] = tableFor(entity, driver.repo(entity), related);
   }
   // Built key by key from `entities`, so each table is the one `Database<E>` names.
   return tables as Database<E>;

package/src/describe.ts

@@ -5,15 +5,16 @@
 // Money is the one place the projection is not one-to-one: one property becomes the two
 // physical columns that back it.
 
-import { bindingOf, snake } from './column';
-import { currencyCheck } from './columns';
-import { invariantViolated } from './errors';
+import { columnName, moneyColumns, referenceBinding } from './column';
+import { currencyCheck, scaleCheck } from './columns';
 import type { Invariant } from './invariants';
-import type { ColumnDescription, EntityDescription } from './registry';
+import type { ColumnDescription, EntityDescription, ReferenceDescription } from './registry';
 import type { AnyColumn, ColumnMeta, IndexDef } from './types';
 
 export interface DescribeInput<Row> {
   readonly name: string;
+  /** The physical table. The entity's own name unless `entity(name, { table })` said otherwise. */
+  readonly table: string;
   readonly columns: readonly (readonly [string, AnyColumn])[];
   readonly primaryKey: readonly string[];
   readonly invariants: readonly Invariant<Row>[];
@@ -24,27 +25,65 @@ export interface DescribeInput<Row> {
   readonly tenantColumn: string | null;
 }
 
-const referenceOf = (entityName: string, property: string, meta: ColumnMeta): string | null => {
-  if (meta.references === undefined) return null;
-  const target = bindingOf(meta.references());
-  if (target === undefined) {
-    throw invariantViolated(
-      entityName,
-      property,
-      'references a column that belongs to no entity — pass a column of an entity() result',
-    );
+/**
+ * The foreign keys an entity declares, resolved through the one binding resolver. Money is
+ * skipped for the reason the DDL projection drops a reference there too: one property is two
+ * physical columns, so `snake(property)` names neither of them, and a relation and a foreign-key
+ * constraint must not disagree about which columns exist.
+ */
+export const describeReferences = (
+  entityName: string,
+  columns: readonly (readonly [string, AnyColumn])[],
+): readonly ReferenceDescription[] =>
+  columns.flatMap(([property, column]) => {
+    const meta = column.$meta;
+    if (meta.kind === 'money') return [];
+    const target = referenceBinding(entityName, property, meta);
+    if (target === null) return [];
+    return [
+      {
+        property,
+        column: columnName(property, meta),
+        nullable: !meta.notNull,
+        targetEntity: target.table,
+        targetProperty: target.property,
+        targetColumn: target.name,
+      },
+    ];
+  });
+
+/**
+ * The Postgres type a column becomes. `kind` is what the migration generator reads and its table
+ * falls through to the kind itself for anything it does not name (`SQL_TYPES[kind] ?? kind`), so a
+ * precise type belongs HERE, where the precision, the element and the length are still in scope —
+ * the alternative is a second copy of the column vocabulary inside `@ultimat3/db`.
+ */
+export const sqlTypeOf = (meta: ColumnMeta): string => {
+  if (meta.kind === 'numeric') {
+    return meta.precision === undefined || meta.numericScale === undefined
+      ? 'numeric'
+      : `numeric(${meta.precision}, ${meta.numericScale})`;
   }
-  return `${target.table}.${target.name}`;
+  if (meta.kind === 'array') {
+    const element = meta.element?.$meta;
+    // `arrayOf` refuses an element that is not one scalar column, so this is total in practice;
+    // `text[]` is the answer that keeps a description renderable rather than throwing inside a
+    // projection, which is the one place an error has no caller to instruct.
+    return `${element === undefined ? 'text' : sqlTypeOf(element)}[]`;
+  }
+  return meta.kind;
 };
 
 const describeColumn = <Row>(
   input: DescribeInput<Row>,
   property: string,
   meta: ColumnMeta,
+  reference: ReferenceDescription | undefined,
 ): readonly ColumnDescription[] => {
-  const physical = snake(property);
+  const physical = columnName(property, meta);
   if (meta.kind === 'money') {
-    const currency = `${physical}_currency`;
+    const parts = moneyColumns(property, meta);
+    const currency = parts.currency;
     const shared = {
       notNull: meta.notNull,
       primaryKey: false,
@@ -55,7 +94,7 @@ const describeColumn = <Row>(
     return [
       {
         property: `${property}Minor`,
-        column: `${physical}_minor`,
+        column: parts.minor,
         kind: 'bigint',
         check: null,
         ...shared,
@@ -67,40 +106,83 @@ const describeColumn = <Row>(
         check: currencyCheck(currency),
         ...shared,
       },
+      // Always nullable, whatever the property's own nullability: NULL is how a row says "the
+      // currency's own minor unit", which is every amount written before the column existed and
+      // every ordinary price after it. A NOT NULL here would demand a scale on values that have
+      // none, and `0` is not that value — it means whole units.
+      //
+      // Absent entirely when the table has none: an adopted amount column predating scale is two
+      // physical columns, and describing a third would put a column in the DDL and in every
+      // statement that the table does not have.
+      ...(parts.scale === null
+        ? []
+        : [
+            {
+              property: `${property}Scale`,
+              column: parts.scale,
+              kind: 'integer',
+              check: scaleCheck(parts.scale),
+              ...shared,
+              notNull: false,
+            },
+          ]),
     ];
   }
   return [
     {
       property,
       column: physical,
-      kind: meta.kind,
+      kind: sqlTypeOf(meta),
       notNull: meta.notNull,
       primaryKey: meta.primaryKey || input.primaryKey.includes(property),
       unique: meta.unique,
       hasDefault: meta.default !== undefined,
       check: meta.check?.(physical) ?? null,
-      references: referenceOf(input.name, property, meta),
+      // Rendered from the resolved record, so the string a migration reads and the record a
+      // traversal reads can never disagree about what a `references()` points at.
+      references:
+        reference === undefined ? null : `${reference.targetEntity}.${reference.targetColumn}`,
     },
   ];
 };
 
-export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescription => ({
-  name: input.name,
-  table: input.name,
-  primaryKey: input.primaryKey.map((property) => snake(property)),
-  columns: input.columns.flatMap(([property, column]) =>
-    describeColumn(input, property, column.$meta),
-  ),
-  invariants: input.invariants.map((inv) => ({
-    name: inv.name,
-    kind: inv.kind,
-    message: inv.message,
-    sql: inv.sql,
-    where: inv.where ?? null,
-  })),
-  indexes: input.indexes.map((index) => index.name),
-  tags: input.tags,
-  cacheTag: input.cacheTag,
-  softDelete: input.softDelete,
-  orgScoped: input.tenantColumn !== null,
-});
+export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescription => {
+  const physicalOf = (property: string): string => {
+    const column = input.columns.find(([key]) => key === property)?.[1];
+    return column === undefined ? property : columnName(property, column.$meta);
+  };
+  const references = new Map(
+    describeReferences(input.name, input.columns).map((reference) => [
+      reference.property,
+      reference,
+    ]),
+  );
+  return {
+    name: input.name,
+    table: input.table,
+    primaryKey: input.primaryKey.map(physicalOf),
+    columns: input.columns.flatMap(([property, column]) =>
+      describeColumn(input, property, column.$meta, references.get(property)),
+    ),
+    invariants: input.invariants.map((inv) => ({
+      name: inv.name,
+      kind: inv.kind,
+      message: inv.message,
+      sql: inv.sql,
+      where: inv.where ?? null,
+    })),
+    // Projected whole, never reduced to the name: the generator spells the column list from this
+    // and a name cannot be parsed back into one. See `IndexDescription`.
+    indexes: input.indexes.map((index) => ({
+      name: index.name,
+      columns: index.columns,
+      unique: index.unique,
+      where: index.where ?? null,
+      order: index.order ?? null,
+    })),
+    tags: input.tags,
+    cacheTag: input.cacheTag,
+    softDelete: input.softDelete,
+    orgScoped: input.tenantColumn !== null,
+  };
+};

package/src/entity.ts

@@ -3,16 +3,17 @@
 // (the typed db handle, migrations, cache tags, the admin UI, the manifest) is projected from
 // this one call.
 
-import type { StandardSchemaV1 } from '@ultimat3/schema';
-import { bindColumn, snake } from './column';
+import { systemClock } from '@ultimat3/core';
+import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
+import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
-import { describeEntity } from './describe';
+import { describeEntity, describeReferences } from './describe';
 import { invariantViolated } from './errors';
 import type { Expr, InvariantColumns, Resolve } from './expr';
 import { invariantColumns } from './expr';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant, invariantsToSql } from './invariants';
-import type { EntityDescription } from './registry';
+import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
 import { resolveTenantColumn } from './tenancy';
 import type { AnyColumn, ColumnMap, ColumnMeta, IndexDef, RowOf } from './types';
@@ -27,11 +28,20 @@ export interface IndexInit<C extends ColumnMap> {
   readonly order?: 'asc' | 'desc';
   readonly unique?: boolean;
   /** Partial index predicate, written in the same language as an invariant. */
-  readonly where?: (columns: InvariantColumns) => Expr;
+  readonly where?: (columns: InvariantColumns<C>) => Expr;
 }
 
 export interface EntityInit<C extends ColumnMap> {
   readonly columns: C;
+  /**
+   * The physical table, when it is not the entity's own name. The half of adoption a column name
+   * cannot cover: `entity('user', { table: 'users', … })` reads and writes the table that is
+   * already there, and every statement, index name and foreign key follows it.
+   *
+   * The entity NAME stays the framework's key — the registry, the cache tag, `x entities describe`
+   * and every relation are keyed by it — so renaming a table never moves a cache tag or a policy.
+   */
+  readonly table?: string;
   /**
    * The tenant column, said out loud. Omitted, it is inferred from `.tenant()` or a column named
    * `orgId`, so silence never means unscoped.
@@ -39,7 +49,12 @@ export interface EntityInit<C extends ColumnMap> {
   readonly tenant?: keyof C & string;
   /** Composite keys only — a single key is `uuid().primaryKey()` on the column itself. */
   readonly primaryKey?: readonly (keyof C & string)[];
-  readonly invariants?: readonly InvariantDef[];
+  /**
+   * A callback, not an array of `(c) => …` builders: the column proxy is typed from `C`, and `C`
+   * is only fixed once for the whole `invariants` argument. Per-element builders were checked
+   * before `C` existed, which is why `c.title` used to be `ColumnExpr | undefined`.
+   */
+  readonly invariants?: (columns: InvariantColumns<C>) => readonly InvariantDef[];
   readonly indexes?: readonly IndexInit<C>[];
   /** Extra cache tags this entity participates in, beyond its own. */
   readonly tags?: readonly string[];
@@ -81,6 +96,12 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   /** The CHECK/UNIQUE statements the migration emits for this entity. */
   $migration(): string;
   $describe(): EntityDescription;
+  /**
+   * The foreign keys this entity declares, resolved — one record per `references()`, both ends
+   * named. The relation map reads it off the registry entry; a consumer holding the entity
+   * itself reads it here. Same closure, so there is one reading of a foreign key, not two.
+   */
+  $references(): readonly ReferenceDescription[];
 }
 
 export type Entity<Row, C extends ColumnMap = ColumnMap> = EntityCore<Row, C> & C;
@@ -94,7 +115,7 @@ const defaultValue = (meta: ColumnMeta): unknown => {
   const declared = meta.default;
   if (declared === undefined) return undefined;
   if (declared.kind === 'value') return declared.value;
-  return declared.by === 'uuid-v7' ? newId() : new Date();
+  return declared.by === 'uuid-v7' ? newId() : systemClock.now();
 };
 
 export const entity = <const C extends ColumnMap>(
@@ -105,6 +126,7 @@ export const entity = <const C extends ColumnMap>(
   const entries: readonly (readonly [string, AnyColumn])[] = Object.entries(init.columns);
   for (const [property, column] of entries) bindColumn(column, name, property);
 
+  const table = init.table === undefined ? name : assertColumnName(init.table);
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
@@ -135,35 +157,46 @@ export const entity = <const C extends ColumnMap>(
           `${property} is money: name ${property}.minor or ${property}.currency`,
         );
       }
-      return snake(property);
+      return columnName(property, column.$meta);
     }
     if (!isMoney || !MONEY_PARTS.has(part)) {
       throw invariantViolated(name, property, `${property} has no part "${part}"`);
     }
-    return `${snake(property)}_${part}`;
+    const parts = moneyColumns(property, column.$meta);
+    return part === 'minor' ? parts.minor : parts.currency;
   };
 
-  const columnsExpr = invariantColumns(
+  const columnsExpr = invariantColumns<C>(
     name,
     entries.map(([property]) => property),
   );
-  const partialWhere = softDelete ? `${snake(SOFT_DELETE_COLUMN)} is null` : undefined;
-  const invariants: readonly Invariant<Row>[] = (init.invariants ?? []).map((def) =>
-    bindInvariant<Row>(def, columnsExpr, resolve, partialWhere),
+  // Through the one resolver, so a soft-delete column the table spells differently is still the
+  // column every partial index excludes rows by.
+  const partialWhere = softDelete ? `${resolve([SOFT_DELETE_COLUMN])} is null` : undefined;
+  // Called once, here, so an unknown column throws while the entity is being declared.
+  const invariants: readonly Invariant<Row>[] = (init.invariants?.(columnsExpr) ?? []).map((def) =>
+    bindInvariant<Row>(def, resolve, partialWhere),
   );
 
   const declared: readonly IndexDef[] = [
     ...entries.flatMap(([property, column]) => {
       const meta = column.$meta;
       if (!meta.unique && !meta.index) return [];
-      const physical = [meta.kind === 'money' ? `${snake(property)}_minor` : snake(property)];
+      const physical = [
+        meta.kind === 'money' ? moneyColumns(property, meta).minor : columnName(property, meta),
+      ];
       return [
-        { name: indexName(name, physical, meta.unique), columns: physical, unique: meta.unique },
+        { name: indexName(table, physical, meta.unique), columns: physical, unique: meta.unique },
       ];
     }),
     ...(init.indexes ?? []).map((index) => {
       const columns = index.on.map((property) => resolve([property]));
       const unique = index.unique === true;
+      // `on: []` is type-legal and names nothing: the generated DDL would be `on "posts" ()`, a
+      // syntax error one migration later. Refused where it was written instead.
+      if (columns.length === 0) {
+        throw invariantViolated(name, 'index', 'an index must name at least one column');
+      }
       const where = index.where?.(columnsExpr).toSql(resolve) ?? null;
       if (index.where !== undefined && where === null) {
         throw invariantViolated(
@@ -173,7 +206,7 @@ export const entity = <const C extends ColumnMap>(
         );
       }
       return {
-        name: indexName(name, columns, unique),
+        name: indexName(table, columns, unique),
         columns,
         unique,
         ...(index.order === undefined ? {} : { order: index.order }),
@@ -190,6 +223,7 @@ export const entity = <const C extends ColumnMap>(
   const describe = (): EntityDescription =>
     describeEntity({
       name,
+      table,
       columns: entries,
       primaryKey,
       invariants,
@@ -199,15 +233,25 @@ export const entity = <const C extends ColumnMap>(
       softDelete,
       tenantColumn,
     });
+  const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);
 
   const parse = (value: unknown): Row => {
     if (typeof value !== 'object' || value === null) {
-      throw invariantViolated(name, 'row', `expected an object, got ${String(value)}`);
+      // `describeValue`, never `String(value)`: this message is a `$parse` failure, which reaches
+      // the caller and the log line — and the whole row is the last value in the framework that
+      // may be echoed there. Same renderer as the column builders (`columns.ts`) use.
+      throw invariantViolated(name, 'row', `expected an object, got ${describeValue(value)}`);
     }
     const input = value as Readonly<Record<string, unknown>>;
     const row: Record<string, unknown> = {};
     for (const [property, column] of entries) {
-      const given = input[property] ?? defaultValue(column.$meta);
+      // `=== undefined`, never `??`: an explicit `null` is the caller CLEARING a nullable column,
+      // and `??` read it as absence and wrote the column's declared default straight back — so
+      // `update(id, { status: null })` reported success and stored `'draft'`, with nothing on any
+      // surface to say otherwise. A present `undefined` still means absence, which is what a
+      // spread of an omitted optional key produces and is the shape every existing caller has.
+      const raw = input[property];
+      const given = raw === undefined ? defaultValue(column.$meta) : raw;
       if (given === undefined || given === null) {
         if (column.$meta.notNull) {
           throw invariantViolated(name, property, 'is required and has no default');
@@ -223,7 +267,7 @@ export const entity = <const C extends ColumnMap>(
 
   const core: EntityCore<Row, C> = {
     $name: name,
-    $table: name,
+    $table: table,
     $columns: init.columns,
     $primaryKey: primaryKey,
     $indexes: indexes,
@@ -258,9 +302,10 @@ export const entity = <const C extends ColumnMap>(
     $assert: (row) => assertInvariants(name, invariants, row),
     $migration: () => invariantsToSql(name, invariants),
     $describe: describe,
+    $references: references,
   };
 
-  registerEntity({ name, tableName: name, describe });
+  registerEntity({ name, tableName: table, describe, references });
   // The columns land on the entity itself so `orgs.id` is a column reference; every framework
   // member is `$`-prefixed, which is why a column may be called `name`.
   return Object.assign(core, init.columns);