@ultimat3/entity 1.1.0 → 2.0.0

package/src/describe.ts

@@ -5,11 +5,10 @@
 // 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 { referenceBinding, snake } 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> {
@@ -24,23 +23,38 @@ 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',
-    );
-  }
-  return `${target.table}.${target.name}`;
-};
+/**
+ * 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: snake(property),
+        nullable: !meta.notNull,
+        targetEntity: target.table,
+        targetProperty: target.property,
+        targetColumn: target.name,
+      },
+    ];
+  });
 
 const describeColumn = <Row>(
   input: DescribeInput<Row>,
   property: string,
   meta: ColumnMeta,
+  reference: ReferenceDescription | undefined,
 ): readonly ColumnDescription[] => {
   const physical = snake(property);
   if (meta.kind === 'money') {
@@ -67,6 +81,18 @@ 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.
+      {
+        property: `${property}Scale`,
+        column: `${physical}_scale`,
+        kind: 'integer',
+        check: scaleCheck(`${physical}_scale`),
+        ...shared,
+        notNull: false,
+      },
     ];
   }
   return [
@@ -79,28 +105,47 @@ const describeColumn = <Row>(
       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 references = new Map(
+    describeReferences(input.name, input.columns).map((reference) => [
+      reference.property,
+      reference,
+    ]),
+  );
+  return {
+    name: input.name,
+    table: input.name,
+    primaryKey: input.primaryKey.map((property) => snake(property)),
+    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 { systemClock } from '@ultimat3/core';
+import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
 import { bindColumn, snake } 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,7 +28,7 @@ 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> {
@@ -39,7 +40,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 +87,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 +106,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>(
@@ -143,13 +155,14 @@ export const entity = <const C extends ColumnMap>(
     return `${snake(property)}_${part}`;
   };
 
-  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),
+  // 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[] = [
@@ -164,6 +177,11 @@ export const entity = <const C extends ColumnMap>(
     ...(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(
@@ -199,15 +217,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');
@@ -258,9 +286,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: name, 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);