bend-schema 0.1.0

package/src/index.ts

@@ -0,0 +1,350 @@
+// bend-schema's TypeScript face: build a schema with `s`, then call
+// `.parse`, `.check` or `.encode` on it. What is proved is the core's
+// (core/LAWS.bend): which values a schema accepts, the first error and its
+// path, and that dec reads what enc writes. What is NOT proved lives here: the
+// builder (a mirror of the core's Schema constructors), the conversion between
+// the core's Meaning values and plain JS, and `.refine()` predicates, whose
+// errors say `proved: false`.
+
+import * as core from "../dist-core/core.mjs";
+import type { BendList, Schema as Node, Step } from "../dist-core/core.mjs";
+import { toRaw, whyText } from "./codec";
+
+// enc and dec return a type computed from the schema (Meaning(s)), which
+// bend-emit cannot write as a TS signature; they are untyped here.
+const { enc, dec } = core as unknown as { enc: (s: Node, m: unknown) => core.Raw; dec: (s: Node, r: core.Raw) => core.BendMaybe<unknown> };
+
+export { BUDGET, KEYS_MAX, NAT_MAX, nat, toRaw } from "./codec";
+export type { Raw } from "../dist-core/core.mjs";
+
+// ------------------------------------------------------------------ issues
+
+export type PathPart = string | number;
+
+/** The first error: where it is, and why. `proved: true` came from the core;
+ * `proved: false` from a `.refine()` predicate. */
+export class Issue {
+  constructor(
+    readonly path: PathPart[],
+    readonly message: string,
+    readonly proved: boolean,
+  ) {}
+
+  /** "plan.tiers[3].up: must be ..." -- `where` names the value. */
+  text(where = ""): string {
+    const p = this.path.map((x) => (typeof x === "number" ? `[${x}]` : `.${x}`)).join("");
+    const at = (where + p).replace(/^\./, "") || "the value";
+    return `${at}: ${this.message}`;
+  }
+
+  toString(): string {
+    return this.text();
+  }
+}
+
+export type Result<T> = { ok: true; value: T } | { ok: false; error: Issue };
+
+// ---------------------------------------------------------------- the builder
+
+type Kind =
+  | { k: "nat" }
+  | { k: "natIn"; lo: number; hi: number }
+  | { k: "str" }
+  | { k: "strLen"; lo: number; hi: number; inner: Schema<string> }
+  | { k: "bool" }
+  | { k: "true" }
+  | { k: "nullable"; inner: Schema<any> }
+  | { k: "optional"; inner: Schema<any> }
+  | { k: "list"; elem: Schema<any> }
+  | { k: "listLen"; lo: number; hi: number; inner: Schema<any[]> }
+  | { k: "tuple"; items: Schema<any>[] }
+  | { k: "object"; fields: [string, Schema<any>][] }
+  | { k: "strict"; obj: Schema<any> }
+  | { k: "enum"; names: string[] }
+  | { k: "oneKey"; cases: [string, Schema<any>][] }
+  | { k: "tagged"; key: string; cases: [string, Schema<any>][] };
+
+type Refinement = { fn: (x: any) => boolean; why: string };
+
+export class Schema<T> {
+  declare readonly _T: T;
+  /** @internal */ readonly kind: Kind;
+  /** @internal */ readonly refines: Refinement[];
+  private cached?: Node;
+
+  /** @internal */ constructor(kind: Kind, refines: Refinement[] = []) {
+    this.kind = kind;
+    this.refines = refines;
+  }
+
+  /** A host-side predicate, run after the proved check passes. Not proved:
+   * its error carries `proved: false`. Keeps the schema's own methods. */
+  refine(fn: (x: T) => boolean, why: string): this {
+    const Ctor = this.constructor as new (k: Kind, r: Refinement[]) => this;
+    return new Ctor(this.kind, [...this.refines, { fn, why }]);
+  }
+
+  /** null or this. The key must still be present. */
+  nullable(): Schema<T | null> {
+    return new Schema<T | null>({ k: "nullable", inner: this });
+  }
+
+  /** The key may be absent. Only valid as an object field. */
+  optional(): Optional<T> {
+    return new Optional<T>({ k: "optional", inner: this });
+  }
+
+  /** Check v, then read it as T. */
+  parse(v: unknown): Result<T> {
+    const node = this.node;
+    const raw = toRaw(v);
+    const e = core.check0(node, raw);
+    if (e.$ === "Some") return { ok: false, error: new Issue(pathOf(e.value.path), whyText(e.value.why), true) };
+    const m = dec(node, raw);
+    if (m.$ !== "Some") throw new Error("bend-schema: dec refused a value check0 accepted (a bug in the core)");
+    const value = toJs(this, m.value) as T;
+    const r = refineAt(this, value, []);
+    return r ? { ok: false, error: r } : { ok: true, value };
+  }
+
+  /** The first error, or null. */
+  check(v: unknown): Issue | null {
+    const r = this.parse(v);
+    return r.ok ? null : r.error;
+  }
+
+  /** Write x as plain JSON-ready JS; parse reads it back. Throws when x breaks
+   * a bound or a refinement, which its type cannot rule out. */
+  encode(x: T): unknown {
+    const out = rawToJs(enc(this.node, toMeaning(this, x)));
+    // An absent top-level value is legitimate for an Optional schema, and
+    // JSON has no way to write it, so it stays undefined rather than throwing.
+    if (out === undefined) return undefined;
+    const e = this.check(out);
+    if (e) throw new Error(`bend-schema: encode: ${e.text()}`);
+    return out;
+  }
+
+  /** The core's Schema value. Throws if the core finds it ill-formed. */
+  get node(): Node {
+    if (!this.cached) {
+      const n = toNode(this);
+      if (!core.wf(n)) {
+        throw new Error(
+          "bend-schema: ill-formed schema (a duplicate key, a nullable inside a nullable, " +
+            ".optional() outside an object field, or .strict() on a non-object)",
+        );
+      }
+      this.cached = n;
+    }
+    return this.cached;
+  }
+}
+
+/** A field that may be absent. */
+export class Optional<T> extends Schema<T | undefined> {
+  declare readonly _optional: true;
+}
+
+export class NatSchema extends Schema<number> {
+  /** lo <= n <= hi, both ends included. */
+  in(lo: number, hi: number): NatSchema {
+    return new NatSchema({ k: "natIn", lo: whole(lo), hi: whole(hi) }, this.refines);
+  }
+}
+
+export class StrSchema extends Schema<string> {
+  /** lo <= length <= hi, both ends included. */
+  len(lo: number, hi: number): StrSchema {
+    return new StrSchema({ k: "strLen", lo: whole(lo), hi: whole(hi), inner: this });
+  }
+}
+
+export class ListSchema<T> extends Schema<T[]> {
+  /** lo <= element count <= hi, both ends included. */
+  len(lo: number, hi: number): ListSchema<T> {
+    return new ListSchema<T>({ k: "listLen", lo: whole(lo), hi: whole(hi), inner: this });
+  }
+}
+
+export class ObjectSchema<T> extends Schema<T> {
+  /** Refuse keys this object does not name (by default they are dropped). */
+  strict(): ObjectSchema<T> {
+    return new ObjectSchema<T>({ k: "strict", obj: this });
+  }
+}
+
+function whole(n: number): number {
+  if (!Number.isSafeInteger(n) || n < 0) throw new Error(`bend-schema: a bound must be a whole number >= 0, got ${n}`);
+  return n;
+}
+
+type Shape = Record<string, Schema<any>>;
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+type OptKeys<S extends Shape> = { [K in keyof S]: S[K] extends Optional<any> ? K : never }[keyof S];
+type ObjOf<S extends Shape> = Simplify<
+  { [K in Exclude<keyof S, OptKeys<S>>]: Infer<S[K]> } & { [K in OptKeys<S>]?: Exclude<Infer<S[K]>, undefined> }
+>;
+type Union<S extends Shape> = { [K in keyof S]: { [P in K]: Infer<S[K]> } }[keyof S];
+type TaggedUnion<K extends string, S extends Record<string, ObjectSchema<any>>> = {
+  [N in keyof S]: Simplify<{ [P in K]: N } & Infer<S[N]>>;
+}[keyof S];
+
+export type Infer<X> = X extends Schema<infer T> ? T : never;
+
+export const s = {
+  nat: () => new NatSchema({ k: "nat" }),
+  str: () => new StrSchema({ k: "str" }),
+  bool: () => new Schema<boolean>({ k: "bool" }),
+  true: () => new Schema<true>({ k: "true" }),
+  list: <T>(elem: Schema<T>) => new ListSchema<T>({ k: "list", elem }),
+  tuple: <A extends Schema<any>[]>(...items: A) =>
+    new Schema<{ [I in keyof A]: Infer<A[I]> }>({ k: "tuple", items }),
+  object: <S extends Shape>(shape: S) => new ObjectSchema<ObjOf<S>>({ k: "object", fields: Object.entries(shape) }),
+  enum: <const N extends readonly [string, ...string[]]>(names: N) => new Schema<N[number]>({ k: "enum", names: [...names] }),
+  oneKey: <S extends Shape>(cases: S) => new Schema<Union<S>>({ k: "oneKey", cases: Object.entries(cases) }),
+  tagged: <K extends string, S extends Record<string, ObjectSchema<any>>>(key: K, cases: S) =>
+    new Schema<TaggedUnion<K, S>>({ k: "tagged", key, cases: Object.entries(cases) }),
+};
+
+// `s.Infer<typeof x>` reads as `Infer<typeof x>`.
+export declare namespace s {
+  type Infer<X> = X extends Schema<infer T> ? T : never;
+}
+
+function toNode(x: Schema<any>): Node {
+  const k = x.kind;
+  switch (k.k) {
+    case "nat": return { $: "SNat" };
+    case "natIn": return { $: "SNatIn", lo: BigInt(k.lo), hi: BigInt(k.hi) };
+    case "str": return { $: "SStr" };
+    case "strLen": return { $: "SStrLen", lo: BigInt(k.lo), hi: BigInt(k.hi), s: toNode(k.inner) };
+    case "bool": return { $: "SBool" };
+    case "true": return { $: "STrue" };
+    case "nullable": return { $: "SOpt", inner: toNode(k.inner) };
+    case "optional": return { $: "SOptional", inner: toNode(k.inner) };
+    case "listLen": return { $: "SListLen", lo: BigInt(k.lo), hi: BigInt(k.hi), s: toNode(k.inner) };
+    case "list": return { $: "SList", elem: toNode(k.elem) };
+    case "tuple": return k.items.reduceRight<Node>((rest, it) => ({ $: "STuple", s: toNode(it), rest }), { $: "STEnd" });
+    case "object": return k.fields.reduceRight<Node>((rest, [name, f]) => ({ $: "SField", name, s: toNode(f), rest }), { $: "SEnd" });
+    case "strict": return { $: "SStrict", s: toNode(k.obj) };
+    case "enum": return { $: "SEnum", names: k.names.reduceRight<BendList<string>>((tail, head) => ({ $: "Con", head, tail }), { $: "Nil" }) };
+    case "oneKey": return k.cases.reduceRight<Node>((rest, [name, c]) => ({ $: "SVariant", name, s: toNode(c), rest }), { $: "SVEnd" });
+    case "tagged": return k.cases.reduceRight<Node>((rest, [name, c]) => ({ $: "STagged", key: k.key, name, s: toNode(c), rest }), { $: "STagEnd", key: k.key });
+  }
+}
+
+// ------------------------------------------- Meaning <-> plain JS (not proved)
+
+type M = any; // a core Meaning(s) value: number (a Nat), string, boolean, Unit, Both, Either, Maybe, List
+
+const unit = { $: "Unit" };
+const both = (a: M, b: M) => ({ $: "Both", a, b });
+
+function toJs(x: Schema<any>, m: M): unknown {
+  const k = x.kind;
+  switch (k.k) {
+    case "nat": case "natIn": return Number(m);
+    case "str": case "bool": case "enum": return m;
+    case "strLen": return toJs(k.inner, m);
+    case "true": return true;
+    case "nullable": return m.$ === "None" ? null : toJs(k.inner, m.value);
+    case "optional": return m.$ === "None" ? undefined : toJs(k.inner, m.value);
+    case "listLen": return toJs(k.inner, m);
+    case "list": { const out = []; for (let l = m; l.$ === "Con"; l = l.tail) out.push(toJs(k.elem, l.head)); return out; }
+    case "tuple": { const out = []; let b = m; for (const it of k.items) { out.push(toJs(it, b.a)); b = b.b; } return out; }
+    case "object": { const out: Record<string, unknown> = {}; let b = m; for (const [n, f] of k.fields) { const x = toJs(f, b.a); if (x !== undefined) put(out, n, x); b = b.b; } return out; }
+    case "strict": return toJs(k.obj, m);
+    case "oneKey": { let e = m; for (const [n, c] of k.cases) { if (e.$ === "Inl") return { [n]: toJs(c, e.value) }; e = e.value; } throw new Error("unreachable: Empty"); }
+    case "tagged": { let e = m; for (const [n, c] of k.cases) { if (e.$ === "Inl") return { [k.key]: n, ...(toJs(c, e.value) as object) }; e = e.value; } throw new Error("unreachable: Empty"); }
+  }
+}
+
+function toMeaning(x: Schema<any>, v: any): M {
+  const k = x.kind;
+  switch (k.k) {
+    case "nat": case "natIn": return BigInt(whole(v));
+    case "str": case "bool": case "enum": return v;
+    case "strLen": return toMeaning(k.inner, v);
+    case "true": return unit;
+    case "nullable": return v === null ? { $: "None" } : { $: "Some", value: toMeaning(k.inner, v) };
+    case "optional": return v === undefined ? { $: "None" } : { $: "Some", value: toMeaning(k.inner, v) };
+    case "listLen": return toMeaning(k.inner, v);
+    case "list": return (v as any[]).reduceRight((tail, h) => ({ $: "Con", head: toMeaning(k.elem, h), tail }), { $: "Nil" });
+    case "tuple": return k.items.reduceRight((rest: M, it, i) => both(toMeaning(it, v[i]), rest), unit);
+    case "object": return k.fields.reduceRight((rest: M, [n, f]) => both(toMeaning(f, v[n]), rest), unit);
+    case "strict": return toMeaning(k.obj, v);
+    case "oneKey": {
+      const i = k.cases.findIndex(([n]) => n in v);
+      if (i < 0) throw new Error("bend-schema: encode: no case key present");
+      return inj(i, toMeaning(k.cases[i]![1], v[k.cases[i]![0]]));
+    }
+    case "tagged": {
+      const i = k.cases.findIndex(([n]) => v[k.key] === n);
+      if (i < 0) throw new Error(`bend-schema: encode: unknown tag ${String(v[k.key])}`);
+      const { [k.key]: _, ...rest } = v;
+      return inj(i, toMeaning(k.cases[i]![1], rest));
+    }
+  }
+}
+
+const inj = (i: number, m: M): M => (i === 0 ? { $: "Inl", value: m } : { $: "Inr", value: inj(i - 1, m) });
+
+// `out[n] = x` is a prototype setter for a field named `__proto__`, which would
+// silently drop it -- a required field gone from a value parse calls valid, and
+// an encode whose own re-check then fails. defineProperty has no such case.
+function put(out: Record<string, unknown>, n: string, x: unknown): void {
+  Object.defineProperty(out, n, { value: x, enumerable: true, writable: true, configurable: true });
+}
+
+function rawToJs(r: core.Raw): unknown {
+  switch (r.$) {
+    case "RNum": return Number(r.n);
+    case "RBool": return r.b;
+    case "RNull": return null;
+    case "RStr": return r.s;
+    case "RNil": case "RCons": { const out = []; for (let l: core.Raw = r; l.$ === "RCons"; l = l.tail) out.push(rawToJs(l.head)); return out; }
+    case "REnd": case "RKey": { const out: Record<string, unknown> = {}; for (let l: core.Raw = r; l.$ === "RKey"; l = l.rest) if (l.val.$ !== "RMissing") put(out, l.key, rawToJs(l.val)); return out; }
+    // An absent value is legitimate at the top level of an Optional schema. JSON
+    // cannot write it, so it reads as undefined; a nested one never reaches
+    // here, because the RKey arm drops it.
+    case "RMissing": return undefined;
+    default: throw new Error(`bend-schema: encode produced ${r.$}`);
+  }
+}
+
+// --------------------------------------------------------------- issues' paths
+
+function pathOf(p: BendList<Step>): PathPart[] {
+  const out: PathPart[] = [];
+  for (let x = p; x.$ === "Con"; x = x.tail) {
+    const st = x.head;
+    if (st.$ === "AtIndex") out.push(Number(st.i));
+    else if (st.$ === "AtField") out.push(st.name);
+    else if (st.$ === "AtKey") out.push(st.key);
+    else out.push(Number(st.i), st.key);
+  }
+  return out;
+}
+
+// Run refinements bottom-up over the parsed value, first failure in reading order.
+function refineAt(x: Schema<any>, v: any, path: PathPart[]): Issue | null {
+  const k = x.kind;
+  const sub = (c: Schema<any>, cv: any, p: PathPart) => refineAt(c, cv, [...path, p]);
+  let e: Issue | null = null;
+  switch (k.k) {
+    case "strLen": e = refineAt(k.inner, v, path); break;
+    case "nullable": if (v !== null) e = refineAt(k.inner, v, path); break;
+    case "optional": if (v !== undefined) e = refineAt(k.inner, v, path); break;
+    case "listLen": e = refineAt(k.inner, v, path); break;
+    case "list": for (let i = 0; i < v.length && !e; i++) e = sub(k.elem, v[i], i); break;
+    case "tuple": for (let i = 0; i < k.items.length && !e; i++) e = sub(k.items[i]!, v[i], i); break;
+    case "object": for (const [n, f] of k.fields) if (!e && !(f.kind.k === "optional" && v[n] === undefined)) e = sub(f, v[n], n); break;
+    case "strict": e = refineAt(k.obj, v, path); break;
+    case "oneKey": for (const [n, c] of k.cases) if (!e && n in v) e = sub(c, v[n], n); break;
+    case "tagged": for (const [n, c] of k.cases) if (!e && v[k.key] === n) e = refineAt(c, v, path); break;
+  }
+  if (e) return e;
+  for (const r of x.refines) if (!r.fn(v)) return new Issue(path, r.why, false);
+  return null;
+}