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

package/src/axis/role/Role.ts

@@ -1,56 +1,72 @@
-import type { EntityConstructor } from './EntityConstructor.js';
 import type { Relation } from './Relation.js';
-import type { RoleRules } from './RoleRules.js';
+import type { EntityConstructor } from './EntityConstructor.js';
+import { isObject } from '../../lib/utils.js';
+import { Format, type Accepted } from '../../lib/Format.js';
+import { ON_DELETE, RELATION_KINDS } from './Relation.js';
 
 export class Role {
-  private readonly primary?: boolean;
-  private readonly index?: boolean;
-  private readonly unique?: boolean;
-  private readonly relation?: Relation;
+  static readonly format = Format.of('axis/role')
+    .key('primary', Format.flag)
+    .key('index', Format.flag)
+    .key('unique', Format.flag)
+    .key(
+      'relation',
+      Format.of()
+        .key('to', Format.anything.as<() => EntityConstructor>())
+        .key('kind', Format.tokens(RELATION_KINDS))
+        .key('onDelete', Format.tokens(ON_DELETE))
+        .needs('to', 'kind')
+        .closed(),
+    )
+    .closed();
+
+  static refusals(value: unknown) {
+    const relation = isObject(value) ? value.relation : undefined;
+    if (!isObject(relation) || !('to' in relation) || typeof relation.to === 'function') return [];
 
-  private constructor(rules: RoleRules = {}) {
-    this.primary = rules.primary;
-    this.index = rules.index;
-    this.unique = rules.unique;
-    this.relation = rules.relation;
+    return [{ path: ['role', 'relation', 'to'], message: 'Expected a function returning the target entity, such as () => Post' }];
   }
 
+  private constructor(private readonly rules: RoleRules = {}) {}
+
   static of(field: { role?: RoleRules }): Role {
     return new Role(field.role);
   }
 
   get isPrimary(): boolean {
-    return this.primary === true;
+    return this.rules.primary === true;
   }
 
   get isIndexed(): boolean {
-    return this.index === true;
+    return this.rules.index === true;
   }
 
   /** A field unique on its own. A group spanning several belongs to the schema. */
   get isUnique(): boolean {
-    return this.unique === true;
+    return this.rules.unique === true;
   }
 
   get isCollection(): boolean {
-    return this.relation?.kind === 'many';
+    return this.rules.relation?.kind === 'many';
   }
 
   get isReference(): boolean {
-    return this.relation?.kind === 'one';
+    return this.rules.relation?.kind === 'one';
   }
 
   /** Either kind — what a CLI flag and a GraphQL selection both leave out. */
   get isRelation(): boolean {
-    return this.relation !== undefined;
+    return this.rules.relation !== undefined;
   }
 
   /** Calls `() => Post` so no caller has to. */
   get target(): EntityConstructor | undefined {
-    return this.relation?.to();
+    return this.rules.relation?.to();
   }
 
   get onDelete(): Relation['onDelete'] {
-    return this.relation?.onDelete;
+    return this.rules.relation?.onDelete;
   }
 }
+
+export type RoleRules = Accepted<typeof Role.format>;

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/axis/shape/{Formats.ts → StringFormats.ts}

@@ -5,6 +5,6 @@ import type { FormatPredicate } from './FormatPredicate.js';
  * String formats the JSON Schema engine does not know. `find` answers `undefined` for
  * `email` or `uuid`, which it validates on its own.
  * FR : les formats de chaîne que le moteur ignore ; `find` rend `undefined` pour les siens.
- * `Formats.register('siret', (v) => /^\d{14}$/.test(v))`
+ * `StringFormats.register('siret', (v) => /^\d{14}$/.test(v))`
  */
-export const Formats = new Registry<FormatPredicate>('format');
+export const StringFormats = new Registry<FormatPredicate>('format');

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

@@ -1,14 +1,22 @@
 import type { Shape } from '../axis/shape/Shape.js';
-import type { RoleRules } from '../axis/role/RoleRules.js';
-import type { LifecycleRules } from '../axis/lifecycle/LifecycleRules.js';
-import type { BoundaryRef } from '../axis/boundary/BoundaryRef.js';
+import type { RoleRules } from '../axis/role/Role.js';
+import type { LifecycleRules } from '../axis/lifecycle/Lifecycle.js';
+import type { BoundaryRef } from '../axis/boundary/Boundary.js';
 import type { Meta } from './Meta.js';
-import type { Axis } from '../axis/Axis.js';
+import { Axes } from '../axis/Axes.js';
+import type { FougereFieldAxes } from './FougereFieldAxes.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'>;
+interface FieldDeclaration extends FougereFieldAxes {
+  shape: Shape;
+  role?: RoleRules;
+  lifecycle?: LifecycleRules;
+  boundary?: BoundaryRef;
+  meta?: Meta;
+}
 
 export class Field<T = unknown> {
   readonly shape: Shape;
@@ -23,25 +31,28 @@ 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('; '),
       );
     }
 
     this.shape = init.shape;
