Schemas

/**
 * A schema describes the shape of a value as plain data: what kind each part
 * is, what it is called, and what it may hold. Because it is data, an interface
 * can be built from it — a form, an inspector, the columns of a grid — and it
 * can itself be edited by the same interface.
 *
 * Schemas are the single source for three things that otherwise drift apart:
 * the TypeScript type of a value (`Infer`), whether a value is valid
 * (`validate`), and how each part is read, shown and edited.
 *
 * A schema costs nothing at the type level — `Infer` is erased — and nothing at
 * run time beyond the object literal that states it.
 *
 * The kinds combine: a record of fields, a list of items, one of several records
 * told apart by a tag (`variant`), and a schema given by reference (`lazy`), so
 * that one can contain itself. With those a schema can describe schemas.
 */
import { isDate } from "./date-type.ts";

interface Common {
  /** What people call this value. */
  readonly label?: string;
  /** Whether the value may be absent, held as `null`. */
  readonly optional?: boolean;
  /** A sentence of help: what the value is for, or the form it takes. */
  readonly description?: string;
  /** Whether the value is shown but not for changing. It is checked like any other. */
  readonly readOnly?: boolean;
  /**
   * How the value is computed from the record's other fields, as a formula
   * (`price * quantity`): a computed value follows them, and is not typed in
   * unless it is frozen. Read by `schemaDerivations`.
   */
  readonly formula?: string;
}

export interface NumberSchema extends Common {
  readonly kind: "number";
  readonly minimum?: number;
  readonly maximum?: number;
  readonly step?: number;
  readonly precision?: number;
  readonly format?: "decimal" | "percent" | "currency";
  readonly currency?: string;
  /** A unit of the named dimension, as `mm` of `length`. */
  readonly dimension?: "length" | "angle";
  readonly unit?: string;
  /** What a new record starts with, in place of nothing. */
  readonly default?: number;
}

export interface DateSchema extends Common {
  readonly kind: "date";
  /** The earliest and latest dates allowed, as ISO strings. */
  readonly minimum?: string;
  readonly maximum?: string;
  readonly default?: string;
}

export interface TextSchema extends Common {
  readonly kind: "text";
  /** Lengths in characters as people count them, not code units. */
  readonly minLength?: number;
  readonly maxLength?: number;
  /** A regular expression the whole text must match. */
  readonly pattern?: string;
  readonly multiline?: boolean;
  /**
   * What the text holds, so it can be entered with the right keyboard and
   * filled in by the browser. An email address or a URL must also look like one.
   */
  readonly format?: TextFormat;
  readonly default?: string;
}

export type TextFormat =
  | "email"
  | "url"
  | "tel"
  | "name"
  | "given-name"
  | "family-name"
  | "organization"
  | "street-address"
  | "postal-code"
  | "username";

export interface BooleanSchema extends Common {
  readonly kind: "boolean";
  readonly default?: boolean;
}

export interface ChoiceSchema extends Common {
  readonly kind: "choice";
  readonly options: ReadonlyArray<{ readonly value: string; readonly label: string }>;
  /** The value of one of the options. */
  readonly default?: string;
}

export interface ObjectSchema extends Common {
  readonly kind: "object";
  /** The fields, in the order they are shown. */
  readonly fields: ReadonlyArray<{ readonly key: string; readonly schema: Schema }>;
}

export interface ListSchema extends Common {
  readonly kind: "list";
  readonly item: Schema;
  readonly minItems?: number;
  readonly maxItems?: number;
}

/**
 * One of several records, told apart by a tag: a value is a record holding the
 * chosen variant's `value` under `tag`, beside that variant's own fields. No
 * variant has a field with the tag's key.
 */
export interface VariantSchema extends Common {
  readonly kind: "variant";
  /** The key under which a value says which variant it is. */
  readonly tag: string;
  readonly variants: ReadonlyArray<{
    readonly value: string;
    readonly label: string;
    readonly schema: ObjectSchema;
  }>;
  /** The `value` of the variant a new record starts as, in place of none chosen. */
  readonly default?: string;
}

