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

package/src/index.ts

@@ -1,69 +1,33 @@
-export { Field, type Fields } from './schema/fields/Field.js';
-export { FieldSet } from './schema/fields/FieldSet.js';
-export { type Shape, Anatomy } from './schema/axis/shape/Shape.js';
-export {
-  type StringFormat,
-  type FormatPredicate,
-  Formats,
-} from './schema/axis/shape/Formats.js';
-export { Role, type RoleRules } from './schema/axis/role/Role.js';
-export { type Relation, type EntityConstructor } from './schema/axis/role/Relation.js';
-export { Lifecycle, type LifecycleRules } from './schema/axis/lifecycle/Lifecycle.js';
-export { type GeneratorRef, Generators } from './schema/axis/lifecycle/Generators.js';
-export { Clock } from './schema/axis/lifecycle/Clock.js';
-export {
-  Boundary,
-  type BoundaryRules,
-  type BoundaryRef,
-} from './schema/axis/boundary/Boundary.js';
-export { type Decoder, type Encoder, Boundaries } from './schema/axis/boundary/Boundaries.js';
-export { type Meta } from './schema/axis/Meta.js';
-export { FieldGroup } from './schema/fields/constraint/FieldGroup.js';
-export { Unique } from './schema/fields/constraint/Unique.js';
+export { entity } from './entity.js';
 
-export {
-  Schema,
-  ANONYMOUS_SCHEMA_NAME,
-  type SchemaConstructor,
-} from './schema/Schema.js';
-export { SchemaDerivation } from './schema/SchemaDerivation.js';
-export { Cases, type Case } from './projection/Cases.js';
-export { RowRefusal } from './judge/RowRefusal.js';
-export { type SchemaView, type Row, type PartialRow } from './schema/SchemaView.js';
-export { type FougereEntityAdapters, type EntityAdapters } from './entity/EntityAdapters.js';
-export {
-  type EntityDeclarations,
-  type CompositeUnique,
-  type PreviousNames,
-} from './entity/EntityDeclarations.js';
-export { lowerFirst, upperFirst, isObject } from './utils.js';
+export * from './vocabulary/index.js';
 
-export { primary } from './vocabulary/primary.js';
-export { text } from './vocabulary/text.js';
-export { email } from './vocabulary/email.js';
-export { url } from './vocabulary/url.js';
-export { list } from './vocabulary/list.js';
-export { number } from './vocabulary/number.js';
-export { bool } from './vocabulary/bool.js';
-export { date } from './vocabulary/date.js';
-export { created } from './vocabulary/created.js';
-export { updated } from './vocabulary/updated.js';
-export { oneOf } from './vocabulary/oneOf.js';
-export { ref } from './vocabulary/ref.js';
-export { many } from './vocabulary/many.js';
-export { optional } from './vocabulary/optional.js';
-export { nullable } from './vocabulary/nullable.js';
-export { immutable } from './vocabulary/immutable.js';
-export { unique } from './vocabulary/unique.js';
-export { indexed } from './vocabulary/indexed.js';
-export { readOnly } from './vocabulary/readOnly.js';
-export { writeOnly } from './vocabulary/writeOnly.js';
-export { json } from './vocabulary/json.js';
+export { Schema, ANONYMOUS_SCHEMA_NAME, type SchemaConstructor } from './Schema.js';
+export { type SchemaView } from './SchemaView.js';
+export { Field, type Fields } from './field/Field.js';
+export { FieldSet } from './field/FieldSet.js';
+export { type Shape, Shapes } from './axis/shape/Shape.js';
+export { Role } from './axis/role/Role.js';
+export { type EntityConstructor } from './axis/role/Relation.js';
+export { Lifecycle, type LifecycleRules } from './axis/lifecycle/Lifecycle.js';
+export { Boundary, type BoundaryRef } from './axis/boundary/Boundary.js';
+export { applyCreate, applyUpdate } from './axis/lifecycle/apply.js';
+export { InputRefusal } from './validator/InputRefusal.js';
+export { type ValidationError, type ValidationResult } from './validation.js';
 
