@vef-framework-react/expression 2.4.0

package/dist/cjs/condition/compile.cjs

@@ -0,0 +1 @@
+const e=require("../engine/errors.cjs"),t=require("../engine/loader.cjs");let n=require("@vef-framework-react/shared");var r=/^[A-Z_$][\w$]*(?:\.[A-Z_$][\w$]*|\[\d+\])*$/i;function i(t){if((0,n.isNullish)(t))return`null`;if(typeof t==`number`||typeof t==`boolean`||typeof t==`bigint`)return String(t);if((0,n.isString)(t))return a(t);if((0,n.isArray)(t))return`[${t.map(e=>i(e)).join(`, `)}]`;throw new e.ExpressionError(`Value of type "${typeof t}" has no ZEN literal representation`)}function a(t){let n=t.includes(`'`),r=t.includes(`"`);if(n&&r)throw new e.ExpressionError(`String contains both single and double quotes and has no ZEN literal representation`);return n?`"${t}"`:`'${t}'`}function o(e){return(0,n.isArray)(e)?i(e):`[${i(e)}]`}function s(e){return`(${e} == null or (type(${e}) == 'string' and len(trim(${e})) == 0) or (type(${e}) == 'array' and len(${e}) == 0))`}function c(t,n,r){switch(n){case`eq`:return`${t} == ${i(r)}`;case`ne`:return`${t} != ${i(r)}`;case`gt`:return`${t} > ${i(r)}`;case`gte`:return`${t} >= ${i(r)}`;case`lt`:return`${t} < ${i(r)}`;case`lte`:return`${t} <= ${i(r)}`;case`contains`:return`contains(${t}, ${i(r)})`;case`not_contains`:return`not contains(${t}, ${i(r)})`;case`starts_with`:return`startsWith(${t}, ${i(r)})`;case`ends_with`:return`endsWith(${t}, ${i(r)})`;case`in`:return`${t} in ${o(r)}`;case`not_in`:return`not (${t} in ${o(r)})`;case`is_empty`:return s(t);case`is_not_empty`:return`not ${s(t)}`;default:throw new e.ExpressionError(`Unsupported operator: ${String(n)}`)}}function l(e){if(e.kind===`expression`){let t=e.expression.trim();return t===``?null:t}let t=e.subject.trim();if(!r.test(t))return null;try{return c(t,e.operator,e.value)}catch{return null}}function u(e){let t=e.conditions.map(e=>l(e)).filter(e=>e!==null);return t.length===0?null:t.join(` and `)}function d(e){let t=(e.conditionGroups??[]).map(e=>u(e)).filter(e=>e!==null);return t.length===0?null:t.map(e=>`(${e})`).join(` or `)}function f(e,t,n){let r=e.toSorted((e,t)=>e.priority-t.priority);for(let e of r){if(e.isDefault)continue;let r=d(e);if(r!==null&&p(n,r,t))return{branchId:e.id,matched:!0}}return{branchId:r.find(e=>e.isDefault)?.id??null,matched:!1}}function p(e,t,n){try{return e.evaluate(t,n)===!0}catch{return!1}}async function m(e,n){return f(e,n,await t.loadEngine())}exports.compileBranch=d,exports.compileCondition=l,exports.compileGroup=u,exports.selectBranch=m,exports.selectBranchWith=f,exports.toZenLiteral=i;

package/dist/cjs/condition/types.cjs

@@ -0,0 +1 @@
+var e=[`eq`,`ne`,`gt`,`gte`,`lt`,`lte`,`contains`,`not_contains`,`starts_with`,`ends_with`,`in`,`not_in`,`is_empty`,`is_not_empty`];exports.CONDITION_OPERATORS=e;

package/dist/cjs/engine/errors.cjs

@@ -0,0 +1 @@
+var e=class extends Error{expression;constructor(e,t,n){super(e,{cause:n}),this.name=`ExpressionError`,this.expression=t}},t=class extends e{constructor(e=`Expression engine is not initialized. Await loadEngine() or render under <ExpressionEngineProvider>.`){super(e),this.name=`ExpressionNotReadyError`}};exports.ExpressionError=e,exports.ExpressionNotReadyError=t;

package/dist/cjs/engine/evaluate.cjs

@@ -0,0 +1 @@
+const e=require("./loader.cjs");async function t(t,n){return(await e.loadEngine()).evaluate(t,n)}async function n(t,n){return(await e.loadEngine()).evaluateUnary(t,n)}function r(t,n){return e.getEngineSync().evaluate(t,n)}function i(t,n){return e.getEngineSync().evaluateUnary(t,n)}async function a(t){return(await e.loadEngine()).validate(t)}async function o(t){return(await e.loadEngine()).validateUnary(t)}async function s(){return(await e.loadEngine()).getCompletions()}exports.evaluate=t,exports.evaluateSync=r,exports.evaluateUnary=n,exports.evaluateUnarySync=i,exports.getCompletions=s,exports.validate=a,exports.validateUnary=o;

package/dist/cjs/engine/intellisense.cjs