-    this.role = init.role;
-    this.lifecycle = init.lifecycle;
-    this.boundary = init.boundary;
     this.meta = init.meta;
 
+    const stated = init as unknown as Record<string, unknown>;
+
+    for (const slot of Axes.names) {
+      (this as unknown as Record<string, unknown>)[slot] = stated[slot];
+    }
+
     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/FieldFormat.ts

@@ -0,0 +1,18 @@
+import type { Axis } from '../axis/Axis.js';
+import { Format } from '../lib/Format.js';
+import type { JsonSchema } from '../lib/JsonSchema.js';
+import { META_FORMAT } from './Meta.js';
+
+/**
+ * What a field may state, composed from the keys that state a format: each is carried whole and
+ * cited by its `$id`, so the document travels alone and a key keeps its own identity. `shape` is
+ * JSON Schema itself, and `Shapes.is` is what reads it.
+ */
+export function fieldFormat(axes: readonly [string, Axis][]): JsonSchema {
+  const document = axes.reduce(
+    (held, [slot, axis]) => held.cites(slot, axis.format),
+    Format.of('field').key('shape', Format.anything),
+  );
+
+  return document.cites('meta', META_FORMAT).closed().schema as JsonSchema;
+}

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/field/FougereFieldAxes.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface FougereFieldAxes {}

package/src/field/Meta.ts

@@ -1,3 +1,5 @@
-export interface Meta {
-  description?: string;
-}
+import { Format, type Accepted } from '../lib/Format.js';
+
+export const META_FORMAT = Format.of('field/meta').key('description', Format.text).closed();
+
+export type Meta = Accepted<typeof META_FORMAT>;

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';
@@ -35,11 +37,14 @@ export type { SetDiff } from './projection/card/SetDiff.js';
 export type { SetDiffOptions } from './projection/card/SetDiffOptions.js';
 
 export * from './lib/index.js';
-export { Formats } from './axis/shape/Formats.js';
+export { StringFormats } from './axis/shape/StringFormats.js';
 export { Generators } from './axis/lifecycle/Generators.js';
 export { Boundaries } from './axis/boundary/Decoder.js';
-export { Clock } from './axis/lifecycle/Clock.js';
 export { type FougereEntityAdapters } from './entity/FougereEntityAdapters.js';
 export { InputValidator } from './validator/InputValidator.js';
 export { FieldValueValidator } from './validator/FieldValueValidator.js';
-export { AdapterFieldValidator } from './validator/AdapterFieldValidator.js';
+export { JsonSchemaValidator } from './validator/JsonSchemaValidator.js';
+export type { JsonSchema } from './lib/JsonSchema.js';
+export { Axes } from './axis/Axes.js';
+export { Format } from './lib/Format.js';
+export type { Axis } from './axis/Axis.js';

package/src/lib/Format.ts

