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

package/src/SchemaDefinition.ts

@@ -9,6 +9,7 @@ import { SchemaDerivation } from './SchemaDerivation.js';
 import { type ValidateOptions } from './validator/ValidateOptions.js';
 import type { SchemaView } from './SchemaView.js';
 import { SchemaConstraints } from './SchemaConstraints.js';
+import { SchemaError } from './SchemaError.js';
 
 /**
  * Everything a definition is made of, every member required.
@@ -225,7 +226,7 @@ export class SchemaDefinition {
     const strangers = keys.filter((key) => !Object.hasOwn(this.fields, key));
     if (strangers.length === 0) return;
 
-    throw new Error(
+    throw new SchemaError(
       `${operation}(): unknown field ${strangers.map((s) => `\`${s}\``).join(', ')}. ` +
         `This schema carries ${Object.keys(this.fields).join(', ')}.`,
     );

package/src/SchemaError.ts

@@ -0,0 +1,7 @@
+export class SchemaError extends Error {
+  constructor(message: string) {
+    super(message);
+
+    this.name = new.target.name;
+  }
+}

package/src/SchemaView.ts

@@ -5,7 +5,7 @@ import type { EntityAdapters } from './entity/EntityAdapters.js';
 import type { ValidationResult } from './lib/ValidationResult.js';
 import type { ValidateOptions } from './validator/ValidateOptions.js';
 import type { SchemaDerivation } from './SchemaDerivation.js';
-import type { Values } from './Values.js';
+import type { Values } from './field/Values.js';
 
 export interface SchemaView<TFields extends Fields = Fields> {
   readonly name: string;

package/src/axis/boundary/Boundary.ts

@@ -5,6 +5,7 @@ import type { Field } from '../../field/Field.js';
 import { type Shape } from '../shape/Shape.js';
 import { Shapes } from '../shape/Shape.js';
 import type { BoundaryRules } from './BoundaryRules.js';
+import { SchemaError } from '../../SchemaError.js';
 
 const identityDecoder: Decoder = (value) => ({ value });
 
@@ -33,7 +34,7 @@ export class Boundary {
     if (typeof ref !== 'string') return new Boundary(ref);
 
     const alias = Boundaries.aliases.find(ref);
-    if (!alias) throw new Error(`Unknown boundary alias: '${ref}'`);
+    if (!alias) throw new SchemaError(`Unknown boundary alias: '${ref}'`);
     return new Boundary(alias);
   }
 
@@ -58,7 +59,7 @@ export class Boundary {
 
   /** `date-time` means a `Date` on both sides, without a word in the entity. */
   static forShape(shape: Shape | undefined): Boundary {
-    if (Shapes.typeOf(shape) === 'date') return new Boundary(Boundaries.aliases.find('isoDate')!);
+    if (Shapes.typeOf(shape) === 'date') return new Boundary(Boundaries.aliases.resolve('isoDate'));
     return new Boundary();
   }
 

package/src/axis/boundary/Decoder.ts

@@ -1,13 +1,14 @@
 import type { BoundaryRules } from './BoundaryRules.js';
 import { Registry } from '../../lib/Registry.js';
 import type { Encoder } from './Encoder.js';
+import type { Verdict } from '../../lib/Verdict.js';
 
 /**
  * Wire to domain, and it must ANSWER a value it already produced: two facades decode — the
  * client one on what arrives, `StorageGuard` on what a handler writes — so a decoder that
  * halves cents halves them twice and stores a hundredth.
  */