@@ -0,0 +1 @@
+const e=require("./loader.cjs"),t=require("./messages.cjs");function n(e){let t=e.split(` at `),n=t.length<=1?void 0:t.at(-1);if(n===void 0)return null;let[r,i]=n.replace(`(`,``).replace(`)`,``).split(`, `),a=r===void 0?NaN:Number.parseInt(r,10);if(Number.isNaN(a))return null;if(i===void 0)return a;let o=Number.parseInt(i,10);return Number.isNaN(o)?a:[a,o]}function r(e,r){if(e==null)return null;let i=e,a=typeof i.source==`string`?i.source:String(e),o=n(a),[s,c]=o===null?[0,r.length]:typeof o==`number`?[o,o]:o;return{from:s,to:c,message:a,source:t.localizeSourceLabel(i.type)}}function i(e){return Array.isArray(e)?e.flatMap(e=>{let n=e;return typeof n.label!=`string`||n.label===``?[]:[{type:n.type===`method`||n.type===`variable`?n.type:`function`,label:n.label,detail:typeof n.detail==`string`?n.detail.replaceAll("`",``):``,info:t.localizeCompletionInfo(typeof n.info==`string`?n.info:``),boost:typeof n.boost==`number`?n.boost:null,methodFor:typeof n.methodFor==`string`?n.methodFor:null}]}):[]}async function a(t,n){let i=await e.loadEngine();return r(n===`unary`?i.validateUnary(t):i.validate(t),t)}function o(t,n){let i=e.getEngineSync();return r(n===`unary`?i.validateUnary(t):i.validate(t),t)}async function s(){return i((await e.loadEngine()).getCompletions())}function c(){return i(e.getEngineSync().getCompletions())}async function l(t,n,r){return(await e.loadEngine()).analyze(t,n,r===`unary`)}function u(t,n,r){return e.getEngineSync().analyze(t,n,r===`unary`)}async function d(t,n){return(await e.loadEngine()).satisfies(t,n)}function f(t,n){return e.getEngineSync().satisfies(t,n)}exports.analyzeTypes=l,exports.analyzeTypesSync=u,exports.getCompletionItems=s,exports.getCompletionItemsSync=c,exports.getDiagnostics=a,exports.getDiagnosticsSync=o,exports.satisfiesType=d,exports.satisfiesTypeSync=f;

package/dist/cjs/engine/loader.cjs

@@ -0,0 +1 @@
+const e=require("./errors.cjs");let t=require("@vef-framework-react/shared");var n=null,r=null,i=null,a;function o(t,n){try{return n()}catch(n){throw new e.ExpressionError(`Failed to evaluate expression: ${t}`,t,n)}}function s(){let e=`Failed to load the ZEN expression engine`;return(0,t.isUndefined)(globalThis.window)?`${e}. In a non-browser host (Node / SSR) the wasm cannot be auto-resolved; call configureEngine({ wasmInput }) with the wasm bytes or URL before loading.`:e}function c(t){if(n||r)throw new e.ExpressionError(`configureEngine() must be called before the engine loads.`);a=t.wasmInput}function l(){return n||(i=null,n=(async()=>{let e=await import(`@gorules/zen-engine-wasm`);await e.default((0,t.isUndefined)(a)?void 0:{module_or_path:a});let n=Object.freeze({evaluate:(t,n={})=>o(t,()=>e.evaluateExpression(t,n)),evaluateUnary:(t,n={})=>o(t,()=>e.evaluateUnaryExpression(t,n)),validate:t=>e.validateExpression(t),validateUnary:t=>e.validateUnaryExpression(t),getCompletions:()=>e.getCompletions(),analyze:(t,n,r)=>{let i=e.VariableType.fromJson(t);try{let e=i.toJson(),t=r?i.typeCheckUnary(n):i.typeCheck(n);return{rootKind:e,spans:Array.isArray(t)?t:[]}}finally{i.free()}},satisfies:(t,n)=>{let r=e.VariableType.fromJson(t),i=e.VariableType.fromJson(n);try{return r.satisfies(i)}finally{r.free(),i.free()}},isReady:()=>e.isReady()});return r=n,n})().catch(t=>{throw n=null,i=new e.ExpressionError(s(),void 0,t),i}),n)}function u(){return r?.isReady()??!1}function d(){return i}function f(){if(!r)throw new e.ExpressionNotReadyError;return r}exports.configureEngine=c,exports.getEngineError=d,exports.getEngineSync=f,exports.isEngineReady=u,exports.loadEngine=l;

package/dist/cjs/engine/messages.cjs

@@ -0,0 +1 @@
+var e=`en-US`;function t(t){e=t}function n(){return e}var r={"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":`检查日期所在年份是否为闰年`};function i(t){return e!==`zh-CN`||t===``?t:r[t]??t}var a={"en-US":{lexerError:`Lexer error`,parserError:`Parser error`,compilerError:`Compiler error`,vmError:`VM error`,fallback:`Error`},"zh-CN":{lexerError:`词法错误`,parserError:`语法错误`,compilerError:`编译错误`,vmError:`运行时错误`,fallback:`错误`}};function o(t){let n=a[e];return(t===void 0?void 0:n[t])??n.fallback}exports.getExpressionLocale=n,exports.localizeCompletionInfo=i,exports.localizeSourceLabel=o,exports.setExpressionLocale=t;

package/dist/cjs/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./engine/errors.cjs"),t=require("./engine/loader.cjs"),n=require("./condition/compile.cjs"),r=require("./condition/types.cjs"),i=require("./engine/evaluate.cjs"),a=require("./engine/messages.cjs"),o=require("./engine/intellisense.cjs");exports.CONDITION_OPERATORS=r.CONDITION_OPERATORS,exports.ExpressionError=e.ExpressionError,exports.ExpressionNotReadyError=e.ExpressionNotReadyError,exports.analyzeTypes=o.analyzeTypes,exports.analyzeTypesSync=o.analyzeTypesSync,exports.compileBranch=n.compileBranch,exports.compileCondition=n.compileCondition,exports.compileGroup=n.compileGroup,exports.configureEngine=t.configureEngine,exports.evaluate=i.evaluate,exports.evaluateSync=i.evaluateSync,exports.evaluateUnary=i.evaluateUnary,exports.evaluateUnarySync=i.evaluateUnarySync,exports.getCompletionItems=o.getCompletionItems,exports.getCompletionItemsSync=o.getCompletionItemsSync,exports.getCompletions=i.getCompletions,exports.getDiagnostics=o.getDiagnostics,exports.getDiagnosticsSync=o.getDiagnosticsSync,exports.getEngineError=t.getEngineError,exports.getEngineSync=t.getEngineSync,exports.getExpressionLocale=a.getExpressionLocale,exports.isEngineReady=t.isEngineReady,exports.loadEngine=t.loadEngine,exports.satisfiesType=o.satisfiesType,exports.satisfiesTypeSync=o.satisfiesTypeSync,exports.selectBranch=n.selectBranch,exports.selectBranchWith=n.selectBranchWith,exports.setExpressionLocale=a.setExpressionLocale,exports.toZenLiteral=n.toZenLiteral,exports.validate=i.validate,exports.validateUnary=i.validateUnary;

package/dist/cjs/react/context.cjs

