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

package/src/axis/shape/Shape.ts

@@ -4,27 +4,58 @@ import type { ShapeType } from './ShapeType.js';
 
 type Nullably<T extends string> = T | readonly [T, 'null'];
 
-interface StringConstraints { minLength?: number; maxLength?: number; pattern?: string; enum?: readonly (string | null)[]; format?: StringFormat }
+/** The sentence a field carries, where JSON Schema already holds one. */
+interface Documented {
+  description?: string;
+}
+
+interface StringConstraints extends Documented {
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  enum?: readonly (string | null)[];
+  format?: StringFormat;
+}
 
-interface NumericConstraints { minimum?: number; maximum?: number }
+interface NumericConstraints extends Documented {
+  minimum?: number;
+  maximum?: number;
+  enum?: readonly (number | null)[];
+}
 
-interface ArrayConstraints { items?: Shape; minItems?: number; maxItems?: number }
+interface ArrayConstraints extends Documented {
+  items?: Shape;
+  minItems?: number;
+  maxItems?: number;
+}
 
-interface ObjectConstraints { properties?: Record<string, unknown>; required?: readonly string[]; additionalProperties?: boolean | Shape; propertyNames?: Shape }
+interface ObjectConstraints extends Documented {
+  properties?: Record<string, unknown>;
+  required?: readonly string[];
+  additionalProperties?: boolean | Shape;
+  propertyNames?: Shape;
+}
 
 export type Shape =
   | ({ type: Nullably<'string'> } & StringConstraints)
   | ({ type: Nullably<'number'> | Nullably<'integer'> } & NumericConstraints)
-  | { type: Nullably<'boolean'> }
+  | ({ type: Nullably<'boolean'> } & Documented)
   | ({ type: Nullably<'array'> } & ArrayConstraints)
   | ({ type: Nullably<'object'> } & ObjectConstraints);
 
-const SHAPE_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'] as const;
+export const SHAPE_TYPES = [
+  'string',
+  'number',
+  'integer',
+  'boolean',
+  'array',
+  'object',
+] as const;
 
 type BaseShape =
   | ({ type: 'string' } & StringConstraints)
   | ({ type: 'number' | 'integer' } & NumericConstraints)
-  | { type: 'boolean' }
+  | ({ type: 'boolean' } & Documented)
   | ({ type: 'array' } & ArrayConstraints)
   | ({ type: 'object' } & ObjectConstraints);
 
@@ -42,26 +73,21 @@ type _ShapeConformsToJsonSchema = Assert<
 >;
 
 type _ShapeTypesAreTheStandardsLessNull = Assert<
-  [Exclude<Exclude<JSONSchema7TypeName, 'null'>, (typeof SHAPE_TYPES)[number]>] extends [never]
+  [Exclude<Exclude<JSONSchema7TypeName, 'null'>, (typeof SHAPE_TYPES)[number]>] extends [
+    never,
+  ]
     ? true
     : false
 >;
 
+/** Every type name a shape states, whether it states one or a union of them. */
+const typesOf = (shape: Shape): readonly string[] =>
+  (Array.isArray(shape.type) ? shape.type : [shape.type]) as readonly string[];
+
 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;