/**
 * A schema given by reference and read only when a value reaches it, so that a
 * schema can contain itself. What the reference states of its own — a label, a
 * description, being optional or read-only — stands in place of what its target
 * states, so one schema can be optional in one place and required in another.
 *
 * `T` is the type of its values where TypeScript cannot work it out: a schema
 * that refers to itself. It is a type only, and nothing is held for it.
 */
export interface LazySchema<T = unknown> extends Common {
  readonly kind: "lazy";
  readonly schema: () => Schema;
  /** Never set: it carries `T` for `Infer`. */
  readonly type?: T;
}

export type Schema =
  | NumberSchema
  | DateSchema
  | TextSchema
  | BooleanSchema
  | ChoiceSchema
  | ObjectSchema
  | ListSchema
  | VariantSchema
  | LazySchema;

/** Any schema but a reference: what a reference leads to. */
export type ResolvedSchema = Exclude<Schema, LazySchema>;

type Flat<T> = { [K in keyof T]: T[K] };

type Fields<S extends ObjectSchema> = {
  -readonly [F in S["fields"][number] as F["key"]]: Infer<F["schema"]>;
};

type DraftFields<S extends ObjectSchema> = {
  -readonly [F in S["fields"][number] as F["key"]]: Draft<F["schema"]>;
};

/** One variant's record: its tag, then its fields. Distributes over the variants. */
type Case<Tag extends string, V> = V extends { readonly value: infer Value; readonly schema: infer O }
  ? O extends ObjectSchema
    ? Flat<{ -readonly [T in Tag]: Value } & Fields<O>>
    : never
  : never;

type DraftCase<Tag extends string, V> = V extends { readonly value: infer Value; readonly schema: infer O }
  ? O extends ObjectSchema
    ? Flat<{ -readonly [T in Tag]: Value } & DraftFields<O>>
    : never
  : never;

/**
 * What a reference's values are: the type it declares; else that of what it
 * returns, where that is known more nearly than as "a schema"; else unknown.
 */
type Referred<S extends LazySchema> =
  S extends LazySchema<infer T>
    ? unknown extends T
      ? Schema extends ReturnType<S["schema"]>
        ? unknown
        : S extends { readonly optional: boolean }
          ? Present<ReturnType<S["schema"]>>
          : Infer<ReturnType<S["schema"]>>
      : T
    : never;

type Present<S extends Schema> = S extends NumberSchema
  ? number
  : S extends DateSchema | TextSchema
    ? string
    : S extends BooleanSchema
      ? boolean
      : S extends ChoiceSchema
        ? S["options"][number]["value"]
        : S extends ObjectSchema
          ? Fields<S>
          : S extends ListSchema
            ? Infer<S["item"]>[]
            : S extends VariantSchema
              ? Case<S["tag"], S["variants"][number]>
              : S extends LazySchema
                ? Referred<S>
                : never;

/** The type of a value the schema describes. */
export type Infer<S extends Schema> = S extends { readonly optional: true } ? Present<S> | null : Present<S>;

/**
 * The type of a value while it is being entered: shaped as the schema says, but
 * with any single value possibly not yet given.
 */
export type Draft<S extends Schema> = S extends ObjectSchema
  ? DraftFields<S>
  : S extends ListSchema
    ? Draft<S["item"]>[]
    : S extends VariantSchema
      ? DraftCase<S["tag"], S["variants"][number]> | null
      : S extends LazySchema<infer T>
        ? unknown extends T
          ? Schema extends ReturnType<S["schema"]>
            ? unknown
            : Draft<ReturnType<S["schema"]>> | null
          : T | null
        : Present<S> | null;

/** States a schema, keeping its literal types so `Infer` can read them. */
export function schema<const S extends Schema>(definition: S): S {
  return definition;
}

/**
 * A reference to a schema, read when a value reaches it. Give `T` where the
 * schema refers to itself — TypeScript cannot work a type out from its own
 * definition — and say what the function returns:
 * `lazy<Folder>((): Schema => folder)`.
 */