@@ -0,0 +1 @@
+var e=(0,require("react").createContext)(null);exports.ExpressionEngineContext=e;

package/dist/cjs/react/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./provider.cjs"),t=require("./use-expression-engine.cjs");exports.ExpressionEngineProvider=e.ExpressionEngineProvider,exports.useExpressionEngine=t.useExpressionEngine;

package/dist/cjs/react/provider.cjs

@@ -0,0 +1 @@
+const e=require("../engine/loader.cjs"),t=require("../engine/messages.cjs"),n=require("./context.cjs");let r=require("react"),i=require("react/jsx-runtime");function a({children:t}){if(!e.isEngineReady())throw e.getEngineError()||e.loadEngine();let r=e.getEngineSync();return(0,i.jsx)(n.ExpressionEngineContext,{value:r,children:t})}var o=({children:e,fallback:n=null,locale:o})=>(o!==void 0&&t.setExpressionLocale(o),(0,i.jsx)(r.Suspense,{fallback:n,children:(0,i.jsx)(a,{children:e})}));exports.ExpressionEngineProvider=o;

package/dist/cjs/react/use-expression-engine.cjs

@@ -0,0 +1 @@
+const e=require("./context.cjs");let t=require("react");function n(){let n=(0,t.use)(e.ExpressionEngineContext);if(!n)throw Error(`useExpressionEngine must be used within <ExpressionEngineProvider>.`);return n}exports.useExpressionEngine=n;

package/dist/es/condition/compile.js

@@ -0,0 +1,91 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { ExpressionError as e } from "../engine/errors.js";
+import { loadEngine as t } from "../engine/loader.js";
+import { isArray as n, isNullish as r, isString as i } from "@vef-framework-react/shared";
+//#region src/condition/compile.ts
+var a = /^[A-Z_$][\w$]*(?:\.[A-Z_$][\w$]*|\[\d+\])*$/i;
+function o(t) {
+	if (r(t)) return "null";
+	if (typeof t == "number" || typeof t == "boolean" || typeof t == "bigint") return String(t);
+	if (i(t)) return s(t);
+	if (n(t)) return `[${t.map((e) => o(e)).join(", ")}]`;
+	throw new e(`Value of type "${typeof t}" has no ZEN literal representation`);
+}
+function s(t) {
+	let n = t.includes("'"), r = t.includes("\"");
+	if (n && r) throw new e("String contains both single and double quotes and has no ZEN literal representation");
+	return n ? `"${t}"` : `'${t}'`;
+}
+function c(e) {
+	return n(e) ? o(e) : `[${o(e)}]`;
+}
+function l(e) {
+	return `(${e} == null or (type(${e}) == 'string' and len(trim(${e})) == 0) or (type(${e}) == 'array' and len(${e}) == 0))`;
+}
+function u(t, n, r) {
+	switch (n) {
+		case "eq": return `${t} == ${o(r)}`;
+		case "ne": return `${t} != ${o(r)}`;
+		case "gt": return `${t} > ${o(r)}`;
+		case "gte": return `${t} >= ${o(r)}`;
+		case "lt": return `${t} < ${o(r)}`;
+		case "lte": return `${t} <= ${o(r)}`;
+		case "contains": return `contains(${t}, ${o(r)})`;
+		case "not_contains": return `not contains(${t}, ${o(r)})`;
+		case "starts_with": return `startsWith(${t}, ${o(r)})`;
+		case "ends_with": return `endsWith(${t}, ${o(r)})`;
+		case "in": return `${t} in ${c(r)}`;
+		case "not_in": return `not (${t} in ${c(r)})`;
+		case "is_empty": return l(t);
+		case "is_not_empty": return `not ${l(t)}`;
+		default: throw new e(`Unsupported operator: ${String(n)}`);
+	}
+}
+function d(e) {
+	if (e.kind === "expression") {
+		let t = e.expression.trim();
+		return t === "" ? null : t;
+	}
+	let t = e.subject.trim();
+	if (!a.test(t)) return null;
+	try {
+		return u(t, e.operator, e.value);
+	} catch {
+		return null;
+	}
+}
+function f(e) {
+	let t = e.conditions.map((e) => d(e)).filter((e) => e !== null);
+	return t.length === 0 ? null : t.join(" and ");
+}
+function p(e) {
+	let t = (e.conditionGroups ?? []).map((e) => f(e)).filter((e) => e !== null);
+	return t.length === 0 ? null : t.map((e) => `(${e})`).join(" or ");
+}
+function m(e, t, n) {
+	let r = e.toSorted((e, t) => e.priority - t.priority);
+	for (let e of r) {
+		if (e.isDefault) continue;
+		let r = p(e);
+		if (r !== null && h(n, r, t)) return {
+			branchId: e.id,
+			matched: !0
+		};
+	}
+	return {
+		branchId: r.find((e) => e.isDefault)?.id ?? null,
+		matched: !1
+	};
+}
+function h(e, t, n) {
+	try {
+		return e.evaluate(t, n) === !0;
+	} catch {
+		return !1;
+	}
+}
+async function g(e, n) {
+	return m(e, n, await t());
+}
+//#endregion
+export { p as compileBranch, d as compileCondition, f as compileGroup, g as selectBranch, m as selectBranchWith, o as toZenLiteral };

package/dist/es/condition/types.js

@@ -0,0 +1,20 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+//#region src/condition/types.ts
+var e = [
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"contains",
+	"not_contains",
+	"starts_with",
+	"ends_with",
+	"in",
+	"not_in",
+	"is_empty",
+	"is_not_empty"
+];
+//#endregion
+export { e as CONDITION_OPERATORS };

package/dist/es/engine/errors.js

@@ -0,0 +1,14 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+//#region src/engine/errors.ts
+var e = class extends Error {
+	expression;
+	constructor(e, t, n) {
+		super(e, { cause: n }), this.name = "ExpressionError", this.expression = t;
+	}
+}, t = class extends e {
+	constructor(e = "Expression engine is not initialized. Await loadEngine() or render under <ExpressionEngineProvider>.") {
+		super(e), this.name = "ExpressionNotReadyError";
+	}
+};
+//#endregion
+export { e as ExpressionError, t as ExpressionNotReadyError };

