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

package/src/SchemaDefinition.ts

@@ -113,7 +113,7 @@ export class SchemaDefinition {
       ...addressed,
       ...Object.keys(declarations.previous ?? {}),
     ]);
-    const declared = FieldSet.declaring(this.fields, declarations.unique);
+    const declared = FieldSet.declaring(this.fields, declarations);
 
     return this.restated({
       fields: declared.fields,
@@ -123,9 +123,9 @@ export class SchemaDefinition {
       ]),
       previous: declarations.previous ?? this.previous,
       constraints:
-        declarations.unique === undefined
+        declarations.unique === undefined && declarations.index === undefined
           ? this.constraints
-          : SchemaConstraints.of(declared.groups),
+          : SchemaConstraints.of(declared),
     });
   }
 
@@ -199,11 +199,13 @@ export class SchemaDefinition {
   static merged(views: readonly SchemaView[]): SchemaDefinition {
     const fields: Fields = {};
     let opts: ValidateOptions = {};
-    const groups: (readonly string[])[] = [];
+    const groups: { unique: (readonly string[])[]; index: (readonly string[])[] } =
+      { unique: [], index: [] };
     for (const view of views) {
       Object.assign(fields, view.getFields());
       opts = { ...opts, ...view.getOpts() };
-      groups.push(...(view.getUnique() ?? []));
+      groups.unique.push(...(view.getUnique() ?? []));
+      groups.index.push(...(view.getIndex() ?? []));
     }
 
     return SchemaDefinition.derived({

package/src/SchemaError.ts

@@ -1,7 +1,13 @@
 export class SchemaError extends Error {
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: { received: unknown }) {
+    super(
+      options ? `${message} — got ${SchemaError.inspect(options.received)}` : message,
+    );
 
-    this.name = new.target.name;
+    this.name = 'SchemaError';
+  }
+
+  static inspect(value: unknown): string {
+    return JSON.stringify(value) ?? typeof value;
   }
 }

package/src/SchemaView.ts

@@ -1,5 +1,5 @@
 import type { Fields } from './field/Fields.js';
-import type { CompositeUnique } from './entity/CompositeUnique.js';
+import type { FieldGroups } from './entity/FieldGroups.js';
 import type { PreviousNames } from './entity/PreviousNames.js';
 import type { EntityAdapters } from './entity/EntityAdapters.js';
 import type { ValidationResult } from './lib/ValidationResult.js';
@@ -17,7 +17,8 @@ export interface SchemaView<TFields extends Fields = Fields> {
   readonly anchored?: boolean;
   getFields(): TFields;
   getAdapters(): EntityAdapters<TFields>;
-  getUnique(): CompositeUnique<TFields> | undefined;
+  getUnique(): FieldGroups<TFields> | undefined;
+  getIndex(): FieldGroups<TFields> | undefined;
   getOpts(): ValidateOptions;
   validate(input: unknown): ValidationResult<Values<TFields>>;
 }

package/src/axis/Axes.ts

@@ -0,0 +1,34 @@
+import { Registry } from '../lib/Registry.js';
+import type { JsonSchema } from '../lib/JsonSchema.js';
+import { fieldFormat } from '../field/FieldFormat.js';
+import type { Axis } from './Axis.js';
+import { Boundary } from './boundary/Boundary.js';
+import { Lifecycle } from './lifecycle/Lifecycle.js';
+import { Role } from './role/Role.js';
+
+class AxisRegistry extends Registry<Axis> {
+  private composed?: JsonSchema;
+
+  register(name: string, axis: Axis): Axis {
+    this.composed = undefined;
+
+    return super.register(name, axis);
+  }
+
+  /** The document a field declaration is judged against, rebuilt the next time one arrives. */
+  get fieldFormat(): JsonSchema {
+    this.composed ??= fieldFormat(this.entries);
+
+    return this.composed;
+  }
+}
+
+/**
+ * The axes this process reads, and the door an axis declared elsewhere comes through.
+ * `Axes.register('tenancy', Tenancy)` — from a `vocabulary/` file, read before `entities/`
+ */
+export const Axes = new AxisRegistry('axis', 'call Axes.register(name, axis)', [
+  ['role', Role],
+  ['lifecycle', Lifecycle],
+  ['boundary', Boundary],
+]);

package/src/axis/Axis.ts

@@ -1,24 +1,20 @@
-import { roleAxis } from './role/RoleAxis.js';
-import { lifecycleAxis } from './lifecycle/LifecycleAxis.js';
-import { boundaryAxis } from './boundary/BoundaryAxis.js';
+import type { Format } from '../lib/Format.js';
+import type { Field } from '../field/Field.js';
 import type { ValidationError } from '../lib/ValidationError.js';
-import type { Resolver } from './Resolver.js';
 
-export interface Axis<Declared = unknown, Wire = unknown> {
-  readonly slot: 'role' | 'lifecycle' | 'boundary';
+export interface Axis {
+  readonly format: Format;
 
-  validator(value: unknown, errors: ValidationError[]): void;
+  /**
+   * What a format cannot state: `role.relation.to` is a function, and JSON holds none.
+   * The whole declaration comes with the name, because a contradiction is a PAIR — a
+   * primary key that admits null states one legal `role` beside one legal `shape`.
+   */
+  refusals?(value: unknown, declaration: Record<string, unknown>): ValidationError[];
 
-  describe(value: Declared, key: string): Wire | undefined;
-
-  reconstruct(wire: Wire, resolve?: Resolver): Declared;
+  /**
+   * Whether this axis alone lets the field be absent from what a caller sends. Asked of every
+   * REGISTERED axis, so a fourth one weighs on it without the validator naming it.
+   */
+  admitsAbsence?(field: Field): boolean;
 }
-
-export const EXTENSION_AXES: readonly Axis[] = [
-  roleAxis,
-  lifecycleAxis,
-  boundaryAxis,
-];
-
-/** The slots they occupy: the keys of `x-fougere` on a field descriptor. */
-export const EXTENSION_SLOTS = EXTENSION_AXES.map((axis) => axis.slot);

package/src/axis/boundary/Boundary.ts

@@ -4,25 +4,37 @@ import { Boundaries } from './Decoder.js';
 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';
+import { Format, type Accepted } from '../../lib/Format.js';
+
+const closedOr = <Verb extends 'decode' | 'encode'>(verb: Verb) =>
+  Format.either(Format.tokens(['closed']), Format.of().key(verb, Format.text).needs(verb).closed());
+
+const RULES = Format.of().key('in', closedOr('decode')).key('out', closedOr('encode')).closed();
+
+const BOUNDARY = Format.named(
+  'axis/boundary',
+  Format.either(Format.text.as<'isoDate' | (string & {})>(), RULES),
+);
+
+export type BoundaryRules = Accepted<typeof RULES>;
+
+export type BoundaryRef = Accepted<typeof BOUNDARY>;
 
 const identityDecoder: Decoder = (value) => ({ value });
 
 const identityEncoder: Encoder = (value) => value;
 
 export class Boundary {
-  private readonly in?: BoundaryRules['in'];
-  private readonly out?: BoundaryRules['out'];
+  static readonly format = BOUNDARY;
+
   readonly decode: Decoder;
   readonly encode: Encoder;
 
   private constructor(
-    rules: BoundaryRules = {},
+    private readonly rules: BoundaryRules = {},
     codecs?: { decode: Decoder; encode: Encoder },
   ) {
-    this.in = rules.in;
-    this.out = rules.out;
     this.decode = codecs?.decode ?? identityDecoder;
     this.encode = codecs?.encode ?? identityEncoder;
   }
@@ -35,16 +47,23 @@ export class Boundary {
 
     const alias = Boundaries.aliases.find(ref);
     if (!alias) throw new SchemaError(`Unknown boundary alias: '${ref}'`);
+
     return new Boundary(alias);
   }
 
+  /** The server fills it, so a caller never sends it. */
+  static admitsAbsence(field: Field): boolean {
+    return this.of(field).readOnly();
+  }
+
   static of(field: Field): Boundary {
     const declared = Boundary.declared(field);
     const derived = Boundary.forShape(field.shape);
     const rules: BoundaryRules = {
-      in: declared.in ?? derived.in,
-      out: declared.out ?? derived.out,
+      in: declared.rules.in ?? derived.rules.in,
+      out: declared.rules.out ?? derived.rules.out,
     };
+
     return new Boundary(rules, {
       decode:
         typeof rules.in === 'object'
@@ -60,19 +79,26 @@ 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.resolve('isoDate'));
+
     return new Boundary();
   }
 
   /** The dual of `declared`: what `readOnly()` writes back on the field, not a judge. */
   declaring(overrides: BoundaryRules): BoundaryRules {
-    return { in: overrides.in ?? this.in, out: overrides.out ?? this.out };
+    return { in: overrides.in ?? this.rules.in, out: overrides.out ?? this.rules.out };
   }
 
-  get readOnly(): boolean {
-    return this.in === 'closed';
+  readOnly(): boolean {
+    return this.rules.in === 'closed';
   }
 
-  get writeOnly(): boolean {
-    return this.out === 'closed';
+  writeOnly(): boolean {
+    return this.rules.out === 'closed';
+  }
+}
+
+declare module '../../FougereFieldAxes.js' {
+  interface FougereFieldAxes {
+    readonly boundary?: BoundaryRef;
   }
 }

package/src/axis/boundary/Decoder.ts

@@ -1,4 +1,4 @@
-import type { BoundaryRules } from './BoundaryRules.js';
+import type { BoundaryRules } from './Boundary.js';
 import { Registry } from '../../lib/Registry.js';
 import type { Encoder } from './Encoder.js';
 import type { Verdict } from '../../lib/Verdict.js';
@@ -33,8 +33,10 @@ 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()) ? { message: 'Invalid date' } : { value: date };
   }
+
   return { message: 'Expected a date' };
 });
 Boundaries.encoders.register('isoDate', (value) =>

package/src/axis/lifecycle/Lifecycle.ts

@@ -1,19 +1,45 @@
+import { Format, type Accepted } from '../../lib/Format.js';
 import { Generators } from './Generators.js';
-import type { LifecycleRules } from './LifecycleRules.js';
+import type { GeneratorRef } from './Generators.js';
 
+export type LifecycleRules = Accepted<typeof Lifecycle.format>;
 export class Lifecycle {
-  private readonly create?: LifecycleRules['create'];
-  private readonly update?: LifecycleRules['update'];
+  static readonly CREATE = ['now', 'optional'] as const;
+  static readonly UPDATE = ['now', 'forbidden'] as const;
 
-  private constructor(rules: LifecycleRules = {}) {
-    this.create = rules.create;
-    this.update = rules.update;
+  static readonly format = Format.of('axis/lifecycle')
+    .key(
+      'create',
+      Format.either(
+        Format.tokens(Lifecycle.CREATE),
+        Format.exactlyOne({
+          value: Format.anything,
+          generate: Format.text.as<GeneratorRef>(),
+        }),
+      ),
+    )
+    .key('update', Format.tokens(Lifecycle.UPDATE))
+    .closed();
+
+  private constructor(private readonly rules: LifecycleRules = {}) {}
+
+  /** `optional()`, a default, a generator: the rule says the value need not arrive. */
+  static admitsAbsence(field: { lifecycle?: LifecycleRules }): boolean {
+    return !this.of(field).requiredAtCreate();
   }
 
   static of(field: { lifecycle?: LifecycleRules }): Lifecycle {
     return new Lifecycle(field.lifecycle);
   }
 
+  private get create() {
+    return this.rules.create;
+  }
+
+  private get update() {
+    return this.rules.update;
+  }
+
   bornWith(instant: number): { value: unknown } | undefined {
     const rule = this.create;
 
@@ -26,23 +52,19 @@ export class Lifecycle {
     return { value: Generators.resolve(rule.generate)() };
   }
 
-  get requiredAtCreate(): boolean {
+  requiredAtCreate(): boolean {
     return this.create === undefined;
   }
 
-  get stampedAtCreate(): boolean {
+  stampedAtCreate(): boolean {
     return this.create === 'now';
   }
 
-  get stampedOnce(): boolean {
-    return this.stampedAtCreate && !this.stampedOnUpdate;
-  }
-
-  get immutable(): boolean {
+  immutable(): boolean {
     return this.update === 'forbidden';
   }
 
-  get stampedOnUpdate(): boolean {
+  stampedOnUpdate(): boolean {
     return this.update === 'now';
   }
 
@@ -54,3 +76,9 @@ export class Lifecycle {
       : undefined;
   }
 }
+
+declare module '../../FougereFieldAxes.js' {
+  interface FougereFieldAxes {
+    readonly lifecycle?: LifecycleRules;
+  }
+}

package/src/axis/lifecycle/apply.ts

@@ -1,5 +1,4 @@
 import { Lifecycle } from './Lifecycle.js';
-import { Clock } from './Clock.js';
 import { type Field } from '../../field/Field.js';
 import { type Fields } from '../../field/Fields.js';
 
@@ -8,12 +7,16 @@ import { type Fields } from '../../field/Fields.js';
  * FR : remplit ce que la déclaration laisse au storage : aucun handler n'estampe lui-même.
  * `applyCreate({ id: primary(), createdAt: created() }, { title: 'a' })` → `id`, `createdAt`
  */
-export function applyCreate(fields: Fields, input: Record<string, unknown>): Record<string, unknown> {
+export function applyCreate(
+  fields: Fields,
+  input: Record<string, unknown>,
+): Record<string, unknown> {
   const values: Record<string, unknown> = { ...input };
-  const instant = Clock.now();
+  const instant = Date.now();
 
   for (const [name, field] of Object.entries(fields) as [string, Field][]) {
     if (name in values) continue;
+
     const born = Lifecycle.of(field).bornWith(instant);
 
     if (born) values[name] = born.value;
@@ -28,12 +31,15 @@ export function applyCreate(fields: Fields, input: Record<string, unknown>): Rec
  * sont touchés.
  * `applyUpdate(fields, { title: 'b' })` → `updatedAt` added, nothing else
  */
-export function applyUpdate(fields: Fields, patch: Record<string, unknown>): Record<string, unknown> {
+export function applyUpdate(
+  fields: Fields,
+  patch: Record<string, unknown>,
+): Record<string, unknown> {
   const values: Record<string, unknown> = { ...patch };
-  const instant = Clock.now();
+  const instant = Date.now();
 
   for (const [name, field] of Object.entries(fields) as [string, Field][]) {
-    if (Lifecycle.of(field).stampedOnUpdate && !(name in values))
+    if (Lifecycle.of(field).stampedOnUpdate() && !(name in values))
       values[name] = new Date(instant);
   }
 

package/src/axis/role/Role.ts

@@ -1,56 +1,104 @@
-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 { Shapes, type Shape } from '../shape/Shape.js';
+import type { ValidationError } from '../../lib/ValidationError.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, declaration: Record<string, unknown> = {}): ValidationError[] {
+    const role = Role.of({ role: isObject(value) ? (value as RoleRules) : undefined });
+    const errors: ValidationError[] = [];
+    const relation = isObject(value) ? value.relation : undefined;
+
+    if (isObject(relation) && 'to' in relation && typeof relation.to !== 'function')
+      errors.push({
+        path: ['role', 'relation', 'to'],
+        message: 'Expected a function returning the target entity, such as () => Post',
+      });
 
-  private constructor(rules: RoleRules = {}) {
-    this.primary = rules.primary;
-    this.index = rules.index;
-    this.unique = rules.unique;
-    this.relation = rules.relation;
+    if (role.isPrimary() && Shapes.isNullable(declaration.shape as Shape))
+      errors.push({
+        path: ['role', 'primary'],
+        message: 'A primary key admits no null — a row is addressed by it',
+      });
+
+    if (role.isCollection() && (role.isUnique() || role.isIndexed()))
+      errors.push({
+        path: ['role', role.isUnique() ? 'unique' : 'index'],
+        message: 'A collection has no column of its own, so there is nothing to index',
+      });
+
+    return errors;
+  }
+
+  private constructor(private readonly rules: RoleRules = {}) {}
+
+  /** A collection has no column: the far side of the relation carries the key. */
+  static admitsAbsence(field: { role?: RoleRules }): boolean {
+    return this.of(field).isCollection();
   }
 
   static of(field: { role?: RoleRules }): Role {
     return new Role(field.role);
   }
 
-  get isPrimary(): boolean {
-    return this.primary === true;
+  isPrimary(): boolean {
+    return this.rules.primary === true;
   }
 
-  get isIndexed(): boolean {
-    return this.index === true;
+  isIndexed(): boolean {
+    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;
+  isUnique(): boolean {
+    return this.rules.unique === true;
   }
 
-  get isCollection(): boolean {
-    return this.relation?.kind === 'many';
+  isCollection(): boolean {
+    return this.rules.relation?.kind === 'many';
   }
 
-  get isReference(): boolean {
-    return this.relation?.kind === 'one';
+  isReference(): boolean {
+    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;
+  isRelation(): boolean {
+    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>;
+
+declare module '../../FougereFieldAxes.js' {
+  interface FougereFieldAxes {
+    readonly role?: RoleRules;
   }
 }