cerulea/lexicon

git clone https://git.t4t.associates/cerulea/lexicon

Charlotte Somschema: split union() into its three ways of naming variants62f5f172026-09-27

import { expand } from "./util/build.ts";
import { compile, type ValidationResult } from "./validation.ts";
import { isNsid } from "./util/syntax.ts";

export declare const output: unique symbol;
export declare const input: unique symbol;

interface Typed<T, I = T> {
  readonly [output]?: readonly [T];
  readonly [input]?: readonly [I];
}

// deno-lint-ignore ban-types -- the intersection forces editor expansion
type Simplify<T> = { [K in keyof T]: T[K] } & {};

type Channel = typeof output | typeof input;
type Read<S, C extends Channel> = S extends { readonly [K in C]?: readonly [infer T] } ? T : never;
export type Infer<S> = Read<S, typeof output>;
/** What builders accept for a schema, where union and record discriminators may be implied. */
export type Input<S> = Read<S, typeof input>;
type Validated<T, I = T> = Typed<T, I> & { validate(value: unknown): ValidationResult<T> };
export type Schema<T = unknown, I = T> = Node & Validated<T, I>;

export type StringFormat =
  | "did"
  | "handle"
  | "at-identifier"
  | "at-uri"
  | "datetime"
  | "uri"
  | "language"
  | "cid"
  | "nsid"
  | "tid";
export type StringOptions = {
  readonly description?: string;
  readonly format?: StringFormat;
  readonly minLength?: number;
  readonly maxLength?: number;
  readonly minGraphemes?: number;
  readonly maxGraphemes?: number;
};
export type IntegerOptions = {
  readonly description?: string;
  readonly minimum?: number;
  readonly maximum?: number;
};
export type LengthOptions = {
  readonly description?: string;
  readonly minLength?: number;
  readonly maxLength?: number;
};
export type BlobOptions = {
  readonly description?: string;
  readonly accept?: readonly string[];
  readonly maxSize?: number;
};

export type CidLink = { readonly $link: string };
export type BytesValue = { readonly $bytes: string };
export type BlobValue = {
  readonly $type: "blob";
  readonly ref: CidLink;
  readonly mimeType: string;
  readonly size: number;
};

export type OptionalField<T = unknown, I = T> = Typed<T, I> & {
  readonly type: "optional";
  readonly inner: Schema | NullableField;
};
export type NullableField<T = unknown, I = T> = Typed<T | null, I | null> & {
  readonly type: "nullable";
  readonly inner: Schema;
};
export type Field = Schema | OptionalField | NullableField;
export type Shape = Readonly<Record<string, Field>>;

type ObjectValue<S extends Shape, C extends Channel = typeof output> =
  & { readonly [K in keyof S as S[K] extends OptionalField ? never : K]: Read<S[K], C> }
  & {
    readonly [K in keyof S as S[K] extends OptionalField ? K : never]?: Read<S[K], C> | undefined;
  };

type Node =
  | (
    & { readonly type: "string"; readonly const?: string; readonly enum?: readonly string[] }
    & StringOptions
  )
  | (
    & { readonly type: "integer"; readonly const?: number; readonly enum?: readonly number[] }
    & IntegerOptions
  )
  | { readonly type: "boolean"; readonly const?: boolean; readonly description?: string }
  | ({ readonly type: "bytes" } & LengthOptions)
  | { readonly type: "cid-link"; readonly description?: string }
  | ({ readonly type: "blob" } & BlobOptions)
  | ({ readonly type: "array"; readonly items: Schema } & LengthOptions)
  | { readonly type: "object"; readonly properties: Shape; readonly description?: string }
  | {
    readonly type: "ref";
    readonly id: string;
    readonly target: Schema;
    readonly description?: string;
  }
  | {
    readonly type: "union";
    readonly variants: Variants;
    readonly closed: boolean;
    readonly namespace?: string;
    readonly description?: string;
  }
  | {
    readonly type: "record";
    readonly id: string;
    readonly key: RecordKey;
    readonly record: ObjectSchema;
    readonly description?: string;
  };

export type ObjectSchema<S extends Shape = Shape> =
  & Schema<ObjectValue<S>, ObjectValue<S, typeof input>>
  & {
    readonly type: "object";
    readonly properties: S;
  };