export function lazy<T = unknown>(
  target: () => Schema,
  own?: Pick<LazySchema, "label" | "description" | "optional" | "readOnly">,
): LazySchema<T> {
  return { ...own, kind: "lazy", schema: target };
}

export type Path = ReadonlyArray<string | number>;

export interface Issue {
  /** Where in the value the problem is. */
  readonly path: Path;
  /**
   * What is wrong; the words for it belong to the interface and its language.
   * `unique` is never `validate`'s: it is for a check beside a schema, of what a
   * schema cannot state. Nor is `formula`: a formula that cannot be used, with
   * the reader's own words for why and the part of the formula it is about.
   */
  readonly code:
    | "formula"
    | "required"
    | "type"
    | "minimum"
    | "maximum"
    | "minLength"
    | "maxLength"
    | "pattern"
    | "option"
    | "minItems"
    | "maxItems"
    | "unique";
  /** Of a `formula` problem: what is wrong, and where in the formula — UTF-16 indices — to mark. */
  readonly message?: string;
  readonly at?: number;
  readonly length?: number;
}

// A reference is followed once: what it leads to is kept against the reference
// itself, and `null` while it is being followed.
const followed = new WeakMap<LazySchema, ResolvedSchema | null>();

/**
 * What a schema is once any reference is followed: the schema itself, or what a
 * reference leads to with the reference's own label, description, optional and
 * read-only in place of its target's. The same object every time. A reference
 * that leads only back to itself describes nothing, and throws.
 */
export function resolve(definition: Schema): ResolvedSchema {
  if (definition.kind !== "lazy") return definition;
  const known = followed.get(definition);
  if (known !== undefined) {
    if (known === null) throw new Error("A lazy schema refers only to itself.");
    return known;
  }
  followed.set(definition, null);
  let target: ResolvedSchema;
  try {
    target = resolve(definition.schema());
  } finally {
    followed.delete(definition);
  }
  const { label, description, optional, readOnly } = definition;
  if (label !== undefined || description !== undefined || optional !== undefined || readOnly !== undefined) {
    target = {
      ...target,
      ...(label !== undefined && { label }),
      ...(description !== undefined && { description }),
      ...(optional !== undefined && { optional }),
      ...(readOnly !== undefined && { readOnly }),
    };
  }
  followed.set(definition, target);
  return target;
}

type Variant = VariantSchema["variants"][number];

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value);

/** The variant a tag's value names, if it names one. */
export function variantOf(definition: VariantSchema, tag: unknown): Variant | undefined {
  for (const variant of definition.variants) if (variant.value === tag) return variant;
  return undefined;
}

/** The variant a value is, if it says so. */
function variantIn(definition: VariantSchema, value: unknown): Variant | undefined {
  return isRecord(value) ? variantOf(definition, value[definition.tag]) : undefined;
}

const tags = new WeakMap<VariantSchema, ChoiceSchema>();

/**
 * The choice a variant's tag is: an option for each variant, with the variant
 * schema's own label, description and default, and whether it is optional or
 * read-only. The same object every time.
 */
export function tagSchema(definition: VariantSchema): ChoiceSchema {
  let choice = tags.get(definition);
  if (choice === undefined) {
    const { label, description, optional, readOnly } = definition;
    choice = {
      kind: "choice",
      options: definition.variants,
      ...(label !== undefined && { label }),
      ...(description !== undefined && { description }),
      ...(optional !== undefined && { optional }),
      ...(readOnly !== undefined && { readOnly }),
      ...(definition.default !== undefined && { default: definition.default }),
    };
    tags.set(definition, choice);
  }
  return choice;
}

const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });

/** The length of a text in characters as people perceive them. */
export function characterCount(text: string): number {
  let count = 0;
  for (const _ of segmenter.segment(text)) count += 1;
  return count;
}

// Loose on purpose: only the address's own server knows whether it is one.
const EMAIL = /^[^\s@]+@[^\s@]+$/u;