package/dist/es/engine/evaluate.js

@@ -0,0 +1,26 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { getEngineSync as e, loadEngine as t } from "./loader.js";
+//#region src/engine/evaluate.ts
+async function n(e, n) {
+	return (await t()).evaluate(e, n);
+}
+async function r(e, n) {
+	return (await t()).evaluateUnary(e, n);
+}
+function i(t, n) {
+	return e().evaluate(t, n);
+}
+function a(t, n) {
+	return e().evaluateUnary(t, n);
+}
+async function o(e) {
+	return (await t()).validate(e);
+}
+async function s(e) {
+	return (await t()).validateUnary(e);
+}
+async function c() {
+	return (await t()).getCompletions();
+}
+//#endregion
+export { n as evaluate, i as evaluateSync, r as evaluateUnary, a as evaluateUnarySync, c as getCompletions, o as validate, s as validateUnary };

package/dist/es/engine/intellisense.js

@@ -0,0 +1,64 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { getEngineSync as e, loadEngine as t } from "./loader.js";
+import { localizeCompletionInfo as n, localizeSourceLabel as r } from "./messages.js";
+//#region src/engine/intellisense.ts
+function i(e) {
+	let t = e.split(" at "), n = t.length <= 1 ? void 0 : t.at(-1);
+	if (n === void 0) return null;
+	let [r, i] = n.replace("(", "").replace(")", "").split(", "), a = r === void 0 ? NaN : Number.parseInt(r, 10);
+	if (Number.isNaN(a)) return null;
+	if (i === void 0) return a;
+	let o = Number.parseInt(i, 10);
+	return Number.isNaN(o) ? a : [a, o];
+}
+function a(e, t) {
+	if (e == null) return null;
+	let n = e, a = typeof n.source == "string" ? n.source : String(e), o = i(a), [s, c] = o === null ? [0, t.length] : typeof o == "number" ? [o, o] : o;
+	return {
+		from: s,
+		to: c,
+		message: a,
+		source: r(n.type)
+	};
+}
+function o(e) {
+	return Array.isArray(e) ? e.flatMap((e) => {
+		let t = e;
+		return typeof t.label != "string" || t.label === "" ? [] : [{
+			type: t.type === "method" || t.type === "variable" ? t.type : "function",
+			label: t.label,
+			detail: typeof t.detail == "string" ? t.detail.replaceAll("`", "") : "",
+			info: n(typeof t.info == "string" ? t.info : ""),
+			boost: typeof t.boost == "number" ? t.boost : null,
+			methodFor: typeof t.methodFor == "string" ? t.methodFor : null
+		}];
+	}) : [];
+}
+async function s(e, n) {
+	let r = await t();
+	return a(n === "unary" ? r.validateUnary(e) : r.validate(e), e);
+}
+function c(t, n) {
+	let r = e();
+	return a(n === "unary" ? r.validateUnary(t) : r.validate(t), t);
+}
+async function l() {
+	return o((await t()).getCompletions());
+}
+function u() {
+	return o(e().getCompletions());
+}
+async function d(e, n, r) {
+	return (await t()).analyze(e, n, r === "unary");
+}
+function f(t, n, r) {
+	return e().analyze(t, n, r === "unary");
+}
+async function p(e, n) {
+	return (await t()).satisfies(e, n);
+}
+function m(t, n) {
+	return e().satisfies(t, n);
+}
+//#endregion
+export { d as analyzeTypes, f as analyzeTypesSync, l as getCompletionItems, u as getCompletionItemsSync, s as getDiagnostics, c as getDiagnosticsSync, p as satisfiesType, m as satisfiesTypeSync };

package/dist/es/engine/loader.js

@@ -0,0 +1,69 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { ExpressionError as e, ExpressionNotReadyError as t } from "./errors.js";
+import { isUndefined as n } from "@vef-framework-react/shared";
+//#region src/engine/loader.ts
+var r = null, i = null, a = null, o;
+function s(t, n) {
+	try {
+		return n();
+	} catch (n) {
+		throw new e(`Failed to evaluate expression: ${t}`, t, n);
+	}
+}
+function c() {
+	let e = "Failed to load the ZEN expression engine";
+	return n(globalThis.window) ? `${e}. In a non-browser host (Node / SSR) the wasm cannot be auto-resolved; call configureEngine({ wasmInput }) with the wasm bytes or URL before loading.` : e;
+}
+function l(t) {
+	if (r || i) throw new e("configureEngine() must be called before the engine loads.");
+	o = t.wasmInput;
+}
+function u() {
+	return r || (a = null, r = (async () => {
+		let e = await import("@gorules/zen-engine-wasm");
+		await e.default(n(o) ? void 0 : { module_or_path: o });
+		let t = Object.freeze({
+			evaluate: (t, n = {}) => s(t, () => e.evaluateExpression(t, n)),
+			evaluateUnary: (t, n = {}) => s(t, () => e.evaluateUnaryExpression(t, n)),
+			validate: (t) => e.validateExpression(t),
+			validateUnary: (t) => e.validateUnaryExpression(t),
+			getCompletions: () => e.getCompletions(),
+			analyze: (t, n, r) => {
+				let i = e.VariableType.fromJson(t);
+				try {
+					let e = i.toJson(), t = r ? i.typeCheckUnary(n) : i.typeCheck(n);
+					return {
+						rootKind: e,
+						spans: Array.isArray(t) ? t : []
+					};
+				} finally {
+					i.free();
+				}
+			},
+			satisfies: (t, n) => {
+				let r = e.VariableType.fromJson(t), i = e.VariableType.fromJson(n);
+				try {
+					return r.satisfies(i);
+				} finally {
+					r.free(), i.free();
+				}
+			},
+			isReady: () => e.isReady()
+		});
+		return i = t, t;
+	})().catch((t) => {
+		throw r = null, a = new e(c(), void 0, t), a;
+	}), r);
+}
+function d() {
+	return i?.isReady() ?? !1;
+}
+function f() {
+	return a;
+}
+function p() {
+	if (!i) throw new t();
+	return i;
+}
+//#endregion
+export { l as configureEngine, f as getEngineError, p as getEngineSync, d as isEngineReady, u as loadEngine };

