bonsai-js 1.0.0 → 1.2.0

package/dist/environment.mjs

@@ -1,17 +1,15 @@
 import { BonsaiCheckError, BonsaiError, BonsaiLimitError, BonsaiRuntimeError, locate } from "./errors.mjs";
 import { isName } from "./syntax/lexer.mjs";
-import { errorText, isMap } from "./runtime/values.mjs";
-import { warmZone } from "./runtime/time.mjs";
-import { formatType, isNullable } from "./types.mjs";
-import { assertHostSpec, assertType, conforms, describeMismatch, isRecord, overload } from "./functions/define.mjs";
-import { BUILTINS, zoneParameter } from "./functions/builtins.mjs";
-import { isStackOverflow, tooDeep } from "./runtime/overflow.mjs";
+import { isExact, isNullable, typeData } from "./types.mjs";
+import { assertHostSpec, assertType, builtinsOption, isRecord, overload } from "./functions/define.mjs";
+import { BUILTINS } from "./functions/builtins.mjs";
 import { DEFAULT_PARSE_LIMITS, parse } from "./syntax/parser.mjs";
 import { analyze } from "./check/checker.mjs";
-import { escaping, isOwn, raised } from "./runtime/attribution.mjs";
-import { compileProgram } from "./compile/compiler.mjs";
-import { DEFAULT_RUNTIME_LIMITS, MAX_VALUE_DEPTH_LIMIT, State } from "./runtime/state.mjs";
-import { recordDeclared } from "./declared.mjs";
+import { raised } from "./runtime/attribution.mjs";
+import { descriptionOf } from "./functions/descriptions.mjs";
+import { DEFAULT_RUNTIME_LIMITS, MAX_VALUE_DEPTH_LIMIT } from "./runtime/state.mjs";
+import { recordCompiled, recordDeclared } from "./declared.mjs";
+import { assertKeys, numberOption, programRunner, timeoutOption, warmZones } from "./program.mjs";
 //#region src/environment.ts
 /**
 * Declares a host function.
@@ -107,24 +105,6 @@ function mergeVariables(base, options) {
 	for (const [k, v] of Object.entries(options.variables ?? {})) add(k, v, "the variables option");
 	return out === void 0 ? void 0 : Object.freeze(out);
 }
-/** A number option: TypeError when it is not a number, RangeError when out of range. */
-function numberOption(name, value, fallback, minimum) {
-	if (value === void 0) return fallback;
-	if (typeof value !== "number") throw new TypeError(`${name} must be a number`);
-	if (!Number.isInteger(value) || value < minimum) throw new RangeError(minimum === 0 ? `${name} must be a non-negative integer (0 disables it)` : `${name} must be a positive integer`);
-	return value;
-}
-/**
-* A timeout in milliseconds: 0 turns it off; any other non-negative number,
-* fractions included, is a limit, so a budget computed down to its last
-* fraction of a millisecond stays a limit rather than becoming 0.
-*/
-function timeoutOption(name, value, fallback) {
-	if (value === void 0) return fallback;
-	if (typeof value !== "number") throw new TypeError(`${name} must be a number`);
-	if (!Number.isFinite(value) || value < 0) throw new RangeError(`${name} must be a non-negative number of milliseconds (0 disables it)`);
-	return value;
-}
 const OPTION_KEYS = /* @__PURE__ */ new Set([
 	"variables",
 	"strict",
@@ -133,7 +113,8 @@ const OPTION_KEYS = /* @__PURE__ */ new Set([
 	"limits",
 	"cacheSize",
 	"clock",
-	"validateContext"
+	"validateContext",
+	"builtins"
 ]);
 const LIMIT_KEYS = /* @__PURE__ */ new Set([
 	...Object.keys(DEFAULT_PARSE_LIMITS),
@@ -145,10 +126,6 @@ const LIBRARY_KEYS = /* @__PURE__ */ new Set([
 	"functions",
 	"variables"
 ]);
-function assertKeys(value, allowed, what) {
-	if (!isRecord(value)) throw new TypeError(`${what} must be an object`);
-	for (const key of Object.keys(value)) if (!allowed.has(key)) throw new TypeError(`Unknown ${what.toLowerCase()} key "${key}" (expected one of: ${[...allowed].join(", ")})`);
-}
 /** Environment options come from configuration: mistakes there are programming errors. */
 function assertOptions(options) {
 	assertKeys(options, OPTION_KEYS, "Options");
@@ -190,7 +167,11 @@ const DEPTH_CAPS = {
 	maxDepth: 256,
 	maxValueDepth: MAX_VALUE_DEPTH_LIMIT
 };
-function settingsFrom(base, options) {
+/**
+* Settings from options, over a base (extend) or, for a new environment or
+* runtime, over the entry point's built-ins.
+*/
+function settingsFrom(base, options, builtins = /* @__PURE__ */ new Map()) {
 	assertOptions(options);
 	const limits = options.limits ?? {};
 	const variables = mergeVariables(base?.variables, options);
@@ -200,6 +181,7 @@ function settingsFrom(base, options) {
 		strictOption,
 		strict: strictOption ?? variables !== void 0,
 		host: mergeFunctions(base?.host ?? /* @__PURE__ */ new Map(), options),
+		builtins: builtinsOption(options.builtins, base?.builtins ?? (options.builtins === void 0 ? builtins : /* @__PURE__ */ new Map())),
 		parseLimits: pickLimits(DEFAULT_PARSE_LIMITS, base?.parseLimits ?? DEFAULT_PARSE_LIMITS, limits),
 		runtimeLimits: pickLimits(DEFAULT_RUNTIME_LIMITS, base?.runtimeLimits ?? DEFAULT_RUNTIME_LIMITS, limits),
 		timeout: timeoutOption("Limit \"timeout\"", limits.timeout, base?.timeout ?? 0),
@@ -253,7 +235,6 @@ var ProgramCache = class {
 		}
 	}
 };
-const EMPTY_CONTEXT = Object.freeze({});
 const NO_DIAGNOSTICS = Object.freeze([]);
 /**
 * What check() found. `ok`, `type`, and `diagnostics` are the JSON form; the
@@ -292,66 +273,6 @@ var CheckSuccess = class extends CheckFailure {
 		return this.#program();
 	}
 };
-const EVALUATE_OPTION_KEYS = /* @__PURE__ */ new Set([
-	"timeout",
-	"maxSteps",
-	"signal",
-	"now",
-	"validateContext"
-]);
-/** Whether a value is a valid Date (an object that only inherits from Date.prototype is not). */
-function isValidDate(value) {
-	try {
-		return value instanceof Date && !Number.isNaN(Date.prototype.getTime.call(value));
-	} catch {
-		return false;
-	}
-}
-/** Whether a value has an AbortSignal's members; a signal whose getters throw does not. */
-function looksLikeSignal(signal) {
-	try {
-		const s = signal;
-		return typeof s.aborted === "boolean" && typeof s.addEventListener === "function" && typeof s.removeEventListener === "function";
-	} catch {
-		return false;
-	}
-}
-/** Validates per-evaluation options the way `limits` are validated; nothing fails open. */
-function evaluationLimits(options, settings) {
-	if (options === void 0) return {
-		maxSteps: settings.runtimeLimits.maxSteps,
-		timeout: settings.timeout,
-		signal: void 0,
-		now: void 0,
-		validateContext: void 0
-	};
-	let o;
-	try {
-		assertKeys(options, EVALUATE_OPTION_KEYS, "Evaluate option");
-		const read = options;
-		o = {
-			maxSteps: read.maxSteps,
-			timeout: read.timeout,
-			signal: read.signal,
-			now: read.now,
-			validateContext: read.validateContext
-		};
-	} catch (error) {
-		if (error instanceof TypeError || error instanceof RangeError) throw error;
-		throw new TypeError(`Evaluate options could not be read: ${errorText(error)}`, { cause: error });
-	}
-	const signal = o.signal;
-	if (signal !== void 0 && (typeof signal !== "object" || signal === null || !looksLikeSignal(signal))) throw new TypeError("signal must be an AbortSignal");
-	if (o.now !== void 0 && !isValidDate(o.now)) throw new TypeError("now must be a valid Date");
-	if (o.validateContext !== void 0 && typeof o.validateContext !== "boolean") throw new TypeError("validateContext must be a boolean");
-	return {
-		maxSteps: numberOption("maxSteps", o.maxSteps, settings.runtimeLimits.maxSteps, 0),
-		timeout: timeoutOption("timeout", o.timeout, settings.timeout),
-		signal,
-		now: o.now,
-		validateContext: o.validateContext
-	};
-}
 /** Freezes a syntax tree (or any tree of plain objects and arrays) in place, without recursion. */
 function deepFreeze(root) {
 	const seen = /* @__PURE__ */ new Set();
@@ -365,87 +286,6 @@ function deepFreeze(root) {
 	}
 	return root;
 }
-function validationBudget(source, limits) {
-	return {
-		maxDepth: limits.maxDepth,
-		remaining: limits.maxSteps > 0 ? limits.maxSteps : Number.POSITIVE_INFINITY,
-		deadline: limits.timeout > 0 ? performance.now() + limits.timeout : 0,
-		onExhausted: (reason) => {
-			if (reason === "depth") throw raised(new BonsaiLimitError("VALUE_DEPTH_LIMIT", `Context nests deeper than ${limits.maxDepth}`, { source }));
-			if (reason === "time") throw raised(new BonsaiLimitError("TIMEOUT", "Context validation timed out", { source }));
-			throw raised(new BonsaiLimitError("STEP_LIMIT", "Context validation exceeded the step limit", { source }));
-		}
-	};
-}
-function invalidContext(problem, source) {
-	if (problem !== void 0) throw raised(new BonsaiRuntimeError("INVALID_CONTEXT", `Invalid context: ${problem}`, { source }));
-}
-function validateContext(ctx, variables, source, limits) {
-	const budget = validationBudget(source, limits);
-	for (const [name, type] of Object.entries(variables)) {
-		const value = Object.hasOwn(ctx, name) ? ctx[name] : void 0;
-		invalidContext(describeMismatch(value, type, name, budget), source);
-	}
-}
-/**
-* Why the value read along `segments` (from index `at`) does not conform, or
-* undefined. Each step is judged by its own declared type: an absent or null
-* value is fine only where that type is nullable; a declared field is followed
-* (a missing required one fails); an undeclared key of an object (objects are
-* open) or an absent record entry ends the check; past a type that is not a
-* map, and at the end of the path, the value is checked whole, as a context is.
-* Fields the path does not name are not checked.
-*/
-function describeAlong(value, type, segments, at, path, budget) {
-	if (at === segments.length) return describeMismatch(value, type, path, budget);
-	if (--budget.remaining < 0) budget.onExhausted("steps");
-	if (type.kind === "union") {
-		let first;
-		for (const member of type.types) {
-			const problem = describeAlong(value, member, segments, at, path, budget);
-			if (problem === void 0) return void 0;
-			first ??= problem;
-		}
-		return first;
-	}
-	const actual = value === void 0 ? null : value;
-	if (type.kind !== "map" || !isMap(actual)) return describeMismatch(value, type, path, budget);
-	const key = segments[at];
-	const field = Object.hasOwn(actual, key) ? actual[key] : void 0;
-	if (Object.hasOwn(type.fields, key)) return describeAlong(field, type.fields[key], segments, at + 1, `${path}.${key}`, budget);
-	if (type.rest === void 0 || field === void 0) return void 0;
-	return describeAlong(field, type.rest, segments, at + 1, `${path}.${key}`, budget);
-}
-/**
-* Validates the values a residual reads: each path in `dependsOn`, step by
-* step against the types declared along it (see describeAlong), so a context
-* holding exactly those paths passes and invalid data on them fails as it
-* would for the program.
-*/
-function validatePaths(ctx, variables, paths, source, limits) {
-	const budget = validationBudget(source, limits);
-	for (const path of paths) {
-		const segments = path.split(".");
-		const name = segments[0];
-		if (!Object.hasOwn(variables, name)) continue;
-		invalidContext(describeAlong(Object.hasOwn(ctx, name) ? ctx[name] : void 0, variables[name], segments, 1, name, budget), source);
-	}
-}
-/**
-* Reading host data (a getter, a Proxy trap, a `then` hook) can throw. Such a
-* failure is a HOST_ERROR, never a raw JavaScript error. Only the errors this
-* evaluation raised pass through: any other Bonsai error (from another
-* evaluation, from parsing, checking, or translating, or built by the host)
-* that host data threw is the host data's failure too.
-*/
-function hostDataFailure(error, source) {
-	if (isOwn(error)) return error;
-	if (isStackOverflow(error)) return raised(tooDeep(source, error));
-	return raised(new BonsaiRuntimeError("HOST_ERROR", `Reading host data failed: ${errorText(error)}`, {
-		source,
-		cause: error
-	}));
-}
 const systemClock = () => /* @__PURE__ */ new Date();
 /** A host clock whose results are checked: now() must be a valid timestamp. */
 function checkedClock(clock) {
@@ -460,62 +300,50 @@ function checkedClock(clock) {
 		return value;
 	};
 }
-/** The most zones one program warms when it is compiled. */
-const WARMED_ZONES = 16;
-/**
-* Loads the time zone data a program's calls need, so its first evaluation
-* does not pay for it inside its deadline. Only built-in functions that take a
-* zone count: a zone written as text is loaded itself, and any other zone
-* argument loads the data every zone shares. Each zone is warmed once, and at
-* most WARMED_ZONES of them, so a source full of zone names compiles quickly.
-*/
-function warmZones(analysis) {
+/** Whether a type has an exact map type anywhere in it. */
+function holdsExact(type) {
+	const stack = [type];
 	const seen = /* @__PURE__ */ new Set();
-	for (const [call, plan] of analysis.calls) {
-		const index = zoneParameter(plan.def);
-		const arg = index === void 0 ? void 0 : call.args[index];
-		if (arg === void 0) continue;
-		const zone = arg.type === "Literal" ? arg.value : void 0;
-		if (zone !== void 0 && typeof zone !== "string" || seen.has(zone)) continue;
-		seen.add(zone);
-		warmZone(zone);
-		if (seen.size >= WARMED_ZONES) return;
+	while (stack.length > 0) {
+		const next = stack.pop();
+		if (seen.has(next)) continue;
+		seen.add(next);
+		if (isExact(next)) return true;
+		if (next.kind === "list") stack.push(next.element);
+		else if (next.kind === "union") stack.push(...next.types);
+		else if (next.kind === "map") {
+			stack.push(...Object.values(next.fields));
+			if (next.rest !== void 0) stack.push(next.rest);
+		}
 	}
+	return false;
 }
-/** Reads compile() and check() options: only `expect`, which must be a type built with t. */
-function compileExpect(options) {
+/** Reads compile(), check(), and the runtime's load() options: only `expect`, which must be a type built with t. Returns a frozen copy of it. */
+function expectOption(options, what) {
 	if (options === void 0) return void 0;
-	if (typeof options !== "object" || options === null || Array.isArray(options)) throw new TypeError("Compile options must be an object");
+	if (typeof options !== "object" || options === null || Array.isArray(options)) throw new TypeError(`${what} options must be an object`);
 	let expect;
 	try {
-		for (const key of Object.keys(options)) if (key !== "expect") throw new TypeError(`Unknown compile option key "${key}" (expected one of: expect)`);
+		for (const key of Object.keys(options)) if (key !== "expect") throw new TypeError(`Unknown ${what.toLowerCase()} option key "${key}" (expected one of: expect)`);
 		expect = options.expect;
 	} catch (error) {
 		if (error instanceof TypeError) throw error;
-		throw new TypeError("Compile options could not be read", { cause: error });
+		throw new TypeError(`${what} options could not be read`, { cause: error });
 	}
-	if (expect !== void 0) assertType(expect, "Compile option \"expect\"");
-	return expect;
-}
-function contextOf(value) {
-	if (value === void 0 || value === null) return EMPTY_CONTEXT;
-	let map;
-	try {
-		map = typeof value === "object" && isMap(value);
-	} catch (error) {
-		throw new BonsaiRuntimeError("HOST_ERROR", "Reading the evaluation context failed", { cause: error });
-	}
-	if (!map) throw new TypeError("The evaluation context must be a plain object or class instance");
-	return value;
+	if (expect === void 0) return void 0;
+	assertType(expect, `${what} option "expect"`);
+	const own = typeData(expect);
+	if (own !== expect) assertType(own, `${what} option "expect"`);
+	return own;
 }
 function createEnvironment(settings) {
 	const checkEnv = {
 		variables: settings.variables,
 		strict: settings.strict,
-		lookup: (name) => settings.host.get(name) ?? BUILTINS.get(name),
+		lookup: (name) => settings.host.get(name) ?? settings.builtins.get(name),
 		*functionNames() {
 			yield* settings.host.keys();
-			for (const name of BUILTINS.keys()) if (!settings.host.has(name)) yield name;
+			for (const name of settings.builtins.keys()) if (!settings.host.has(name)) yield name;
 		}
 	};
 	const cache = new ProgramCache(settings.cacheSize);
@@ -539,101 +367,14 @@ function createEnvironment(settings) {
 	function makeProgram(source, analysis, expect, constants, residualOf) {
 		if (residualOf === void 0) warmZones(analysis);
 		const guard = expect !== void 0 && analysis.checkResult ? expect : void 0;
-		const checked = (result, state) => {
-			if (guard !== void 0 && !conforms(result, guard, state)) throw raised(new BonsaiRuntimeError("TYPE_ERROR", `The result does not match the expected type ${formatType(guard)}`, { source }));
-		};
-		const defaultLimits = evaluationLimits(void 0, settings);
-		const limitsOf = (options) => options === void 0 ? defaultLimits : evaluationLimits(options, settings);
-		let syncCode;
-		let asyncCode;
-		let pooled;
-		let pooledInUse = false;
-		const compileOptions = constants === void 0 ? {} : {
+		const { prepare, checked, settle, runSync, runAsync, compileOptions } = programRunner({
+			source,
+			analysis,
+			guard,
+			settings,
 			constants,
-			shapes: residualOf?.shapes
-		};
-		const syncProgram = () => syncCode ??= compileProgram(analysis, "sync", compileOptions);
-		const asyncProgram = () => asyncCode ??= analysis.async ? compileProgram(analysis, "async", compileOptions) : syncProgram();
-		function prepare(state, ctx, limits, locals) {
-			state.reset(ctx, source, locals, limits.maxSteps, limits.timeout, limits.signal);
-			if (limits.now !== void 0) state.nowValue = limits.now;
-			const residual = residualOf;
-			if (residual !== void 0 && residual.readsContext) {
-				const roots = residual.knownRoots;
-				state.charge(roots.length);
-				const declared = settings.strict ? settings.variables : void 0;
-				const missing = roots.find((name) => {
-					if (declared !== void 0 && !Object.hasOwn(declared, name)) return false;
-					const descriptor = Object.getOwnPropertyDescriptor(ctx, name);
-					return descriptor === void 0 || "value" in descriptor && descriptor.value === void 0;
-				});
-				if (missing !== void 0) throw raised(new BonsaiRuntimeError("INVALID_CONTEXT", `Invalid context: ${missing} is missing; this residual calls a call: true host function, so pass the full context, as for the program`, { source }));
-			}
-			const validation = limits.validateContext ?? settings.validateContext ? settings.variables : void 0;
-			if (validation !== void 0) {
-				const validationLimits = {
-					maxDepth: settings.runtimeLimits.maxValueDepth,
-					maxSteps: limits.maxSteps,
-					timeout: limits.timeout
-				};
-				if (residual === void 0 || residual.readsContext) validateContext(ctx, validation, source, validationLimits);
-				else validatePaths(ctx, validation, residual.dependsOn, source, validationLimits);
-			}
-		}
-		function runSync(context, options) {
-			if (analysis.async) throw escaping(new BonsaiRuntimeError("ASYNC_IN_SYNC", "This expression calls an async function; use evaluate() instead of evaluateSync()", { source }));
-			const code = syncProgram();
-			const limits = limitsOf(options);
-			const ctx = contextOf(context);
-			let state;
-			const reuse = !pooledInUse;
-			if (reuse) {
-				pooled ??= new State(settings.runtimeLimits, settings.clock);
-				state = pooled;
-				pooledInUse = true;
-			} else state = new State(settings.runtimeLimits, settings.clock);
-			try {
-				prepare(state, ctx, limits, code.localCount);
-				const result = code.run(state);
-				checked(result, state);
-				state.checkTime();
-				return result;
-			} catch (error) {
-				throw escaping(hostDataFailure(error, source));
-			} finally {
-				state.release();
-				if (reuse) pooledInUse = false;
-			}
-		}
-		async function runAsync(context, options) {
-			if (!analysis.async) {
-				const result = runSync(context, options);
-				try {
-					return settle(result);
-				} catch (error) {
-					throw escaping(hostDataFailure(error, source));
-				}
-			}
-			const code = asyncProgram();
-			const limits = limitsOf(options);
-			const ctx = contextOf(context);
-			const state = new State(settings.runtimeLimits, settings.clock);
-			try {
-				prepare(state, ctx, limits, code.localCount);
-				const result = (await code.run(state)).v;
-				checked(result, state);
-				state.checkTime();
-				return settle(result);
-			} catch (error) {
-				throw escaping(hostDataFailure(error, source));
-			} finally {
-				state.release();
-			}
-		}
-		function settle(result) {
-			if (result !== null && (typeof result === "object" || typeof result === "function") && typeof result.then === "function") throw raised(new BonsaiRuntimeError("TYPE_ERROR", "evaluate() cannot return a promise-like value; use evaluateSync()", { source }));
-			return result;
-		}
+			residualOf
+		});
 		const features = settings.features?.program({
 			source,
 			analysis,
@@ -674,6 +415,13 @@ function createEnvironment(settings) {
 			evaluateSync: (...args) => runSync(args[0], args[1])
 		});
 		recordDeclared(program, settings.variables);
+		recordCompiled(program, {
+			source,
+			analysis,
+			expect,
+			lookup: checkEnv.lookup,
+			variables: settings.variables
+		});
 		return program;
 	}
 	function compile(source, expect) {
@@ -684,10 +432,12 @@ function createEnvironment(settings) {
 	}
 	/**
 	* compile(), through the program cache: programs are immutable, so the same
-	* source with an equal expected type (types are plain JSON data) shares one.
+	* source with an equal expected type shares one. `expect` is expectOption's
+	* plain copy, so its JSON is the type the program is checked against.
 	*/
 	function cachedCompile(source, expect) {
 		if (typeof source !== "string") throw new TypeError("An expression must be a string");
+		if (expect !== void 0 && holdsExact(expect)) return compile(source, expect);
 		const expectKey = expect === void 0 ? void 0 : JSON.stringify(expect);
 		const key = expectKey === void 0 ? source : `${source}\u0000${expectKey}`;
 		const entry = cache.get(key);
@@ -706,7 +456,7 @@ function createEnvironment(settings) {
 	function info(def) {
 		return {
 			name: def.name,
-			description: def.description,
+			description: descriptionOf(def),
 			host: def.host === true,
 			async: def.async === true,
 			call: def.call === true,
@@ -724,7 +474,7 @@ function createEnvironment(settings) {
 		strict: settings.strict,
 		parse: parseSource,
 		check(source, options) {
-			const expect = compileExpect(options);
+			const expect = expectOption(options, "Compile");
 			let analysis;
 			try {
 				analysis = analyzeSource(source, expect);
@@ -745,7 +495,7 @@ function createEnvironment(settings) {
 			let program;
 			return Object.freeze(new CheckSuccess(type, diagnostics, analysis, () => program ??= makeProgram(source, analysis, expect)));
 		},
-		compile: (source, options) => cachedCompile(source, compileExpect(options)),
+		compile: (source, options) => cachedCompile(source, expectOption(options, "Compile")),
 		...settings.features === void 0 ? {} : { partial: (source, known, options) => cached(source).partial(known, options) },
 		evaluate(source, ...args) {
 			try {
@@ -789,11 +539,11 @@ function createEnvironment(settings) {
 */
 function environmentWith(features, options) {
 	return createEnvironment({
-		...settingsFrom(void 0, options),
+		...settingsFrom(void 0, options, BUILTINS),
 		features
 	});
 }
 //#endregion
-export { EVALUATE_OPTION_KEYS, contextOf, environmentWith, evaluationLimits, fn, hostDataFailure, internalsOf, invalidContext, isValidDate, validationBudget, withContext };
+export { ProgramCache, environmentWith, expectOption, fn, internalsOf, settingsFrom, withContext };
 
 //# sourceMappingURL=environment.mjs.map