function fitsFormat(format: TextFormat | undefined, text: string): boolean {
  if (format === "email") return EMAIL.test(text);
  if (format === "url") return URL.canParse(text);
  return true;
}

// Each pattern is compiled once; one that is not a regular expression is kept as none.
const patterns = new Map<string, RegExp | null>();

/** A pattern as the expression a whole text must match, or `null` if it is not one. */
export function patternOf(pattern: string): RegExp | null {
  let expression = patterns.get(pattern);
  if (expression === undefined) {
    try {
      expression = new RegExp(`^(?:${pattern})$`, "u");
    } catch {
      expression = null;
    }
    patterns.set(pattern, expression);
  }
  return expression;
}

function check(stated: Schema, value: unknown, path: Path, issues: Issue[]): void {
  const definition = resolve(stated);
  if (value === null || value === undefined) {
    if (definition.optional !== true) issues.push({ path, code: "required" });
    return;
  }
  const fail = (code: Issue["code"]) => issues.push({ path, code });

  switch (definition.kind) {
    case "number":
      if (typeof value !== "number" || !Number.isFinite(value)) return void fail("type");
      if (definition.minimum !== undefined && value < definition.minimum) fail("minimum");
      if (definition.maximum !== undefined && value > definition.maximum) fail("maximum");
      return;
    case "date":
      if (typeof value !== "string" || !isDate(value)) return void fail("type");
      if (definition.minimum !== undefined && value < definition.minimum) fail("minimum");
      if (definition.maximum !== undefined && value > definition.maximum) fail("maximum");
      return;
    case "text": {
      if (typeof value !== "string") return void fail("type");
      // A required text that is empty has not been given.
      if (value === "" && definition.optional !== true) return void fail("required");
      if (definition.minLength !== undefined || definition.maxLength !== undefined) {
        const length = characterCount(value);
        if (definition.minLength !== undefined && length < definition.minLength) fail("minLength");
        if (definition.maxLength !== undefined && length > definition.maxLength) fail("maxLength");
      }
      // Nothing matches a pattern that cannot be read: the fault is said, not thrown.
      if (definition.pattern !== undefined && patternOf(definition.pattern)?.test(value) !== true) {
        fail("pattern");
      } else if (!fitsFormat(definition.format, value)) fail("pattern");
      return;
    }
    case "boolean":
      if (typeof value !== "boolean") fail("type");
      return;
    case "choice":
      if (typeof value !== "string") return void fail("type");
      if (!definition.options.some((option) => option.value === value)) fail("option");
      return;
    case "object":
      if (typeof value !== "object" || Array.isArray(value)) return void fail("type");
      for (const field of definition.fields) {
        check(field.schema, (value as Record<string, unknown>)[field.key], [...path, field.key], issues);
      }
      return;
    case "list":
      if (!Array.isArray(value)) return void fail("type");
      if (definition.minItems !== undefined && value.length < definition.minItems) fail("minItems");
      if (definition.maxItems !== undefined && value.length > definition.maxItems) fail("maxItems");
      value.forEach((item, index) => check(definition.item, item, [...path, index], issues));
      return;
    case "variant": {
      if (typeof value !== "object" || Array.isArray(value)) return void fail("type");
      const record = value as Record<string, unknown>;
      const tag = record[definition.tag];
      const chosen = variantOf(definition, tag);
      if (chosen === undefined) {
        // Which variant it is cannot be told, so no variant's fields are checked.
        const code =
          tag === null || tag === undefined ? "required" : typeof tag === "string" ? "option" : "type";
        issues.push({ path: [...path, definition.tag], code });
        return;
      }
      for (const field of chosen.schema.fields) {
        check(field.schema, record[field.key], [...path, field.key], issues);
      }
    }
  }
}

/**
 * Everything about a value that its schema does not allow; none when it is
 * valid. It goes only as deep as the value does, so a schema that contains
 * itself checks any value that ends.
 */
export function validate(definition: Schema, value: unknown): Issue[] {
  const issues: Issue[] = [];
  check(definition, value, [], issues);
  return issues;
}