package/dist/es/engine/messages.js

@@ -0,0 +1,122 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+//#region src/engine/messages.ts
+var e = "en-US";
+function t(t) {
+	e = t;
+}
+function n() {
+	return e;
+}
+var r = {
+	"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": "检查日期所在年份是否为闰年"
+};
+function i(t) {
+	return e !== "zh-CN" || t === "" ? t : r[t] ?? t;
+}
+var a = {
+	"en-US": {
+		lexerError: "Lexer error",
+		parserError: "Parser error",
+		compilerError: "Compiler error",
+		vmError: "VM error",
+		fallback: "Error"
+	},
+	"zh-CN": {
+		lexerError: "词法错误",
+		parserError: "语法错误",
+		compilerError: "编译错误",
+		vmError: "运行时错误",
+		fallback: "错误"
+	}
+};
+function o(t) {
+	let n = a[e];
+	return (t === void 0 ? void 0 : n[t]) ?? n.fallback;
+}
+//#endregion
+export { n as getExpressionLocale, i as localizeCompletionInfo, o as localizeSourceLabel, t as setExpressionLocale };

package/dist/es/index.js

@@ -0,0 +1,9 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { ExpressionError as e, ExpressionNotReadyError as t } from "./engine/errors.js";
+import { configureEngine as n, getEngineError as r, getEngineSync as i, isEngineReady as a, loadEngine as o } from "./engine/loader.js";
+import { compileBranch as s, compileCondition as c, compileGroup as l, selectBranch as u, selectBranchWith as d, toZenLiteral as f } from "./condition/compile.js";
+import { CONDITION_OPERATORS as p } from "./condition/types.js";
+import { evaluate as m, evaluateSync as h, evaluateUnary as g, evaluateUnarySync as _, getCompletions as v, validate as y, validateUnary as b } from "./engine/evaluate.js";
+import { getExpressionLocale as x, setExpressionLocale as S } from "./engine/messages.js";
+import { analyzeTypes as C, analyzeTypesSync as w, getCompletionItems as T, getCompletionItemsSync as E, getDiagnostics as D, getDiagnosticsSync as O, satisfiesType as k, satisfiesTypeSync as A } from "./engine/intellisense.js";
+export { p as CONDITION_OPERATORS, e as ExpressionError, t as ExpressionNotReadyError, C as analyzeTypes, w as analyzeTypesSync, s as compileBranch, c as compileCondition, l as compileGroup, n as configureEngine, m as evaluate, h as evaluateSync, g as evaluateUnary, _ as evaluateUnarySync, T as getCompletionItems, E as getCompletionItemsSync, v as getCompletions, D as getDiagnostics, O as getDiagnosticsSync, r as getEngineError, i as getEngineSync, x as getExpressionLocale, a as isEngineReady, o as loadEngine, k as satisfiesType, A as satisfiesTypeSync, u as selectBranch, d as selectBranchWith, S as setExpressionLocale, f as toZenLiteral, y as validate, b as validateUnary };

package/dist/es/react/context.js

@@ -0,0 +1,6 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { createContext as e } from "react";
+//#region src/react/context.ts
+var t = e(null);
+//#endregion
+export { t as ExpressionEngineContext };

package/dist/es/react/index.js

@@ -0,0 +1,4 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { ExpressionEngineProvider as e } from "./provider.js";
+import { useExpressionEngine as t } from "./use-expression-engine.js";
+export { e as ExpressionEngineProvider, t as useExpressionEngine };

package/dist/es/react/provider.js

@@ -0,0 +1,20 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { getEngineError as e, getEngineSync as t, isEngineReady as n, loadEngine as r } from "../engine/loader.js";
+import { setExpressionLocale as i } from "../engine/messages.js";
+import { ExpressionEngineContext as a } from "./context.js";
+import { Suspense as o } from "react";
+import { jsx as s } from "react/jsx-runtime";
+//#region src/react/provider.tsx
+function c({ children: i }) {
+	if (!n()) throw e() || r();
+	return /* @__PURE__ */ s(a, {
+		value: t(),
+		children: i
+	});
+}
+var l = ({ children: e, fallback: t = null, locale: n }) => (n !== void 0 && i(n), /* @__PURE__ */ s(o, {
+	fallback: t,
+	children: /* @__PURE__ */ s(c, { children: e })
+}));
+//#endregion
+export { l as ExpressionEngineProvider };

package/dist/es/react/use-expression-engine.js

@@ -0,0 +1,11 @@
+/*! @vef-framework-react/expression v2.4.0 made by Venus | 2026-06-15T15:10:07.346Z */
+import { ExpressionEngineContext as e } from "./context.js";
+import { use as t } from "react";
+//#region src/react/use-expression-engine.ts
+function n() {
+	let n = t(e);
+	if (!n) throw Error("useExpressionEngine must be used within <ExpressionEngineProvider>.");
+	return n;
+}
+//#endregion
+export { n as useExpressionEngine };

package/dist/types/src/condition/compile.d.ts

@@ -0,0 +1,49 @@
+import { ExpressionContext, ExpressionEngine } from '../engine/loader';
+import { BranchSelection, ConditionBranchInput, ConditionGroupInput, ConditionInput } from './types';
+/**
+ * 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.
+ */
+export declare function toZenLiteral(value: unknown): string;
+/**
+ * Compile a single condition into a ZEN boolean expression. Field conditions map
+ * their operator to ZEN; expression conditions pass through verbatim. Returns
+ * `null` when the condition is empty, its subject is not an identifier path, or
+ * its value has no ZEN representation.
+ */
+export declare function compileCondition(condition: ConditionInput): string | null;
+/**
+ * Compile a condition group (its conditions joined with AND). Returns `null`
+ * when the group has no compilable conditions.
+ */
+export declare function compileGroup(group: ConditionGroupInput): string | null;
+/**
+ * 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).
+ */
+export declare function compileBranch(branch: ConditionBranchInput): string | null;
+/**
+ * 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.
+ */
+export declare function selectBranchWith(branches: ConditionBranchInput[], context: ExpressionContext, engine: Pick<ExpressionEngine, "evaluate" | "validate">): BranchSelection;
+/**
+ * Pick the matching branch for the given context, loading the ZEN engine on
+ * first use. See {@link selectBranchWith} for the selection semantics.
+ */
+export declare function selectBranch(branches: ConditionBranchInput[], context: ExpressionContext): Promise<BranchSelection>;