-export { applyCreate, applyUpdate } from './schema/axis/lifecycle/apply.js';
-export { Visibility } from './projection/Visibility.js';
 export { Card } from './projection/card/Card.js';
 export { Bundle } from './projection/card/Bundle.js';
+export { Visibility } from './projection/Visibility.js';
+export { Cases, type ValidationCase } from './projection/Cases.js';
+export type {
+  SchemaBundle,
+  SchemaDescriptor,
+  DerivedFrom,
+  FieldDescriptor,
+  FieldExtension,
+  RoleDescriptor,
+  RelationDescriptor,
+} from './projection/card/Descriptor.js';
 export type {
   Change,
   Diff,
@@ -73,34 +37,13 @@ export type {
   RenameCandidate,
   TypeSet,
 } from './projection/card/diff.js';
-export {
-  EntityTypeSource,
-  type EntityTypeSourceOptions,
-} from './projection/card/EntityTypeSource.js';
-export {
-  FacadeTypeSource,
-  type FacadeTypeSourceOptions,
-  type OpDescriptor,
-} from './projection/card/FacadeTypeSource.js';
-export {
-  type SchemaBundle,
-  type SchemaDescriptor,
-  type FieldDescriptor,
-  type FieldExtension,
-  type RoleDescriptor,
-  type RelationDescriptor,
-} from './projection/card/Descriptor.js';
-export { type SchemaOrCard, schemaOf, fieldsOf } from './projection/SchemaOrCard.js';
-export type { StandardSchemaV1 } from './projection/standard.js';
-
-export { entity } from './entity.js';
 
-export { FieldJudge } from './judge/FieldJudge.js';
-export { ValueJudge } from './judge/ValueJudge.js';
-export { RowJudge } from './judge/RowJudge.js';
-export { type ValidateOptions } from './judge/options.js';
-export {
-  type ValidationError,
-  type ValidationResult,
-  type Checked,
-} from './judge/result.js';
+export * from './lib/index.js';
+export { Formats } from './axis/shape/Formats.js';
+export { Generators } from './axis/lifecycle/Generators.js';
+export { Boundaries } from './axis/boundary/Boundaries.js';
+export { Clock } from './axis/lifecycle/Clock.js';
+export { type FougereEntityAdapters } from './entity/EntityAdapters.js';
+export { InputValidator } from './validator/InputValidator.js';
+export { FieldValueValidator } from './validator/FieldValueValidator.js';
+export { AdapterFieldValidator } from './validator/AdapterFieldValidator.js';

package/src/lib/Registry.ts

@@ -0,0 +1,37 @@
+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]>,
+  ) {
+    this.entries = new Map(builtins);
+  }
+
+  register(name: string, value: T): T {
+    this.entries.set(name, value);
+
+    return value;
+  }
+
+  find(name: string): T | undefined {
+    return this.entries.get(name);
+  }
+
+  resolve(name: string, path?: string): T {
+    const found = this.find(name);
+
+    if (found !== undefined) return found;
+
+    throw new Error(
+      `${path ? `${path}: ` : ''}Unknown ${this.label} '${name}'${this.hint ? ` — ${this.hint}` : ''}. ` +
+        `This process answers ${this.names.join(', ') || 'nothing yet'}.`,
+    );
+  }
+
+  private get names(): string[] {
+    return [...this.entries.keys()];
+  }
+}

package/src/lib/index.ts

@@ -0,0 +1,2 @@
+export * from './Registry.js';
+export * from './utils.js';

package/src/projection/Cases.ts