/** Whether a value is what the schema describes, as a type guard. */
export function conforms<S extends Schema>(definition: S, value: unknown): value is Infer<S> {
  return validate(definition, value).length === 0;
}

// The records being started, outermost first, each known by its fields: a
// reference's own label makes a copy of its target, which keeps the fields.
// Kept and reused, so starting a value allocates nothing but the value.
const starting: unknown[] = [];

function start(stated: Schema): unknown {
  const definition = resolve(stated);
  if (definition.kind === "list") return [];
  let fields: ObjectSchema["fields"];
  const record: Record<string, unknown> = {};
  if (definition.kind === "object") fields = definition.fields;
  else if (definition.kind === "variant") {
    const chosen = variantOf(definition, definition.default);
    if (chosen === undefined) return null;
    fields = chosen.schema.fields;
    record[definition.tag] = chosen.value;
  } else return definition.default ?? null;
  // Within itself a schema starts as nothing, or a blank value would never end.
  if (starting.includes(fields)) return null;
  starting.push(fields);
  try {
    for (const field of fields) record[field.key] = start(field.schema);
  } finally {
    starting.pop();
  }
  return record;
}

/**
 * A value with nothing entered: every scalar absent unless its schema states a
 * default, every object with its fields, every list empty, every variant not
 * yet chosen unless its schema states which to start as. It is where a new
 * record starts, and is valid only if nothing without a default is required. A
 * schema met again within itself starts as nothing there.
 */
export function blank<S extends Schema>(definition: S): Draft<S> {
  return start(definition) as Draft<S>;
}

function faults(stated: Schema, path: Path, seen: Set<Schema>, issues: Issue[]): void {
  const definition = resolve(stated);
  if (stated.kind === "lazy") {
    // What a reference leads to is looked at once, however often it is met.
    if (seen.has(definition)) return;
    seen.add(definition);
  }
  if (definition.kind === "object") {
    for (const field of definition.fields) faults(field.schema, [...path, field.key], seen, issues);
  } else if (definition.kind === "list") faults(definition.item, [...path, 0], seen, issues);
  else if (definition.kind === "variant") {
    if (definition.default !== undefined && variantOf(definition, definition.default) === undefined) {
      issues.push({ path, code: "option" });
    }
    for (const variant of definition.variants) {
      for (const field of variant.schema.fields) faults(field.schema, [...path, field.key], seen, issues);
    }
  } else if (definition.default !== undefined) {
    for (const issue of validate(definition, definition.default)) issues.push({ path, code: issue.code });
  }
}

/**
 * What is wrong with the defaults a schema states: each issue is `validate`'s,
 * at the path of the part whose default its own schema does not allow. A
 * variant's default must name one of its variants.
 */
export function defaultIssues(definition: Schema, path: Path = []): Issue[] {
  const issues: Issue[] = [];
  faults(definition, path, new Set(), issues);
  return issues;
}

function fieldOf(definition: ObjectSchema, key: string | number): Schema | undefined {
  for (const field of definition.fields) if (field.key === key) return field.schema;
  return undefined;
}

/**
 * The schema of the part of a value at `path`, if the path leads somewhere,
 * with any reference followed. A variant's tag is a choice of its variants. A
 * path into a variant's field needs to know which variant: given the value, the
 * one the value is; without it, the first that has the field.
 */
export function schemaAt(definition: Schema, path: Path, value?: unknown): ResolvedSchema | undefined {
  let current = resolve(definition);
  let held = value;
  for (const key of path) {
    let next: Schema | undefined;
    if (current.kind === "object") next = fieldOf(current, key);
    else if (current.kind === "list" && typeof key === "number") next = current.item;
    else if (current.kind === "variant") {
      if (key === current.tag) next = tagSchema(current);
      else if (value !== undefined) {
        const chosen = variantIn(current, held);
        next = chosen === undefined ? undefined : fieldOf(chosen.schema, key);
      } else {
        for (const variant of current.variants) {
          next = fieldOf(variant.schema, key);
          if (next !== undefined) break;
        }
      }
    }
    if (next === undefined) return undefined;
    current = resolve(next);
    held =
      held === null || typeof held !== "object" ? undefined : (held as Record<string | number, unknown>)[key];
  }
  return current;
}

