@fougere/schema 0.11.0-alpha.0 → 0.12.1-alpha.0

package/src/projection/Cases.ts

@@ -95,66 +95,70 @@ export class Cases {
 function enumerate(entity: SchemaView, valid: Record<string, unknown>): ValidationCase[] {
   const fields = entity.getFields();
   const validator = InputValidator.of(fields);
+
+  return [
+    ...aboutTheInput(valid),
+    ...Object.entries(fields).flatMap(([name, field]) => aboutField(name, field as Field, valid, validator)),
+  ];
+}
+
+function aboutTheInput(valid: Record<string, unknown>): ValidationCase[] {
+  return [
+    { why: 'a valid input', input: valid, patch: false, expect: 'accept' },
+    {
+      why: 'a key outside the contract',
+      input: { ...valid, __unknown__: 'x' },
+      patch: false,
+      expect: { reject: '__unknown__' },
+    },
+    { why: 'not an object at all', input: 'a string', patch: false, expect: { reject: '.' } },
+  ];
+}
+
+function aboutField(
+  name: string,
+  field: Field,
+  valid: Record<string, unknown>,
+  validator: InputValidator,
+): ValidationCase[] {
+  const withField = (value: unknown) => ({ ...valid, [name]: value });
   const cases: ValidationCase[] = [];
-  const withField = (name: string, value: unknown) => ({ ...valid, [name]: value });
-
-  cases.push({ why: 'a valid input', input: valid, patch: false, expect: 'accept' });
-  cases.push({
-    why: 'a key outside the contract',
-    input: { ...valid, __unknown__: 'x' },
-    patch: false,
-    expect: { reject: '__unknown__' },
-  });
-  cases.push({
-    why: 'not an object at all',
-    input: 'a string',
-    patch: false,
-    expect: { reject: '.' },
-  });
-
-  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
-    // A reference names a row that must exist; the caller supplied its id and we do not
-    // get to invent a second one, so the only case we can state about it is the bound one.
-    const isRef = Role.of(field).isReference;
-
-    if (validator.onAbsent(field) === null && name in valid) {
-      const input = { ...valid };
-      delete input[name];
-      cases.push({ why: `${name} absent`, input, patch: false, expect: { reject: name } });
-    }
 
-    if (Boundary.of(field).readOnly) {
-      cases.push({
-        why: `${name} supplied although read-only`,
-        input: withField(name, wrongTypeFor(field)),
-        patch: false,
-        expect: { reject: name },
-      });
-    }
+  if (validator.onAbsent(field) === null && name in valid) {
+    const input = { ...valid };
+    delete input[name];
+    cases.push({ why: `${name} absent`, input, patch: false, expect: { reject: name } });
+  }
 
-    if (Lifecycle.of(field).immutable && !Role.of(field).isPrimary) {
-      cases.push({
-        why: `${name} supplied on an update`,
-        input: { [name]: valid[name] ?? wrongTypeFor(field) },
-        patch: true,
-        expect: { reject: name },
-      });
-    }
+  if (Boundary.of(field).readOnly) {
+    cases.push({
+      why: `${name} supplied although read-only`,
+      input: withField(wrongTypeFor(field)),
+      patch: false,
+      expect: { reject: name },
+    });
+  }
 
-    if (name in valid && !isRef) {
-      cases.push({
-        why: `${name} of the wrong type`,
-        input: withField(name, wrongTypeFor(field)),
-        patch: false,
-        expect: { reject: name },
-      });
-      for (const { why, value } of outOfBoundsFor(field))
-        cases.push({
-          why: `${name} ${why}`,
-          input: withField(name, value),
-          patch: false,
-          expect: { reject: name },
-        });
+  if (Lifecycle.of(field).immutable && !Role.of(field).isPrimary) {
+    cases.push({
+      why: `${name} supplied on an update`,
+      input: { [name]: valid[name] ?? wrongTypeFor(field) },
+      patch: true,
+      expect: { reject: name },
+    });
+  }
+
+  // A reference names a row that must exist; the caller supplied its id and we do not
+  // get to invent a second one, so the only case we can state about it is the bound one.
+  if (name in valid && !Role.of(field).isReference) {
+    cases.push({
+      why: `${name} of the wrong type`,
+      input: withField(wrongTypeFor(field)),
+      patch: false,
+      expect: { reject: name },
+    });
+    for (const { why, value } of outOfBoundsFor(field)) {
+      cases.push({ why: `${name} ${why}`, input: withField(value), patch: false, expect: { reject: name } });
     }
   }
 
@@ -162,4 +166,4 @@ function enumerate(entity: SchemaView, valid: Record<string, unknown>): Validati
 }
 
 /** What a case names: the input itself, or the field the refusal lands on. */
-const rejected = (path: readonly string[]): string => (path.length === 0 ? '.' : path[0]!);
+const rejected = (path: readonly string[]): string => path[0] ?? '.';

package/src/projection/Visibility.ts

@@ -33,6 +33,28 @@ export class Visibility {
     return result;
   }
 
+  /**
+   * The dual of `encode`, read where a caller RECEIVES a row.
+   *
+   * `date-time` means a `Date` on both sides, and only the outgoing half was ever applied: a
+   * handler answered `new Date(0)`, the facade encoded it, and the caller was handed
+   * `"1970-01-01T00:00:00.000Z"` while its type said `Date` — locally as well as across a wire.
+   *
+   * It converts and never judges: what arrives was validated where it was produced, so a value
+   * the codec refuses is kept as it came rather than replaced or thrown over.
+   */
+  decode(record: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = { ...record };
+    for (const [key, field] of Object.entries(this.fields)) {
+      const value = record[key];
+      if (!(key in record) || value === null || value === undefined) continue;
+      const verdict = Boundary.of(field).decode(value);
+      if ('value' in verdict) out[key] = verdict.value;
+    }
+
+    return out;
+  }
+
   encode(record: Record<string, unknown>): Record<string, unknown> {
     const out: Record<string, unknown> = { ...record };
     for (const [key, field] of Object.entries(this.fields)) {

package/src/projection/card/Bundle.ts

@@ -8,6 +8,7 @@ import type { SchemaDescriptor } from './SchemaDescriptor.js';
 import type { Diff } from './Diff.js';
 import type { SetDiff } from './SetDiff.js';
 import type { SetDiffOptions } from './SetDiffOptions.js';
+import { SchemaError } from '../../SchemaError.js';
 
 type SchemaSet = Record<string, SchemaView> | SchemaView[];
 
@@ -26,7 +27,7 @@ export class Bundle {
       const key = lowerFirst(entry.name);
       const previous = claimedBy.get(key);
       if (previous !== undefined) {
-        throw new Error(
+        throw new SchemaError(
           `Schemas '${previous}' and '${entry.name}' both claim bundle key '${key}'. `
           + 'Each schema in a bundle must have a distinct registration key.',
         );

package/src/projection/card/Card.ts

@@ -1,4 +1,5 @@
-import { EXTENSION_AXES } from '../../axis/Axis.js';
+import { Axes } from '../../axis/Axes.js';
+import { CardForms } from './CardForms.js';
 import { type Resolver } from '../../axis/Resolver.js';
 import { clean, isObject } from '../../lib/utils.js';
 import { Field } from '../../field/Field.js';
@@ -8,7 +9,7 @@ import { InputValidator } from '../../validator/InputValidator.js';
 import { Schema } from '../../Schema.js';
 import { type SchemaConstructor } from '../../SchemaConstructor.js';
 import type { SchemaView } from '../../SchemaView.js';
-import type { Values } from '../../Values.js';
+import type { Values } from '../../field/Values.js';
 import { admitPatterns, refuse } from './admission.js';
 import type { DerivedFrom } from './DerivedFrom.js';
 import type { FieldDescriptor } from './FieldDescriptor.js';
@@ -16,6 +17,7 @@ import type { FieldExtension } from './FieldExtension.js';
 import type { SchemaDescriptor } from './SchemaDescriptor.js';
 import { compare, type Diff } from './Diff.js';
 import { type DiffOptions } from './DiffOptions.js';
+import { SchemaError } from '../../SchemaError.js';
 
 type FieldsOf<T> = { [K in keyof T]-?: Field<T[K]> };
 
@@ -125,11 +127,12 @@ export class Card<T = Values<Fields>> {
  */
 function describeExtension(field: Field, key: string): FieldExtension | undefined {
   const extension: Record<string, unknown> = {};
-  for (const axis of EXTENSION_AXES) {
-    const declared = (field as unknown as Record<string, unknown>)[axis.slot];
+  for (const slot of Axes.names) {
+    const declared = (field as unknown as Record<string, unknown>)[slot];
     if (declared === undefined) continue;
-    const wire = axis.describe(declared, key);
-    if (wire !== undefined) extension[axis.slot] = wire;
+    const form = CardForms.find(slot);
+    const wire = form ? form.describe(declared, key) : declared;
+    if (wire !== undefined) extension[slot] = wire;
   }
   clean(extension);
   return Object.keys(extension).length ? (extension as FieldExtension) : undefined;
@@ -165,7 +168,11 @@ function originOf(schema: SchemaView): DerivedFrom | undefined {
  * `{ type: 'string', maxLength: 200 }` → the same shape `text({ max: 200 })` states
  */
 function reconstructShape(property: FieldDescriptor): Field['shape'] | undefined {
-  const types = Array.isArray(property.type) ? property.type : property.type ? [property.type] : [];
+  const types = Array.isArray(property.type)
+    ? property.type
+    : property.type
+      ? [property.type]
+      : [];
   if (!types.some((type) => type !== 'null')) return undefined;
 
   // `describeField` writes the shape whole, so it is read whole: a list of keywords here
@@ -188,7 +195,7 @@ function reconstructField(
 ): Field {
   const shape = reconstructShape(property);
   if (!shape) {
-    throw new Error(
+    throw new SchemaError(
       `Field '${key}': the card carries no \`type\` for it, so there is no shape to rebuild. ` +
         'A field always states one.',
     );
@@ -196,9 +203,10 @@ function reconstructField(
   admitPatterns(shape, `Field '${key}'`);
   const extension = property['x-fougere'];
   const axes: Record<string, unknown> = {};
-  for (const axis of EXTENSION_AXES) {
-    const wire = (extension as Record<string, unknown> | undefined)?.[axis.slot];
-    if (wire !== undefined) axes[axis.slot] = axis.reconstruct(wire, resolve);
+  for (const slot of Axes.names) {
+    const wire = (extension as Record<string, unknown> | undefined)?.[slot];
+    const form = CardForms.find(slot);
+    if (wire !== undefined) axes[slot] = form ? form.reconstruct(wire, resolve) : wire;
   }
   return new Field({
     shape,
@@ -207,7 +215,7 @@ function reconstructField(
       property.description !== undefined
         ? { description: property.description }
         : undefined,
-  } as never);
+  } as never, key);
 }
 
 /**
@@ -215,7 +223,10 @@ function reconstructField(
  * FR : écrit un groupe sur CHAQUE membre — un lecteur du fil ne voit qu'un champ.
  * `carryGroup(properties.listId, ['listId', 'docId'])` → the pair lands under its `role`
  */
-function carryGroup(property: FieldDescriptor | undefined, group: readonly string[]): void {
+function carryGroup(
+  property: FieldDescriptor | undefined,
+  group: readonly string[],
+): void {
   if (!property) return;
   const extension = (property['x-fougere'] ??= {}) as { role?: { unique?: string[][] } };
   const role = (extension.role ??= {});

package/src/projection/card/CardForm.ts

@@ -0,0 +1,8 @@
+import type { Resolver } from '../../axis/Resolver.js';
+
+/** How a card writes what an axis declared, and reads it back — stated by the card, not the axis. */
+export interface CardForm<Declared = unknown, Wire = unknown> {
+  describe(value: Declared, key: string): Wire | undefined;
+
+  reconstruct(wire: Wire, resolve?: Resolver): Declared;
+}

package/src/projection/card/CardForms.ts

@@ -0,0 +1,13 @@
+import { Registry } from '../../lib/Registry.js';
+import type { CardForm } from './CardForm.js';
+import { roleOnCard } from './RoleDescriptor.js';
+
+/**
+ * The axes a card writes differently from their declaration. An axis absent here travels as
+ * itself, which is what `lifecycle`, `boundary` and anything registered from outside do.
+ * FR : les axes qu'une carte écrit autrement que déclarés ; les autres voyagent tels quels.
+ * `CardForms.register('tenancy', tenancyOnCard)`
+ */
+export const CardForms = new Registry<CardForm>('card form', 'call CardForms.register(slot, form)', [
+  ['role', roleOnCard as CardForm],
+]);

package/src/projection/card/Change.ts

@@ -1,5 +1,5 @@
-import type { BoundaryRef } from '../../axis/boundary/BoundaryRef.js';
-import type { LifecycleRules } from '../../axis/lifecycle/LifecycleRules.js';
+import type { BoundaryRef } from '../../axis/boundary/Boundary.js';
+import type { LifecycleRules } from '../../axis/lifecycle/Lifecycle.js';
 import type { FieldDescriptor } from './FieldDescriptor.js';
 import type { RoleDescriptor } from './RoleDescriptor.js';
 import type { TypeSet } from './TypeSet.js';

package/src/projection/card/Diff.ts

@@ -1,5 +1,5 @@
 import { dequal } from 'dequal';
-import { EXTENSION_SLOTS } from '../../axis/Axis.js';
+import { Axes } from '../../axis/Axes.js';
 import type { FieldDescriptor } from './FieldDescriptor.js';
 import type { FieldExtension } from './FieldExtension.js';
 
@@ -27,65 +27,65 @@ export function compare(
   is: SchemaDescriptor,
   options: DiffOptions = {},
 ): Diff {
-  const changes: Change[] = [];
   const renamed = options.renamed ?? {};
   const before = was.properties ?? {};
   const after = is.properties ?? {};
-  const requiredBefore = new Set(was.required ?? []);
-  const requiredAfter = new Set(is.required ?? []);
+  const wasRequired = new Set(was.required ?? []);
+  const isRequired = new Set(is.required ?? []);
 
-  // Apply a declared rename first so subsequent differences use the new field name.
-  const nameAfter = (field: string): string => renamed[field] ?? field;
+  const kept: Change[] = [];
   const removed: string[] = [];
+  // A declared rename first, so every difference below is read under the new name.
   for (const [field, descriptor] of Object.entries(before)) {
-    const now = nameAfter(field);
+    const now = renamed[field] ?? field;
     const target = after[now];
     if (target === undefined) {
       removed.push(field);
       continue;
     }
+    kept.push(...movedIn(field, now, descriptor, target, wasRequired.has(field), isRequired.has(now)));
+  }
 
-    if (now !== field)
-      changes.push({ kind: 'renamed', from: field, to: now, field: target });
+  const claimed = new Set(Object.values(renamed));
+  const added = Object.keys(after).filter((field) => !(field in before) && !claimed.has(field));
 
-    const wasType = typesOf(descriptor);
-    const isType = typesOf(target);
-    if (!dequal(wasType, isType))
-      changes.push({ kind: 'retyped', field: now, from: wasType, to: isType });
-    else if (!dequal(boundsOf(descriptor), boundsOf(target))) {
-      changes.push({ kind: 'reshaped', field: now, from: descriptor, to: target });
-    }
+  return {
+    changes: [
+      ...kept,
+      ...removed.map((field): Change => ({
+        kind: 'removed', field, from: before[field]!, required: wasRequired.has(field),
+      })),
+      ...added.map((field): Change => ({
+        kind: 'added', field, to: after[field]!, required: isRequired.has(field),
+      })),
+    ],
+    ambiguous: candidates(removed, added, before, after),
+  };
+}
 
-    const wasRequired = requiredBefore.has(field);
-    const isRequired = requiredAfter.has(now);
-    if (wasRequired !== isRequired) {
-      changes.push({ kind: 'required', field: now, from: wasRequired, to: isRequired });
-    }
-    changes.push(...restated(now, descriptor['x-fougere'], target['x-fougere']));
-  }
+/** What one field that survived the two descriptions says about itself now. */
+function movedIn(
+  field: string,
+  now: string,
+  before: FieldDescriptor,
+  after: FieldDescriptor,
+  was: boolean,
+  is: boolean,
+): Change[] {
+  const changes: Change[] = [];
+  if (now !== field) changes.push({ kind: 'renamed', from: field, to: now, field: after });
 
-  const claimed = new Set(Object.values(renamed));
-  const added = Object.keys(after).filter(
-    (field) => !(field in before) && !claimed.has(field),
-  );
-  for (const field of removed) {
-    changes.push({
-      kind: 'removed',
-      field,
-      from: before[field],
-      required: requiredBefore.has(field),
-    });
-  }
-  for (const field of added) {
-    changes.push({
-      kind: 'added',
-      field,
-      to: after[field],
-      required: requiredAfter.has(field),
-    });
+  const wasType = typesOf(before);
+  const isType = typesOf(after);
+  if (!dequal(wasType, isType)) changes.push({ kind: 'retyped', field: now, from: wasType, to: isType });
+  else if (!dequal(boundsOf(before), boundsOf(after))) {
+    changes.push({ kind: 'reshaped', field: now, from: before, to: after });
   }
 
-  return { changes, ambiguous: candidates(removed, added, before, after) };
+  if (was !== is) changes.push({ kind: 'required', field: now, from: was, to: is });
+  changes.push(...restated(now, before['x-fougere'], after['x-fougere']));
+
+  return changes;
 }
 
 function restated(
@@ -93,7 +93,7 @@ function restated(
   before: FieldExtension | undefined,
   after: FieldExtension | undefined,
 ): Change[] {
-  return EXTENSION_SLOTS.filter((axis) => !dequal(before?.[axis], after?.[axis])).map(
+  return Axes.names.filter((axis) => !dequal(before?.[axis], after?.[axis])).map(
     (axis) =>
       ({
         kind: 'restated',

package/src/projection/card/FieldExtension.ts

@@ -1,9 +1,12 @@
-import type { BoundaryRef } from '../../axis/boundary/BoundaryRef.js';
-import type { LifecycleRules } from '../../axis/lifecycle/LifecycleRules.js';
+import type { BoundaryRef } from '../../axis/boundary/Boundary.js';
+import type { LifecycleRules } from '../../axis/lifecycle/Lifecycle.js';
 import type { RoleDescriptor } from './RoleDescriptor.js';
 
 export interface FieldExtension {
   role?: RoleDescriptor;
   lifecycle?: LifecycleRules;
   boundary?: BoundaryRef;
+
+  /** An axis registered from outside writes its own slot here, under its own name. */
+  [slot: string]: unknown;
 }

package/src/projection/card/RoleDescriptor.ts

@@ -1,7 +1,53 @@
-import type { RoleRules } from '../../axis/role/RoleRules.js';
-import type { RelationDescriptor } from './RelationDescriptor.js';
+import type { EntityConstructor } from '../../axis/role/EntityConstructor.js';
+import type { Relation } from '../../axis/role/Relation.js';
+import type { RoleRules } from '../../axis/role/Role.js';
+import type { Resolver } from '../../axis/Resolver.js';
+import { lowerFirst } from '../../lib/utils.js';
+import type { CardForm } from './CardForm.js';
 
+/** What a role becomes on a card: a target is a NAME there, and a unique is a group. */
 export type RoleDescriptor = Pick<RoleRules, 'primary' | 'index'> & {
   unique?: string[][];
   relation?: RelationDescriptor;
 };
+
+export type RelationDescriptor = Pick<Relation, 'kind' | 'onDelete'> & { to: string };
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
+/** A card carries the target's NAME: a class cannot cross a process boundary. */
+export const roleOnCard: CardForm<RoleRules, RoleDescriptor> = {
+  describe(role, key) {
+    const descriptor: Mutable<RoleDescriptor> = {};
+    if (role.primary) descriptor.primary = true;
+    if (role.unique) descriptor.unique = [[key]];
+    if (role.index) descriptor.index = true;
+    if (role.relation) {
+      const target = role.relation.to() as { name?: string };
+      descriptor.relation = {
+        to: lowerFirst(target.name ?? ''),
+        kind: role.relation.kind,
+        ...(role.relation.onDelete ? { onDelete: role.relation.onDelete } : {}),
+      };
+    }
+
+    return Object.keys(descriptor).length ? descriptor : undefined;
+  },
+
+  reconstruct(wire, resolve?: Resolver) {
+    const rules: Mutable<RoleRules> = {};
+    if (wire.primary) rules.primary = true;
+    if (wire.unique?.some((group) => group.length === 1)) rules.unique = true;
+    if (wire.index) rules.index = true;
+    if (wire.relation) {
+      const name = wire.relation.to;
+      rules.relation = {
+        to: () => (resolve?.(name) ?? ({ name } as unknown)) as EntityConstructor,
+        kind: wire.relation.kind,
+        ...(wire.relation.onDelete ? { onDelete: wire.relation.onDelete } : {}),
+      };
+    }
+
+    return rules;
+  },
+};

package/src/projection/card/admission.ts

@@ -1,6 +1,5 @@
-import type { ValidationError } from '../../lib/ValidationError.js';
 import { Shapes } from '../../axis/shape/Shape.js';
-import { dotted } from '../../lib/ValidationResult.js';
+import { SchemaError } from '../../SchemaError.js';
 
 /**
  * Throws with what is wrong AND what to write: a card's author is in another process.
@@ -8,40 +7,9 @@ import { dotted } from '../../lib/ValidationResult.js';
  * `refuse('role.relation.kind is "maybe"', 'Expected one of one, many.')`
  */
 export function refuse(what: string, fix: string): never {
-  throw new Error(`This card cannot be read: ${what}.\n  ${fix}`);
+  throw new SchemaError(`This card cannot be read: ${what}.\n  ${fix}`);
 }
 
-/**
- * Runs a card's axis through the validator a hand-written field goes through, so there is
- * one judge and not two.
- * FR : passe l'axe d'une carte par le juge d'un champ écrit à la main : un juge, pas deux.
- * `{ update: 'maybe' }` → `lifecycle is malformed — lifecycle.update: Expected 'now' or 'forbidden'`
- */
-export function admitWire(
-  validator: (value: unknown, errors: ValidationError[]) => void,
-  value: unknown,
-  slot: string,
-): void {
-  const errors: ValidationError[] = [];
-  validator(value, errors);
-  if (errors.length) {
-    refuse(
-      `${slot} is malformed — ${errors.map((e) => `${dotted(e.path)}: ${e.message}`).join('; ')}`,
-      'A card states an axis the way a declaration does.',
-    );
-  }
-}
-
-/**
- * Checks a token against the list that declares it, never against a copy written here.
- * FR : vérifie un mot contre la liste qui le déclare, jamais contre une copie locale.
- * `oneOfTokens('many', RELATION_KINDS)` → `true`
- */
-export const oneOfTokens = <T extends readonly string[]>(
-  value: unknown,
-  tokens: T,
-): value is T[number] => typeof value === 'string' && (tokens as readonly string[]).includes(value);
-
 /**
  * Compiles every `pattern` at the facade, so a bad one is refused here and not at the first row.
  * FR : compile chaque `pattern` à la porte : un mauvais est refusé ici, pas au premier row.

package/src/validator/FieldDeclarationValidator.ts

@@ -1,9 +1,10 @@
-import { EXTENSION_AXES } from '../axis/Axis.js';
+import { Axes } from '../axis/Axes.js';
 import { Shapes } from '../axis/shape/Shape.js';
 import type { Field } from '../field/Field.js';
 import { isObject, shown } from '../lib/utils.js';
 import type { ValidationError } from '../lib/ValidationError.js';
 import type { ValidationResult } from '../lib/ValidationResult.js';
+import { JsonSchemaValidator } from './JsonSchemaValidator.js';
 
 export class FieldDeclarationValidator {
   private constructor(private readonly declaration: unknown) {}
@@ -36,23 +37,10 @@ export class FieldDeclarationValidator {
       });
     }
 
-    for (const axis of EXTENSION_AXES) {
-      const declared = declaration[axis.slot];
-      if (declared !== undefined) axis.validator(declared, errors);
-    }
+    errors.push(...JsonSchemaValidator.of(Axes.fieldFormat).refusalsOf(declaration, []));
 
-    if (declaration.meta !== undefined) {
-      if (!isObject(declaration.meta)) {
-        errors.push({
-          path: ['meta'],
-          message: `Expected an object — got ${shown(declaration.meta)}`,
-        });
-      } else if (
-        declaration.meta.description !== undefined &&
-        typeof declaration.meta.description !== 'string'
-      ) {
-        errors.push({ path: ['meta', 'description'], message: 'Expected a string' });
-      }
+    for (const [slot, axis] of Axes.entries) {
+      errors.push(...(axis.refusals?.(declaration[slot]) ?? []));
     }
 
     return errors.length