bonsai-js 0.2.1 → 0.4.0

package/dist/index.mjs

@@ -1,477 +1,5 @@
-import { a as attachLocation, c as offsetToPosition, i as ExpressionError, l as suggest, n as BonsaiSecurityError, o as formatBonsaiError, r as BonsaiTypeError, s as formatError, t as BonsaiReferenceError } from "./errors-t5i9AEaf.mjs";
-//#region src/lexer.ts
-const KEYWORDS = new Map([
-	["true", {
-		type: "Boolean",
-		value: "true"
-	}],
-	["false", {
-		type: "Boolean",
-		value: "false"
-	}],
-	["null", {
-		type: "Null",
-		value: "null"
-	}],
-	["undefined", {
-		type: "Undefined",
-		value: "undefined"
-	}],
-	["in", {
-		type: "Operator",
-		value: "in"
-	}],
-	["not", {
-		type: "Operator",
-		value: "not"
-	}]
-]);
-function isDigit(ch) {
-	return ch >= "0" && ch <= "9";
-}
-function isAlpha(ch) {
-	return ch >= "a" && ch <= "z" || ch >= "A" && ch <= "Z" || ch === "_" || ch === "$";
-}
-function isAlphaNumeric(ch) {
-	return isAlpha(ch) || isDigit(ch);
-}
-function isHexDigit(ch) {
-	return isDigit(ch) || ch >= "a" && ch <= "f" || ch >= "A" && ch <= "F";
-}
-function tokenize(source) {
-	const tokens = [];
-	let i = 0;
-	while (i < source.length) {
-		const ch = source[i];
-		if (ch === " " || ch === "	" || ch === "\n" || ch === "\r") {
-			i++;
-			continue;
-		}
-		if (isDigit(ch)) {
-			const start = i;
-			if (ch === "0" && i + 1 < source.length && (source[i + 1] === "x" || source[i + 1] === "X")) {
-				i += 2;
-				while (i < source.length && (isHexDigit(source[i]) || source[i] === "_")) i++;
-				tokens.push({
-					type: "Number",
-					value: source.slice(start, i),
-					start,
-					end: i
-				});
-				continue;
-			}
-			if (ch === "0" && i + 1 < source.length && (source[i + 1] === "b" || source[i + 1] === "B")) {
-				i += 2;
-				while (i < source.length && (source[i] === "0" || source[i] === "1" || source[i] === "_")) i++;
-				tokens.push({
-					type: "Number",
-					value: source.slice(start, i),
-					start,
-					end: i
-				});
-				continue;
-			}
-			if (ch === "0" && i + 1 < source.length && (source[i + 1] === "o" || source[i + 1] === "O")) {
-				i += 2;
-				while (i < source.length && (source[i] >= "0" && source[i] <= "7" || source[i] === "_")) i++;
-				tokens.push({
-					type: "Number",
-					value: source.slice(start, i),
-					start,
-					end: i
-				});
-				continue;
-			}
-			while (i < source.length && (isDigit(source[i]) || source[i] === "_")) i++;
-			if (i < source.length && source[i] === "." && i + 1 < source.length && isDigit(source[i + 1])) {
-				i++;
-				while (i < source.length && (isDigit(source[i]) || source[i] === "_")) i++;
-			}
-			if (i < source.length && (source[i] === "e" || source[i] === "E")) {
-				i++;
-				if (i < source.length && (source[i] === "+" || source[i] === "-")) i++;
-				while (i < source.length && (isDigit(source[i]) || source[i] === "_")) i++;
-			}
-			tokens.push({
-				type: "Number",
-				value: source.slice(start, i),
-				start,
-				end: i
-			});
-			continue;
-		}
-		if (ch === "\"" || ch === "'") {
-			const quote = ch;
-			const start = i;
-			i++;
-			let value = "";
-			while (i < source.length && source[i] !== quote) {
-				if (source[i] === "\\") {
-					i++;
-					const escaped = source[i];
-					switch (escaped) {
-						case "n":
-							value += "\n";
-							break;
-						case "t":
-							value += "	";
-							break;
-						case "r":
-							value += "\r";
-							break;
-						case "\\":
-							value += "\\";
-							break;
-						case "0":
-							value += "\0";
-							break;
-						case "x": {
-							const hex = source.slice(i + 1, i + 3);
-							if (hex.length < 2 || !isHexDigit(hex[0]) || !isHexDigit(hex[1])) throw new ExpressionError("Invalid \\x escape: expected 2 hex digits", {
-								source,
-								start,
-								end: i + 3
-							});
-							value += String.fromCharCode(parseInt(hex, 16));
-							i += 2;
-							break;
-						}
-						case "u":
-							if (i + 1 < source.length && source[i + 1] === "{") {
-								const closeBrace = source.indexOf("}", i + 2);
-								if (closeBrace === -1) throw new ExpressionError("Invalid \\u{} escape: missing closing brace", {
-									source,
-									start,
-									end: source.length
-								});
-								const hex = source.slice(i + 2, closeBrace);
-								if (hex.length === 0) throw new ExpressionError("Invalid \\u{} escape: empty code point", {
-									source,
-									start,
-									end: closeBrace + 1
-								});
-								for (const c of hex) if (!isHexDigit(c)) throw new ExpressionError(`Invalid \\u{} escape: non-hex digit "${c}"`, {
-									source,
-									start,
-									end: closeBrace + 1
-								});
-								const MAX_UNICODE_CODE_POINT = 1114111;
-								const codePoint = parseInt(hex, 16);
-								if (codePoint > MAX_UNICODE_CODE_POINT) throw new ExpressionError("Invalid \\u{} escape: code point out of range", {
-									source,
-									start,
-									end: closeBrace + 1
-								});
-								value += String.fromCodePoint(codePoint);
-								i = closeBrace;
-							} else {
-								const UNICODE_ESCAPE_LEN = 4;
-								const hex = source.slice(i + 1, i + 1 + UNICODE_ESCAPE_LEN);
-								if (hex.length < UNICODE_ESCAPE_LEN) throw new ExpressionError("Invalid \\u escape: expected 4 hex digits", {
-									source,
-									start,
-									end: i + 1 + UNICODE_ESCAPE_LEN
-								});
-								for (const c of hex) if (!isHexDigit(c)) throw new ExpressionError("Invalid \\u escape: expected 4 hex digits", {
-									source,
-									start,
-									end: i + 1 + UNICODE_ESCAPE_LEN
-								});
-								value += String.fromCharCode(parseInt(hex, 16));
-								i += UNICODE_ESCAPE_LEN;
-							}
-							break;
-						default:
-							value += escaped;
-							break;
-					}
-				} else value += source[i];
-				i++;
-			}
-			if (i >= source.length) throw new ExpressionError("Unterminated string", {
-				source,
-				start,
-				end: i
-			});
-			i++;
-			tokens.push({
-				type: "String",
-				value,
-				start,
-				end: i
-			});
-			continue;
-		}
-		if (ch === "`") {
-			const start = i;
-			i++;
-			let raw = "`";
-			while (i < source.length && source[i] !== "`") if (source[i] === "$" && i + 1 < source.length && source[i + 1] === "{") {
-				raw += "${";
-				i += 2;
-				let depth = 1;
-				while (i < source.length && depth > 0) {
-					const ic = source[i];
-					if (ic === "\"" || ic === "'") {
-						raw += ic;
-						i++;
-						while (i < source.length && source[i] !== ic) {
-							if (source[i] === "\\" && i + 1 < source.length) {
-								raw += source[i] + source[i + 1];
-								i += 2;
-								continue;
-							}
-							raw += source[i];
-							i++;
-						}
-						if (i < source.length) {
-							raw += source[i];
-							i++;
-						}
-						continue;
-					}
-					if (ic === "{") depth++;
-					else if (ic === "}") depth--;
-					if (depth > 0) raw += ic;
-					i++;
-				}
-				raw += "}";
-			} else {
-				raw += source[i];
-				i++;
-			}
-			if (i >= source.length) throw new ExpressionError("Unterminated template literal", {
-				source,
-				start,
-				end: i
-			});
-			raw += "`";
-			i++;
-			tokens.push({
-				type: "TemplateLiteral",
-				value: raw,
-				start,
-				end: i
-			});
-			continue;
-		}
-		if (isAlpha(ch)) {
-			const start = i;
-			while (i < source.length && isAlphaNumeric(source[i])) i++;
-			const value = source.slice(start, i);
-			const kw = KEYWORDS.get(value);
-			if (kw) tokens.push({
-				type: kw.type,
-				value: kw.value,
-				start,
-				end: i
-			});
-			else tokens.push({
-				type: "Identifier",
-				value,
-				start,
-				end: i
-			});
-			continue;
-		}
-		const start = i;
-		if (ch === "." && i + 2 < source.length && source[i + 1] === "." && source[i + 2] === ".") {
-			tokens.push({
-				type: "Spread",
-				value: "...",
-				start,
-				end: i + 3
-			});
-			i += 3;
-			continue;
-		}
-		if (ch === ".") {
-			tokens.push({
-				type: "Punctuation",
-				value: ".",
-				start,
-				end: i + 1
-			});
-			i++;
-			continue;
-		}
-		if (ch === "|") {
-			if (i + 1 < source.length && source[i + 1] === ">") {
-				tokens.push({
-					type: "Pipe",
-					value: "|>",
-					start,
-					end: i + 2
-				});
-				i += 2;
-				continue;
-			}
-			if (i + 1 < source.length && source[i + 1] === "|") {
-				tokens.push({
-					type: "Operator",
-					value: "||",
-					start,
-					end: i + 2
-				});
-				i += 2;
-				continue;
-			}
-		}
-		if (ch === "&" && i + 1 < source.length && source[i + 1] === "&") {
-			tokens.push({
-				type: "Operator",
-				value: "&&",
-				start,
-				end: i + 2
-			});
-			i += 2;
-			continue;
-		}
-		if (ch === "=" && i + 1 < source.length && source[i + 1] === "=") {
-			tokens.push({
-				type: "Operator",
-				value: "==",
-				start,
-				end: i + 2
-			});
-			i += 2;
-			continue;
-		}
-		if (ch === "!" && i + 1 < source.length && source[i + 1] === "=") {
-			tokens.push({
-				type: "Operator",
-				value: "!=",
-				start,
-				end: i + 2
-			});
-			i += 2;
-			continue;
-		}
-		if (ch === "!") {
-			tokens.push({
-				type: "Operator",
-				value: "!",
-				start,
-				end: i + 1
-			});
-			i++;
-			continue;
-		}
-		if (ch === "<") {
-			if (i + 1 < source.length && source[i + 1] === "=") {
-				tokens.push({
-					type: "Operator",
-					value: "<=",
-					start,
-					end: i + 2
-				});
-				i += 2;
-				continue;
-			}
-			tokens.push({
-				type: "Operator",
-				value: "<",
-				start,
-				end: i + 1
-			});
-			i++;
-			continue;
-		}
-		if (ch === ">") {
-			if (i + 1 < source.length && source[i + 1] === "=") {
-				tokens.push({
-					type: "Operator",
-					value: ">=",
-					start,
-					end: i + 2
-				});
-				i += 2;
-				continue;
-			}
-			tokens.push({
-				type: "Operator",
-				value: ">",
-				start,
-				end: i + 1
-			});
-			i++;
-			continue;
-		}
-		if (ch === "*" && i + 1 < source.length && source[i + 1] === "*") {
-			tokens.push({
-				type: "Operator",
-				value: "**",
-				start,
-				end: i + 2
-			});
-			i += 2;
-			continue;
-		}
-		if (ch === "?") {
-			if (i + 1 < source.length && source[i + 1] === ".") {
-				tokens.push({
-					type: "OptionalChain",
-					value: "?.",
-					start,
-					end: i + 2
-				});
-				i += 2;
-				continue;
-			}
-			if (i + 1 < source.length && source[i + 1] === "?") {
-				tokens.push({
-					type: "NullishCoalescing",
-					value: "??",
-					start,
-					end: i + 2
-				});
-				i += 2;
-				continue;
-			}
-			tokens.push({
-				type: "Punctuation",
-				value: "?",
-				start,
-				end: i + 1
-			});
-			i++;
-			continue;
-		}
-		if (ch === "+" || ch === "-" || ch === "*" || ch === "/" || ch === "%") {
-			tokens.push({
-				type: "Operator",
-				value: ch,
-				start,
-				end: i + 1
-			});
-			i++;
-			continue;
-		}
-		if ("()[]{},:".includes(ch)) {
-			tokens.push({
-				type: "Punctuation",
-				value: ch,
-				start,
-				end: i + 1
-			});
-			i++;
-			continue;
-		}
-		throw new ExpressionError(`Unexpected character "${ch}"`, {
-			source,
-			start,
-			end: i + 1
-		});
-	}
-	tokens.push({
-		type: "EOF",
-		value: "",
-		start: i,
-		end: i
-	});
-	return tokens;
-}
-//#endregion
+import { a as attachLocation, c as offsetToPosition, i as ExpressionError, l as suggest, n as BonsaiSecurityError, o as formatBonsaiError, r as BonsaiTypeError, s as formatError, t as BonsaiReferenceError } from "./errors-BONB6P_5.mjs";
+import { i as tokenize, n as ExecutionContext, r as SecurityPolicy } from "./execution-context-B-5hQ92X.mjs";
 //#region src/parser.ts
 const PIPE_PRECEDENCE = 5;
 const PRECEDENCE = {
@@ -731,7 +259,7 @@ function parse(source, _depth = 0) {
 		const tok = current();
 		if (tok.type === "Number") {
 			advance();
-			const raw = tok.value.replace(/_/g, "");
+			const raw = tok.value.replace(/_/gu, "");
 			return {
 				type: "NumberLiteral",
 				value: Number(raw),
@@ -1355,9 +883,16 @@ function resolveTransform(name, transforms) {
 	if (!Object.hasOwn(transforms, name)) throw new BonsaiReferenceError("transform", name, suggest(name, Object.keys(transforms)));
 	return transforms[name];
 }
-function resolveFunction(name, functions) {
-	if (!Object.hasOwn(functions, name)) throw new BonsaiReferenceError("function", name, suggest(name, Object.keys(functions)));
-	return functions[name];
+/**
+* Resolve a callable by name in the shared function namespace. Pure and context
+* functions occupy one registry keyed by name, so a single lookup returns the
+* tagged entry; the call site uses `kind` to decide how to invoke it (pure
+* functions take only call args; context functions receive the evaluation
+* context first, then call args).
+*/
+function resolveCallable(name, functions) {
+	if (Object.hasOwn(functions, name)) return functions[name];
+	throw new BonsaiReferenceError("function", name, suggest(name, Object.keys(functions)));
 }
 function getIdentifierName(node, message = "Expected identifier") {
 	if (node.type !== "Identifier") throw new Error(message);
@@ -1408,29 +943,34 @@ function rejectPromise(value, kind, name) {
 	if (value instanceof Promise) throw new BonsaiTypeError(name, `a synchronous ${kind} result — use evaluate() instead of evaluateSync() for async`, value);
 	return value;
 }
-function evaluate(node, context, transforms, functions, guard, source) {
+function evaluate(node, context, bindings, guard, source) {
 	return evalNode(node, {
 		ctx: context,
-		tr: transforms,
-		fn: functions,
+		tr: bindings.transforms,
+		fn: bindings.functions,
 		g: guard,
 		s: source
 	});
 }
 function evalNode(node, env) {
-	const { ctx, g, s } = env;
+	switch (node.type) {
+		case "NumberLiteral":
+		case "StringLiteral":
+		case "BooleanLiteral": return node.value;
+		case "NullLiteral": return null;
+		case "UndefinedLiteral": return;
+		case "Identifier":
+			env.g.checkNameAccess(node.name, "identifier");
+			return Object.hasOwn(env.ctx, node.name) ? env.ctx[node.name] : void 0;
+	}
+	return evalCompound(node, env);
+}
+function evalCompound(node, env) {
+	const { g, s } = env;
 	g.enterDepth();
 	g.step();
 	try {
 		switch (node.type) {
-			case "NumberLiteral":
-			case "StringLiteral":
-			case "BooleanLiteral": return node.value;
-			case "NullLiteral": return null;
-			case "UndefinedLiteral": return;
-			case "Identifier":
-				g.checkNameAccess(node.name, "identifier");
-				return Object.hasOwn(ctx, node.name) ? ctx[node.name] : void 0;
 			case "UnaryExpression": return applyUnaryOp(node.operator, evalNode(node.operand, env));
 			case "BinaryExpression": {
 				const op = node.operator;
@@ -1529,10 +1069,10 @@ function evalCallExpression(node, env) {
 		}
 	}
 	if (node.callee.type === "Identifier") try {
-		const func = resolveFunction(node.callee.name, fn);
+		const resolved = resolveCallable(node.callee.name, fn);
 		const args = [];
 		for (const arg of node.args) pushCallArgument(args, arg, env);
-		return rejectPromise(func(...args), "function", node.callee.name);
+		return rejectPromise(resolved.kind === "context" ? resolved.fn(env.ctx, ...args) : resolved.fn(...args), "function", node.callee.name);
 	} catch (e) {
 		if (s) attachLocation(e, s, node.start, node.end);
 		throw e;
@@ -1642,11 +1182,11 @@ function makeLambdaAccessor$1(property, guard) {
 }
 //#endregion
 //#region src/evaluator-async.ts
-async function evaluateAsync(node, context, transforms, functions, guard, source) {
+async function evaluateAsync(node, context, bindings, guard, source) {
 	const result = await evalNodeAsync(node, {
 		ctx: context,
-		tr: transforms,
-		fn: functions,
+		tr: bindings.transforms,
+		fn: bindings.functions,
 		g: guard,
 		s: source
 	});
@@ -1654,19 +1194,24 @@ async function evaluateAsync(node, context, transforms, functions, guard, source
 	return result;
 }
 async function evalNodeAsync(node, env) {
-	const { ctx, g, s } = env;
+	switch (node.type) {
+		case "NumberLiteral":
+		case "StringLiteral":
+		case "BooleanLiteral": return node.value;
+		case "NullLiteral": return null;
+		case "UndefinedLiteral": return;
+		case "Identifier":
+			env.g.checkNameAccess(node.name, "identifier");
+			return Object.hasOwn(env.ctx, node.name) ? env.ctx[node.name] : void 0;
+	}
+	return evalCompoundAsync(node, env);
+}
+async function evalCompoundAsync(node, env) {
+	const { g, s } = env;
 	g.enterDepth();
 	g.step();
 	try {
 		switch (node.type) {
-			case "NumberLiteral":
-			case "StringLiteral":
-			case "BooleanLiteral": return node.value;
-			case "NullLiteral": return null;
-			case "UndefinedLiteral": return;
-			case "Identifier":
-				g.checkNameAccess(node.name, "identifier");
-				return Object.hasOwn(ctx, node.name) ? ctx[node.name] : void 0;
 			case "UnaryExpression": return applyUnaryOp(node.operator, await evalNodeAsync(node.operand, env));
 			case "BinaryExpression": {
 				const op = node.operator;
@@ -1776,10 +1321,10 @@ async function evalCallExpressionAsync(node, env) {
 		}
 	}
 	if (node.callee.type === "Identifier") try {
-		const func = resolveFunction(node.callee.name, fn);
+		const resolved = resolveCallable(node.callee.name, fn);
 		const args = [];
 		for (const arg of node.args) await pushCallArgumentAsync(args, arg, env);
-		const result = await func(...args);
+		const result = resolved.kind === "context" ? await resolved.fn(env.ctx, ...args) : await resolved.fn(...args);
 		g.checkTimeout();
 		return result;
 	} catch (e) {
@@ -1937,99 +1482,23 @@ function makeLambdaAccessor(property, guard) {
 	};
 }
 //#endregion
-//#region src/execution-context.ts
-const BLOCKED_PROPERTIES = new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
-const MAX_INDEX_DIGITS = 10;
-function isCanonicalIndex(key) {
-	if (key.length === 0 || key.length > MAX_INDEX_DIGITS) return false;
-	const n = Number(key);
-	return Number.isInteger(n) && n >= 0 && String(n) === key;
-}
-const TIMEOUT_CHECK_INTERVAL = 1e3;
-const DEFAULT_MAX_DEPTH = 100;
-const DEFAULT_MAX_ARRAY_LENGTH = 1e5;
-/** Immutable per-instance security configuration derived from BonsaiOptions. */
-var SecurityPolicy = class {
-	maxDepth;
-	maxArrayLength;
-	timeout;
-	allowedProperties;
-	deniedProperties;
-	constructor(options = {}) {
-		this.maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
-		this.maxArrayLength = options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH;
-		this.timeout = options.timeout ?? 0;
-		this.allowedProperties = options.allowedProperties ? new Set(options.allowedProperties) : void 0;
-		this.deniedProperties = options.deniedProperties ? new Set(options.deniedProperties) : void 0;
-	}
-};
-/** Mutable per-evaluation state: tracks depth, step count, and deadline for a single evaluation. */
-var ExecutionContext = class {
-	stepCount = 0;
-	depth = 0;
-	deadline;
-	policy;
-	now;
-	constructor(policy, now = Date.now) {
-		this.policy = policy;
-		this.now = now;
-		this.deadline = policy.timeout ? now() + policy.timeout : 0;
-	}
-	step() {
-		if (this.deadline) {
-			this.stepCount++;
-			if (this.stepCount % TIMEOUT_CHECK_INTERVAL === 0) this.checkTimeout();
-		}
-	}
-	checkTimeout() {
-		if (this.deadline && this.now() >= this.deadline) throw new BonsaiSecurityError("TIMEOUT", `Expression timeout: exceeded ${this.policy.timeout}ms`);
-	}
-	enterDepth() {
-		if (++this.depth > this.policy.maxDepth) throw new BonsaiSecurityError("MAX_DEPTH", `Maximum expression depth (${this.policy.maxDepth}) exceeded`);
-	}
-	exitDepth() {
-		this.depth--;
-	}
-	withDepth(fn) {
-		this.enterDepth();
-		try {
-			return fn();
-		} finally {
-			this.exitDepth();
-		}
-	}
-	checkNameAccess(key, kind) {
-		if (BLOCKED_PROPERTIES.has(key)) throw new BonsaiSecurityError("BLOCKED_PROPERTY", `Blocked: access to "${key}" is not allowed`);
-		if (kind === "identifier" || kind === "object-key") return;
-		if (isCanonicalIndex(key)) return;
-		if (this.policy.allowedProperties) {
-			if (!this.policy.allowedProperties.has(key)) throw new BonsaiSecurityError("PROPERTY_NOT_ALLOWED", `Blocked: "${key}" is not in allowed properties`);
-		}
-		if (this.policy.deniedProperties) {
-			if (this.policy.deniedProperties.has(key)) throw new BonsaiSecurityError("PROPERTY_DENIED", `Blocked: "${key}" is in denied properties`);
-		}
-	}
-	checkArrayLength(length) {
-		if (length > this.policy.maxArrayLength) throw new BonsaiSecurityError("MAX_ARRAY_LENGTH", `Array length (${length}) exceeds maximum (${this.policy.maxArrayLength})`);
-	}
-};
-//#endregion
 //#region src/cache.ts
 var LRUCache = class {
 	max;
 	map = /* @__PURE__ */ new Map();
+	lastKey;
+	lastValue;
 	constructor(max) {
 		this.max = max > 0 ? max : 0;
 	}
 	get(key) {
+		if (key === this.lastKey) return this.lastValue;
 		if (!this.map.has(key)) return void 0;
 		const value = this.map.get(key);
 		this.map.delete(key);
 		this.map.set(key, value);
+		this.lastKey = key;
+		this.lastValue = value;
 		return value;
 	}
 	set(key, value) {
@@ -2038,14 +1507,22 @@ var LRUCache = class {
 		else if (this.map.size >= this.max) {
 			const oldest = this.map.keys().next().value;
 			this.map.delete(oldest);
+			if (this.lastKey === oldest) {
+				this.lastKey = void 0;
+				this.lastValue = void 0;
+			}
 		}
 		this.map.set(key, value);
+		this.lastKey = key;
+		this.lastValue = value;
 	}
 	get size() {
 		return this.map.size;
 	}
 	clear() {
 		this.map.clear();
+		this.lastKey = void 0;
+		this.lastValue = void 0;
 	}
 };
 //#endregion
@@ -2057,13 +1534,24 @@ function createPluginRegistry() {
 	let functionsCache = {};
 	let transformsDirty = false;
 	let functionsDirty = false;
+	let bindingsCache;
 	const registry = {
 		addTransform(name, fn) {
 			transformMap.set(name, fn);
 			transformsDirty = true;
 		},
 		addFunction(name, fn) {
-			functionMap.set(name, fn);
+			functionMap.set(name, {
+				kind: "pure",
+				fn
+			});
+			functionsDirty = true;
+		},
+		addContextFunction(name, fn) {
+			functionMap.set(name, {
+				kind: "context",
+				fn
+			});
 			functionsDirty = true;
 		},
 		removeTransform(name) {
@@ -2082,6 +1570,12 @@ function createPluginRegistry() {
 		getFunction(name) {
 			return functionMap.get(name);
 		},
+		isContextFunction(name) {
+			return functionMap.get(name)?.kind === "context";
+		},
+		hasFunction(name) {
+			return functionMap.has(name);
+		},
 		getTransformNames() {
 			return [...transformMap.keys()];
 		},
@@ -2104,6 +1598,15 @@ function createPluginRegistry() {
 				functionsDirty = false;
 			}
 			return functionsCache;
+		},
+		get bindings() {
+			const t = registry.transforms;
+			const f = registry.functions;
+			if (!bindingsCache || bindingsCache.transforms !== t || bindingsCache.functions !== f) bindingsCache = {
+				transforms: t,
+				functions: f
+			};
+			return bindingsCache;
 		}
 	};
 	return registry;
@@ -2111,24 +1614,36 @@ function createPluginRegistry() {
 //#endregion
 //#region src/index.ts
 const DEFAULT_CACHE_SIZE = 256;
-let _shared;
+let sharedInstance;
 /**
 * Evaluate a single expression with default options. Uses a shared instance internally.
 * For repeated evaluation or custom configuration, use `bonsai()` to create a dedicated instance.
 */
 function evaluateExpression(expression, context) {
-	if (!_shared) _shared = bonsai();
-	return _shared.evaluateSync(expression, context);
+	if (!sharedInstance) sharedInstance = bonsai();
+	return sharedInstance.evaluateSync(expression, context);
 }
 /**
 * Create a new Bonsai instance with optional safety and caching configuration.
-* Register transforms and functions via `.use()`, `.addTransform()`, and `.addFunction()`.
+* Register transforms and functions via `.use()`, `.addTransform()`, `.addFunction()`,
+* and `.addContextFunction()`.
+*
+* Pass a context type argument to get end-to-end type safety on the evaluation
+* context: `bonsai<MyContext>()` will type-check `evaluate(expr, ctx)` calls,
+* require a context argument when `MyContext` has required fields, and
+* propagate `MyContext` into context-aware function signatures.
 *
 * @example
 * ```ts
 * const expr = bonsai({ timeout: 50 })
 * expr.use(strings)
 * expr.evaluateSync('name |> trim |> upper', { name: '  hello  ' }) // "HELLO"
+*
+* type AppCtx = { userId: string; perms: string[] }
+* const app = bonsai<AppCtx>()
+* app.addContextFunction('hasPermission', (ctx, action) =>
+*   ctx.perms.includes(String(action)))
+* app.evaluateSync('hasPermission("write")', { userId: 'u_1', perms: ['write'] })
 * ```
 */
 function bonsai(options = {}) {
@@ -2136,6 +1651,8 @@ function bonsai(options = {}) {
 	const cache = new LRUCache(options.cacheSize ?? DEFAULT_CACHE_SIZE);
 	const astCache = new LRUCache(options.cacheSize ?? DEFAULT_CACHE_SIZE);
 	const policy = new SecurityPolicy(options);
+	const syncCtx = new ExecutionContext(policy);
+	let syncCtxInUse = false;
 	function createExecutionContext() {
 		return new ExecutionContext(policy);
 	}
@@ -2153,11 +1670,19 @@ function bonsai(options = {}) {
 		const compiled = {
 			ast: optimized,
 			source,
-			async evaluate(context = {}) {
-				return evaluateAsync(optimized, context, registry.transforms, registry.functions, createExecutionContext(), source);
+			async evaluate(...args) {
+				return evaluateAsync(optimized, args[0] ?? {}, registry.bindings, createExecutionContext(), source);
 			},
-			evaluateSync(context = {}) {
-				return evaluate(optimized, context, registry.transforms, registry.functions, createExecutionContext(), source);
+			evaluateSync(...args) {
+				const ctx = args[0] ?? {};
+				if (syncCtxInUse) return evaluate(optimized, ctx, registry.bindings, createExecutionContext(), source);
+				syncCtxInUse = true;
+				try {
+					syncCtx.reset();
+					return evaluate(optimized, ctx, registry.bindings, syncCtx, source);
+				} finally {
+					syncCtxInUse = false;
+				}
 			}
 		};
 		cache.set(source, compiled);
@@ -2176,6 +1701,10 @@ function bonsai(options = {}) {
 			registry.addFunction(name, fn);
 			return instance;
 		},
+		addContextFunction(name, fn) {
+			registry.addContextFunction(name, fn);
+			return instance;
+		},
 		removeTransform(name) {
 			return registry.removeTransform(name);
 		},
@@ -2186,7 +1715,10 @@ function bonsai(options = {}) {
 			return registry.getTransform(name) !== void 0;
 		},
 		hasFunction(name) {
-			return registry.getFunction(name) !== void 0;
+			return registry.hasFunction(name);
+		},
+		isContextFunction(name) {
+			return registry.isContextFunction(name);
 		},
 		listTransforms() {
 			return registry.getTransformNames();
@@ -2194,6 +1726,12 @@ function bonsai(options = {}) {
 		listFunctions() {
 			return registry.getFunctionNames();
 		},
+		getPolicy() {
+			return {
+				...policy.allowedProperties ? { allowedProperties: [...policy.allowedProperties] } : {},
+				...policy.deniedProperties ? { deniedProperties: [...policy.deniedProperties] } : {}
+			};
+		},
 		clearCache() {
 			cache.clear();
 			astCache.clear();
@@ -2201,11 +1739,20 @@ function bonsai(options = {}) {
 		compile(expression) {
 			return compileExpr(expression);
 		},
-		async evaluate(expression, context = {}) {
-			return evaluateAsync(getAst(expression), context, registry.transforms, registry.functions, createExecutionContext(), expression);
+		async evaluate(expression, ...args) {
+			return evaluateAsync(getAst(expression), args[0] ?? {}, registry.bindings, createExecutionContext(), expression);
 		},
-		evaluateSync(expression, context = {}) {
-			return evaluate(getAst(expression), context, registry.transforms, registry.functions, createExecutionContext(), expression);
+		evaluateSync(expression, ...args) {
+			const ast = getAst(expression);
+			const ctx = args[0] ?? {};
+			if (syncCtxInUse) return evaluate(ast, ctx, registry.bindings, createExecutionContext(), expression);
+			syncCtxInUse = true;
+			try {
+				syncCtx.reset();
+				return evaluate(ast, ctx, registry.bindings, syncCtx, expression);
+			} finally {
+				syncCtxInUse = false;
+			}
 		},
 		validate(expression) {
 			try {