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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/schema",
-  "version": "0.12.0-alpha.0",
+  "version": "0.12.1-alpha.0",
   "description": "The entity and its 4 axes — shape, role, lifecycle, boundary. Subject-owned judgments, edge-safe.",
   "keywords": [
     "fougere",

package/src/SchemaError.ts

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

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(slot: string, axis: Axis): Axis {
+    this.composed = undefined;
+
+    return super.register(slot, 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(slot, axis)', [
+  ['role', Role],
+  ['lifecycle', Lifecycle],
+  ['boundary', Boundary],
+]);

package/src/axis/Axis.ts

@@ -1,24 +1,9 @@
-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 { 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;
-
-  describe(value: Declared, key: string): Wire | undefined;
-
-  reconstruct(wire: Wire, resolve?: Resolver): Declared;
+  /** What a format cannot state: `role.relation.to` is a function, and JSON holds none. */
+  refusals?(value: unknown): ValidationError[];
 }
-
-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;
   }
@@ -42,8 +54,8 @@ export class 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:
@@ -65,14 +77,14 @@ export class 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';
+    return this.rules.in === 'closed';
   }
 
   get writeOnly(): boolean {
-    return this.out === 'closed';
+    return this.rules.out === 'closed';
   }
 }

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';

package/src/axis/lifecycle/Lifecycle.ts

@@ -1,19 +1,40 @@
+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 = {}) {}
 
   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;
 
@@ -34,10 +55,6 @@ export class Lifecycle {
     return this.create === 'now';
   }
 
-  get stampedOnce(): boolean {
-    return this.stampedAtCreate && !this.stampedOnUpdate;
-  }
-
   get immutable(): boolean {
     return this.update === 'forbidden';
   }

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,9 +31,12 @@ 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))

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

@@ -1,15 +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;
@@ -31,11 +38,14 @@ export class Field<T = unknown> {
     }
 
     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);

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/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/index.ts

@@ -37,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,24 +1,24 @@
 import { SchemaError } from '../SchemaError.js';
 
 export class Registry<T> {
-  private readonly entries: Map<string, T>;
+  private readonly held: Map<string, T>;
 
   constructor(
     private readonly label: string,
     private readonly hint?: string,
     entries?: Iterable<readonly [string, T]>,
   ) {
-    this.entries = new Map(entries);
+    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 {
@@ -32,7 +32,15 @@ export class Registry<T> {
     );
   }
 
-  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, '~'));