@fougere/schema 0.6.0-alpha.0 → 0.8.0-alpha.0

package/src/SchemaDefinition.ts

@@ -0,0 +1,257 @@
+import { type Fields } from './field/Field.js';
+import { FieldSet, deduplicated } from './field/FieldSet.js';
+import {
+  type CompositeUnique,
+  type EntityDeclarations,
+  type PreviousNames,
+} from './entity/EntityDeclarations.js';
+import { type EntityAdapters } from './entity/EntityAdapters.js';
+import { EntityAdapterSet } from './entity/EntityAdapterSet.js';
+import { SchemaDerivation } from './SchemaDerivation.js';
+import { type ValidateOptions } from './validator/InputValidator.js';
+import type { SchemaView } from './SchemaView.js';
+
+/**
+ * What a schema constrains beyond any single field.
+ *
+ * `unique` is the one member today. It sits under an owner rather than beside `fields`
+ * and `opts` because the next rule spanning two fields — a check, an exclusion — is a
+ * member here, not an eighth positional argument in a list that has already lost one.
+ */
+export interface SchemaConstraints<TFields extends Fields = Fields> {
+  readonly unique?: CompositeUnique<TFields>;
+}
+
+/**
+ * Everything a definition is made of, every member required.
+ *
+ * A transformation states what it keeps AND what it clears — `previous: undefined` and
+ * `anchored: false` are the two a derivation decides, and positionally they were an
+ * `undefined` and a `false` a reader had to count arguments to name.
+ */
+interface SchemaState {
+  fields: Fields;
+  adapterSet: EntityAdapterSet;
+  opts: ValidateOptions;
+  previous: PreviousNames<Fields> | undefined;
+  derivation: SchemaDerivation | undefined;
+  anchored: boolean;
+  constraints: SchemaConstraints;
+}
+
+/** The keys a derivation keeps, in the order it keeps them, under the names they take. */
+type Renaming = ReadonlyMap<string, string>;
+
+/**
+ * Everything a schema IS, apart from being a class whose instances are rows.
+ *
+ * The members used to be that many statics assigned side by side, and every derivation
+ * re-threaded them by hand — which is how one of them came to be dropped from a list
+ * without anyone noticing. A transformation here returns a COMPLETE definition or it does
+ * not compile, so no gesture can mix the fields of one with the options of another.
+ *
+ * Internal: it is not exported from the package and never appears on `SchemaConstructor`.
+ * A user derives with `Order.pick(…)`, never `Order.definition.pick(…)`.
+ */
+export class SchemaDefinition {
+  readonly fields: Fields;
+  readonly adapterSet: EntityAdapterSet;
+  readonly opts: ValidateOptions;
+  readonly previous: PreviousNames<Fields> | undefined;
+  readonly derivation: SchemaDerivation | undefined;
+  readonly anchored: boolean;
+  readonly constraints: SchemaConstraints;
+
+  private constructor(state: SchemaState) {
+    this.fields = state.fields;
+    this.adapterSet = state.adapterSet;
+    this.opts = state.opts;
+    this.previous = state.previous;
+    this.derivation = state.derivation;
+    this.anchored = state.anchored;
+    this.constraints = state.constraints;
+  }
+
+  /** Built complete or not at all — no static assigned on the side. */
+  static of(declaration: {
+    fields: Fields;
+    adapters?: EntityAdapters<Fields>;
+    opts?: ValidateOptions;
+    previous?: PreviousNames<Fields>;
+    derivation?: SchemaDerivation;
+    anchored?: boolean;
+    constraints?: SchemaConstraints;
+  }): SchemaDefinition {
+    return new SchemaDefinition({
+      fields: declaration.fields,
+      adapterSet: EntityAdapterSet.of(declaration.adapters),
+      opts: declaration.opts ?? {},
+      previous: declaration.previous,
+      derivation: declaration.derivation,
+      anchored: declaration.anchored ?? false,
+      constraints: declaration.constraints ?? {},
+    });
+  }
+
+  declaring(declarations: EntityDeclarations<Fields>): SchemaDefinition {
+    const addressed = EntityAdapterSet.of(declarations.adapters).fieldNames;
+    this.assertKnown('declares', [
+      ...addressed,
+      ...Object.keys(declarations.previous ?? {}),
+    ]);
+    const declared = FieldSet.declaring(this.fields, declarations.unique);
+
+    return new SchemaDefinition({
+      fields: declared.fields,
+      adapterSet: EntityAdapterSet.merged([
+        this.adapterSet,
+        EntityAdapterSet.of(declarations.adapters),
+      ]),
+      opts: this.opts,
+      previous: declarations.previous ?? this.previous,
+      derivation: this.derivation,
+      anchored: this.anchored,
+      constraints:
+        declarations.unique === undefined ? this.constraints : { unique: declared.unique },
+    });
+  }
+
+  anchoring(): SchemaDefinition {
+    return new SchemaDefinition({
+      fields: this.fields,
+      adapterSet: this.adapterSet,
+      opts: this.opts,
+      previous: this.previous,
+      derivation: this.derivation,
+      anchored: true,
+      constraints: this.constraints,
+    });
+  }
+
+  pick(keys: readonly string[], root: SchemaView): SchemaDefinition {
+    this.assertKnown('pick', keys);
+
+    return this.renaming(new Map(keys.map((key) => [key, key])), root);
+  }
+
+  omit(keys: readonly string[], root: SchemaView): SchemaDefinition {
+    this.assertKnown('omit', keys);
+    const kept = Object.keys(this.fields).filter((key) => !keys.includes(key));
+
+    return this.renaming(new Map(kept.map((key) => [key, key])), root);
+  }
+
+  rename(mapping: Record<string, string>, root: SchemaView): SchemaDefinition {
+    this.assertKnown('rename', Object.keys(mapping));
+    const here = Object.keys(this.fields).map((key) => [key, mapping[key] ?? key] as const);
+
+    return this.renaming(new Map(here), root);
+  }
+
+  /**
+   * `pick`, `omit` and `rename` are one gesture, and the renaming IS that gesture: the
+   * fields it keeps and everything else addressed by field name are both read from it.
+   */
+  private renaming(kept: Renaming, root: SchemaView): SchemaDefinition {
+    const fields: Fields = {};
+    for (const [from, to] of kept) {
+      const field = this.fields[from];
+      if (field) fields[to] = field;
+    }
+    const nameOf = (key: string) => kept.get(key);
+
+    return new SchemaDefinition({
+      fields,
+      adapterSet: this.adapterSet.rename(nameOf),
+      opts: this.opts,
+      previous: undefined,
+      derivation: this.origin(root).rename(nameOf),
+      anchored: false,
+      constraints: this.constraintsRenamed(nameOf),
+    });
+  }
+
+  /** One member gone and the group is gone: it constrained a pair that no longer exists. */
+  private constraintsRenamed(
+    transform: (key: string) => string | undefined,
+  ): SchemaConstraints {
+    if (!this.constraints.unique) return this.constraints;
+    const kept: string[][] = [];
+    for (const group of this.constraints.unique) {
+      const renamed = group.map(transform);
+      if (renamed.every((key): key is string => key !== undefined)) kept.push(renamed);
+    }
+
+    return { unique: deduplicated(kept) as CompositeUnique<Fields> | undefined };
+  }
+
+  patched(root: SchemaView): SchemaDefinition {
+    return new SchemaDefinition({
+      fields: { ...this.fields },
+      adapterSet: this.adapterSet,
+      opts: { ...this.opts, patch: true },
+      previous: undefined,
+      derivation: this.origin(root),
+      anchored: false,
+      constraints: this.constraints,
+    });
+  }
+
+  /** An added field does not pretend to come from the root, which never declared it. */
+  extended(extra: Fields, root: SchemaView): SchemaDefinition {
+    return new SchemaDefinition({
+      fields: { ...this.fields, ...extra },
+      adapterSet: this.adapterSet,
+      opts: this.opts,
+      previous: undefined,
+      derivation: this.origin(root),
+      anchored: false,
+      constraints: this.constraints,
+    });
+  }
+
+  /** Several schemas fold into one, which has no single origin to point at. */
+  static merged(views: readonly SchemaView[]): SchemaDefinition {
+    const fields: Fields = {};
+    let opts: ValidateOptions = {};
+    const groups: (readonly string[])[] = [];
+    for (const view of views) {
+      Object.assign(fields, view.getFields());
+      opts = { ...opts, ...view.getOpts() };
+      groups.push(...(view.getUnique() ?? []));
+    }
+
+    return new SchemaDefinition({
+      fields,
+      adapterSet: EntityAdapterSet.merged(
+        views.map((view) => EntityAdapterSet.of(view.getAdapters())),
+      ),
+      opts,
+      previous: undefined,
+      derivation: undefined,
+      anchored: false,
+      constraints: { unique: deduplicated(groups) as CompositeUnique<Fields> | undefined },
+    });
+  }
+
+  /**
+   * So a gesture naming a field that does not exist says so, and lists what there is.
+   * FR : pour qu'un geste nommant un champ inexistant le dise, et énumère ce qui existe.
+   * `pick('titel')` → `pick(): unknown field \`titel\`. This schema carries id, title, body.`
+   */
+  private assertKnown(operation: string, keys: readonly string[]): void {
+    const strangers = keys.filter((key) => !Object.hasOwn(this.fields, key));
+    if (strangers.length === 0) return;
+
+    throw new Error(
+      `${operation}(): unknown field ${strangers.map((s) => `\`${s}\``).join(', ')}. ` +
+        `This schema carries ${Object.keys(this.fields).join(', ')}.`,
+    );
+  }
+
+  private origin(root: SchemaView): SchemaDerivation {
+    if (!this.anchored && this.derivation) return this.derivation;
+
+    return SchemaDerivation.first(root, this.fields);
+  }
+}

package/src/SchemaDerivation.ts

@@ -0,0 +1,44 @@
+import { type Fields } from './field/Field.js';
+import type { SchemaView } from './SchemaView.js';
+
+/**
+ * The origin is the ROOT: `Post.pick(a, b).omit(b)` answers `Post`, never the intermediate.
+ */
+export class SchemaDerivation {
+  private constructor(
+    readonly source: SchemaView,
+    readonly nameOf: Readonly<Record<string, string | undefined>>,
+  ) {}
+
+  static first(source: SchemaView, fields: Fields): SchemaDerivation {
+    return new SchemaDerivation(
+      source,
+      Object.fromEntries(Object.keys(fields).map((key) => [key, key])),
+    );
+  }
+
+  rename(transform: (key: string) => string | undefined): SchemaDerivation {
+    return new SchemaDerivation(
+      this.source,
+      Object.fromEntries(
+        Object.entries(this.nameOf).map(([origin, here]) => [
+          origin,
+          here === undefined ? undefined : transform(here),
+        ]),
+      ),
+    );
+  }
+
+  get sourceName(): string {
+    return this.source.name;
+  }
+
+  /** Whose rows this one borrows, however many cuts away: `Post.pick('t').omit('t')` → `Post`. */
+  get anchor(): SchemaView {
+    const source = this.source;
+
+    return source.anchored !== undefined || !source.derivation
+      ? source
+      : source.derivation.anchor;
+  }
+}

package/src/{schema/SchemaView.ts → SchemaView.ts}

@@ -1,15 +1,15 @@
-import type { Field, Fields } from './fields/Field.js';
-import type { CompositeUnique, PreviousNames } from '../entity/EntityDeclarations.js';
-import type { EntityAdapters } from '../entity/EntityAdapters.js';
-import type { ValidationResult } from '../judge/result.js';
-import type { ValidateOptions } from '../judge/options.js';
+import type { Field, Fields } from './field/Field.js';
+import type { CompositeUnique, PreviousNames } from './entity/EntityDeclarations.js';
+import type { EntityAdapters } from './entity/EntityAdapters.js';
+import type { ValidationResult } from './validation.js';
+import type { ValidateOptions } from './validator/InputValidator.js';
 import type { SchemaDerivation } from './SchemaDerivation.js';
 
-export type Row<TFields extends Fields> = {
+export type Values<TFields extends Fields> = {
   [K in keyof TFields]: TFields[K] extends Field<infer T> ? T : never;
 };
 
-export type PartialRow<TFields extends Fields> = Partial<Row<TFields>>;
+export type PartialValues<TFields extends Fields> = Partial<Values<TFields>>;
 
 export interface SchemaView<TFields extends Fields = Fields> {
   readonly name: string;
@@ -20,8 +20,8 @@ export interface SchemaView<TFields extends Fields = Fields> {
   /** Does it hold rows of its own? False on a derivation means an answer. */
   readonly anchored?: boolean;
   getFields(): TFields;
-  getAdapters(): EntityAdapters<TFields> | undefined;
+  getAdapters(): EntityAdapters<TFields>;
   getUnique(): CompositeUnique<TFields> | undefined;
   getOpts(): ValidateOptions;
-  validate(input: unknown): ValidationResult<Row<TFields>>;
+  validate(input: unknown): ValidationResult<Values<TFields>>;
 }

package/src/{schema/axis → axis}/Axis.ts

@@ -1,12 +1,12 @@
 import { roleAxis } from './role/RoleAxis.js';
 import { lifecycleAxis } from './lifecycle/LifecycleAxis.js';
 import { boundaryAxis } from './boundary/BoundaryAxis.js';
-import type { ValidationError } from '../../judge/result.js';
+import type { ValidationError } from '../validation.js';
 
 export interface Axis<Declared = unknown, Wire = unknown> {
   readonly slot: 'role' | 'lifecycle' | 'boundary';
 
-  judge(value: unknown, errors: ValidationError[]): void;
+  validator(value: unknown, errors: ValidationError[]): void;
 
   describe(value: Declared, key: string): Wire | undefined;
 

package/src/axis/boundary/Boundaries.ts

@@ -0,0 +1,37 @@
+import type { BoundaryRules } from './Boundary.js';
+import { Registry } from '../../lib/Registry.js';
+
+export type Decoder = (value: unknown) => { value: unknown } | { error: string };
+export type Encoder = (value: unknown) => unknown;
+
+/**
+ * `decoders` for a value coming in, `encoders` for one going out, `aliases` for the word
+ * that names a pair. Three registries, so a codec is never half declared.
+ * FR : `decoders` à l'entrée, `encoders` à la sortie, `aliases` pour le mot qui nomme la paire.
+ * `Boundaries.aliases.register('isoDate', { in: { decode: 'isoDate' }, out: { encode: 'isoDate' } })`
+ * → a field saying `boundary: 'isoDate'` decodes to a `Date` and leaves as a string
+ */
+export const Boundaries = {
+  decoders: new Registry<Decoder>(
+    'boundary decoder',
+    'call Boundaries.decoders.register(name, fn)',
+  ),
+  encoders: new Registry<Encoder>(
+    'boundary encoder',
+    'call Boundaries.encoders.register(name, fn)',
+  ),
+  aliases: new Registry<BoundaryRules>('boundary alias'),
+};
+
+Boundaries.decoders.register('isoDate', (value) => {
+  if (value instanceof Date) return { value };
+  if (typeof value === 'string') {
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? { error: 'Invalid date' } : { value: date };
+  }
+  return { error: 'Expected a date' };
+});
+Boundaries.encoders.register('isoDate', (value) =>
+  value instanceof Date ? value.toISOString() : value,
+);
+Boundaries.aliases.register('isoDate', { in: { decode: 'isoDate' }, out: { encode: 'isoDate' } });

package/src/{schema/axis → axis}/boundary/Boundary.ts

@@ -1,7 +1,7 @@
 import type { Decoder, Encoder } from './Boundaries.js';
 import { Boundaries } from './Boundaries.js';
-import type { Field } from '../../fields/Field.js';
-import { Anatomy, type Shape } from '../shape/Shape.js';
+import type { Field } from '../../field/Field.js';
+import { Shapes, type Shape } from '../shape/Shape.js';
 
 export interface BoundaryRules {
   in?: 'closed' | { decode: string };
@@ -29,12 +29,13 @@ export class Boundary implements BoundaryRules {
     this.encode = codecs?.encode ?? identityEncoder;
   }
 
+  /** An unknown alias stops here. */
   static declared(field: Field): Boundary {
     const ref = field.boundary;
     if (ref === undefined) return new Boundary();
     if (typeof ref !== 'string') return new Boundary(ref);
 
-    const alias = Boundaries.alias(ref);
+    const alias = Boundaries.aliases.find(ref);
     if (!alias) throw new Error(`Unknown boundary alias: '${ref}'`);
     return new Boundary(alias);
   }
@@ -49,19 +50,20 @@ export class Boundary implements BoundaryRules {
     return new Boundary(rules, {
       decode:
         typeof rules.in === 'object'
-          ? Boundaries.decoder(rules.in.decode)
+          ? Boundaries.decoders.resolve(rules.in.decode)
           : identityDecoder,
       encode:
         typeof rules.out === 'object'
-          ? Boundaries.encoder(rules.out.encode)
+          ? Boundaries.encoders.resolve(rules.out.encode)
           : identityEncoder,
     });
   }
 
+  /** `date-time` means a `Date` on both sides, without a word in the entity. */
   static forShape(shape: Shape | undefined): Boundary {
-    const base = Anatomy.of(shape).base;
+    const base = Shapes.of(shape).base;
     if (base?.type === 'string' && base.format === 'date-time') {
-      return new Boundary(Boundaries.alias('isoDate')!);
+      return new Boundary(Boundaries.aliases.find('isoDate')!);
     }
     return new Boundary();
   }

package/src/{schema/axis → axis}/boundary/BoundaryAxis.ts

@@ -1,12 +1,12 @@
 import type { Axis } from '../Axis.js';
-import { admitWire } from '../../../projection/card/admission.js';
-import { isObject } from '../../../utils.js';
+import { admitWire } from '../../projection/card/admission.js';
+import { isObject } from '../../lib/utils.js';
 import type { BoundaryRef } from './Boundary.js';
 
 export const boundaryAxis: Axis<BoundaryRef, BoundaryRef> = {
   slot: 'boundary',
 
-  judge(value, errors) {
+  validator(value, errors) {
     if (typeof value === 'string') return; 
     if (!isObject(value)) {
       errors.push({
@@ -26,7 +26,7 @@ export const boundaryAxis: Axis<BoundaryRef, BoundaryRef> = {
 
   describe: (value) => value,
   reconstruct: (wire) => {
-    admitWire(boundaryAxis.judge, wire, 'boundary');
+    admitWire(boundaryAxis.validator, wire, 'boundary');
     return wire;
   },
 };

package/src/{schema/axis → axis}/lifecycle/Clock.ts

@@ -16,7 +16,7 @@ export class Clock {
     return this.reading();
   }
 
-  /** Freeze the instant this clock reads. Returns the gesture that restores it. */
+  /** One substitution moves time for every stamp in the process at once. */
   static freeze(at: number | Date): () => void {
     const previous = this.reading;
     const instant = at instanceof Date ? at.getTime() : at;

package/src/axis/lifecycle/Generators.ts

@@ -0,0 +1,29 @@
+import { createId } from '@paralleldrive/cuid2';
+
+import { Registry } from '../../lib/Registry.js';
+
+export type GeneratorRef = 'cuid2' | 'uuid' | 'nanoid' | (string & {});
+
+const NANOID_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+function nanoid(): string {
+  const bytes = new Uint8Array(21);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => NANOID_ALPHABET[byte & 63]).join('');
+}
+
+/**
+ * Who answers a `generate:` name. `cuid2`, `uuid` and `nanoid` are registered like any
+ * other, so `Generators.resolve('ulid')` is refused here and lists the three.
+ * FR : pour qu'un `generate:` soit répondu par un registre, builtins compris.
+ * `Generators.register('ulid', ulid)` → `create: { generate: 'ulid' }` now resolves
+ */
+export const Generators = new Registry<() => string>(
+  'generator',
+  'call Generators.register(name, fn)',
+  [
+    ['cuid2', createId],
+    ['uuid', () => globalThis.crypto.randomUUID()],
+    ['nanoid', nanoid],
+  ],
+);

package/src/{schema/axis → axis}/lifecycle/LifecycleAxis.ts

@@ -1,18 +1,18 @@
 import type { Axis } from '../Axis.js';
-import type { ValidationError } from '../../../judge/result.js';
-import { admitWire, oneOfTokens } from '../../../projection/card/admission.js';
-import { isObject } from '../../../utils.js';
+import type { ValidationError } from '../../validation.js';
+import { admitWire, oneOfTokens } from '../../projection/card/admission.js';
+import { isObject } from '../../lib/utils.js';
 import { CREATE_TOKENS, UPDATE_TOKENS, type LifecycleRules } from './Lifecycle.js';
 
 export const lifecycleAxis: Axis<LifecycleRules, LifecycleRules> = {
   slot: 'lifecycle',
 
-  judge(value, errors) {
+  validator(value, errors) {
     if (!isObject(value)) {
       errors.push({ path: 'lifecycle', message: `Expected an object — got ${JSON.stringify(value)}` });
       return;
     }
-    if (value.create !== undefined) judgeCreate(value.create, errors);
+    if (value.create !== undefined) validateCreate(value.create, errors);
     if (value.update !== undefined && !oneOfTokens(value.update, UPDATE_TOKENS)) {
       errors.push({
         path: 'lifecycle.update',
@@ -23,12 +23,17 @@ export const lifecycleAxis: Axis<LifecycleRules, LifecycleRules> = {
 
   describe: (value) => value,
   reconstruct: (wire) => {
-    admitWire(lifecycleAxis.judge, wire, 'lifecycle');
+    admitWire(lifecycleAxis.validator, wire, 'lifecycle');
     return wire;
   },
 };
 
-function judgeCreate(rule: unknown, errors: ValidationError[]): void {
+/**
+ * So the four legal ways to declare a creation are stated once, and anything else names them.
+ * FR : pour que les quatre façons de déclarer une création soient dites une fois.
+ * `create: 3` → `Expected 'now', 'optional', { value } or { generate } — got 3`
+ */
+function validateCreate(rule: unknown, errors: ValidationError[]): void {
   if (oneOfTokens(rule, CREATE_TOKENS)) return;
   if (isObject(rule)) {
     if ('value' in rule) return;

package/src/axis/lifecycle/apply.ts

@@ -0,0 +1,53 @@
+import { Lifecycle } from './Lifecycle.js';
+import { Generators } from './Generators.js';
+import { Clock } from './Clock.js';
+import { type Field, type Fields } from '../../field/Field.js';
+
+/**
+ * So every storage realizes a create the same way.
+ * FR : pour que chaque storage réalise une création de la même façon.
+ * `applyCreate({ id: primary(), createdAt: created() }, { title: 'a' })`
+ * → `id` generated, `createdAt` stamped, `title` untouched
+ */
+export function applyCreate(fields: Fields, input: Record<string, unknown>): Record<string, unknown> {
+  const values: Record<string, unknown> = { ...input };
+  const instant = Clock.now();
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    if (name in values) continue;
+    const rule = Lifecycle.of(field);
+
+    if (rule.create === 'now') values[name] = new Date(instant);
+    else if (rule.literal) values[name] = freshValue(rule.literal.value);
+    else if (rule.generator) values[name] = Generators.resolve(rule.generator)();
+  }
+
+  return values;
+}
+
+/**
+ * So two rows created from one declared default never end up sharing the same object.
+ * FR : pour que deux lignes nées d'un même défaut ne partagent pas l'objet.
+ * `create: { value: [] }` → each instance gets its own array
+ */
+function freshValue(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  return structuredClone(value);
+}
+
+/**
+ * So `updated()` is stamped by the storage, and no handler has to remember it.
+ * FR : pour qu'`updated()` soit estampé par le storage, pas par le handler.
+ * `applyUpdate(fields, { title: 'b' })` → `updatedAt` added, nothing else
+ */
+export function applyUpdate(fields: Fields, patch: Record<string, unknown>): Record<string, unknown> {
+  const values: Record<string, unknown> = { ...patch };
+  const instant = Clock.now();
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    if (Lifecycle.of(field).stampedOnUpdate && !(name in values))
+      values[name] = new Date(instant);
+  }
+
+  return values;
+}

package/src/{schema/axis → axis}/role/Relation.ts

@@ -10,22 +10,23 @@ export interface Relation {
 }
 
 /**
- * How a relation is built — the one place a target becomes a thunk.
+ * How a relation is built — the one place a target becomes `() => Entity`.
  *
  * A target arrives as the class or as a function returning it, because a cycle between two
  * entities can only be written the second way. Recognised by FORM, `getFields` on the
- * value: a class answers it, a thunk does not.
+ * value: a class answers it, `() => Post` does not.
  */
 export const Relation = {
+  /** `() => Post` so two entities can point at each other. */
   one(target: EntityConstructor | (() => EntityConstructor), cascade?: boolean): Relation {
-    return { to: thunk(target), kind: 'one', onDelete: cascade ? 'cascade' : undefined };
+    return { to: normalizeTarget(target), kind: 'one', onDelete: cascade ? 'cascade' : undefined };
   },
 
   many(target: EntityConstructor | (() => EntityConstructor)): Relation {
-    return { to: thunk(target), kind: 'many' };
+    return { to: normalizeTarget(target), kind: 'many' };
   },
 };
 
-function thunk<E extends EntityConstructor>(target: E | (() => E)): () => E {
+function normalizeTarget<E extends EntityConstructor>(target: E | (() => E)): () => E {
   return 'getFields' in target ? () => target as E : (target as () => E);
 }