/** The part of a value at `path`. */
export function valueAt(value: unknown, path: Path): unknown {
  let current = value;
  for (const key of path) {
    if (current === null || typeof current !== "object") return undefined;
    current = (current as Record<string | number, unknown>)[key];
  }
  return current;
}

/**
 * The value with the part at `path` replaced. Only the objects and arrays along
 * the path are copied; everything else is shared with the original, and
 * replacing a part with itself returns the original. Where the value is not of
 * the shape the path asks for — text where a record should be — the way is made
 * anew rather than through it, and a list reached past its end is filled with
 * nothing up to there.
 */
export function withValueAt<T>(value: T, path: Path, next: unknown): T {
  if (path.length === 0) return next as T;
  const [key, ...rest] = path as [string | number, ...Path];
  const listed = typeof key === "number";
  const fits = typeof value === "object" && value !== null && Array.isArray(value) === listed;
  const container = (fits ? value : listed ? [] : {}) as Record<string | number, unknown>;
  const current = container[key];
  const replaced = withValueAt(current, rest, next);
  if (fits && Object.is(replaced, current)) return value;
  if (Array.isArray(container)) {
    const copy = container.slice();
    // Assigning past the end would leave holes, which are not values.
    while (copy.length < (key as number)) copy.push(null);
    copy[key as number] = replaced;
    return copy as T;
  }
  return { ...container, [key]: replaced } as T;
}

/**
 * What something is now, if it was renamed in place: it stood among `before`
 * where something stands whose name `before` did not have, and its own name
 * is gone.
 */
function renamed<P extends string, N extends { readonly [K in P]: string }>(
  now: readonly N[],
  before: readonly N[] | undefined,
  property: P,
  name: unknown,
): N | undefined {
  if (before === undefined) return undefined;
  const candidate = now[before.findIndex((entry) => entry[property] === name)];
  if (candidate === undefined) return undefined;
  // Its name is still in use, or the name now there is an old one moved: not a renaming.
  if (now.some((entry) => entry[property] === name)) return undefined;
  if (before.some((entry) => entry[property] === candidate[property])) return undefined;
  return candidate;
}

function fitFields(
  definition: ObjectSchema,
  record: Record<string, unknown>,
  before: ObjectSchema | undefined,
  tag: string | undefined,
  tagged: string | undefined,
): Record<string, unknown> {
  const { fields } = definition;
  // The same record unless something has to change; then a copy from there on.
  const begin = (upTo: number) => {
    const copy: Record<string, unknown> = {};
    if (tag !== undefined) copy[tag] = tagged;
    for (let index = 0; index < upTo; index += 1) copy[fields[index]!.key] = record[fields[index]!.key];
    return copy;
  };
  let next: Record<string, unknown> | undefined;
  let kept = 0;
  if (tag !== undefined) {
    if (record[tag] === tagged) kept += 1;
    else next = begin(0);
  }
  for (let index = 0; index < fields.length; index += 1) {
    const field = fields[index]!;
    const own = Object.hasOwn(record, field.key);
    let held = record[field.key];
    let was = before === undefined ? undefined : fieldOf(before, field.key);
    if (!own && before !== undefined) {
      const old = before.fields[index];
      if (
        old !== undefined &&
        Object.hasOwn(record, old.key) &&
        renamed(fields, before.fields, "key", old.key) === field
      ) {
        held = record[old.key];
        was = old.schema;
      }
    }
    const fitted = fit(field.schema, held, was);
    if (own) kept += 1;
    if (next === undefined && (!own || !Object.is(fitted, held))) next = begin(index);
    if (next !== undefined) next[field.key] = fitted;
  }
  if (next !== undefined) return next;
  // A key the schema does not have is dropped.
  let count = 0;
  for (const _ in record) count += 1;
  return count === kept ? record : begin(fields.length);
}