-    const names = Array.isArray(type) ? type : [type];
-
-    return (
-      names.some((name) => (SHAPE_TYPES as readonly unknown[]).includes(name)) &&
-      names.every((name) => name === 'null' || (SHAPE_TYPES as readonly unknown[]).includes(name))
-    );
-  }
-
   /**
    * Every `pattern` a shape states, the nested ones included — `items`, `properties`.
    *
@@ -89,11 +115,28 @@ export class Shapes {
     for (const member of Object.values(value)) Shapes.collectPatterns(member, found);
   }
 
+  /**
+   * `null` enters the grammar, and every constraint stays. It is added when it is ABSENT,
+   * read off the shape rather than assumed from its form — a shape already stating it comes
+   * back as itself, so `optional(nullable(text()))` does the work once.
+   *
+   * `enum` is widened TOO, because JSON Schema checks it apart from `type`: a shape saying
+   * `['string','null']` and `enum: ['draft','live']` calls null a legal type and not a legal
+   * value, and the engine answers `Instance does not match any of ["draft","live"]`.
+   *
+   * `{ type: 'string', minLength: 3 }`      → `{ type: ['string','null'], minLength: 3 }`
+   * `{ type: 'string', enum: ['draft'] }`   → `{ type: ['string','null'], enum: ['draft', null] }`
+   */
   static nullable(shape: Shape): Shape {
-    if (Array.isArray(shape.type)) return shape;
-    const nullable = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
+    const types = typesOf(shape);
+    if (types.includes('null')) return shape;
+
+    const nullable = { ...shape, type: [...types, 'null'] } as unknown as Shape;
     if ('enum' in nullable && nullable.enum && !nullable.enum.includes(null)) {
-      (nullable as { enum: readonly (string | null)[] }).enum = [...nullable.enum, null];
+      (nullable as { enum: readonly (string | number | null)[] }).enum = [
+        ...nullable.enum,
+        null,
+      ];
     }
 
     return nullable;
@@ -107,7 +150,9 @@ export class Shapes {
         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);
+          (base as { enum: readonly (string | number | null)[] }).enum = base.enum.filter(
+            (v) => v !== null,
+          );
         }
         parts = { base, nullable: true };
       } else {
@@ -115,6 +160,7 @@ export class Shapes {
       }
       this.cache.set(shape, parts);
     }
+
     return parts;
   }
 
@@ -122,6 +168,26 @@ export class Shapes {
     return this.of(shape).nullable;
   }
 
+  /**
+   * A value that came in as text — a form control, a command-line flag — read as the shape
+   * declares it. What does not read that way stays as it came, for the judge to refuse by name.
+   * `fromText({ type: 'integer' }, '12')` → `12`, and `fromText({ type: 'integer' }, 'abc')` → `'abc'`
+   */
+  static fromText(shape: Shape | undefined, value: unknown): unknown {
+    const type = this.of(shape).base?.type;
+
+    if (
+      (type !== 'number' && type !== 'integer') ||
+      typeof value !== 'string' ||
+      value === ''
+    )
+      return value;
+
+    const number = Number(value);
+
+    return Number.isFinite(number) ? number : value;
+  }
+
   /**
    * `shape.type` read off the base, except that a `string` answers `date` or `choice`.
    * FR : `shape.type` lu sur la base, sauf qu'une chaîne répond `date` ou `choice`.

package/src/axis/shape/ShapeFormat.ts

@@ -0,0 +1,37 @@
+import { Format } from '../../lib/Format.js';
+import { SHAPE_TYPES, type Shape } from './Shape.js';
+
+const SHAPE = 'field/shape';
+
+/** A word, or that word beside `null` — the second place is what makes a shape nullable. */
+const TYPE = Format.either(
+  Format.tokens(SHAPE_TYPES),
+  Format.tuple(Format.tokens(SHAPE_TYPES), Format.tokens(['null'])),
+);
+
+/**
+ * What a shape may state — JSON Schema's own keywords, less the ones this package has no word
+ * for. `shape` used to be the one key of a field declaration nothing judged, so `minLenght: 1`
+ * passed and was dropped where `lifecycle: { craete: 'now' }` had been refused since `Format`.
+ * `properties` stays open because a projection folds `meta.description` into it.
+ */
+export const SHAPE_FORMAT = Format.of(SHAPE)
+  .key('type', TYPE)
+  .key('description', Format.text)
+  .key('minLength', Format.count)
+  .key('maxLength', Format.count)
+  .key('pattern', Format.text)
+  .key('format', Format.text)
+  .key('enum', Format.listOf(Format.anything))
+  .key('minimum', Format.number)
+  .key('maximum', Format.number)
+  .key('items', Format.ref(SHAPE))
+  .key('minItems', Format.count)
+  .key('maxItems', Format.count)
+  .key('properties', Format.anything)
+  .key('required', Format.listOf(Format.text))
+  .key('additionalProperties', Format.anything)
+  .key('propertyNames', Format.ref(SHAPE))
+  .needs('type')
+  .closed()
+  .as<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/EntityDeclarations.ts