package/dist/types/src/condition/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+export declare const CONDITION_OPERATORS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "contains", "not_contains", "starts_with", "ends_with", "in", "not_in", "is_empty", "is_not_empty"];
+/**
+ * Operators understood by {@link compileCondition}. The compiler maps each to a
+ * ZEN expression; this closed set is the single source of truth for the operator
+ * vocabulary (the flow editor shares it instead of re-declaring its own).
+ */
+export type ConditionOperator = typeof CONDITION_OPERATORS[number];
+/**
+ * A field/operator/value condition.
+ */
+export interface FieldConditionInput {
+    kind: "field";
+    /**
+     * The field path the operator tests. Emitted **verbatim** into the compiled
+     * ZEN source as a path expression (guarded by an identifier-path pattern),
+     * unlike `value`, which is serialized to a ZEN literal — so callers must supply
+     * a valid identifier path, not arbitrary user text.
+     */
+    subject: string;
+    operator: ConditionOperator;
+    value: unknown;
+}
+/**
+ * A raw ZEN expression condition, passed through to the engine verbatim.
+ */
+export interface ExpressionConditionInput {
+    kind: "expression";
+    expression: string;
+}
+/**
+ * A single condition: either a field/operator/value triple or a raw expression.
+ */
+export type ConditionInput = FieldConditionInput | ExpressionConditionInput;
+/**
+ * A group of conditions, combined with AND.
+ */
+export interface ConditionGroupInput {
+    conditions: ConditionInput[];
+}
+/**
+ * A branch guarded by one or more condition groups (combined with OR).
+ */
+export interface ConditionBranchInput {
+    id: string;
+    priority: number;
+    isDefault?: boolean;
+    conditionGroups?: ConditionGroupInput[];
+}
+/**
+ * The branch chosen by {@link selectBranch}. `matched` is true only when a
+ * non-default branch's expression evaluated true (then `branchId` is that
+ * branch's id). On the default-branch fallback `matched` is false while
+ * `branchId` is the default's id; `branchId` is null only when nothing matched
+ * and there is no default branch.
+ */
+export type BranchSelection = {
+    matched: true;
+    branchId: string;
+} | {
+    matched: false;
+    branchId: string | null;
+};

package/dist/types/src/engine/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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}.
+ */
+export declare class ExpressionError extends Error {
+    readonly expression?: string;
+    constructor(message: string, expression?: string, cause?: unknown);
+}
+/**
+ * Raised by the synchronous evaluation helpers when the engine has not finished
+ * initializing yet. Await {@link loadEngine} (or render under
+ * `<ExpressionEngineProvider>`) before evaluating synchronously.
+ */
+export declare class ExpressionNotReadyError extends ExpressionError {
+    constructor(message?: string);
+}

package/dist/types/src/engine/evaluate.d.ts

@@ -0,0 +1,36 @@
+import { ExpressionContext } from './loader';
+/**
+ * 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.
+ */
+export declare function evaluate<T = unknown>(expression: string, context?: ExpressionContext): Promise<T>;
+/**
+ * Evaluate a ZEN unary (test) expression, loading the engine on first use.
+ */
+export declare function evaluateUnary(expression: string, context?: ExpressionContext): Promise<boolean>;
+/**
+ * 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>`).
+ */
+export declare function evaluateSync<T = unknown>(expression: string, context?: ExpressionContext): T;
+/**
+ * Evaluate a ZEN unary (test) expression synchronously. Throws
+ * {@link ExpressionNotReadyError} when the engine has not loaded yet.
+ */
+export declare function evaluateUnarySync(expression: string, context?: ExpressionContext): boolean;
+/**
+ * Validate a standard expression, loading the engine on first use.
+ */
+export declare function validate(expression: string): Promise<unknown>;
+/**
+ * Validate a unary expression, loading the engine on first use.
+ */
+export declare function validateUnary(expression: string): Promise<unknown>;
+/**
+ * Return ZEN completion metadata, loading the engine on first use.
+ */
+export declare function getCompletions(): Promise<unknown>;

package/dist/types/src/engine/intellisense.d.ts