@@ -0,0 +1,139 @@
+import type { JsonSchema } from './JsonSchema.js';
+import { SchemaError } from '../SchemaError.js';
+
+type Stated = JsonSchema | boolean;
+
+const HERE = 'https://fougere.dev/schema/';
+
+const absolute = (id?: string): string | undefined =>
+  id === undefined || id.includes('://') ? id : `${HERE}${id}`;
+
+/** The values a format lets in, as a type — `Accepted<typeof Lifecycle.format>`. */
+export type Accepted<F> = F extends Format<infer T> ? T : never;
+
+/**
+ * How a format is written here: its keys, never its JSON Schema. `$id`, `$ref`, `$defs` and the
+ * closing are produced, and what it accepts is carried as a TYPE, so a declaration is stated once.
+ * FR : on écrit les clés d'un format ; le document et le type sont produits.
+ * `Format.of('axis/tenancy').key('scope', Format.tokens(SCOPES)).closed()`
+ */
+export class Format<T = unknown> {
+  static readonly anything = new Format<unknown>(true);
+  static readonly text = new Format<string>({ type: 'string' });
+  static readonly flag = new Format<boolean>({ type: 'boolean' });
+
+  declare readonly _admits?: T;
+
+  protected constructor(
+    private readonly stated: Stated,
+    readonly id?: string,
+  ) {}
+
+  /** `Format.tokens(['now', 'optional'])` → `Instance does not match any of ["now","optional"].` */
+  static tokens<const Words extends readonly string[]>(words: Words): Format<Words[number]> {
+    return new Format({ enum: [...words] });
+  }
+
+  /** A word or a shape, told apart by TYPE, so a refusal names the half the value belongs to. */
+  static either<Word, Shape>(word: Format<Word>, shape: Format<Shape>): Format<Word | Shape> {
+    return new Format({
+      if: { type: 'string' },
+      then: word.schema as JsonSchema,
+      else: shape.schema as JsonSchema,
+    });
+  }
+
+  /** One of these keys and no other — `{ value }` or `{ generate }`, never both and never neither. */
+  static exactlyOne<Keys extends Record<string, Format<unknown>>>(
+    keys: Keys,
+  ): Format<{ [K in keyof Keys]: { [P in K]: Accepted<Keys[K]> } }[keyof Keys]> {
+    return new Format({
+      type: 'object',
+      properties: Object.fromEntries(
+        Object.entries(keys).map(([key, format]) => [key, format.schema]),
+      ),
+      propertyNames: { enum: Object.keys(keys) },
+      minProperties: 1,
+      maxProperties: 1,
+    });
+  }
+
+  /** A name resolves under this project's own space; another one states its whole `$id`. */
+  static of(id?: string): ObjectFormat<object> {
+    return new ObjectFormat(absolute(id));
+  }
+
+  /** What `of` does for an object, for a format that is not one — `either`, a list of words. */
+  static named<Value>(id: string, format: Format<Value>): Format<Value> {
+    const named = absolute(id) as string;
+
+    return new Format({ $id: named, ...(format.schema as JsonSchema) }, named);
+  }
+
+  /** The type JSON Schema cannot carry: a generator's name, a thunk to an entity. */
+  as<Value>(): Format<Value> {
+    return this as unknown as Format<Value>;
+  }
+
+  get schema(): Stated {
+    return this.stated;
+  }
+}
+
+export class ObjectFormat<T extends object> extends Format<T> {
+  private readonly keys = new Map<string, Stated>();
+  private readonly cited = new Map<string, JsonSchema>();
+  private readonly needed: string[] = [];
+
+  constructor(id?: string) {
+    super(true, id);
+  }
+
+  key<Name extends string, Value>(
+    name: Name,
+    format: Format<Value>,
+  ): ObjectFormat<T & { [K in Name]?: Value }> {
+    this.keys.set(name, format.schema);
+
+    return this as ObjectFormat<T & { [K in Name]?: Value }>;
+  }
+
+  /** A key carried whole and pointed at by its `$id`, so it keeps an identity of its own. */
+  cites<Name extends string, Value>(
+    name: Name,
+    format: Format<Value>,
+  ): ObjectFormat<T & { [K in Name]?: Value }> {
+    if (!format.id) {
+      throw new SchemaError(
+        `A format cited as '${name}' states no \`$id\`, so nothing can point at it.`,
+      );
+    }
+    this.keys.set(name, { $ref: format.id });
+    this.cited.set(name, format.schema as JsonSchema);
+
+    return this as ObjectFormat<T & { [K in Name]?: Value }>;
+  }
+
+  needs<Name extends keyof T & string>(
+    ...names: Name[]
+  ): ObjectFormat<Omit<T, Name> & Required<Pick<T, Name>>> {
+    this.needed.push(...names);
+
+    return this as unknown as ObjectFormat<Omit<T, Name> & Required<Pick<T, Name>>>;
+  }
+
+  /** These keys and no other: a name nothing states is refused UNDER that name. */
+  closed(): Format<{ [K in keyof T]: T[K] }> {
+    return new Format(
+      {
+        ...(this.id ? { $id: this.id } : {}),
+        type: 'object',
+        properties: Object.fromEntries(this.keys),
+        propertyNames: { enum: [...this.keys.keys()] },
+        ...(this.needed.length ? { required: [...this.needed] } : {}),
+        ...(this.cited.size ? { $defs: Object.fromEntries(this.cited) } : {}),
+      },
+      this.id,
+    );
+  }
+}

package/src/lib/JsonSchema.ts

@@ -0,0 +1 @@
+export type { Schema as JsonSchema } from '@cfworker/json-schema';

package/src/lib/Registry.ts

@@ -1,23 +1,24 @@
+import { SchemaError } from '../SchemaError.js';
+
 export class Registry<T> {
-  private readonly entries: Map<string, T>;
+  private readonly held: 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.held = new Map(entries);
   }
 
   register(name: string, value: T): T {
-    this.entries.set(name, value);
+    this.held.set(name, value);
 
     return value;
   }
 
   find(name: string): T | undefined {
-    return this.entries.get(name);
+    return this.held.get(name);
   }
 
   resolve(name: string, path?: string): T {
@@ -25,13 +26,21 @@ 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'}.`,
     );
   }
 
-  private get names(): string[] {
-    return [...this.entries.keys()];
+  get names(): string[] {
+    return [...this.held.keys()];
+  }
+
+  get entries(): [string, T][] {
+    return [...this.held];
+  }
+
+  get all(): T[] {
+    return [...this.held.values()];
   }
 }

package/src/lib/ValidationResult.ts

@@ -9,3 +9,11 @@ export type ValidationResult<T> =
  * reason the value stays segmented: this one cannot be read back.
  */
 export const dotted = (path: readonly string[]): string => path.join('.');
+
+/** `#/city/zip` — a JSON Pointer fragment, and `~1`/`~0` are how it spells `/` and `~`. */
+export const locationOf = (instanceLocation: string): string[] =>
+  instanceLocation
+    .replace(/^#/, '')
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'));

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'] });