@coldsmirk/abacus-core 0.2.0

package/dist/index.cjs

@@ -0,0 +1,762 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/engine/errors.ts
+/**
+* Error raised when the ZEN engine fails to load or an expression cannot be
+* evaluated. The original failure is preserved on {@link cause} and the
+* offending expression (if any) on {@link expression}.
+*/
+var ExpressionError = class extends Error {
+	expression;
+	constructor(message, expression, cause) {
+		super(message, { cause });
+		this.name = "ExpressionError";
+		this.expression = expression;
+	}
+};
+/**
+* Raised by the synchronous evaluation helpers when the engine has not finished
+* initializing yet. Await {@link loadEngine} (or render under
+* `<ExpressionEngineProvider>`) before evaluating synchronously.
+*/
+var ExpressionNotReadyError = class extends ExpressionError {
+	constructor(message = "Expression engine is not initialized. Await loadEngine() or render under <ExpressionEngineProvider>.") {
+		super(message);
+		this.name = "ExpressionNotReadyError";
+	}
+};
+//#endregion
+//#region src/internal/predicates.ts
+/**
+* Minimal internal type predicates. Inlined so the engine stays dependency-free
+* (no shared-utility package), keeping `@coldsmirk/abacus-core` framework- and
+* ecosystem-agnostic.
+*/
+function isUndefined(value) {
+	return value === void 0;
+}
+function isString(value) {
+	return typeof value === "string";
+}
+function isArray(value) {
+	return Array.isArray(value);
+}
+function isNullish(value) {
+	return value === null || value === void 0;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/engine/loader.ts
+let enginePromise = null;
+let engineSync = null;
+let engineError = null;
+let configuredInput;
+let typeContextCache = null;
+function evaluateSafely(expression, run) {
+	try {
+		return run();
+	} catch (error) {
+		throw new ExpressionError(`Failed to evaluate expression: ${expression}`, expression, error);
+	}
+}
+function loadFailureMessage() {
+	const base = "Failed to load the ZEN expression engine";
+	if (typeof window === "undefined") return `${base}. In a non-browser or non-DOM host (Node, SSR, Web Worker) the wasm cannot be auto-resolved; call configureEngine({ wasmInput }) with the wasm bytes or URL before loading.`;
+	return base;
+}
+/**
+* Configure how the wasm binary is located, before the engine loads. Must be
+* called before the first {@link loadEngine} (or any evaluation), so that the
+* configured input is the one actually used — calling it after the engine has
+* started loading throws, rather than silently taking no effect.
+*/
+function configureEngine(options) {
+	if (enginePromise || engineSync) throw new ExpressionError("configureEngine() must be called before the engine loads.");
+	configuredInput = options.wasmInput;
+}
+/**
+* Load and initialize the ZEN expression engine exactly once. Concurrent and
+* subsequent calls share the same in-flight promise / resolved instance. Set a
+* custom wasm source up front with {@link configureEngine}.
+*
+* The GoRules wasm dependency is reached via a dynamic `import()` on purpose: it
+* keeps this module usable from the package's CommonJS build (the dep is
+* ESM-only, so a static `require` would throw) and defers the multi-megabyte
+* wasm download until the engine is actually needed. Do NOT convert this to a
+* static import.
+*
+* A failed load is not cached: the rejected promise is dropped (the error is
+* latched on {@link getEngineError} for inspection), so calling `loadEngine()`
+* again retries from scratch. This is the clear-and-reload retry primitive after
+* a transient failure — an error boundary should call it before resetting.
+*/
+function loadEngine() {
+	if (enginePromise) return enginePromise;
+	engineError = null;
+	enginePromise = (async () => {
+		const zen = await import("@gorules/zen-engine-wasm");
+		await zen.default(isUndefined(configuredInput) ? void 0 : { module_or_path: configuredInput });
+		const toVariableType = (type) => zen.VariableType.fromJson(type);
+		const ensureTypeContext = (variables) => {
+			if (typeContextCache && typeContextCache.variables === variables) return typeContextCache;
+			const stale = typeContextCache;
+			typeContextCache = null;
+			stale?.handle.free();
+			const handle = toVariableType(variables);
+			try {
+				typeContextCache = {
+					variables,
+					handle,
+					rootKind: handle.toJson()
+				};
+			} catch (error) {
+				handle.free();
+				throw error;
+			}
+			return typeContextCache;
+		};
+		const engine = Object.freeze({
+			evaluate: (expression, context = {}) => evaluateSafely(expression, () => zen.evaluateExpression(expression, context)),
+			evaluateUnary: (expression, context = {}) => evaluateSafely(expression, () => zen.evaluateUnaryExpression(expression, context)),
+			validate: (expression) => zen.validateExpression(expression),
+			validateUnary: (expression) => zen.validateUnaryExpression(expression),
+			getCompletions: () => zen.getCompletions(),
+			analyze: (variables, source, unary) => {
+				const context = ensureTypeContext(variables);
+				const rawSpans = unary ? context.handle.typeCheckUnary(source) : context.handle.typeCheck(source);
+				return {
+					rootKind: context.rootKind,
+					spans: Array.isArray(rawSpans) ? rawSpans : []
+				};
+			},
+			satisfies: (actual, expected) => {
+				const actualType = toVariableType(actual);
+				try {
+					const expectedType = toVariableType(expected);
+					try {
+						return actualType.satisfies(expectedType);
+					} finally {
+						expectedType.free();
+					}
+				} finally {
+					actualType.free();
+				}
+			},
+			isReady: () => zen.isReady()
+		});
+		engineSync = engine;
+		return engine;
+	})().catch((error) => {
+		enginePromise = null;
+		engineError = new ExpressionError(loadFailureMessage(), void 0, error);
+		throw engineError;
+	});
+	return enginePromise;
+}
+/**
+* Whether the engine has finished initializing and is ready for sync use.
+*/
+function isEngineReady() {
+	return engineSync?.isReady() ?? false;
+}
+/**
+* The error from the last failed {@link loadEngine} attempt, or `null`. Used by
+* the React provider to surface a wasm-load failure to an error boundary rather
+* than suspending forever, and by imperative pollers to tell "failed" apart from
+* "still loading". Cleared when a new load starts or {@link resetEngine}.
+*/
+function getEngineError() {
+	return engineError;
+}
+/**
+* Return the already-initialized engine synchronously, or throw
+* {@link ExpressionNotReadyError} if {@link loadEngine} has not resolved yet.
+*/
+function getEngineSync() {
+	if (!engineSync) throw new ExpressionNotReadyError();
+	return engineSync;
+}
+/**
+* Reset the engine singleton — drops the loaded engine, the cached type context,
+* the latched error, and the configured wasm input. Mainly for tests, but also the
+* way to re-run {@link configureEngine} after a load (configure throws once the
+* engine has started loading).
+*/
+function resetEngine() {
+	typeContextCache?.handle.free();
+	typeContextCache = null;
+	enginePromise = null;
+	engineSync = null;
+	engineError = null;
+	configuredInput = void 0;
+}
+//#endregion
+//#region src/internal/env.ts
+/**
+* Best-effort development-mode flag for diagnostic-only code paths.
+*
+* Detected from `process.env.NODE_ENV` (defined by Node, test runners, webpack,
+* and Vite's SSR/`define`). The `typeof` guard is load-bearing: in a plain
+* browser bundle `process` is not declared at all, and any bare reference would
+* throw a ReferenceError while this module is being imported. Hosts without a
+* `process` default to "production" — the safe choice, since `isDev` only gates
+* extra developer-facing warnings.
+*/
+const isDev = detectDev();
+function detectDev() {
+	if (typeof process === "undefined") return false;
+	return process.env ? process.env.NODE_ENV !== "production" : false;
+}
+//#endregion
+//#region src/condition/compile.ts
+/**
+* A subject must be a plain identifier path (`amount`, `user.age`, `items[0]`).
+* It is emitted verbatim into ZEN source, so anything else is rejected to keep
+* the condition compiler from being an expression-injection sink.
+*/
+const SUBJECT_PATTERN = /^[A-Z_$][\w$]*(?:\.[A-Z_$][\w$]*|\[\d+\])*$/i;
+const ZEN_RESERVED_WORDS = new Set([
+	"and",
+	"or",
+	"not",
+	"in",
+	"true",
+	"false",
+	"null"
+]);
+function isIdentifierPath(subject) {
+	return SUBJECT_PATTERN.test(subject) && (subject.match(/[A-Z_$][\w$]*/gi) ?? []).every((segment) => !ZEN_RESERVED_WORDS.has(segment));
+}
+/**
+* Serialize a JavaScript value into a ZEN literal. Nullish becomes `null`;
+* numbers / booleans / bigints are emitted verbatim; strings are quoted via
+* {@link encodeZenString}; arrays become `[a, b, ...]`.
+*
+* Throws {@link ExpressionError} for a value with no faithful ZEN
+* representation — an object, symbol, or function, or a string containing both
+* quote styles. Callers that need a sentinel instead of a throw go through
+* {@link compileCondition}, which degrades such a value to a non-compiling
+* (null) condition.
+*/
+function toZenLiteral(value) {
+	if (isNullish(value)) return "null";
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new ExpressionError(`Number ${String(value)} has no ZEN literal representation`);
+		return String(value);
+	}
+	if (typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (isString(value)) return encodeZenString(value);
+	if (isArray(value)) return `[${value.map((item) => toZenLiteral(item)).join(", ")}]`;
+	throw new ExpressionError(`Value of type "${typeof value}" has no ZEN literal representation`);
+}
+/**
+* Encode a string as a ZEN literal. ZEN string literals are **raw** between
+* matching quotes and honor no backslash escapes (`'a\nb'` is the four
+* characters `a \ n b`), so the encoder must not escape — it picks a delimiter
+* the value does not contain. A value containing both quote styles cannot be
+* represented as a raw ZEN literal and throws.
+*/
+function encodeZenString(value) {
+	const hasSingle = value.includes("'");
+	const hasDouble = value.includes("\"");
+	if (hasSingle && hasDouble) throw new ExpressionError("String contains both single and double quotes and has no ZEN literal representation");
+	return hasSingle ? `"${value}"` : `'${value}'`;
+}
+function toArrayLiteral(value) {
+	return isArray(value) ? toZenLiteral(value) : `[${toZenLiteral(value)}]`;
+}
+/**
+* Emit the ZEN emptiness test matching the backend field evaluator's
+* `isEmptyValue`: null, blank (whitespace-only) text, and empty arrays are
+* empty; numbers and booleans never are. ZEN's `or` short-circuits, so the
+* type-guarded branches never evaluate against a null subject. The backend
+* additionally treats an empty map as empty for totality, but form values —
+* the only subjects this compiler targets — are never objects, and ZEN's
+* `len()` does not accept one.
+*/
+function zenIsEmpty(subject) {
+	return `(${subject} == null or (type(${subject}) == 'string' and len(trim(${subject})) == 0) or (type(${subject}) == 'array' and len(${subject}) == 0))`;
+}
+function compileFieldCondition(subject, operator, value) {
+	switch (operator) {
+		case "eq": return `${subject} == ${toZenLiteral(value)}`;
+		case "ne": return `${subject} != ${toZenLiteral(value)}`;
+		case "gt": return `${subject} > ${toZenLiteral(value)}`;
+		case "gte": return `${subject} >= ${toZenLiteral(value)}`;
+		case "lt": return `${subject} < ${toZenLiteral(value)}`;
+		case "lte": return `${subject} <= ${toZenLiteral(value)}`;
+		case "contains": return `contains(${subject}, ${toZenLiteral(value)})`;
+		case "not_contains": return `not contains(${subject}, ${toZenLiteral(value)})`;
+		case "starts_with": return `startsWith(${subject}, ${toZenLiteral(value)})`;
+		case "ends_with": return `endsWith(${subject}, ${toZenLiteral(value)})`;
+		case "in": return `${subject} in ${toArrayLiteral(value)}`;
+		case "not_in": return `not (${subject} in ${toArrayLiteral(value)})`;
+		case "is_empty": return zenIsEmpty(subject);
+		case "is_not_empty": return `not ${zenIsEmpty(subject)}`;
+		default: throw new ExpressionError(`Unsupported operator: ${String(operator)}`);
+	}
+}
+/**
+* Compile a single condition into a ZEN boolean expression. Field conditions map
+* their operator to ZEN; expression conditions are wrapped in parentheses to
+* preserve their grouping. Returns `null` when the condition is empty, its
+* subject is not an identifier path, or its value has no ZEN representation.
+*/
+function compileCondition(condition) {
+	if (condition.kind === "expression") {
+		const expression = condition.expression.trim();
+		return expression === "" ? null : `(${expression})`;
+	}
+	const subject = condition.subject.trim();
+	if (!isIdentifierPath(subject)) return null;
+	try {
+		return compileFieldCondition(subject, condition.operator, condition.value);
+	} catch {
+		return null;
+	}
+}
+/**
+* Compile a condition group (its conditions joined with AND). Returns `null`
+* when the group has no compilable conditions.
+*/
+function compileGroup(group) {
+	const parts = group.conditions.map((condition) => compileCondition(condition)).filter((part) => part !== null);
+	return parts.length === 0 ? null : parts.join(" and ");
+}
+/**
+* Compile a branch's condition groups into a single ZEN expression (groups
+* joined with OR). Returns `null` when the branch has no compilable groups
+* (e.g. a default branch).
+*/
+function compileBranch(branch) {
+	const groups = (branch.conditionGroups ?? []).map((group) => compileGroup(group)).filter((group) => group !== null);
+	return groups.length === 0 ? null : groups.map((group) => `(${group})`).join(" or ");
+}
+/**
+* Pick the matching branch for the given context using a pre-loaded engine.
+* Non-default branches are tested in ascending `priority` order; the first whose
+* compiled expression evaluates to `true` wins. Falls back to the default
+* branch, or a `null` id when neither matches.
+*
+* A branch whose expression throws for the given context (e.g. ZEN's `>`
+* throws when the subject is missing or non-numeric) is treated as not matching
+* rather than propagating — so a missing field degrades to the default branch
+* instead of crashing the caller.
+*/
+function selectBranchWith(branches, context, engine) {
+	const ordered = branches.toSorted((a, b) => a.priority - b.priority);
+	for (const branch of ordered) {
+		if (branch.isDefault) continue;
+		const expression = compileBranch(branch);
+		if (expression === null) {
+			if (isDev) console.warn(`[expression] branch "${branch.id}" has no compilable condition and can never match`);
+			continue;
+		}
+		if (evaluatesTrue(engine, expression, context)) return {
+			branchId: branch.id,
+			matched: true
+		};
+	}
+	return {
+		branchId: ordered.find((branch) => branch.isDefault)?.id ?? null,
+		matched: false
+	};
+}
+function evaluatesTrue(engine, expression, context) {
+	try {
+		return engine.evaluate(expression, context) === true;
+	} catch (error) {
+		if (isDev) reportEvaluationFailure(engine, expression, error);
+		return false;
+	}
+}
+function reportEvaluationFailure(engine, expression, error) {
+	let diagnostic;
+	try {
+		diagnostic = engine.validate(expression);
+	} catch {
+		return;
+	}
+	if (!isNullish(diagnostic)) console.warn(`[expression] compiled branch expression failed to parse: ${expression}`, diagnostic, error);
+}
+/**
+* Pick the matching branch for the given context, loading the ZEN engine on
+* first use. See {@link selectBranchWith} for the selection semantics.
+*/
+async function selectBranch(branches, context) {
+	return selectBranchWith(branches, context, await loadEngine());
+}
+//#endregion
+//#region src/condition/types.ts
+/**
+* Structural shapes for the visual condition model compiled to ZEN. They mirror
+* the condition types used in the form and flow editors so a host can map those
+* definitions to {@link compileCondition} / {@link selectBranch} without this
+* package depending on either editor. The editors keep a flat working model for
+* form ergonomics (a row can hold both a half-typed field triple and an
+* expression while the author toggles between them); this discriminated input is
+* the narrowed, compiler-facing shape where each kind carries only what it uses.
+*/
+/**
+* The closed operator vocabulary understood by {@link compileCondition}, as a
+* runtime constant so validators can build allow-lists from it instead of
+* re-declaring the set. The {@link ConditionOperator} type derives from this
+* array — one definition site for both the type and the runtime list.
+*/
+const CONDITION_OPERATORS = [
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"contains",
+	"not_contains",
+	"starts_with",
+	"ends_with",
+	"in",
+	"not_in",
+	"is_empty",
+	"is_not_empty"
+];
+//#endregion
+//#region src/engine/evaluate.ts
+/**
+* Evaluate a standard ZEN expression, loading the engine on first use.
+*
+* `T` is an **unchecked** assertion — the value is returned as `T` with no
+* runtime validation, and ZEN's result type depends on the expression and
+* context. Prefer the `unknown` default and narrow at the call site.
+*/
+async function evaluate(expression, context) {
+	await loadEngine();
+	return evaluateSync(expression, context);
+}
+/**
+* Evaluate a ZEN unary (test) expression, loading the engine on first use.
+*/
+async function evaluateUnary(expression, context) {
+	await loadEngine();
+	return evaluateUnarySync(expression, context);
+}
+/**
+* Evaluate a standard ZEN expression synchronously. Throws
+* {@link ExpressionNotReadyError} when the engine has not loaded yet — use this
+* only behind a readiness gate (e.g. under `<ExpressionEngineProvider>`).
+*/
+function evaluateSync(expression, context) {
+	return getEngineSync().evaluate(expression, context);
+}
+/**
+* Evaluate a ZEN unary (test) expression synchronously. Throws
+* {@link ExpressionNotReadyError} when the engine has not loaded yet.
+*/
+function evaluateUnarySync(expression, context) {
+	return getEngineSync().evaluateUnary(expression, context);
+}
+//#endregion
+//#region src/engine/messages.ts
+const COMPLETION_INFO_ZH = {
+	"Returns the length of variable": "返回变量的长度",
+	"Checks if variable contains a needle": "检查变量是否包含指定元素",
+	"Flattens an array": "将数组扁平化",
+	"Merges multiple objects into one.": "将多个对象合并为一个。",
+	"Deeply merges multiple objects into one.": "将多个对象深度合并为一个。",
+	"Converts all characters in a string to uppercase": "将字符串中所有字符转换为大写",
+	"Converts all characters in a string to lowercase": "将字符串中所有字符转换为小写",
+	"Returns the string with leading and trailing whitespace removed": "返回去除首尾空白后的字符串",
+	"Returns true if the string starts with the specified prefix": "若字符串以指定前缀开头则返回 true",
+	"Returns true if the string ends with the specified suffix": "若字符串以指定后缀结尾则返回 true",
+	"Returns true if the string matches the specified pattern": "若字符串匹配指定模式则返回 true",
+	"Extracts matching substrings according to a pattern": "按模式提取匹配的子串",
+	"Performs a fuzzy search of the needle in the haystack, and returns the match score(s).": "在目标中对关键字进行模糊搜索，并返回匹配得分。",
+	"Splits a string into an array of substrings using the specified delimiter.": "使用指定分隔符将字符串拆分为子串数组。",
+	"Returns the absolute value of a number": "返回数字的绝对值",
+	"Returns the sum of all elements in the input array.": "返回输入数组中所有元素之和。",
+	"Calculates the average of all elements in the input array.": "计算输入数组中所有元素的平均值。",
+	"Returns the smallest of the elements in the input array.": "返回输入数组中的最小元素。",
+	"Returns the largest of the elements in the input array.": "返回输入数组中的最大元素。",
+	"Generates a random number between 0 (inclusive) and max (inclusive).": "生成 0 到 max（均包含）之间的随机数。",
+	"Calculates the median value of all elements in the input array.": "计算输入数组中所有元素的中位数。",
+	"Finds the mode(s) of the input array, which are the most frequent element(s).": "求输入数组的众数，即出现最频繁的元素。",
+	"Rounds a number down to the nearest integer.": "向下取整到最接近的整数。",
+	"Rounds a number up to the nearest integer.": "向上取整到最接近的整数。",
+	"Rounds a number to a specified number of decimal places.": "将数字四舍五入到指定的小数位数。",
+	"Truncates a number to a specified number of decimal places.": "将数字截断到指定的小数位数。",
+	"Checks if the given value is of a numeric type.": "检查给定值是否为数值类型。",
+	"Converts the given value to a string.": "将给定值转换为字符串。",
+	"Converts the given value to a number.": "将给定值转换为数字。",
+	"Converts the given value to a boolean.": "将给定值转换为布尔值。",
+	"Returns a string representing the data type of the value.": "返回表示该值数据类型的字符串。",
+	"Returns an array of a given object's own enumerable property names.": "返回由给定对象自身可枚举属性名组成的数组。",
+	"Returns an array of a given object's own enumerable property values.": "返回由给定对象自身可枚举属性值组成的数组。",
+	"Returns a new date time instance.": "返回一个新的日期时间实例。",
+	"Converts a numeric timestamp to a unix timestamp.": "将数值时间戳转换为 Unix 时间戳。",
+	"Extracts the time from a numeric timestamp and returns it as a seconds from beginning of day.": "从数值时间戳中提取时间，以当天起始的秒数返回。",
+	"e.g. 1h30min": "例如 1h30min",
+	"Extracts the year from a given timestamp.": "从给定时间戳中提取年份。",
+	"Gets the day of the week from a given timestamp, where Sunday might be 0.": "获取给定时间戳的星期几（周日可能为 0）。",
+	"Extracts the day of the month from a given timestamp.": "从给定时间戳中提取当月的日期。",
+	"Gets the day of the year from a given timestamp.": "获取给定时间戳在一年中的第几天。",
+	"Calculates the week of the year from a given timestamp.": "计算给定时间戳在一年中的第几周。",
+	"Extracts the month from a given timestamp, typically with January as 1.": "从给定时间戳中提取月份（通常 1 月为 1）。",
+	"Converts the month from a given timestamp into its string representation (e.g., 'Jan').": "将给定时间戳的月份转换为字符串表示（例如 'Jan'）。",
+	"Converts a timestamp to a human-readable date string.": "将时间戳转换为人类可读的日期字符串。",
+	"Converts the day of the week from a given timestamp into its string representation (e.g., 'Mon').": "将给定时间戳的星期几转换为字符串表示（例如 'Mon'）。",
+	"Returns the timestamp representing the start of a specified unit (e.g., day, month, year) based on a given timestamp.": "返回给定时间戳在指定单位（如日、月、年）起始处的时间戳。",
+	"Returns the timestamp representing the end of a specified unit (e.g., day, month, year) based on a given timestamp.": "返回给定时间戳在指定单位（如日、月、年）结束处的时间戳。",
+	"Checks if all elements in the array satisfy the condition defined in the callback.": "检查数组中所有元素是否都满足回调中定义的条件。",
+	"Checks if no elements in the array satisfy the condition defined in the callback.": "检查数组中是否没有任何元素满足回调中定义的条件。",
+	"Checks if at least one element in the array satisfies the condition defined in the callback.": "检查数组中是否至少有一个元素满足回调中定义的条件。",
+	"Checks if exactly one element in the array satisfies the condition defined in the callback.": "检查数组中是否恰好有一个元素满足回调中定义的条件。",
+	"Creates a new array with all elements that satisfy the condition defined in the callback.": "创建一个仅包含满足回调中定义条件的元素的新数组。",
+	"Creates a new array populated with the results of calling the provided function on every element in the calling array.": "创建一个新数组，其元素为对原数组每个元素调用所提供函数的结果。",
+	"First maps each element using a mapping function, then flattens the result into a new array.": "先用映射函数处理每个元素，再将结果扁平化为新数组。",
+	"Counts the number of elements in the array that satisfy the condition defined in the callback.": "统计数组中满足回调中定义条件的元素个数。",
+	"Adds time to a date": "为日期增加时间",
+	"Subtracts time from a date": "从日期中减去时间",
+	"Sets a specific unit of time on a date": "设置日期的某个时间单位",
+	"Formats a date into a string representation": "将日期格式化为字符串",
+	"Returns the start of a specified time unit for a date": "返回日期在指定时间单位上的起始",
+	"Returns the end of a specified time unit for a date": "返回日期在指定时间单位上的结束",
+	"Calculates the difference between two dates": "计算两个日期之间的差值",
+	"Converts a date to a different timezone": "将日期转换到不同的时区",
+	"Checks if two dates are the same": "检查两个日期是否相同",
+	"Checks if a date is before another date": "检查日期是否早于另一个日期",
+	"Checks if a date is after another date": "检查日期是否晚于另一个日期",
+	"Checks if a date is the same as or before another date": "检查日期是否等于或早于另一个日期",
+	"Checks if a date is the same as or after another date": "检查日期是否等于或晚于另一个日期",
+	"Gets the seconds of a date": "获取日期的秒",
+	"Gets the minutes of a date": "获取日期的分钟",
+	"Gets the hours of a date": "获取日期的小时",
+	"Gets the day of the month for a date": "获取日期在当月的第几天",
+	"Gets the day of the year for a date": "获取日期在当年的第几天",
+	"Gets the week of the year for a date": "获取日期在当年的第几周",
+	"Gets the day of the week for a date": "获取日期的星期几",
+	"Gets the month for a date": "获取日期的月份",
+	"Gets the quarter for a date": "获取日期所在的季度",
+	"Gets the year for a date": "获取日期的年份",
+	"Gets the Unix timestamp for a date": "获取日期的 Unix 时间戳",
+	"Gets the timezone offset name for a date": "获取日期的时区偏移名称",
+	"Checks if a date is valid": "检查日期是否有效",
+	"Checks if a date is yesterday": "检查日期是否为昨天",
+	"Checks if a date is today": "检查日期是否为今天",
+	"Checks if a date is tomorrow": "检查日期是否为明天",
+	"Checks if the year of a date is a leap year": "检查日期所在年份是否为闰年"
+};
+const EN_SOURCE_LABELS = {
+	lexerError: "Lexer error",
+	parserError: "Parser error",
+	compilerError: "Compiler error",
+	vmError: "VM error"
+};
+const ZH_SOURCE_LABELS = {
+	lexerError: "词法错误",
+	parserError: "语法错误",
+	compilerError: "编译错误",
+	vmError: "运行时错误"
+};
+function sourceLabelFrom(table, fallback, type) {
+	return (type === void 0 ? void 0 : table[type]) ?? fallback;
+}
+/**
+* Built-in English message catalog (the default).
+*/
+const enMessages = {
+	sourceLabel: (type) => sourceLabelFrom(EN_SOURCE_LABELS, "Error", type),
+	completionInfo: (info) => info,
+	typeCheckSource: "Type check",
+	expectedBoolean: (actualType) => `Expected a boolean test expression, received \`${actualType}\`.`,
+	expectedType: (expectedType, actualType) => `Expected \`${expectedType}\`, received \`${actualType}\`.`
+};
+/**
+* Built-in Simplified Chinese message catalog.
+*/
+const zhCNMessages = {
+	sourceLabel: (type) => sourceLabelFrom(ZH_SOURCE_LABELS, "错误", type),
+	completionInfo: (info) => info === "" ? "" : COMPLETION_INFO_ZH[info] ?? info,
+	typeCheckSource: "类型检查",
+	expectedBoolean: (actualType) => `期望布尔测试表达式，实际类型为 \`${actualType}\`。`,
+	expectedType: (expectedType, actualType) => `期望 \`${expectedType}\`，实际为 \`${actualType}\`。`
+};
+const localeRegistry = new Map([["en-US", enMessages], ["zh-CN", zhCNMessages]]);
+let activeMessages = enMessages;
+/**
+* Register (or replace) the message catalog for a locale key, making it selectable
+* via {@link configureExpressionMessages}. This is how a host adds a language the
+* library does not ship — the built-in locales are registered the same way, so
+* there is no privileged path.
+*/
+function registerExpressionLocale(locale, messages) {
+	localeRegistry.set(locale, messages);
+}
+/**
+* Configure the active message catalog. Pass a `locale`, a partial `messages`
+* override, or both (overrides win). Idempotent and module-global, so a host
+* configures it once (e.g. through `ExpressionConfigProvider`).
+*/
+function configureExpressionMessages({ locale, messages }) {
+	const base = locale === void 0 ? activeMessages : localeRegistry.get(locale) ?? activeMessages;
+	activeMessages = messages === void 0 ? base : {
+		...base,
+		...messages
+	};
+}
+/**
+* The active {@link ExpressionMessages} catalog (English by default).
+*/
+function getExpressionMessages() {
+	return activeMessages;
+}
+//#endregion
+//#region src/engine/intellisense.ts
+function parseOffset(text) {
+	const trimmed = text?.trim();
+	return trimmed ? Number(trimmed) : NaN;
+}
+/**
+* Parse a trailing `... at (from, to)` / `... at pos` position out of a ZEN error
+* message. Returns a `[from, to]` range — a single offset collapses to
+* `[pos, pos]` — or `null` when no position is present.
+*/
+function extractPosition(message) {
+	const segments = message.split(" at ");
+	const last = segments.length <= 1 ? void 0 : segments.at(-1);
+	if (last === void 0) return null;
+	const [left, right] = last.replace("(", "").replace(")", "").split(", ");
+	const from = parseOffset(left);
+	if (Number.isNaN(from)) return null;
+	const to = parseOffset(right);
+	return [from, Number.isNaN(to) ? from : to];
+}
+/**
+* Normalize the wasm validate payload (`null` or `{ type, source }`) into a
+* positioned {@link ExpressionDiagnostic}, or `null` when the expression is valid.
+*/
+function normalizeDiagnostic(raw, source) {
+	if (raw === null || raw === void 0) return null;
+	const errorType = isRecord(raw) && typeof raw.type === "string" ? raw.type : void 0;
+	const message = isRecord(raw) && typeof raw.source === "string" ? raw.source : String(raw);
+	const [from, to] = extractPosition(message) ?? [0, source.length];
+	return {
+		from,
+		to,
+		message,
+		source: getExpressionMessages().sourceLabel(errorType)
+	};
+}
+/**
+* Normalize the wasm `getCompletions` payload into a typed list, dropping
+* malformed entries and stripping the backtick markers ZEN wraps type names in.
+*/
+function normalizeCompletions(raw) {
+	if (!Array.isArray(raw)) return [];
+	const messages = getExpressionMessages();
+	return raw.flatMap((entry) => {
+		if (!isRecord(entry) || typeof entry.label !== "string" || entry.label === "") return [];
+		return [{
+			type: entry.type === "method" || entry.type === "variable" ? entry.type : "function",
+			label: entry.label,
+			detail: typeof entry.detail === "string" ? entry.detail.replaceAll("`", "") : "",
+			info: messages.completionInfo(typeof entry.info === "string" ? entry.info : ""),
+			boost: typeof entry.boost === "number" ? entry.boost : null,
+			methodFor: typeof entry.methodFor === "string" ? entry.methodFor : null
+		}];
+	});
+}
+/**
+* Validate an expression, loading the engine on first use. Resolves to `null`
+* when the expression is valid, or a positioned diagnostic otherwise.
+*/
+async function getDiagnostics(expression, mode) {
+	await loadEngine();
+	return getDiagnosticsSync(expression, mode);
+}
+/**
+* Synchronous {@link getDiagnostics}. Throws `ExpressionNotReadyError` if the
+* engine has not loaded yet — use only behind a readiness gate.
+*/
+function getDiagnosticsSync(expression, mode) {
+	const engine = getEngineSync();
+	return normalizeDiagnostic(mode === "unary" ? engine.validateUnary(expression) : engine.validate(expression), expression);
+}
+/**
+* Return the ZEN built-in completion list, loading the engine on first use.
+*/
+async function getCompletionItems() {
+	await loadEngine();
+	return getCompletionItemsSync();
+}
+/**
+* Synchronous {@link getCompletionItems}. Throws `ExpressionNotReadyError` if the
+* engine has not loaded yet.
+*/
+function getCompletionItemsSync() {
+	return normalizeCompletions(getEngineSync().getCompletions());
+}
+/**
+* Type-check an expression against a `variables` context, loading the engine on
+* first use. See {@link ExpressionAnalysis}.
+*/
+async function analyzeTypes(variables, source, mode) {
+	await loadEngine();
+	return analyzeTypesSync(variables, source, mode);
+}
+/**
+* Synchronous {@link analyzeTypes}. Throws `ExpressionNotReadyError` if the
+* engine has not loaded yet.
+*/
+function analyzeTypesSync(variables, source, mode) {
+	return getEngineSync().analyze(variables, source, mode === "unary");
+}
+/**
+* Whether `actual` satisfies (is assignable to) `expected`, loading the engine on
+* first use. Used for expected-return-type validation.
+*/
+async function satisfiesType(actual, expected) {
+	await loadEngine();
+	return satisfiesTypeSync(actual, expected);
+}
+/**
+* Synchronous {@link satisfiesType}. Throws `ExpressionNotReadyError` if the
+* engine has not loaded yet.
+*/
+function satisfiesTypeSync(actual, expected) {
+	return getEngineSync().satisfies(actual, expected);
+}
+//#endregion
+exports.CONDITION_OPERATORS = CONDITION_OPERATORS;
+exports.ExpressionError = ExpressionError;
+exports.ExpressionNotReadyError = ExpressionNotReadyError;
+exports.analyzeTypes = analyzeTypes;
+exports.analyzeTypesSync = analyzeTypesSync;
+exports.compileBranch = compileBranch;
+exports.compileCondition = compileCondition;
+exports.compileGroup = compileGroup;
+exports.configureEngine = configureEngine;
+exports.configureExpressionMessages = configureExpressionMessages;
+exports.enMessages = enMessages;
+exports.evaluate = evaluate;
+exports.evaluateSync = evaluateSync;
+exports.evaluateUnary = evaluateUnary;
+exports.evaluateUnarySync = evaluateUnarySync;
+exports.getCompletionItems = getCompletionItems;
+exports.getCompletionItemsSync = getCompletionItemsSync;
+exports.getDiagnostics = getDiagnostics;
+exports.getDiagnosticsSync = getDiagnosticsSync;
+exports.getEngineError = getEngineError;
+exports.getEngineSync = getEngineSync;
+exports.getExpressionMessages = getExpressionMessages;
+exports.isEngineReady = isEngineReady;
+exports.loadEngine = loadEngine;
+exports.registerExpressionLocale = registerExpressionLocale;
+exports.resetEngine = resetEngine;
+exports.satisfiesType = satisfiesType;
+exports.satisfiesTypeSync = satisfiesTypeSync;
+exports.selectBranch = selectBranch;
+exports.selectBranchWith = selectBranchWith;
+exports.toZenLiteral = toZenLiteral;
+exports.zhCNMessages = zhCNMessages;
+
+//# sourceMappingURL=index.cjs.map