@@ -0,0 +1,123 @@
+import { VariableTypeJson } from '@gorules/zen-engine-wasm';
+/**
+ * Whether an expression is a standard value expression or a unary (test) expression.
+ */
+export type ExpressionMode = "standard" | "unary";
+/**
+ * A ZEN type descriptor — the shape the engine understands for type-aware
+ * completion and validation. Structurally identical to the wasm
+ * `VariableTypeJson`: a primitive (`"String"`, `"Number"`, `"Bool"`, ...) or one
+ * of `{ Object }`, `{ Array }`, `{ Const }`, `{ Enum }`.
+ */
+export type ExpressionType = VariableTypeJson;
+/**
+ * A single syntax / type diagnostic, positioned by character offset.
+ */
+export interface ExpressionDiagnostic {
+    /**
+     * Start offset in the source.
+     */
+    from: number;
+    /**
+     * End offset in the source.
+     */
+    to: number;
+    /**
+     * Human-readable error message.
+     */
+    message: string;
+    /**
+     * Diagnostic origin label (e.g. `"Parser error"`).
+     */
+    source: string;
+}
+/**
+ * An autocomplete suggestion for a ZEN built-in (function / method / variable).
+ */
+export interface ExpressionCompletion {
+    type: "function" | "method" | "variable";
+    label: string;
+    detail: string;
+    info: string;
+    boost: number | null;
+    /**
+     * For methods, the type-kind they attach to (e.g. `"Date"`); otherwise `null`.
+     */
+    methodFor: string | null;
+}
+/**
+ * The inferred type of one span of the source, produced by type-checking.
+ */
+export interface ExpressionTypeSpan {
+    error: string | null;
+    kind: ExpressionType;
+    nodeKind: string;
+    span: [number, number];
+}
+/**
+ * The result of type-checking an expression against a variable context.
+ */
+export interface ExpressionAnalysis {
+    /**
+     * The root context type (the variables object).
+     */
+    rootKind: ExpressionType;
+    /**
+     * Per-span inferred types; `spans[0]` is the whole-expression result type.
+     */
+    spans: ExpressionTypeSpan[];
+}
+/**
+ * Parse a trailing `... at (from, to)` / `... at pos` position out of a ZEN error
+ * message. Returns a `[from, to]` range, a single offset, or `null` when absent.
+ */
+export declare function extractPosition(message: string): [number, number] | number | null;
+/**
+ * Normalize the wasm validate payload (`null` or `{ type, source }`) into a
+ * positioned {@link ExpressionDiagnostic}, or `null` when the expression is valid.
+ */
+export declare function normalizeDiagnostic(raw: unknown, source: string): ExpressionDiagnostic | null;
+/**
+ * Normalize the wasm `getCompletions` payload into a typed list, dropping
+ * malformed entries and stripping the backtick markers ZEN wraps type names in.
+ */
+export declare function normalizeCompletions(raw: unknown): ExpressionCompletion[];
+/**
+ * Validate an expression, loading the engine on first use. Resolves to `null`
+ * when the expression is valid, or a positioned diagnostic otherwise.
+ */
+export declare function getDiagnostics(expression: string, mode: ExpressionMode): Promise<ExpressionDiagnostic | null>;
+/**
+ * Synchronous {@link getDiagnostics}. Throws `ExpressionNotReadyError` if the
+ * engine has not loaded yet — use only behind a readiness gate.
+ */
+export declare function getDiagnosticsSync(expression: string, mode: ExpressionMode): ExpressionDiagnostic | null;
+/**
+ * Return the ZEN built-in completion list, loading the engine on first use.
+ */
+export declare function getCompletionItems(): Promise<ExpressionCompletion[]>;
+/**
+ * Synchronous {@link getCompletionItems}. Throws `ExpressionNotReadyError` if the
+ * engine has not loaded yet.
+ */
+export declare function getCompletionItemsSync(): ExpressionCompletion[];
+/**
+ * Type-check an expression against a `variables` context, loading the engine on
+ * first use. See {@link ExpressionAnalysis}.
+ */
+export declare function analyzeTypes(variables: ExpressionType, source: string, mode: ExpressionMode): Promise<ExpressionAnalysis>;
+/**
+ * Synchronous {@link analyzeTypes}. Throws `ExpressionNotReadyError` if the
+ * engine has not loaded yet.
+ */
+export declare function analyzeTypesSync(variables: ExpressionType, source: string, mode: ExpressionMode): ExpressionAnalysis;
+/**
+ * Whether `actual` satisfies (is assignable to) `expected`, loading the engine on
+ * first use. Used for expected-return-type validation.
+ */
+export declare function satisfiesType(actual: ExpressionType, expected: ExpressionType): Promise<boolean>;
+/**
+ * Synchronous {@link satisfiesType}. Throws `ExpressionNotReadyError` if the
+ * engine has not loaded yet.
+ */
+export declare function satisfiesTypeSync(actual: ExpressionType, expected: ExpressionType): boolean;

package/dist/types/src/engine/loader.d.ts

@@ -0,0 +1,102 @@
+import { InitInput } from '@gorules/zen-engine-wasm';
+import { ExpressionAnalysis, ExpressionType } from './intellisense';
+import { ExpressionError } from './errors';
+/**
+ * The data an expression reads from. Property paths in the expression (e.g.
+ * `customer.name`) resolve against this object.
+ */
+export type ExpressionContext = Record<string, unknown>;
+export interface LoadEngineOptions {
+    /**
+     * Override how the wasm binary is located. By default the engine resolves the
+     * co-located `.wasm` through the GoRules package's own `import.meta.url`,
+     * which the host bundler (Vite / webpack) rewrites to a served asset URL — no
+     * option is needed in normal browser app setups. Supply a URL / Response /
+     * bytes for exotic hosting (CDN, embedded buffer) or for a non-browser host
+     * (Node / SSR), where `import.meta.url` asset resolution does not work and the
+     * input must be provided explicitly. Aliased to the wasm initializer's own
+     * `InitInput` so it never drifts from the dependency.
+     */
+    wasmInput?: InitInput;
+}
+/**
+ * The initialized ZEN expression engine. Every method is synchronous — obtain
+ * an instance via {@link loadEngine} (async, loads the wasm) before calling.
+ */
+export interface ExpressionEngine {
+    /**
+     * Evaluate a standard ZEN expression, returning its computed value.
+     */
+    evaluate: <T = unknown>(expression: string, context?: ExpressionContext) => T;
+    /**
+     * Evaluate a ZEN unary (test) expression, returning a boolean.
+     */
+    evaluateUnary: (expression: string, context?: ExpressionContext) => boolean;
+    /**
+     * Validate a standard expression; returns ZEN's diagnostic payload (`null`
+     * when the expression parses, an error object otherwise).
+     */
+    validate: (expression: string) => unknown;
+    /**
+     * Validate a unary expression; returns ZEN's diagnostic payload.
+     */
+    validateUnary: (expression: string) => unknown;
+    /**
+     * Return ZEN's completion metadata, for building an expression editor.
+     */
+    getCompletions: () => unknown;
+    /**
+     * Type-check `source` against a `variables` context, returning the root context
+     * type and the inferred type of every span (`unary` selects test-expression
+     * checking). Powers an editor's type-aware completion / hover / diagnostics.
+     */
+    analyze: (variables: ExpressionType, source: string, unary: boolean) => ExpressionAnalysis;
+    /**
+     * Whether `actual` satisfies (is assignable to) `expected`. Powers
+     * expected-return-type validation in an editor.
+     */
+    satisfies: (actual: ExpressionType, expected: ExpressionType) => boolean;
+    /**
+     * Whether the underlying wasm module reports itself ready.
+     */
+    isReady: () => boolean;
+}
+/**
+ * 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.
+ */
+export declare function configureEngine(options: LoadEngineOptions): void;
+/**
+ * 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.
+ */
+export declare function loadEngine(): Promise<ExpressionEngine>;
+/**
+ * Whether the engine has finished initializing and is ready for sync use.
+ */
+export declare function isEngineReady(): boolean;
+/**
+ * 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}.
+ */
+export declare function getEngineError(): ExpressionError | null;
+/**
+ * Return the already-initialized engine synchronously, or throw
+ * {@link ExpressionNotReadyError} if {@link loadEngine} has not resolved yet.
+ */
+export declare function getEngineSync(): ExpressionEngine;
+/**
+ * Reset the singleton. Intended for tests only.
+ */
+export declare function resetEngine(): void;