@@ -1,70 +1,74 @@
-import { Anatomy } from '../schema/axis/shape/Shape.js';
-import { Boundary } from '../schema/axis/boundary/Boundary.js';
-import { Lifecycle } from '../schema/axis/lifecycle/Lifecycle.js';
-import { Role } from '../schema/axis/role/Role.js';
-import type { Field } from '../schema/fields/Field.js';
-import type { SchemaView } from '../schema/SchemaView.js';
-import { RowJudge } from '../judge/RowJudge.js';
-import { RowRefusal } from '../judge/RowRefusal.js';
+import { Shapes } from '../axis/shape/Shape.js';
+import { Boundary } from '../axis/boundary/Boundary.js';
+import { Lifecycle } from '../axis/lifecycle/Lifecycle.js';
+import { Role } from '../axis/role/Role.js';
+import type { Field } from '../field/Field.js';
+import type { SchemaView } from '../SchemaView.js';
+import { InputValidator } from '../validator/InputValidator.js';
+import { InputRefusal } from '../validator/InputRefusal.js';
 
 /**
- * One input, and what the judge must answer.
+ * One input, and what the validator must answer.
  *
  * `expect` carries the PATH of the field at fault and never the message. We know which
  * field must be refused because we are the ones who broke it; naming the message would
- * make this list a second judge, and the two would then have to be kept in step by hand —
+ * make this list a second validator, and the two would then have to be kept in step by hand —
  * which is the duplication the whole thing exists to remove.
  */