export type RecordKey = "tid" | "any" | `literal:${string}`;

const validators = new WeakMap<object, (value: unknown) => ValidationResult<unknown>>();
const schemaPrototype = {
  validate<T>(this: Schema<T>, value: unknown): ValidationResult<T> {
    const check = validators.get(this) ?? compile(this);
    validators.set(this, check);
    return check(value) as ValidationResult<T>;
  },
};
const unionPrototype = Object.setPrototypeOf({
  build(this: Schema, value: unknown) {
    return expand(this, value);
  },
}, schemaPrototype);
const recordPrototype = Object.setPrototypeOf({
  build(this: Schema, fields: Record<string, unknown>) {
    if (Object.hasOwn(fields, "$type")) throw new Error("Record fields must not include $type");
    return expand(this, fields);
  },
}, schemaPrototype);

function schema<S extends Node>(node: S): S & typeof schemaPrototype {
  return Object.setPrototypeOf(node, schemaPrototype);
}

export function withDescription<S extends Schema>(source: S, description: string): S {
  return Object.create(Object.getPrototypeOf(source), {
    ...Object.getOwnPropertyDescriptors(source),
    description: { value: description, enumerable: true, configurable: true, writable: true },
  });
}

function bounds(min: number | undefined, max: number | undefined, nonnegative = true): void {
  for (const n of [min, max]) {
    if (n !== undefined && (!Number.isSafeInteger(n) || (nonnegative && n < 0))) {
      throw new Error("Bounds must be safe integers" + (nonnegative ? " >= 0" : ""));
    }
  }
  if (min !== undefined && max !== undefined && min > max) {
    throw new Error("Minimum must not exceed maximum");
  }
}

export type StringSchema<T extends string = string> = Schema<T> & { readonly type: "string" };
export type IntegerSchema = Schema<number> & { readonly type: "integer" };

export function stringWith(options: StringOptions = {}): StringSchema {
  bounds(options.minLength, options.maxLength);
  bounds(options.minGraphemes, options.maxGraphemes);
  return schema({ ...options, type: "string" });
}

export function integerWith(options: IntegerOptions = {}): IntegerSchema {
  bounds(options.minimum, options.maximum, false);
  return schema({ ...options, type: "integer" });
}

// Exports carry explicit types: JSR's fast check can't follow `typeof` between them.
export const string: StringSchema = stringWith();
export const integer: IntegerSchema = integerWith();
export const boolean: Schema<boolean> = schema({ type: "boolean" });
export const cidLink: Schema<CidLink> = schema({ type: "cid-link" });
export const did: StringSchema<`did:${string}`> = schema({ type: "string", format: "did" });
export const handle: StringSchema = stringWith({ format: "handle" });
export const atIdentifier: StringSchema = stringWith({ format: "at-identifier" });
export const atUri: StringSchema<`at://${string}`> = schema({ type: "string", format: "at-uri" });
export const datetime: StringSchema = stringWith({ format: "datetime" });
export const uri: StringSchema = stringWith({ format: "uri" });
export const language: StringSchema = stringWith({ format: "language" });
export const cid: StringSchema = stringWith({ format: "cid" });
export const nsid: StringSchema = stringWith({ format: "nsid" });
export const tid: StringSchema = stringWith({ format: "tid", minLength: 13, maxLength: 13 });

export function bytesWith(options: LengthOptions = {}): Schema<BytesValue> {
  bounds(options.minLength, options.maxLength);
  return schema({ ...options, type: "bytes" });
}
export const bytes: Schema<BytesValue> = bytesWith();

export function literal<const T extends string | number | boolean>(value: T): Schema<T> {
  if (typeof value === "string") return schema({ type: "string", const: value });
  if (typeof value === "boolean") return schema({ type: "boolean", const: value });
  if (!Number.isSafeInteger(value)) throw new Error("Numeric literals must be safe integers");
  return schema({ type: "integer", const: value });
}

export function enumValues<const T extends readonly [string, ...string[]]>(
  ...values: T
): Schema<T[number]> {
  return schema({ type: "string", enum: [...values] });
}