@@ -1,10 +1,11 @@
 import type { Fields } from '../field/Fields.js';
 import type { EntityAdapters } from './EntityAdapters.js';
-import type { CompositeUnique } from './CompositeUnique.js';
+import type { FieldGroups } from './FieldGroups.js';
 import type { PreviousNames } from './PreviousNames.js';
 
 export interface EntityDeclarations<TFields extends Fields> {
   adapters?: EntityAdapters<TFields>;
   previous?: PreviousNames<TFields>;
-  unique?: CompositeUnique<TFields>;
+  unique?: FieldGroups<TFields>;
+  index?: FieldGroups<TFields>;
 }

package/src/entity/FieldGroups.ts

@@ -0,0 +1,9 @@
+import type { FieldName } from '../field/FieldName.js';
+import type { Fields } from '../field/Fields.js';
+
+/**
+ * Field names grouped, as `unique` and `index` both are — `[['listId', 'docId'], ['slug']]`.
+ * The ORDER inside a group counts for both: a unique constraint on `(a, b)` is not the one on
+ * `(b, a)`, and an index on `(a, b)` serves a filter on `a` alone and never on `b` alone.
+ */
+export type FieldGroups<TFields extends Fields> = readonly (readonly FieldName<TFields>[])[];

package/src/field/Field.ts

