@fougere/schema 0.3.0-alpha.0 → 0.5.0-alpha.0

package/src/axis/lifecycle/LifecycleAxis.ts

@@ -0,0 +1,49 @@
+import type { Axis } from '../Axis.js';
+import type { ValidationError } from '../../judge/result.js';
+import { admitWire } from '../../card/admission.js';
+import { isObject, oneOfTokens } from '../../judge/ValueForm.js';
+import { CREATE_TOKENS, UPDATE_TOKENS, type LifecycleRules } from './Lifecycle.js';
+
+export const lifecycleAxis: Axis<LifecycleRules, LifecycleRules> = {
+  slot: 'lifecycle',
+
+  judge(value, errors) {
+    if (!isObject(value)) {
+      errors.push({ path: 'lifecycle', message: `Expected an object — got ${JSON.stringify(value)}` });
+      return;
+    }
+    if (value.create !== undefined) judgeCreate(value.create, errors);
+    if (value.update !== undefined && !oneOfTokens(value.update, UPDATE_TOKENS)) {
+      errors.push({
+        path: 'lifecycle.update',
+        message: `Expected 'now' or 'forbidden' — got ${JSON.stringify(value.update)}`,
+      });
+    }
+  },
+
+  describe: (value) => value,
+  reconstruct: (wire) => {
+    admitWire(lifecycleAxis.judge, wire, 'lifecycle');
+    return wire;
+  },
+};
+
+function judgeCreate(rule: unknown, errors: ValidationError[]): void {
+  if (oneOfTokens(rule, CREATE_TOKENS)) return;
+  if (isObject(rule)) {
+    if ('value' in rule) return;
+    if ('generate' in rule) {
+      if (typeof rule.generate !== 'string') {
+        errors.push({
+          path: 'lifecycle.create.generate',
+          message: `Expected a generator name — got ${JSON.stringify(rule.generate)}`,
+        });
+      }
+      return;
+    }
+  }
+  errors.push({
+    path: 'lifecycle.create',
+    message: `Expected 'now', 'optional', { value } or { generate } — got ${JSON.stringify(rule)}`,
+  });
+}

package/src/axis/lifecycle/apply.ts

@@ -0,0 +1,38 @@
+import { Lifecycle } from './Lifecycle.js';
+import { Generators } from './Generators.js';
+import { Clock } from './Clock.js';
+import { type Field, type Fields } from '../../fields/Field.js';
+
+type Row = Record<string, unknown>;
+
+export function applyCreate(fields: Fields, input: Row): Row {
+  const out: Row = { ...input };
+  const instant = Clock.now();
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    if (name in out) continue;
+    const rule = Lifecycle.of(field);
+
+    if (rule.create === 'now') out[name] = new Date(instant);
+    else if (rule.literal) out[name] = freshValue(rule.literal.value);
+    else if (rule.generator) out[name] = Generators.resolve(rule.generator)();
+  }
+
+  return out;
+}
+
+function freshValue(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  return structuredClone(value);
+}
+
+export function applyUpdate(fields: Fields, patch: Row): Row {
+  const out: Row = { ...patch };
+  const instant = Clock.now();
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    if (Lifecycle.of(field).stampedOnUpdate && !(name in out)) out[name] = new Date(instant);
+  }
+
+  return out;
+}

package/src/axis/role/Relation.ts

@@ -0,0 +1,31 @@
+export type EntityConstructor = abstract new (...args: any[]) => any;
+
+export const RELATION_KINDS = ['one', 'many'] as const;
+export const ON_DELETE = ['cascade', 'restrict', 'set null'] as const;
+
+export interface Relation {
+  to: () => EntityConstructor;
+  kind: (typeof RELATION_KINDS)[number];
+  onDelete?: (typeof ON_DELETE)[number];
+}
+
+/**
+ * How a relation is built — the one place a target becomes a thunk.
+ *
+ * A target arrives as the class or as a function returning it, because a cycle between two
+ * entities can only be written the second way. Recognised by FORM, `getFields` on the
+ * value: a class answers it, a thunk does not.
+ */
+export const Relation = {
+  one(target: EntityConstructor | (() => EntityConstructor), cascade?: boolean): Relation {
+    return { to: thunk(target), kind: 'one', onDelete: cascade ? 'cascade' : undefined };
+  },
+
+  many(target: EntityConstructor | (() => EntityConstructor)): Relation {
+    return { to: thunk(target), kind: 'many' };
+  },
+};
+
+function thunk<E extends EntityConstructor>(target: E | (() => E)): () => E {
+  return 'getFields' in target ? () => target as E : (target as () => E);
+}

package/src/axis/role/Role.ts