export function blob(options: BlobOptions = {}): Schema<BlobValue> {
  bounds(undefined, options.maxSize);
  if (
    options.accept?.some((mime) => !/^(?:\*\/\*|[\w!#$&^.+-]+\/(?:[\w!#$&^.+-]+|\*))$/.test(mime))
  ) {
    throw new Error("Invalid blob MIME pattern");
  }
  return schema({
    ...options,
    ...(options.accept && { accept: [...options.accept] }),
    type: "blob",
  });
}

export function array<S extends Schema>(
  items: S,
  options: LengthOptions = {},
): Schema<readonly Infer<S>[], readonly Input<S>[]> {
  bounds(options.minLength, options.maxLength);
  return schema({ ...options, type: "array", items });
}

export function optional<S extends Schema | NullableField>(
  inner: S,
): OptionalField<Infer<S>, Input<S>> {
  return { type: "optional", inner };
}

export function nullable<S extends Schema>(inner: S): NullableField<Infer<S>, Input<S>> {
  return { type: "nullable", inner };
}

export function object<const S extends Shape>(
  properties: S,
  options: { readonly description?: string } = {},
): ObjectSchema<S> {
  if (Object.keys(properties).some((key) => key.startsWith("$"))) {
    throw new Error("$-prefixed fields are reserved; records and unions supply $type");
  }
  return schema({ ...options, type: "object", properties: { ...properties } });
}

export function definitionId(id: string): { nsid: string; name: string } {
  const [nsid, name = "main", extra] = id.split("#");
  if (!nsid || !isNsid(nsid) || extra !== undefined || !/^[A-Za-z][A-Za-z0-9]*$/.test(name)) {
    throw new Error(`Invalid definition ID: ${id}`);
  }
  if (id.endsWith("#main")) throw new Error("Use the bare NSID instead of #main");
  return { nsid, name };
}

export type NamedSchema<Id extends string = string, T = unknown, I = T> =
  & Validated<T, I>
  & {
    readonly type: "ref";
    readonly id: Id;
    readonly target: Schema<T, I>;
    readonly description?: string;
  };

export function named<S extends Schema, const Id extends string = string>(
  id: Id,
  target: S | (() => S),
): NamedSchema<Id, Infer<S>, Input<S>> & { readonly target: S } {
  definitionId(id);
  let resolved: S | undefined;
  let resolving = false;
  const ref = schema({
    type: "ref",
    id,
    get target(): S {
      if (resolved) return resolved;
      if (resolving) throw new Error(`Circular definition factory: ${id}`);
      resolving = true;
      try {
        const value = typeof target === "function" ? target() : target;
        if (value.type === "ref" || value.type === "union" || value.type === "record") {
          throw new Error("Only concrete definitions can be named; records already have a name");
        }
        return resolved = value;
      } finally {
        resolving = false;
      }
    },
  });
  if (typeof target !== "function") void ref.target;
  return ref as NamedSchema<Id, Infer<S>, Input<S>> & { readonly target: S };
}

type Variants = Readonly<Record<string, Schema>>;
type ObjectVariants = Readonly<Record<string, ObjectSchema>>;
type NamedVariants<V extends readonly NamedSchema[]> = {
  readonly [S in V[number] as S["id"]]: S["target"];
};
type UnionValue<
  V extends Variants,
  C extends Channel = typeof output,
  Base extends string = never,
> = {
  [K in keyof V & string]: Simplify<
    & { readonly $type: K | (K extends `${Base}#${infer F}` ? `#${F}` : never) }
    & Read<V[K], C>
  >;
}[keyof V & string];
type UnionOptions<Closed extends boolean> = {
  readonly closed?: Closed;
  readonly description?: string;
};
export type UnknownVariant = { readonly $type: string; readonly [key: string]: unknown };
type Open<Closed extends boolean> = Closed extends true ? never : UnknownVariant;
export type UnionSchema<
  V extends Variants,
  Closed extends boolean = true,
  Base extends string = never,
> =
  & Validated<UnionValue<V> | Open<Closed>, UnionValue<V, typeof input, Base> | Open<Closed>>
  & {
    readonly type: "union";
    readonly variants: V;
    readonly closed: Closed;
    readonly description?: string;
    build(value: UnionValue<V, typeof input, Base> | Open<Closed>): UnionValue<V> | Open<Closed>;
  };

// Variants of a namespaced union are declared as "#name" and stored under their full ID.
function namespacedVariants(namespace: string, variants: ObjectVariants): Variants {
  if (!isNsid(namespace)) throw new Error(`Invalid union namespace: ${namespace}`);
  return Object.fromEntries(
    Object.entries(variants).map(([key, variant]) => {
      if (!key.startsWith("#")) throw new Error("Union variant names must start with #");
      return [namespace + key, variant];
    }),
  );
}

// Resolving targets here would re-enter a definition that includes itself in a union, so
// each variant resolves on first access.
function namedVariants(refs: readonly NamedSchema[]): Variants {
  const variants: Record<string, Schema> = {};
  for (const ref of refs) {
    if (ref.type !== "ref") throw new Error("Union arrays must contain named definitions");
    if (Object.hasOwn(variants, ref.id)) throw new Error("Duplicate union variant");
    Object.defineProperty(variants, ref.id, {
      enumerable: true,
      get() {
        const target = ref.target;
        if (target.type !== "object") throw new Error(`Union variant ${ref.id} must be an object`);
        return target;
      },
    });
  }
  return variants;
}

const isNamedList = (value: unknown): value is readonly NamedSchema[] => Array.isArray(value);

function unionOf(variants: Variants, options: UnionOptions<boolean>, namespace?: string): Schema {
  const keys = Object.keys(variants);
  if (keys.length === 0 && options.closed !== false) {
    throw new Error("A closed union cannot be empty");
  }
  for (const key of keys) definitionId(key);
  return Object.setPrototypeOf({
    ...options,
    type: "union",
    variants,
    closed: options.closed ?? true,
    ...(namespace !== undefined && { namespace }),
  }, unionPrototype);
}

export function union<
  const V extends readonly NamedSchema[],
  const Closed extends boolean = true,
>(
  variants: V,
  options?: UnionOptions<Closed>,
): UnionSchema<NamedVariants<V>, Closed>;
export function union<const V extends ObjectVariants, const Closed extends boolean = true>(
  variants: V,
  options?: UnionOptions<Closed>,
): UnionSchema<V, Closed>;
export function union<
  const Id extends string,
  const V extends Readonly<Record<`#${string}`, ObjectSchema>>,
  const Closed extends boolean = true,
>(
  id: Id,
  variants: V,
  options?: UnionOptions<Closed>,
): UnionSchema<{ readonly [K in keyof V & `#${string}` as `${Id}${K}`]: V[K] }, Closed, Id>;
export function union(
  idOrVariants: string | ObjectVariants | readonly NamedSchema[],
  variantsOrOptions: ObjectVariants | UnionOptions<boolean> = {},
  options: UnionOptions<boolean> = {},
): Schema {
  if (typeof idOrVariants === "string") {
    const variants = namespacedVariants(idOrVariants, variantsOrOptions as ObjectVariants);
    return unionOf(variants, options, idOrVariants);
  }
  const variants = isNamedList(idOrVariants) ? namedVariants(idOrVariants) : { ...idOrVariants };
  return unionOf(variants, variantsOrOptions as UnionOptions<boolean>);
}

export type RecordSchema<Id extends string, S extends Shape> =
  & Schema<
    Simplify<{ readonly $type: Id } & ObjectValue<S>>,
    Simplify<{ readonly $type?: Id } & ObjectValue<S, typeof input>>
  >
  & {
    readonly type: "record";
    readonly id: Id;
    readonly record: ObjectSchema<S>;
    build(fields: ObjectValue<S, typeof input> & { readonly $type?: never }): Simplify<
      { readonly $type: Id } & ObjectValue<S>
    >;
  };

export function record<const Id extends string, const S extends Shape>(
  id: Id,
  options: { readonly key: RecordKey; readonly description?: string },
  properties: S,
): RecordSchema<Id, S> {
  if (!isNsid(id)) throw new Error(`Invalid record NSID: ${id}`);
  if (
    options.key !== "tid" && options.key !== "any" &&
    !/^literal:[A-Za-z0-9_~.:-]{1,512}$/.test(options.key)
  ) {
    throw new Error("Invalid record key policy");
  }
  if (options.key === "literal:." || options.key === "literal:..") {
    throw new Error("Invalid literal record key");
  }
  return Object.setPrototypeOf(
    { ...options, type: "record", id, record: object(properties) },
    recordPrototype,
  );
}