-export interface Case {
+export interface ValidationCase {
   /** What this input does, in one clause — carried into the assertion so a failure reads. */
   why: string;
-  body: unknown;
-  /**
-   * Judged as an update rather than a creation. The two modes refuse different things:
-   * an absence is `Required` on create and legal on patch, an immutable field is legal
-   * on create and refused on patch.
-   */
+  input: unknown;
+  /** Judged as an update rather than a creation. */
   patch: boolean;
   expect: 'accept' | { reject: string };
 }
 
-/** A value of the wrong type for the declared shape — the one violation every field has. */
+/**
+ * So every field has at least one case, whatever else it declares.
+ * FR : pour que chaque champ ait un cas, quoi qu'il déclare par ailleurs.
+ * `text()` → `42`; `number()` → `'not-a-value-of-this-shape'`
+ */
 function wrongTypeFor(field: Field): unknown {
   const declared = (field.shape as { type?: string | readonly string[] }).type;
   const names = Array.isArray(declared) ? declared : [declared];
   return names.includes('string') ? 42 : 'not-a-value-of-this-shape';
 }
 
-/** Values that break a stated bound. Empty when the field states none. */
+/**
+ * So a bound stated in a shape produces the case that breaks it, and none is invented.
+ * FR : pour qu'une borne énoncée produise le cas qui la casse, et aucun autre.
+ * `text({ maxLength: 3 })` → one case with `'xxxx'`; `text()` → no case
+ */
 function outOfBoundsFor(field: Field): { why: string; value: unknown }[] {
-  // Through `Anatomy`, not a cast: the cast admitted any keyword, and it declared
+  // Through `Shapes`, not a cast: the cast admitted any keyword, and it declared
   // `maxItems` — which no branch below ever produced. In the one function whose job is
   // to be exhaustive, a bound the type does not carry is a case nobody notices missing.
-  const shape = Anatomy.of(field.shape).base;
-  const out: { why: string; value: unknown }[] = [];
+  const shape = Shapes.of(field.shape).base;
+  const cases: { why: string; value: unknown }[] = [];
   if (shape?.type === 'string') {
     if (typeof shape.minLength === 'number' && shape.minLength > 0)
-      out.push({ why: 'shorter than min', value: 'x'.repeat(shape.minLength - 1) });
+      cases.push({ why: 'shorter than min', value: 'x'.repeat(shape.minLength - 1) });
     if (typeof shape.maxLength === 'number')
-      out.push({ why: 'longer than max', value: 'x'.repeat(shape.maxLength + 1) });
-    if (shape.enum) out.push({ why: 'outside the stated set', value: '__not-in-enum__' });
+      cases.push({ why: 'longer than max', value: 'x'.repeat(shape.maxLength + 1) });
+    if (shape.enum) cases.push({ why: 'outside the stated set', value: '__not-in-enum__' });
   }
   if (shape?.type === 'number' || shape?.type === 'integer') {
     if (typeof shape.minimum === 'number')
-      out.push({ why: 'below minimum', value: shape.minimum - 1 });
+      cases.push({ why: 'below minimum', value: shape.minimum - 1 });
     if (typeof shape.maximum === 'number')
-      out.push({ why: 'above maximum', value: shape.maximum + 1 });
+      cases.push({ why: 'above maximum', value: shape.maximum + 1 });
   }
   if (shape?.type === 'array') {
     if (typeof shape.minItems === 'number' && shape.minItems > 0)
-      out.push({ why: 'fewer items than min', value: [] });
+      cases.push({ why: 'fewer items than min', value: [] });
     if (typeof shape.maxItems === 'number')
-      out.push({
+      cases.push({
         why: 'more items than max',
         value: Array.from({ length: shape.maxItems + 1 }, () => null),
       });
   }
-  return out;
+  return cases;
 }
 
 /**
@@ -74,20 +78,14 @@ function outOfBoundsFor(field: Field): { why: string; value: unknown }[] {
  * supplies a valid row; generating data belongs to the testing package.
  */
 export class Cases {
-  private constructor(readonly all: readonly Case[]) {}
+  private constructor(readonly all: readonly ValidationCase[]) {}
 
   static of(entity: SchemaView, valid: Record<string, unknown>): Cases {
     return new Cases(enumerate(entity, valid));
   }
 
-  /**
-   * Whether a verdict is the one a case expected.
-   *
-   * Takes the RESULT rather than the input so the same reader serves the local judge, the
-   * façade and a door — the three that have to agree.
-   */
   static holds(
-    expected: Case['expect'],
+    expected: ValidationCase['expect'],
     result: { success: boolean; errors?: { path: string }[] },
   ): boolean {
     if (expected === 'accept') return result.success;
@@ -95,32 +93,35 @@ export class Cases {
     return (result.errors ?? []).some((error) => error.path === expected.reject);
   }
 
-  /** Every way a row is refused for its structure — the closed set this table must cover. */
   static get refusals(): string[] {
-    return Object.values(RowRefusal);
+    return Object.values(InputRefusal);
   }
 
-  [Symbol.iterator](): Iterator<Case> {
+  [Symbol.iterator](): Iterator<ValidationCase> {
     return this.all[Symbol.iterator]();
   }
 }
 
-function enumerate(entity: SchemaView, valid: Record<string, unknown>): Case[] {
+/**
+ * So the four axes decide which cases exist, and no list of them is maintained by hand.
+ * FR : pour que les axes décident des cas, sans liste tenue à la main.
+ */
+function enumerate(entity: SchemaView, valid: Record<string, unknown>): ValidationCase[] {
   const fields = entity.getFields();
-  const judge = RowJudge.of(fields);
-  const cases: Case[] = [];
+  const validator = InputValidator.of(fields);
+  const cases: ValidationCase[] = [];
   const withField = (name: string, value: unknown) => ({ ...valid, [name]: value });
 
-  cases.push({ why: 'a valid body', body: valid, patch: false, expect: 'accept' });
+  cases.push({ why: 'a valid input', input: valid, patch: false, expect: 'accept' });
   cases.push({
     why: 'a key outside the contract',
-    body: { ...valid, __unknown__: 'x' },
+    input: { ...valid, __unknown__: 'x' },
     patch: false,
     expect: { reject: '__unknown__' },
   });
   cases.push({
     why: 'not an object at all',
-    body: 'a string',
+    input: 'a string',
     patch: false,
     expect: { reject: '.' },
   });
@@ -130,16 +131,16 @@ function enumerate(entity: SchemaView, valid: Record<string, unknown>): Case[] {
     // 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 (judge.onAbsent(field) === null && name in valid) {
-      const body = { ...valid };
-      delete body[name];
-      cases.push({ why: `${name} absent`, body, 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 (Boundary.of(field).readOnly) {
       cases.push({
         why: `${name} supplied although read-only`,
-        body: withField(name, wrongTypeFor(field)),
+        input: withField(name, wrongTypeFor(field)),
         patch: false,
         expect: { reject: name },
       });
@@ -148,7 +149,7 @@ function enumerate(entity: SchemaView, valid: Record<string, unknown>): Case[] {
     if (Lifecycle.of(field).immutable && !Role.of(field).isPrimary) {
       cases.push({
         why: `${name} supplied on an update`,
-        body: { [name]: valid[name] ?? wrongTypeFor(field) },
+        input: { [name]: valid[name] ?? wrongTypeFor(field) },
         patch: true,
         expect: { reject: name },
       });
@@ -157,14 +158,14 @@ function enumerate(entity: SchemaView, valid: Record<string, unknown>): Case[] {
     if (name in valid && !isRef) {
       cases.push({
         why: `${name} of the wrong type`,
-        body: withField(name, wrongTypeFor(field)),
+        input: withField(name, wrongTypeFor(field)),
         patch: false,
         expect: { reject: name },
       });
       for (const { why, value } of outOfBoundsFor(field))
         cases.push({
           why: `${name} ${why}`,
-          body: withField(name, value),
+          input: withField(name, value),
           patch: false,
           expect: { reject: name },
         });

package/src/projection/Visibility.ts

@@ -1,7 +1,7 @@
-import { Boundary } from '../schema/axis/boundary/Boundary.js';
-import { Lifecycle } from '../schema/axis/lifecycle/Lifecycle.js';
-import { Role } from '../schema/axis/role/Role.js';
-import type { Fields } from '../schema/fields/Field.js';
+import { Boundary } from '../axis/boundary/Boundary.js';
+import { Lifecycle } from '../axis/lifecycle/Lifecycle.js';
+import { Role } from '../axis/role/Role.js';
+import type { Fields } from '../field/Field.js';
 
 export class Visibility {
   private constructor(private readonly fields: Fields) {}
@@ -10,6 +10,7 @@ export class Visibility {
     return new Visibility(fields);
   }
 
+  /** A write-only secret is absent from the type, not just from the value. */
   get input(): Fields {
     const result: Fields = {};
     for (const [name, field] of Object.entries(this.fields)) {

package/src/projection/card/Bundle.ts

@@ -1,7 +1,7 @@
-import type { Resolver } from '../../schema/axis/Axis.js';
-import type { EntityConstructor } from '../../schema/axis/role/Relation.js';
-import { lowerFirst } from '../../utils.js';
-import type { SchemaView } from '../../schema/SchemaView.js';
+import type { Resolver } from '../../axis/Axis.js';
+import type { EntityConstructor } from '../../axis/role/Relation.js';
+import { lowerFirst } from '../../lib/utils.js';
+import type { SchemaView } from '../../SchemaView.js';
 import { Card } from './Card.js';
 import type { SchemaBundle, SchemaDescriptor } from './Descriptor.js';
 import type { Diff, SetDiff, SetDiffOptions } from './diff.js';
@@ -47,12 +47,12 @@ export class Bundle {
   }
 
   toSchemas(): Record<string, SchemaView> {
-    const map: Record<string, EntityConstructor> = {};
-    const resolve: Resolver = (name) => map[name.toLowerCase()];
+    const byName: Record<string, EntityConstructor> = {};
+    const resolve: Resolver = (name) => byName[name.toLowerCase()];
     const schemas: Record<string, SchemaView> = {};
     for (const [name, descriptor] of Object.entries(this.descriptor.$defs)) {
       const schema = Card.fromDescriptor(descriptor).toSchema(resolve, name);
-      map[name.toLowerCase()] = schema as unknown as EntityConstructor;
+      byName[name.toLowerCase()] = schema as unknown as EntityConstructor;
       schemas[name] = schema;
     }
     return schemas;
@@ -65,11 +65,11 @@ export class Bundle {
     for (const [name, descriptor] of Object.entries(before)) {
       const target = after[name];
       if (target === undefined) continue;
-      const answer = Card.fromDescriptor(descriptor).diff(
+      const diff = Card.fromDescriptor(descriptor).diff(
         Card.fromDescriptor(target),
         { renamed: options.renamed?.[name] ?? {} },
       );
-      if (answer.changes.length > 0 || answer.ambiguous.length > 0) entities[name] = answer;
+      if (diff.changes.length > 0 || diff.ambiguous.length > 0) entities[name] = diff;
     }
     return {
       entitiesAdded: Object.keys(after).filter((name) => !(name in before)),