@fougere/schema 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/axis/boundary/Boundaries.ts

@@ -0,0 +1,44 @@
+import type { BoundaryRules } from './Boundary.js';
+
+export type Decoder = (value: unknown) => { value: unknown } | { error: string };
+export type Encoder = (value: unknown) => unknown;
+
+export class Boundaries {
+  private static readonly decoders = new Map<string, Decoder>();
+  private static readonly encoders = new Map<string, Encoder>();
+  private static readonly aliases = new Map<string, BoundaryRules>();
+
+  static registerDecoder(name: string, fn: Decoder): void { this.decoders.set(name, fn); }
+  static registerEncoder(name: string, fn: Encoder): void { this.encoders.set(name, fn); }
+
+  static registerAlias(name: string, boundary: BoundaryRules): void { this.aliases.set(name, boundary); }
+
+  static alias(name: string): BoundaryRules | undefined { return this.aliases.get(name); }
+
+  static decoder(name: string): Decoder { return this.named(this.decoders, name, 'decoder'); }
+  static encoder(name: string): Encoder { return this.named(this.encoders, name, 'encoder'); }
+
+  private static named<T>(registry: Map<string, T>, name: string, kind: string): T {
+    const fn = registry.get(name);
+    if (!fn) {
+      throw new Error(
+        `Unknown boundary ${kind}: '${name}'. Register it with ` +
+          `Boundaries.register${kind[0].toUpperCase()}${kind.slice(1)}('${name}', …).`,
+      );
+    }
+    return fn;
+  }
+}
+
+Boundaries.registerDecoder('isoDate', (value) => {
+  if (value instanceof Date) return { value };
+  if (typeof value === 'string') {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? { error: 'Invalid date' } : { value: d };
+  }
+  return { error: 'Expected a date' };
+});
+Boundaries.registerEncoder('isoDate', (value) =>
+  value instanceof Date ? value.toISOString() : value,
+);
+Boundaries.registerAlias('isoDate', { in: { decode: 'isoDate' }, out: { encode: 'isoDate' } });

package/src/axis/boundary/Boundary.ts

@@ -0,0 +1,69 @@
+import type { Decoder, Encoder } from './Boundaries.js';
+import { Boundaries } from './Boundaries.js';
+import type { Field } from '../../fields/Field.js';
+import { Anatomy, type Shape } from '../shape/Shape.js';
+
+export interface BoundaryRules {
+  in?: 'closed' | { decode: string };
+  out?: 'closed' | { encode: string };
+}
+
+export type BoundaryRef = 'isoDate' | (string & {}) | BoundaryRules;
+
+const identityDecoder: Decoder = (value) => ({ value });
+const identityEncoder: Encoder = (value) => value;
+
+export class Boundary implements BoundaryRules {
+  readonly in?: BoundaryRules['in'];
+  readonly out?: BoundaryRules['out'];
+  readonly decode: Decoder;
+  readonly encode: Encoder;
+
+  private constructor(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;
+  }
+
+  static declared(field: Field): Boundary {
+    const ref = field.boundary;
+    if (ref === undefined) return new Boundary();
+    if (typeof ref !== 'string') return new Boundary(ref);
+
+    const alias = Boundaries.alias(ref);
+    if (!alias) throw new Error(`Unknown boundary alias: '${ref}'`);
+    return new Boundary(alias);
+  }
+
+  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 };
+    return new Boundary(rules, {
+      decode: typeof rules.in === 'object' ? Boundaries.decoder(rules.in.decode) : identityDecoder,
+      encode: typeof rules.out === 'object' ? Boundaries.encoder(rules.out.encode) : identityEncoder,
+    });
+  }
+
+  static forShape(shape: Shape | undefined): Boundary {
+    const base = Anatomy.of(shape).base;
+    if (base?.type === 'string' && base.format === 'date-time') {
+      return new Boundary(Boundaries.alias('isoDate')!);
+    }
+    return new Boundary();
+  }
+
+  with(overrides: BoundaryRules): Boundary {
+    return new Boundary({ in: overrides.in ?? this.in, out: overrides.out ?? this.out });
+  }
+
+  get readOnly(): boolean {
+    return this.in === 'closed';
+  }
+
+  get writeOnly(): boolean {
+    return this.out === 'closed';
+  }
+
+}

package/src/axis/boundary/BoundaryAxis.ts

@@ -0,0 +1,32 @@
+import type { Axis } from '../Axis.js';
+import { admitWire } from '../../card/admission.js';
+import { isObject } from '../../judge/ValueForm.js';
+import type { BoundaryRef } from './Boundary.js';
+
+export const boundaryAxis: Axis<BoundaryRef, BoundaryRef> = {
+  slot: 'boundary',
+
+  judge(value, errors) {
+    if (typeof value === 'string') return; 
+    if (!isObject(value)) {
+      errors.push({
+        path: 'boundary',
+        message: `Expected an alias name or { in, out } — got ${JSON.stringify(value)}`,
+      });
+      return;
+    }
+    for (const [side, verb] of [['in', 'decode'], ['out', 'encode']] as const) {
+      const rule = value[side];
+      if (rule === undefined || rule === 'closed') continue;
+      if (!isObject(rule) || typeof rule[verb] !== 'string') {
+        errors.push({ path: `boundary.${side}`, message: `Expected 'closed' or { ${verb}: <name> }` });
+      }
+    }
+  },
+
+  describe: (value) => value,
+  reconstruct: (wire) => {
+    admitWire(boundaryAxis.judge, wire, 'boundary');
+    return wire;
+  },
+};