package/dist/types/src/engine/messages.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The display language for engine-produced text (built-in descriptions and
+ * diagnostic labels). Defaults to `"en-US"`; a host opts into Chinese with
+ * {@link setExpressionLocale}. Identifiers, type signatures and the wasm's own
+ * error message bodies are never translated — only descriptive prose is.
+ */
+export type ExpressionLocale = "en-US" | "zh-CN";
+/**
+ * Set the active locale for engine-produced descriptive text. Module-global (the
+ * sync editor accessors read it without a React context), mirroring the engine
+ * singleton itself. Defaults to `"en-US"` so published consumers are unaffected.
+ */
+export declare function setExpressionLocale(locale: ExpressionLocale): void;
+/**
+ * The active locale set by {@link setExpressionLocale}.
+ */
+export declare function getExpressionLocale(): ExpressionLocale;
+/**
+ * Translate a built-in's English `info` description to the active locale, or
+ * return it unchanged when the locale is English, the description is empty, or no
+ * translation exists.
+ */
+export declare function localizeCompletionInfo(info: string): string;
+/**
+ * The localized diagnostic origin label for a wasm error `type`
+ * (`"parserError"` → `"语法错误"`), or the locale's fallback label.
+ */
+export declare function localizeSourceLabel(type?: string): string;

package/dist/types/src/index.d.ts

@@ -0,0 +1,7 @@
+export { compileBranch, compileCondition, compileGroup, selectBranch, selectBranchWith, toZenLiteral } from './condition/compile';
+export { CONDITION_OPERATORS, type BranchSelection, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ExpressionConditionInput, type FieldConditionInput } from './condition/types';
+export { ExpressionError, ExpressionNotReadyError } from './engine/errors';
+export { evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletions, validate, validateUnary } from './engine/evaluate';
+export { analyzeTypes, analyzeTypesSync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, satisfiesType, satisfiesTypeSync, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionDiagnostic, type ExpressionMode, type ExpressionType, type ExpressionTypeSpan } from './engine/intellisense';
+export { configureEngine, getEngineError, getEngineSync, isEngineReady, loadEngine, type ExpressionContext, type ExpressionEngine, type LoadEngineOptions } from './engine/loader';
+export { getExpressionLocale, setExpressionLocale, type ExpressionLocale } from './engine/messages';

package/dist/types/src/react/context.d.ts

@@ -0,0 +1,3 @@
+import { ExpressionEngine } from '../engine/loader';
+import { Context } from 'react';
+export declare const ExpressionEngineContext: Context<ExpressionEngine | null>;

package/dist/types/src/react/index.d.ts

@@ -0,0 +1,2 @@
+export { ExpressionEngineProvider, type ExpressionEngineProviderProps } from './provider';
+export { useExpressionEngine } from './use-expression-engine';

package/dist/types/src/react/provider.d.ts

@@ -0,0 +1,23 @@
+import { FC, ReactNode } from 'react';
+import { ExpressionLocale } from '../engine/messages';
+export interface ExpressionEngineProviderProps {
+    children: ReactNode;
+    /**
+     * Shown while the wasm engine is loading. Children do not render — and thus no
+     * synchronous evaluation runs — until the engine is ready, so anything inside
+     * can rely on the engine being initialized.
+     */
+    fallback?: ReactNode;
+    /**
+     * Language for engine-produced descriptive text (built-in descriptions and
+     * diagnostic labels). Omitted leaves the module default (`"en-US"`) untouched.
+     * Equivalent to calling {@link setExpressionLocale} — provided here for hosts
+     * that already wrap their tree in this provider.
+     */
+    locale?: ExpressionLocale;
+}
+/**
+ * Loads the ZEN engine and gates its subtree behind `<Suspense>` until the wasm
+ * is initialized. Descendants read the engine via {@link useExpressionEngine}.
+ */
+export declare const ExpressionEngineProvider: FC<ExpressionEngineProviderProps>;

package/dist/types/src/react/use-expression-engine.d.ts

@@ -0,0 +1,7 @@
+import { ExpressionEngine } from '../engine/loader';
+/**
+ * Return the initialized {@link ExpressionEngine}. Must be rendered under
+ * `<ExpressionEngineProvider>`, which suspends until the wasm engine is ready —
+ * so the returned engine is always safe to evaluate against synchronously.
+ */
+export declare function useExpressionEngine(): ExpressionEngine;

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@vef-framework-react/expression",
+  "type": "module",
+  "version": "2.4.0",
+  "private": false,
+  "description": "Frontend abstraction over the GoRules ZEN expression engine (WASM) for VEF framework",
+  "author": {
+    "name": "Venus",
+    "email": "iweixiaopeng@163.com",
+    "url": "https://github.com/ilxqx"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://vef.ilxqx.com",
+  "keywords": [
+    "vef",
+    "framework",
+    "react",
+    "expression",
+    "zen",
+    "gorules",
+    "wasm"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "vef": "./src/index.ts",
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/es/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./react": {
+      "vef": "./src/react/index.ts",
+      "import": {
+        "types": "./dist/types/react/index.d.ts",
+        "default": "./dist/es/react/index.js"
+      },
+      "require": {
+        "types": "./dist/types/react/index.d.ts",
+        "default": "./dist/cjs/react/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/es/index.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@gorules/zen-engine-wasm": "0.23.1",
+    "@vef-framework-react/shared": "2.4.0"
+  },
+  "devDependencies": {
+    "react": "^19.2.7"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "build": "vite build"
+  }
+}