function fit(stated: Schema, value: unknown, statedBefore: Schema | undefined): unknown {
  const definition = resolve(stated);
  // What was never there is new, and starts as a new record's does; what is
  // absent stays absent where it may be.
  if (value === undefined) return blank(definition);
  if (value === null) return definition.optional === true ? null : blank(definition);
  const before = statedBefore === undefined ? undefined : resolve(statedBefore);
  switch (definition.kind) {
    case "number":
      return typeof value === "number" && Number.isFinite(value) ? value : blank(definition);
    case "date":
      return typeof value === "string" && isDate(value) ? value : blank(definition);
    case "text":
      return typeof value === "string" ? value : blank(definition);
    case "boolean":
      return typeof value === "boolean" ? value : blank(definition);
    case "choice": {
      if (definition.options.some((option) => option.value === value)) return value;
      const was = before?.kind === "choice" ? before.options : undefined;
      return renamed(definition.options, was, "value", value)?.value ?? blank(definition);
    }
    case "object":
      if (!isRecord(value)) return blank(definition);
      return fitFields(
        definition,
        value,
        before?.kind === "object" ? before : undefined,
        undefined,
        undefined,
      );
    case "list": {
      if (!Array.isArray(value)) return [];
      const was = before?.kind === "list" ? before.item : undefined;
      let next: unknown[] | undefined;
      for (let index = 0; index < value.length; index += 1) {
        const fitted = fit(definition.item, value[index], was);
        if (next === undefined && !Object.is(fitted, value[index])) next = value.slice(0, index);
        next?.push(fitted);
      }
      return next ?? value;
    }
    case "variant": {
      if (!isRecord(value)) return blank(definition);
      const tag = value[definition.tag];
      const was = before?.kind === "variant" && before.tag === definition.tag ? before : undefined;
      const chosen = variantOf(definition, tag) ?? renamed(definition.variants, was?.variants, "value", tag);
      if (chosen === undefined) return blank(definition);
      const old = was === undefined ? undefined : variantOf(was, tag)?.schema;
      return fitFields(chosen.schema, value, old, definition.tag, chosen.value);
    }
  }
}

/**
 * A value made to fit a schema, as when the schema has changed under it: what
 * still fits is kept and the rest starts blank.
 *
 * A part fits when it is of its schema's kind — a number, a real date, one of a
 * choice's options, a record for a record. Its limits are not asked: a price
 * below a new minimum is kept, for `validate` to report. A field the schema no
 * longer has is dropped; one it has gained starts as a new record's does; an
 * absent part stays absent where it may be, and starts blank where it may not.
 *
 * Given the schema the value was made for, a renaming is followed: a field, an
 * option or a variant whose name is new, standing where one whose name is gone
 * stood, is that one under its new name, and keeps its value.
 *
 * A value that already fits is returned as it is, and so is each part that does.
 */
export function conform<S extends Schema>(definition: S, value: unknown, before?: Schema): Draft<S> {
  return fit(definition, value, before) as Draft<S>;
}

/**
 * A variant's value as another of its variants, or as none (`null`). A field
 * the two variants share — the same key, and schemas of the same kind once any
 * reference is followed — keeps its value, made to fit the new field as
 * `conform` does; every other field of the new variant starts blank, and what
 * only the old one had is dropped. Choosing the variant it already is returns
 * the value as it is.
 */
export function withVariant(definition: VariantSchema, value: unknown, tag: string | null): unknown {
  if (tag === null) return null;
  const to = variantOf(definition, tag);
  if (to === undefined) return value;
  const from = variantIn(definition, value);
  if (from === to) return value;
  const next: Record<string, unknown> = { [definition.tag]: to.value };
  for (const field of to.schema.fields) {
    const shared = from === undefined ? undefined : fieldOf(from.schema, field.key);
    next[field.key] =
      shared !== undefined && resolve(shared).kind === resolve(field.schema).kind
        ? // Two variants' fields are not one field before and after: nothing is taken for a renaming.
          fit(field.schema, (value as Record<string, unknown>)[field.key], undefined)
        : blank(field.schema);
  }
  return next;
}