package/src/axis/lifecycle/Clock.ts

@@ -0,0 +1,26 @@
+/**
+ * What "now" means, for the two functions that stamp it.
+ *
+ * The ONE place either of them reads the time, which is what makes it substitutable at
+ * all: `created()`, `updated()` and `create: 'now'` are realized through this and nowhere
+ * else, so a test that needs a stable instant sets it here instead of intercepting `Date`
+ * globally — where Rails had to build `travel_to` over the language.
+ *
+ * A value rather than a mock: nothing here is a channel, and a frozen clock is a fact
+ * about the run, not an interception of a call.
+ */
+export class Clock {
+  private static reading: () => number = Date.now;
+
+  static now(): number {
+    return this.reading();
+  }
+
+  /** Freeze the instant this clock reads. Returns the gesture that restores it. */
+  static freeze(at: number | Date): () => void {
+    const previous = this.reading;
+    const instant = at instanceof Date ? at.getTime() : at;
+    this.reading = () => instant;
+    return () => { this.reading = previous; };
+  }
+}

package/src/axis/lifecycle/Generators.ts

@@ -0,0 +1,46 @@
+import { createId } from '@paralleldrive/cuid2';
+
+export type GeneratorRef = 'cuid2' | 'uuid' | 'nanoid' | (string & {});
+
+const NANOID_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+function nanoid(): string {
+  const bytes = new Uint8Array(21);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => NANOID_ALPHABET[byte & 63]).join('');
+}
+
+/**
+ * Who answers a `generate` by name — one registry per process, like `Formats` and
+ * `Boundaries`.
+ *
+ * The three builtins are REGISTERED rather than switched on, which is what brings the
+ * refusal back inside: a registry whose unknown name is refused by a `default:` branch in
+ * its caller does not know what it holds, so it cannot say so.
+ */
+export class Generators {
+  private static readonly registry = new Map<string, () => string>([
+    ['cuid2', createId],
+    ['uuid', () => globalThis.crypto.randomUUID()],
+    ['nanoid', nanoid],
+  ]);
+
+  static register(name: string, fn: () => string): void {
+    this.registry.set(name, fn);
+  }
+
+  /** The generator this name stands for, refused by name when nothing does. */
+  static resolve(ref: GeneratorRef): () => string {
+    const found = this.registry.get(ref);
+    if (found) return found;
+    throw new Error(
+      `Unknown generator '${ref}' — register it with Generators.register('${ref}', fn). ` +
+      `This process answers ${[...this.registry.keys()].join(', ')}.`,
+    );
+  }
+
+  /** Whether a name is answered, for a caller that must not throw to find out. */
+  static answers(ref: GeneratorRef): boolean {
+    return this.registry.has(ref);
+  }
+}

package/src/axis/lifecycle/Lifecycle.ts

@@ -0,0 +1,53 @@
+import type { GeneratorRef } from './Generators.js';
+
+export const CREATE_TOKENS = ['now', 'optional'] as const;
+export const UPDATE_TOKENS = ['now', 'forbidden'] as const;
+
+export interface LifecycleRules {
+  create?: { value: unknown } | { generate: GeneratorRef } | (typeof CREATE_TOKENS)[number];
+  update?: (typeof UPDATE_TOKENS)[number];
+}
+
+export class Lifecycle implements LifecycleRules {
+  readonly create?: LifecycleRules['create'];
+  readonly update?: LifecycleRules['update'];
+
+  private constructor(rules: LifecycleRules = {}) {
+    this.create = rules.create;
+    this.update = rules.update;
+  }
+
+  static of(field: { lifecycle?: LifecycleRules }): Lifecycle {
+    return new Lifecycle(field.lifecycle);
+  }
+
+  get requiredAtCreate(): boolean {
+    return this.create === undefined;
+  }
+
+  get stampedOnce(): boolean {
+    return this.create === 'now' && this.update !== 'now';
+  }
+
+  get immutable(): boolean {
+    return this.update === 'forbidden';
+  }
+
+  get stampedOnUpdate(): boolean {
+    return this.update === 'now';
+  }
+
+  get literal(): { value: unknown } | undefined {
+    const rule = this.create;
+    return typeof rule === 'object' && rule !== null && 'value' in rule
+      ? { value: (rule as { value: unknown }).value }
+      : undefined;
+  }
+
+  get generator(): GeneratorRef | undefined {
+    const rule = this.create;
+    return typeof rule === 'object' && rule !== null && 'generate' in rule
+      ? (rule as { generate: GeneratorRef }).generate
+      : undefined;
+  }
+}

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