-export type Decoder = (value: unknown) => { value: unknown } | { error: string };
+export type Decoder = (value: unknown) => Verdict;
 
 /**
  * `decoders` for a value coming in, `encoders` for one going out, `aliases` for the word
@@ -32,9 +33,9 @@ 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 Number.isNaN(date.getTime()) ? { message: 'Invalid date' } : { value: date };
   }
-  return { error: 'Expected a date' };
+  return { message: 'Expected a date' };
 });
 Boundaries.encoders.register('isoDate', (value) =>
   value instanceof Date ? value.toISOString() : value,

package/src/axis/lifecycle/Clock.ts

@@ -1,14 +1,3 @@
-/**
- * What "now" means, for the two functions that stamp it.
- *
- * The ONE place either of them reads the time, which is what makes it substitutable at
- * all: `created()`, `updated()` and `create: 'now'` are realized through this and nowhere
- * else, so a test that needs a stable instant sets it here instead of intercepting `Date`
- * globally — where Rails had to build `travel_to` over the language.
- *
- * A value rather than a mock: nothing here is a channel, and a frozen clock is a fact
- * about the run, not an interception of a call.
- */
 export class Clock {
   private static reading: () => number = Date.now;
 
@@ -16,11 +5,18 @@ export class Clock {
     return this.reading();
   }
 
-  /** One substitution moves time for every stamp in the process at once. */
+  /**
+   *
+   * @returns function to restore the clock
+   */
   static freeze(at: number | Date): () => void {
     const previous = this.reading;
     const instant = at instanceof Date ? at.getTime() : at;
+
     this.reading = () => instant;
-    return () => { this.reading = previous; };
+
+    return () => {
+      this.reading = previous;
+    };
   }
 }

package/src/axis/lifecycle/Generators.ts

@@ -2,28 +2,16 @@ 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('');
-}
+export type GeneratorRef = 'cuid2' | (string & {});
 
 /**
- * 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
+ * Who answers a `generate:` name. `cuid2` is registered like any other, so
+ * `Generators.resolve('uuid')` is refused here and names what the process holds.
+ * `Generators.register('uuid', () => globalThis.crypto.randomUUID())` →
+ * `create: { generate: 'uuid' }` now resolves
  */
 export const Generators = new Registry<() => string>(
   'generator',
   'call Generators.register(name, fn)',
-  [
-    ['cuid2', createId],
-    ['uuid', () => globalThis.crypto.randomUUID()],
-    ['nanoid', nanoid],
-  ],
+  [['cuid2', createId]],
 );

package/src/axis/lifecycle/Lifecycle.ts

@@ -1,4 +1,4 @@
-import type { GeneratorRef } from './Generators.js';
+import { Generators } from './Generators.js';
 import type { LifecycleRules } from './LifecycleRules.js';
 
 export class Lifecycle {
@@ -14,11 +14,22 @@ export class Lifecycle {
     return new Lifecycle(field.lifecycle);
   }
 
+  bornWith(instant: number): { value: unknown } | undefined {
+    const rule = this.create;
+
+    if (rule === 'now') return { value: new Date(instant) };
+
+    if (typeof rule !== 'object') return undefined;
+
+    if ('value' in rule) return { value: structuredClone(rule.value) };
+
+    return { value: Generators.resolve(rule.generate)() };
+  }
+
   get requiredAtCreate(): boolean {
     return this.create === undefined;
   }
 
-  /** The server fills it at create, so a client form never carries it. */
   get stampedAtCreate(): boolean {
     return this.create === 'now';
   }
@@ -37,15 +48,9 @@ export class Lifecycle {
 
   get literal(): { value: unknown } | undefined {
     const rule = this.create;
+
     return typeof rule === 'object' && rule !== null && 'value' in rule
       ? { value: (rule as { value: unknown }).value }
       : undefined;
   }
-
-  get generator(): GeneratorRef | undefined {
-    const rule = this.create;
-    return typeof rule === 'object' && rule !== null && 'generate' in rule
-      ? (rule as { generate: GeneratorRef }).generate
-      : undefined;
-  }
 }

package/src/axis/lifecycle/apply.ts

@@ -1,5 +1,4 @@
 import { Lifecycle } from './Lifecycle.js';
-import { Generators } from './Generators.js';
 import { Clock } from './Clock.js';
 import { type Field } from '../../field/Field.js';
 import { type Fields } from '../../field/Fields.js';
@@ -15,27 +14,14 @@ export function applyCreate(fields: Fields, input: Record<string, unknown>): Rec
 
   for (const [name, field] of Object.entries(fields) as [string, Field][]) {
     if (name in values) continue;
-    const rule = Lifecycle.of(field);
+    const born = Lifecycle.of(field).bornWith(instant);
 
-    if (rule.stampedAtCreate) 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)();
+    if (born) values[name] = born.value;
   }
 
   return values;
 }
 