@@ -1,24 +1,49 @@
 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 { 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 { isObject } from '../lib/utils.js';
 import { dotted } from '../lib/ValidationResult.js';
 import { SchemaError } from '../SchemaError.js';
 
-type FieldDeclaration = Pick<Field, 'shape' | Axis['slot'] | 'meta'>;
+/** The sentence any word admits, whatever it shapes — a relation and a date carry one too. */
+export interface Described {
+  description?: string;
+}
+
+/** And a value it is born with, for the words that shape one. `many()` has none to hold. */
+export interface Shared<T> extends Described {
+  default?: T;
+}
+
+export interface FieldDeclaration extends FougereFieldAxes {
+  shape: Shape;
+}
+
+/**
+ * Every word ends on `setShared`, so the options are read in ONE place and refused there.
+ * `text(42)` used to pass for a bare `text()`, and nine of the twelve words took it.
+ */
+const refuseLooseOptions = (opts: unknown): void => {
+  if (!isObject(opts))
+    throw new SchemaError('Options must go in an object, like { max: 200 }', { received: opts });
+};
+
+/** The registry answers strings, and a member of a declaration is what they name. */
+const registered = (): (keyof FieldDeclaration)[] => Axes.names as (keyof FieldDeclaration)[];
+
+/**
+ * The axes it carries are `FougereFieldAxes`, which each axis writes its own line in — so the
+ * three of the core are typed the way a fourth declared outside is, and the class names what
+ * the registry decides only once, in the constructor.
+ */
+export interface Field<T = unknown> extends FougereFieldAxes {
+  readonly _type?: T;
+}
 
 export class Field<T = unknown> {
   readonly shape: Shape;
-  readonly role?: RoleRules;
-  readonly lifecycle?: LifecycleRules;
-  readonly boundary?: BoundaryRef;
-  readonly meta?: Meta;
-
-  declare readonly _type?: T;
 
   constructor(init: FieldDeclaration, key?: string) {
     const verdict = FieldDeclarationValidator.of(init).verdict;
@@ -31,10 +56,12 @@ 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;
+
+    for (const name of registered()) {
+      Object.defineProperty(this, name, {
+        value: init[name], writable: true, enumerable: true, configurable: true,
+      });
+    }
 
     const create = this.lifecycle?.create;
     if (typeof create === 'object' && create !== null && 'value' in create) {
@@ -51,7 +78,53 @@ export class Field<T = unknown> {
     return FieldDeclarationValidator.of(value).verdict.success;
   }
 
+  /**
+   * What this field declares on ONE axis, a fourth one registered outside included. An axis is
+   * a member, so it is read by NAME, and three callers reached for it through a cast of their
+   * own before this existed.
+   */
+  axis(name: keyof FieldDeclaration): unknown {
+    return (this satisfies FieldDeclaration)[name];
+  }
+
+  /** Every axis it declares, and nothing for the ones it says nothing on. */
+  get axes(): Record<string, unknown> {
+    return Object.fromEntries(
+      registered()
+        .map((name) => [name, this.axis(name)])
+        .filter(([, declared]) => declared !== undefined),
+    );
+  }
+
+  /** Whether it states anything at all beside its shape. */
+  hasAxes(): boolean {
+    return registered().some((name) => this.axis(name) !== undefined);
+  }
+
   with<U = T>(overrides: Partial<FieldDeclaration>): Field<U> {
     return new Field<U>({ ...this, ...overrides });
   }
+
+  /**
+   * What a word admits whatever its shape, and where it lands: `description` IS a JSON Schema
+   * keyword, `default` IS a lifecycle rule. Stated here alone, so no word writes the conversion.
+   * FR : ce que tout mot admet quelle que soit sa forme, et où ça atterrit.
+   * `text({ max: 200 }).setShared({ description: 'The title' })` → `shape.description`
+   */
+  setShared(opts?: Shared<T>): Field<T> {
+    if (opts === undefined) return this;
+
+    refuseLooseOptions(opts);
+
+    const overrides: Partial<FieldDeclaration> = {
+      ...(opts.description !== undefined
+        ? { shape: { ...this.shape, description: opts.description } }
+        : {}),
+      ...(opts.default !== undefined
+        ? { lifecycle: { ...this.lifecycle, create: { value: opts.default } } }
+        : {}),
+    };
+
+    return Object.keys(overrides).length ? this.with<T>(overrides) : this;
+  }
 }

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 { SHAPE_FORMAT } from '../axis/shape/ShapeFormat.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
+ * cited like the rest — it is JSON Schema, and JSON Schema is what states its keywords.
+ */
+export function fieldFormat(axes: readonly [string, Axis][]): JsonSchema {
+  const document = axes.reduce(
+    (held, [name, axis]) => held.cites(name, axis.format),
+    Format.of('field').cites('shape', SHAPE_FORMAT),
+  );
+
+  return document.closed().schema as JsonSchema;
+}

package/src/field/FieldSet.ts

@@ -1,5 +1,5 @@
 import { Role } from '../axis/role/Role.js';
-import type { CompositeUnique } from '../entity/CompositeUnique.js';
+import type { FieldGroups } from '../entity/FieldGroups.js';
 import { Field } from './Field.js';
 import { type FieldName } from './FieldName.js';
 import { type Fields } from './Fields.js';
@@ -17,39 +17,47 @@ export class FieldSet<TFields extends Fields = Fields> {
    * FR : partage un `unique` déclaré : un groupe d'un va au champ, plusieurs restent au schéma.
    * `declaring(fields, [['email'], ['listId', 'docId']])` → `email` carries it, the pair is a group
    */
+  /**
+   * A group of ONE is the word on the field — `unique: [['slug']]` is `unique(text())` — so it
+   * is written there and never kept as a group, which is what lets a derivation drop it with
+   * its field. A group of several is what no single field can state, and it is kept whole.
+   */
   static declaring<TFields extends Fields>(
     declared: TFields,
-    unique?: CompositeUnique<TFields>,
-  ): { fields: TFields; groups: CompositeUnique<TFields> } {
+    groups: { unique?: FieldGroups<TFields>; index?: FieldGroups<TFields> } = {},
+  ): { fields: TFields; unique: FieldGroups<TFields>; index: FieldGroups<TFields> } {
     const fields: Fields = {};
     for (const [key, field] of Object.entries(declared))
       fields[key] = new Field(field, key);
 
-    const composite: FieldName<TFields>[][] = [];
-    for (const group of unique ?? []) {
-      const missing = group.filter((key) => !Object.hasOwn(fields, key));
-      if (missing.length)
-        throw new SchemaError(
-          `unique: [${group.join(', ')}] names ` +
-            `${missing.map((key) => `'${key}'`).join(', ')}, which the entity does not declare.`,
-        );
+    const composite = { unique: [] as FieldName<TFields>[][], index: [] as FieldName<TFields>[][] };
+
+    for (const kind of ['unique', 'index'] as const) {
+      for (const group of groups[kind] ?? []) {
+        const missing = group.filter((key) => !Object.hasOwn(fields, key));
+        if (missing.length)
+          throw new SchemaError(
+            `${kind}: [${group.join(', ')}] names ` +
+              `${missing.map((key) => `'${key}'`).join(', ')}, which the entity does not declare.`,
+          );
 
-      if (group.length === 1) {
-        const key = group[0]!;
-        const alone = fields[key]!;
-        fields[key] = alone.with({ role: { ...alone.role, unique: true } });
-        continue;
+        if (group.length === 1) {
+          const key = group[0]!;
+          const alone = fields[key]!;
+          fields[key] = alone.with({ role: { ...alone.role, [kind]: true } });
+          continue;
+        }
+        composite[kind].push([...group]);
       }
-      composite.push([...group]);
     }
 
-    return { fields: fields as TFields, groups: composite };
+    return { fields: fields as TFields, unique: composite.unique, index: composite.index };
   }
 
   /** A second `primary` is refused, naming both, rather than the first winning silently. */
   get primary(): FieldName<TFields> | undefined {
     const primaries = Object.entries(this.fields)
-      .filter(([, field]) => Role.of(field).isPrimary)
+      .filter(([, field]) => Role.of(field).isPrimary())
       .map(([name]) => name);
 
     if (primaries.length > 1) {

package/src/index.ts

@@ -37,11 +37,15 @@ 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 { type FougereFieldAxes } from './FougereFieldAxes.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,172 @@
+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' });
+  static readonly number = new Format<number>({ type: 'number' });
+  static readonly count = new Format<number>({ type: 'integer', minimum: 0 });
+
+  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] });
+  }
+
+  /** `enum`, `required` — a list of one format, so `enum: 'draft'` is refused as the scalar it is. */
+  static listOf<Value>(format: Format<Value>): Format<Value[]> {
+    return new Format({ type: 'array', items: format.schema });
+  }
+
+  /**
+   * A list of a FIXED length, each place stating its own format — `['string', 'null']` and
+   * never `['string', 'number']`, which a list of one format cannot tell apart.
+   */
+  static tuple<const Places extends readonly Format<unknown>[]>(
+    ...places: Places
+  ): Format<{ -readonly [K in keyof Places]: Accepted<Places[K]> }> {
+    return new Format({
+      type: 'array',
+      prefixItems: places.map((place) => place.schema),
+      minItems: places.length,
+      maxItems: places.length,
+    });
+  }
+
+  /**
+   * A format naming ITSELF, which no value can do while it is being built: `items` holds a shape,
+   * and the shape is what declares `items`. The `$id` `of()` already posts is what it points at.
+   */
+  static ref(id: string): Format<unknown> {
+    return new Format({ $ref: absolute(id) as string });
+  }
+
+  /**
+   * A word or anything else, told apart by TYPE, so a refusal names the half the value belongs
+   * to — `create: 'nawak'` reads against the words, `type: ['string', 'null']` against the list.
+   */
+  static either<Word, Other>(word: Format<Word>, otherwise: Format<Other>): Format<Word | Other> {
+    return new Format({
+      if: { type: 'string' },
+      then: word.schema as JsonSchema,
+      else: otherwise.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';