bend-schema 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "bend-schema",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "bend-emit": "0.3.1",
+    "bend-falsify": "github:nohzafk/bend-falsify#a50873f",
+    "typescript": "^7.0.2"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./codec": "./src/codec.ts",
+    "./gen": "./src/gen.ts"
+  },
+  "bin": {
+    "bend-schema": "./src/gen-cli.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nohzafk/bend-schema.git"
+  },
+  "homepage": "https://github.com/nohzafk/bend-schema#readme",
+  "bugs": {
+    "url": "https://github.com/nohzafk/bend-schema/issues"
+  },
+  "files": [
+    "src/index.ts",
+    "src/codec.ts",
+    "src/gen.ts",
+    "src/gen-cli.ts",
+    "core/core.bend",
+    "core/LAWS.bend",
+    "core/PROOF.bend",
+    "core/LICENSE",
+    "dist-core/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/codec.ts

@@ -0,0 +1,177 @@
+// The universal codec: any JS value, as the schema check takes it.
+//
+// It knows no schema, so it decides nothing about shapes: a whole number from 0
+// to the runtime's Nat bound (2^48-1) is RNum, a boolean RBool, null RNull, a
+// string RStr, an array a chain of RCons, a plain object a chain of RKey in its
+// own key order, and anything else (a fraction, a negative, NaN, undefined, a
+// Date or any other non-plain object) is RBad, for check to report where it
+// sits. Every rule about shapes is the proved core's (LAWS.bend).
+//
+// Size is the one thing it decides, because it is the one thing the core
+// cannot: the compiled JS walks a list or an object with one native JS frame
+// per element or key, so a long value throws RangeError. So the codec counts
+// what such a walk would cost -- see BUDGET -- and puts one RTooBig in place of
+// the array or object that runs past the budget, which the core reports as
+// TooLarge at that node's path. Nothing here is a rule about values: a size is
+// not a shape, and a host cannot choose the sizes it is sent.
+
+import type { BendList, BendMaybe, Err, Raw, Step, Why } from "../dist-core/core.mjs";
+
+// The largest Nat the runtime holds: bend's own Nat.add(Nat.mul(65535,
+// 4294967295 + 1), 4294967295). A number past it is not a Nat at all, so it
+// is not a value the core can be given.
+export const NAT_MAX = 2 ** 48 - 1;
+
+// One rule, two ways out: the runtime holds v as a Nat, or it does not.
+const natFit = (v: number): boolean => Number.isSafeInteger(v) && v >= 0 && v <= NAT_MAX;
+
+// `nat(name, v)` is v when the runtime can hold it as a Nat, and an Error
+// otherwise. It is toRaw's RNum rule, thrown instead of reported: a host that
+// must refuse a number before building anything -- billing's `units`, which is
+// not part of the plan it checks -- needs the refusal here, and the message
+// names the field, the bound and the value.
+export function nat(name: string, v: number): number {
+  if (!natFit(v)) {
+    throw new Error(`${name} must be a whole number from 0 to ${NAT_MAX} (${name}=${v})`);
+  }
+  return v;
+}
+
+// The most list elements and object keys one value may hold, counted over
+// every level of nesting and summed: `[[1,2],[3]]` is 2 + 3 = 5. Past it, a
+// node becomes RTooBig.
+//
+// Measured, not guessed (with bend 2.0.35 on a macOS arm64 Mac, each shape in
+// its own process). Each shape below is the largest count where toRaw, check0,
+// conforms0, enc and dec all return in bun, and what the next step throws:
+//
+//   flat list       30000   check0: RangeError
+//   nested object    6257   check0: RangeError
+//   nested list      6257   check0: RangeError
+//   list of lists   29929   survived the largest count tried
+//   list of objects 29929   survived the largest count tried
+//   mixed           15224   survived the largest count tried
+//   flat object      6656   check0: RangeError (25 probes, 903 s)
+//
+// The binding shapes are the nested object and the nested list, both at 6257,
+// and a value at the budget keeps about 2.0x of margin under them. (On bend
+// 2.0.27 the nested object reached about 10,600 and a flat object bound first,
+// at 6144, which is why KEYS_MAX exists; the budget was set to half of that,
+// 3072, and is kept.) One budget covers lists, objects and nesting alike, and
+// what makes it enough is the invariant: toRaw never builds a value whose count
+// is past it, so the walk that follows is bounded by it.
+
+export const BUDGET = 3072;
+
+// The most keys one object may hold. A second limit, on time rather than
+// stack: the core finds each field by scanning the object from the front, so
+// walking an object costs about keys^2 lookups. At 3072 keys that was about
+// 8 s for each of check0, conforms0 and dec -- a small request that holds a
+// server for seconds. At 256 keys it is about 65,000 lookups. An object with
+// more keys than this is RTooBig, like a value past the budget; a set that
+// large belongs in a list.
+export const KEYS_MAX = 256;
+
+export function toRaw(v: unknown): Raw {
+  let left = BUDGET;
+  const build = (v: unknown): Raw => {
+    if (v === null) return { $: "RNull" };
+    if (typeof v === "number") return natFit(v) ? { $: "RNum", n: BigInt(v) } : { $: "RBad" };
+    if (typeof v === "boolean") return { $: "RBool", b: v };
+    if (typeof v === "string") return { $: "RStr", s: v };
+    if (Array.isArray(v)) {
+      if (v.length > left) return { $: "RTooBig" };
+      left -= v.length;
+      // Elements are built first to last, so the budget runs out where a
+      // reader would expect: at the first node past it, not at the start.
+      const heads = v.map(build);
+      return heads.reduceRight<Raw>((tail, head) => ({ $: "RCons", head, tail }), { $: "RNil" });
+    }
+    if (typeof v === "object") {
+      // A plain object, and nothing else. A Date, Map, Set or class instance is
+      // not JSON, and carries no own enumerable keys, so it would otherwise
+      // become an empty REnd -- a value the core would accept as conforming to
+      // any object schema with no required key.
+      const proto = Object.getPrototypeOf(v);
+      if (proto !== Object.prototype && proto !== null) return { $: "RBad" };
+      const entries = Object.entries(v as object);
+      if (entries.length > KEYS_MAX || entries.length > left) return { $: "RTooBig" };
+      left -= entries.length;
+      const vals = entries.map(([key, val]) => [key, build(val)] as const);
+      return vals.reduceRight<Raw>((rest, [key, val]) => ({ $: "RKey", key, val, rest }), { $: "REnd" });
+    }
+    return { $: "RBad" };
+  };
+  return build(v);
+}
+
+export const NONE: BendMaybe<bigint> = { $: "None" };
+
+function steps(p: BendList<Step>): Step[] {
+  const out: Step[] = [];
+  for (let x = p; x.$ === "Con"; x = x.tail) out.push(x.head);
+  return out;
+}
+
+// A path as text: "[2].upTo". A field step counts the schema fields it
+// skipped, for the proofs; the text shows only its name.
+export function pathText(p: BendList<Step>): string {
+  return steps(p).map((s) => (s.$ === "AtIndex" ? `[${s.i}]` : s.$ === "AtField" ? `.${s.name}` : s.$ === "AtKey" ? `.${s.key}` : `[${s.i}].${s.key}`)).join("");
+}
+
+// What is wrong, in words. tsc checks every reason is here.
+export function whyText(w: Why): string {
+  switch (w.$) {
+    case "Missing":
+      return "missing";
+    case "NotNat":
+      return `must be a whole number from 0 to ${NAT_MAX}`;
+    case "NotString":
+      return "must be a string";
+    case "NotBool":
+      return "must be a boolean";
+    case "NotList":
+      return "must be a list";
+    case "NotObject":
+      return "must be an object";
+    case "NoElements":
+      return "must not be empty";
+    case "OpenNotLast":
+      return "only the last may be null";
+    case "LastNotOpen":
+      return "the last must be null";
+    case "NotIncreasing":
+      return `must be past ${w.prev} (got ${w.got})`;
+    case "NotTrue":
+      return "must be true";
+    case "NotOneOf":
+      return "is not one of the allowed names";
+    case "NoVariant":
+      return "must have one of its keys";
+    case "TwoVariants":
+      return "is a second key, where only one is allowed";
+    case "TooShort":
+      return "has too few elements";
+    case "TooLong":
+      return "has too many elements";
+    case "LengthNotIn":
+      return `must be ${w.lo} to ${w.hi} characters long`;
+    case "CountNotIn":
+      return `must have ${w.lo} to ${w.hi} elements`;
+    case "UnknownKey":
+      return "is not a key this object allows";
+    case "RepeatedKey":
+      return `is a second ${w.key}`;
+    case "NotIn":
+      return `must be from ${w.lo} to ${w.hi}`;
+    case "TooLarge":
+      return "too large";
+  }
+}
+
+// An error in words, its path after `where` (the name the host gives the
+// value): errText(e, "tiers") is "tiers[0].upTo: missing". With no `where`
+// and an empty path, the value itself is named: "the value: must be a list".
+export function errText(e: Err, where = ""): string {
+  return `${where + pathText(e.path) || "the value"}: ${whyText(e.why)}`;
+}

package/src/gen-cli.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+// The command: `bend-schema gen <module.ts> <out.bend>`, run with bun (`bunx`)
+// or node (`npx`). Bun does the work either way: the shebang is `env bun`,
+// because the command executes the module and Node refuses to strip types from
+// TypeScript in node_modules.
+//
+// The module must export `schemas` — an object whose keys name the Bend defs:
+//
+//   export const schemas = { config: Config, workers: Workers };
+//
+// An explicit map rather than every exported Schema: the names are the author's,
+// and a schema that is a step inside another is not printed by accident.
+//
+// The module is **executed** to be read, so it must be schemas and nothing
+// else: a file that does something on import would do it at build time. (A
+// `describe()` in it fails here — `Cannot use describe outside of the test
+// runner` — which is how this was found.)
+//
+// The import path in the generated file is computed here: this file lives in
+// the package, so the core sits at <pkg>/core/core.bend, and the output file's
+// own directory gives the relative path to it. The caller passes no path.
+//
+// Nothing here needs bun's own APIs. `import.meta.dirname` is Node's name, and
+// bun's; `import.meta.dir` is bun-only, which is why this file does not use it.
+// Node can strip types from a `.ts` file, but not from one inside
+// `node_modules`: a consumer's installed copy is always in there, so Node
+// refuses to run it (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING) and the
+// shebang above is what makes the command work.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { emit } from "./gen";
+import type { Schema } from "./index";
+
+const pkgCore = resolve(import.meta.dirname, "../core/core.bend");
+const args = process.argv.slice(2);
+if (args[0] === "gen") args.shift();
+const [modArg, outArg] = args;
+if (!modArg || !outArg) {
+  console.error("usage: bunx bend-schema gen <module.ts> <out.bend>");
+  process.exit(2);
+}
+
+const mod: Record<string, unknown> = await import(resolve(modArg));
+const schemas = mod.schemas as Record<string, Schema<unknown>> | undefined;
+if (!schemas || typeof schemas !== "object" || Array.isArray(schemas)) {
+  console.error(
+    `gen: ${modArg} must export \`schemas\` — an object of Schema values, one per Bend def:\n` +
+      `     export const schemas = { config: Config };`,
+  );
+  process.exit(1);
+}
+
+const out = resolve(outArg);
+mkdirSync(dirname(out), { recursive: true });
+const rel = relative(dirname(out), pkgCore);
+writeFileSync(
+  out,
+  emit(schemas, { libPath: rel.startsWith(".") ? rel : `./${rel}`, from: modArg }),
+);
+console.error(`gen: ${Object.keys(schemas).length} schema(s) from ${modArg} -> ${outArg}`);

package/src/gen.ts

@@ -0,0 +1,96 @@
+// gen.ts — the same schema, on the Bend side.
+//
+// A project writes its schema once, with `s` (src/index.ts), and this prints
+// the same schema as Bend defs, so a Bend core checks the host's values against
+// the one definition. Nothing is written twice, and nothing can drift: the
+// generated file is output, not a second source.
+//
+// What is printed is `Schema.node` — the core's own Schema value, which `toNode`
+// builds and `wf` accepts, so an ill-formed schema throws before anything is
+// written. This file interprets nothing; it writes that value out in Bend's
+// syntax. A constructor it has no case for throws here, and a case it prints
+// wrongly is a Bend compile error. Neither can be a silent difference.
+//
+// The constructor names and their field order are core/core.bend's own
+// (`type Schema is Data:`), which is why this file goes with bend-schema rather
+// than in a package of its own: a new constructor touches both.
+
+import type { BendList, Schema as Node } from "../dist-core/core.mjs";
+import type { Schema } from "./index";
+
+const q = (s: string) => JSON.stringify(s);
+const n = (x: bigint | number) => `${x}n`;
+const ctor = (name: string, args: string[]) =>
+  args.length ? `S.${name}{${args.join(", ")}}` : `S.${name}{}`;
+
+// A `List<&2, String>` as Bend source: "a" <> "b" <> Nil{}.
+function strList(l: BendList<string>): string {
+  const out: string[] = [];
+  let cur: BendList<string> = l;
+  while (cur.$ === "Con") {
+    out.push(q(cur.head));
+    cur = cur.tail;
+  }
+  return out.length ? out.join(" <> ") + " <> Nil{}" : "Nil{}";
+}
+
+/** One schema as a Bend expression, e.g. `S.SNatIn{1n, 64n}`. */
+export function printNode(x: Node): string {
+  switch (x.$) {
+    case "SNat":
+    case "SStr":
+    case "SBool":
+    case "STrue":
+    case "SEnd":
+    case "STEnd":
+    case "SVEnd":
+      return ctor(x.$, []);
+    case "SNatIn":
+      return ctor("SNatIn", [n(x.lo as bigint), n(x.hi as bigint)]);
+    case "SStrLen":
+      return ctor("SStrLen", [n(x.lo as bigint), n(x.hi as bigint), printNode(x.s as Node)]);
+    case "SOpt":
+      return ctor("SOpt", [printNode(x.inner as Node)]);
+    case "SOptional":
+      return ctor("SOptional", [printNode(x.inner as Node)]);
+    case "SList":
+      return ctor("SList", [printNode(x.elem as Node)]);
+    case "SListLen":
+      return ctor("SListLen", [n(x.lo as bigint), n(x.hi as bigint), printNode(x.s as Node)]);
+    case "SStrict":
+      return ctor("SStrict", [printNode(x.s as Node)]);
+    case "SField":
+      return ctor("SField", [q(x.name as string), printNode(x.s as Node), printNode(x.rest as Node)]);
+    case "SEnum":
+      return ctor("SEnum", [strList(x.names as BendList<string>)]);
+    case "STuple":
+      return ctor("STuple", [printNode(x.s as Node), printNode(x.rest as Node)]);
+    case "SVariant":
+      return ctor("SVariant", [q(x.name as string), printNode(x.s as Node), printNode(x.rest as Node)]);
+    case "STagged":
+      return ctor("STagged", [q(x.key as string), q(x.name as string), printNode(x.s as Node), printNode(x.rest as Node)]);
+    case "STagEnd":
+      return ctor("STagEnd", [q(x.key as string)]);
+    default:
+      throw new Error(`gen: no Bend form for ${x.$}`);
+  }
+}
+
+/** A whole Bend file: one `def <key>_schema() -> S.Schema:` per key. */
+export function emit(
+  schemas: Record<string, Schema<unknown>>,
+  opts: { libPath: string; from: string },
+): string {
+  const defs: string[] = [];
+  for (const [name, s] of Object.entries(schemas)) {
+    if (!/^[A-Za-z_]\w*$/.test(name)) throw new Error(`gen: "${name}" is not a Bend name`);
+    if (!s || typeof s.node !== "object") throw new Error(`gen: ${name} is not a Schema`);
+    defs.push(`def ${name}_schema() -> S.Schema:\n  ${printNode(s.node as Node)}\n`);
+  }
+  if (defs.length === 0) throw new Error("gen: nothing to print");
+  return (
+    `import Base\nimport ${opts.libPath} as S\n\n` +
+    `# Generated by bend-schema from ${opts.from}. Do not edit; regenerate.\n\n` +
+    defs.join("\n")
+  );
+}