-/**
- * Clones a declared default, so two rows born of `create: { value: [] }` hold two arrays.
- * FR : clone un défaut déclaré, pour que deux lignes nées de `create: { value: [] }`
- * tiennent deux tableaux.
- * `create: { value: [] }` → each instance gets its own array
- */
-function freshValue(value: unknown): unknown {
-  if (value === null || typeof value !== 'object') return value;
-  return structuredClone(value);
-}
-
 /**
  * The dual of `applyCreate` on a patch: only `update: 'now'` fields are touched.
  * FR : le dual d'`applyCreate` sur une modification : seuls les champs `update: 'now'`

package/src/axis/shape/Shape.ts

@@ -48,6 +48,9 @@ type _ShapeTypesAreTheStandardsLessNull = Assert<
 >;
 
 export class Shapes {
+  private static readonly cache = new WeakMap<object, ShapeParts>();
+  private static readonly none: ShapeParts = { base: undefined, nullable: false };
+
   static is(value: unknown): value is Shape {
     if (typeof value !== 'object' || value === null) return false;
     const type = (value as Shape).type;
@@ -96,9 +99,6 @@ export class Shapes {
     return nullable;
   }
 
-  private static readonly cache = new WeakMap<object, ShapeParts>();
-  private static readonly none: ShapeParts = { base: undefined, nullable: false };
-
   static of(shape?: Shape): ShapeParts {
     if (!shape) return this.none;
     let parts = this.cache.get(shape);

package/src/entity/EntityAdapterSet.ts

@@ -1,6 +1,7 @@
 import type { Fields } from '../field/Fields.js';
 import { isObject } from '../lib/utils.js';
 import type { EntityAdapters } from './EntityAdapters.js';
+import { SchemaError } from '../SchemaError.js';
 
 type AdapterConfiguration = Record<string, unknown>;
 type AdapterConfigurations = Record<string, AdapterConfiguration>;
@@ -19,14 +20,14 @@ export class EntityAdapterSet {
     if (!adapters) return new EntityAdapterSet({});
 
     if (!isObject(adapters)) {
-      throw new Error(
+      throw new SchemaError(
         `adapters: expected an object keyed by adapter name, got ${typeof adapters}.`,
       );
     }
 
     for (const [adapter, fields] of Object.entries(adapters)) {
       if (!isObject(fields)) {
-        throw new Error(
+        throw new SchemaError(
           `adapters.${adapter}: expected an object keyed by field name, got ${typeof fields}. ` +
             `What an adapter is handed is addressed by the field it applies to.`,
         );

package/src/entity.ts

@@ -5,7 +5,6 @@ import { type SchemaConstructor } from './SchemaConstructor.js';
 
 /**
  * The one call everything derives from: the fields, and what the entity states about them.
- * FR : l'appel dont tout dérive : les champs, et ce que l'entité en dit.
  * `class Post extends entity({ id: primary(), title: text() }, { unique: [['title']] }) {}`
  *
  * Documented: [entities](https://fougere.dev/docs/schema/entities).

package/src/field/Field.ts

@@ -7,6 +7,7 @@ import type { Axis } from '../axis/Axis.js';
 import { FieldDeclarationValidator } from '../validator/FieldDeclarationValidator.js';
 import { FieldValueValidator } from '../validator/FieldValueValidator.js';
 import { dotted } from '../lib/ValidationResult.js';
+import { SchemaError } from '../SchemaError.js';
 
 type FieldDeclaration = Pick<Field, 'shape' | Axis['slot'] | 'meta'>;
 
@@ -23,7 +24,7 @@ export class Field<T = unknown> {
     const verdict = FieldDeclarationValidator.of(init).verdict;
 
     if (!verdict.success) {
-      throw new Error(
+      throw new SchemaError(
         `${key ? `Field '${key}': ` : ''}` +
           verdict.errors.map((e) => `${dotted(e.path)}: ${e.message}`).join('; '),
       );
@@ -38,10 +39,10 @@ export class Field<T = unknown> {
     const create = this.lifecycle?.create;
     if (typeof create === 'object' && create !== null && 'value' in create) {
       const checked = FieldValueValidator.of(this).validate(create.value);
-      if ('error' in checked)
-        throw new Error(
+      if ('message' in checked)
+        throw new SchemaError(
           `${key ? `Field '${key}': ` : ''}the declared default ${JSON.stringify(create.value)} ` +
-            `is not a legal value for it — ${checked.error}.`,
+            `is not a legal value for it — ${checked.message}.`,
         );
     }
   }

package/src/field/FieldSet.ts

@@ -3,6 +3,7 @@ import type { CompositeUnique } from '../entity/CompositeUnique.js';
 import { Field } from './Field.js';
 import { type FieldName } from './FieldName.js';
 import { type Fields } from './Fields.js';
+import { SchemaError } from '../SchemaError.js';
 
 export class FieldSet<TFields extends Fields = Fields> {
   private constructor(private readonly fields: TFields) {}
@@ -28,14 +29,15 @@ export class FieldSet<TFields extends Fields = Fields> {
     for (const group of unique ?? []) {
       const missing = group.filter((key) => !Object.hasOwn(fields, key));
       if (missing.length)
-        throw new Error(
+        throw new SchemaError(
           `unique: [${group.join(', ')}] names ` +
             `${missing.map((key) => `'${key}'`).join(', ')}, which the entity does not declare.`,
         );
 
       if (group.length === 1) {
         const key = group[0]!;
-        fields[key] = fields[key]!.with({ role: { ...fields[key]!.role, unique: true } });
+        const alone = fields[key]!;
+        fields[key] = alone.with({ role: { ...alone.role, unique: true } });
         continue;
       }
       composite.push([...group]);
@@ -51,7 +53,7 @@ export class FieldSet<TFields extends Fields = Fields> {
       .map(([name]) => name);
 
     if (primaries.length > 1) {
-      throw new Error(
+      throw new SchemaError(
         `FieldSet.primary: ${primaries.map((name) => JSON.stringify(name)).join(', ')} all declare ` +
           '`primary`; a field set can have only one primary field.',
       );

package/src/{Values.ts → field/Values.ts}

@@ -1,5 +1,5 @@
-import type { Field } from './field/Field.js';
-import type { Fields } from './field/Fields.js';
+import type { Field } from './Field.js';
+import type { Fields } from './Fields.js';
 
 export type Values<TFields extends Fields> = {
   [K in keyof TFields]: TFields[K] extends Field<infer T> ? T : never;

package/src/index.ts

@@ -18,7 +18,9 @@ export { Lifecycle } from './axis/lifecycle/Lifecycle.js';
 export { Boundary } from './axis/boundary/Boundary.js';
 export { applyCreate, applyUpdate } from './axis/lifecycle/apply.js';
 export { InputRefusal } from './validator/InputRefusal.js';
+export { SchemaError } from './SchemaError.js';
 export { type ValidationError } from './lib/ValidationError.js';
+export { type Verdict } from './lib/Verdict.js';
 export { dotted, type ValidationResult } from './lib/ValidationResult.js';
 
 export { Card } from './projection/card/Card.js';

package/src/lib/Registry.ts

@@ -1,13 +1,14 @@
+import { SchemaError } from '../SchemaError.js';
+
 export class Registry<T> {
   private readonly entries: Map<string, T>;
 
-  /** `Unknown boundary decoder 'celsius' — call Boundaries.decoders.register(name, fn).` */
   constructor(
     private readonly label: string,
     private readonly hint?: string,
-    builtins?: Iterable<readonly [string, T]>,
+    entries?: Iterable<readonly [string, T]>,
   ) {
-    this.entries = new Map(builtins);
+    this.entries = new Map(entries);
   }
 
   register(name: string, value: T): T {
@@ -25,7 +26,7 @@ export class Registry<T> {
 
     if (found !== undefined) return found;
 
-    throw new Error(
+    throw new SchemaError(
       `${path ? `${path}: ` : ''}Unknown ${this.label} '${name}'${this.hint ? ` — ${this.hint}` : ''}. ` +
         `This process answers ${this.names.join(', ') || 'nothing yet'}.`,
     );

package/src/lib/Verdict.ts

@@ -0,0 +1,10 @@
+import type { ValidationError } from './ValidationError.js';
+
+/**
+ * A field's verdict — the value it admitted, or a refusal whose `path` says where INSIDE the
+ * value it happened. That path is optional here and required on a `ValidationError`: a field
+ * does not know its own name, so the key is prefixed by whoever iterates the fields.
+ */
+export type Verdict =
+  | { value: unknown }
+  | (Omit<ValidationError, 'path'> & { path?: ValidationError['path'] });

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/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

@@ -8,7 +8,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 +16,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]> };
 
@@ -165,7 +166,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 +193,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.',
     );
@@ -215,7 +220,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 ??= {});