@@ -0,0 +1,56 @@
+import { FieldGroup } from "../../constraint/FieldGroup.js";
+import { Unique } from "../../constraint/Unique.js";
+import type { EntityConstructor, Relation } from "./Relation.js";
+
+export interface RoleRules {
+  primary?: boolean;
+  index?: boolean;
+  relation?: Relation;
+  rules?: readonly FieldGroup[];
+}
+
+export class Role implements RoleRules {
+  readonly primary?: boolean;
+  readonly index?: boolean;
+  readonly relation?: Relation;
+  readonly rules?: readonly FieldGroup[];
+
+  private constructor(declared: RoleRules = {}) {
+    this.primary = declared.primary;
+    this.index = declared.index;
+    this.relation = declared.relation;
+    this.rules = declared.rules;
+  }
+
+  static of(field: { role?: RoleRules }): Role {
+    return new Role(field.role);
+  }
+
+  /** A group written with no members means "this field": only the key it is declared under resolves it. */
+  static resolvedOn(role: RoleRules | undefined, key?: string): RoleRules | undefined {
+    let rules = FieldGroup.normalize(role?.rules, (members) => new Unique(members));
+    if (rules && key !== undefined && rules.some((group) => group.isSelf))
+      rules = rules.map((group) => group.resolvedOn(key));
+    return rules === role?.rules ? role : { ...role, rules };
+  }
+
+  get isPrimary(): boolean {
+    return this.primary === true;
+  }
+
+  get isIndexed(): boolean {
+    return this.index === true;
+  }
+
+  get isCollection(): boolean {
+    return this.relation?.kind === "many";
+  }
+
+  get isReference(): boolean {
+    return this.relation?.kind === "one";
+  }
+
+  get target(): EntityConstructor | undefined {
+    return this.relation?.to();
+  }
+}

package/src/axis/role/RoleAxis.ts

@@ -0,0 +1,115 @@
+import type { Axis, Resolver } from '../Axis.js';
+import { refuse } from '../../card/admission.js';
+import { isObject, oneOfTokens } from '../../judge/ValueForm.js';
+import type { ValidationError } from '../../judge/result.js';
+import { ON_DELETE, RELATION_KINDS, type EntityConstructor, type Relation } from './Relation.js';
+import { type RoleRules } from './Role.js';
+import { FieldGroup } from '../../constraint/FieldGroup.js';
+import { Unique } from '../../constraint/Unique.js';
+import type { RoleDescriptor } from '../../card/Descriptor.js';
+import { lowerFirst } from '../../utils.js';
+
+export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
+  slot: 'role',
+
+  judge(value, errors) {
+    if (!isObject(value)) {
+      errors.push({ path: 'role', message: `Expected an object — got ${JSON.stringify(value)}` });
+      return;
+    }
+    for (const flag of ['primary', 'index'] as const) {
+      if (value[flag] !== undefined && typeof value[flag] !== 'boolean') {
+        errors.push({
+          path: `role.${flag}`,
+          message: `Expected a boolean — got ${JSON.stringify(value[flag])}`,
+        });
+      }
+    }
+    if (value.rules !== undefined) {
+      const legal =
+        Array.isArray(value.rules) &&
+        value.rules.every(
+          (rule) =>
+            rule instanceof FieldGroup ||
+            (Array.isArray(rule) && rule.every((member) => typeof member === 'string')),
+        );
+      if (!legal) {
+        errors.push({
+          path: 'role.rules',
+          message: 'Expected field groups, or the member lists they denote — string[][]',
+        });
+      }
+    }
+    if (value.relation !== undefined) judgeRelation(value.relation, errors);
+  },
+
+  describe(role, key) {
+    const out: Mutable<RoleDescriptor> = {};
+    if (role.primary) out.primary = true;
+    const unique = (role.rules ?? []).filter((rule) => rule instanceof Unique);
+    if (unique.length) out.unique = unique.map((rule) => [...rule.resolvedOn(key).members]);
+    if (role.index) out.index = true;
+    if (role.relation) {
+      const target = role.relation.to() as { name?: string };
+      out.relation = {
+        to: lowerFirst(target.name ?? ''),
+        kind: role.relation.kind,
+        ...(role.relation.onDelete ? { onDelete: role.relation.onDelete } : {}),
+      };
+    }
+    return Object.keys(out).length ? out : undefined;
+  },
+
+  reconstruct(wire, resolve?: Resolver) {
+    const out: RoleRules = {};
+    if (wire.primary) out.primary = true;
+    if (wire.unique?.length) out.rules = wire.unique.map((group) => new Unique(group));
+    if (wire.index) out.index = true;
+    if (wire.relation) {
+      // `judge` cannot serve here: it demands a thunk where a card carries a name.
+      if (!oneOfTokens(wire.relation.kind, RELATION_KINDS)) {
+        refuse(
+          `role.relation.kind is ${JSON.stringify(wire.relation.kind)}`,
+          `Expected one of ${RELATION_KINDS.join(', ')}.`,
+        );
+      }
+      if (wire.relation.onDelete !== undefined && !oneOfTokens(wire.relation.onDelete, ON_DELETE)) {
+        refuse(
+          `role.relation.onDelete is ${JSON.stringify(wire.relation.onDelete)}`,
+          `Expected one of ${ON_DELETE.join(', ')}.`,
+        );
+      }
+      const name = wire.relation.to;
+      out.relation = {
+        to: () => (resolve?.(name) ?? ({ name } as unknown)) as EntityConstructor,
+        kind: wire.relation.kind as Relation['kind'],
+        ...(wire.relation.onDelete ? { onDelete: wire.relation.onDelete as Relation['onDelete'] } : {}),
+      } as RoleRules['relation'];
+    }
+    return out;
+  },
+};
+
+function judgeRelation(relation: unknown, errors: ValidationError[]): void {
+  if (!isObject(relation)) {
+    errors.push({ path: 'role.relation', message: `Expected an object — got ${JSON.stringify(relation)}` });
+    return;
+  }
+  if (!oneOfTokens(relation.kind, RELATION_KINDS)) {
+    errors.push({
+      path: 'role.relation.kind',
+      message: `Expected 'one' or 'many' — got ${JSON.stringify(relation.kind)}`,
+    });
+  }
+  if (typeof relation.to !== 'function') {
+    errors.push({ path: 'role.relation.to', message: 'Expected a thunk returning the target entity' });
+  }
+  if (relation.onDelete !== undefined && !oneOfTokens(relation.onDelete, ON_DELETE)) {
+    errors.push({
+      path: 'role.relation.onDelete',
+      message: `Expected 'cascade', 'restrict' or 'set null' — got ${JSON.stringify(relation.onDelete)}`,
+    });
+  }
+}
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };

package/src/axis/shape/Formats.ts

@@ -0,0 +1,22 @@
+export type StringFormat =
+  | 'date-time'
+  | 'date'
+  | 'time'
+  | 'email'
+  | 'uuid'
+  | 'uri'
+  | (string & {});
+
+export type FormatPredicate = (value: string) => boolean;
+
+export class Formats {
+  private static readonly registry = new Map<string, FormatPredicate>();
+
+  static register(name: string, predicate: FormatPredicate): void {
+    this.registry.set(name, predicate);
+  }
+
+  static resolve(name: string): FormatPredicate | undefined {
+    return this.registry.get(name);
+  }
+}

package/src/axis/shape/Shape.ts

@@ -0,0 +1,91 @@
+import type { JSONSchema7 } from 'json-schema';
+import type { StringFormat } from './Formats.js';
+
+type Nullably<T extends string> = T | readonly [T, 'null'];
+
+interface StringConstraints { minLength?: number; maxLength?: number; pattern?: string; enum?: readonly (string | null)[]; format?: StringFormat }
+interface NumericConstraints { minimum?: number; maximum?: number }
+interface ArrayConstraints { items?: Shape; minItems?: number; maxItems?: number }
+interface ObjectConstraints { properties?: Record<string, unknown>; required?: readonly string[] }
+
+export type Shape =
+  | ({ type: Nullably<'string'> } & StringConstraints)
+  | ({ type: Nullably<'number'> | Nullably<'integer'> } & NumericConstraints)
+  | { type: Nullably<'boolean'> }
+  | ({ type: Nullably<'array'> } & ArrayConstraints)
+  | ({ type: Nullably<'object'> } & ObjectConstraints);
+
+const SHAPE_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'] as const;
+
+function isShapeImpl(value: unknown): value is Shape {
+  if (typeof value !== 'object' || value === null) return false;
+  const declared = (value as Shape).type;
+  const names = Array.isArray(declared) ? declared : [declared];
+  return (
+    names.some((name) => (SHAPE_TYPES as readonly unknown[]).includes(name)) &&
+    names.every((name) => name === 'null' || (SHAPE_TYPES as readonly unknown[]).includes(name))
+  );
+}
+
+type BaseShape =
+  | ({ type: 'string' } & StringConstraints)
+  | ({ type: 'number' | 'integer' } & NumericConstraints)
+  | { type: 'boolean' }
+  | ({ type: 'array' } & ArrayConstraints)
+  | ({ type: 'object' } & ObjectConstraints);
+
+function nullableShapeImpl(shape: Shape): Shape {
+  if (Array.isArray(shape.type)) return shape;
+  const out = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
+  if ('enum' in out && out.enum && !out.enum.includes(null)) {
+    (out as { enum: readonly (string | null)[] }).enum = [...out.enum, null];
+  }
+  return out;
+}
+
+interface ShapeAnatomy {
+  base?: BaseShape;
+  nullable: boolean;
+}
+
+export class Anatomy {
+  static is(value: unknown): value is Shape {
+    return isShapeImpl(value);
+  }
+
+  static nullable(shape: Shape): Shape {
+    return nullableShapeImpl(shape);
+  }
+
+  private static readonly cache = new WeakMap<object, ShapeAnatomy>();
+  private static readonly none: ShapeAnatomy = { base: undefined, nullable: false };
+
+  static of(shape?: Shape): ShapeAnatomy {
+    if (!shape) return this.none;
+    let a = this.cache.get(shape);
+    if (!a) {
+      if (Array.isArray(shape.type)) {
+        const baseType = shape.type.find((t) => t !== 'null');
+        const base = { ...shape, type: baseType } as BaseShape;
+        if ('enum' in base && base.enum) {
+          (base as { enum: readonly (string | null)[] }).enum = base.enum.filter((v) => v !== null);
+        }
+        a = { base, nullable: true };
+      } else {
+        a = { base: shape as BaseShape, nullable: false };
+      }
+      this.cache.set(shape, a);
+    }
+    return a;
+  }
+
+  static isNullable(shape?: Shape): boolean {
+    return this.of(shape).nullable;
+  }
+}
+
+type Assert<T extends true> = T;
+type ShapeKeys<T> = T extends unknown ? keyof T : never;
+type _ShapeConformsToJsonSchema = Assert<
+  [Exclude<ShapeKeys<Shape>, keyof JSONSchema7>] extends [never] ? true : false
+>;

package/src/card/Bundle.ts

@@ -0,0 +1,80 @@
+import type { Resolver } from '../axis/Axis.js';
+import type { EntityConstructor } from '../axis/role/Relation.js';
+import { lowerFirst } from '../utils.js';
+import type { SchemaView } from '../schema/SchemaView.js';
+import { Card } from './Card.js';
+import type { SchemaBundle, SchemaDescriptor } from './Descriptor.js';
+import type { Diff, SetDiff, SetDiffOptions } from './diff.js';
+
+type SchemaSet = Record<string, SchemaView> | SchemaView[];
+
+/** A portable schema map and the decisions that only a map can make. */
+export class Bundle {
+  private constructor(readonly descriptor: SchemaBundle) {}
+
+  static fromSchemas(schemas: SchemaSet): Bundle {
+    const definitions: Record<string, SchemaDescriptor> = {};
+    const claimedBy = new Map<string, string>();
+    const entries = Array.isArray(schemas)
+      ? schemas.map((schema) => {
+          const card = Card.fromSchema(schema);
+          return { name: card.descriptor.title ?? '', schema };
+        })
+      : Object.entries(schemas).map(([name, schema]) => ({ name, schema }));
+
+    for (const entry of entries) {
+      const key = lowerFirst(entry.name);
+      const previous = claimedBy.get(key);
+      if (previous !== undefined) {
+        throw new Error(
+          `Schemas '${previous}' and '${entry.name}' both claim bundle key '${key}'. `
+          + 'Each schema in a bundle must have a distinct registration key.',
+        );
+      }
+      claimedBy.set(key, entry.name);
+      definitions[key] = Card.fromSchema(entry.schema, key).descriptor;
+    }
+
+    return new Bundle({
+      $defs: definitions,
+      'x-fougere-version': 1,
+      'x-fougere-vendor': 'fougere',
+    });
+  }
+
+  static fromDescriptor(descriptor: SchemaBundle): Bundle {
+    return new Bundle(descriptor);
+  }
+
+  toSchemas(): Record<string, SchemaView> {
+    const map: Record<string, EntityConstructor> = {};
+    const resolve: Resolver = (name) => map[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;
+      schemas[name] = schema;
+    }
+    return schemas;
+  }
+
+  diff(other: Bundle, options: SetDiffOptions = {}): SetDiff {
+    const before = this.descriptor.$defs ?? {};
+    const after = other.descriptor.$defs ?? {};
+    const entities: Record<string, Diff> = {};
+    for (const [name, descriptor] of Object.entries(before)) {
+      const target = after[name];
+      if (target === undefined) continue;
+      const answer = Card.fromDescriptor(descriptor).diff(
+        Card.fromDescriptor(target),
+        { renamed: options.renamed?.[name] ?? {} },
+      );
+      if (answer.changes.length > 0 || answer.ambiguous.length > 0) entities[name] = answer;
+    }
+    return {
+      entitiesAdded: Object.keys(after).filter((name) => !(name in before)),
+      entitiesRemoved: Object.keys(before).filter((name) => !(name in after)),
+      entities,
+    };
+  }
+}