@idooel/expression

@idooel/expression

一个轻量、安全且强大的 JavaScript/TypeScript 表达式求值引擎。它允许你针对数据上下文解析和计算字符串表达式（例如 user.age > 18 && status === 'active'），支持 AST 缓存和严格安全模式。

它旨在作为低代码平台、动态表单规则和数据绑定系统的逻辑处理引擎。

特性

• 安全求值：不使用 eval() 或 new Function()。采用自定义解析器和解释器实现。
• AST 缓存：表达式只需编译一次即可生成 AST 并复用，提供高性能体验。
• 丰富语法：支持绝大多数 JavaScript 表达式语法（成员访问、函数调用、二元/一元运算符、三元运算、数组、对象字面量）。
• 安全防护：内置保护机制，禁止访问危险属性（如 constructor、__proto__）。支持严格模式。
• TypeScript 支持：完全使用 TypeScript 编写，提供完整的类型定义。

安装

# pnpm
pnpm add @idooel/expression

# npm
npm install @idooel/expression

# yarn
yarn add @idooel/expression

使用指南

基础求值

使用 parse 进行一次性求值。

import { parse } from '@idooel/expression'

const context = {
  user: {
    name: 'Alice',
    age: 25,
    role: 'admin'
  },
  items: [10, 20, 30]
}

// 简单比较
parse('user.age >= 18', context) // true

// 逻辑运算
parse('user.role === "admin" && items.length > 0', context) // true

// 算术运算
parse('items[0] * 2 + 5', context) // 25

// 三元运算
parse('user.age > 18 ? "成年人" : "未成年"', context) // "成年人"

编译求值 (高性能)

如果你需要多次使用不同的数据对同一个表达式进行求值，请使用 compile。这样只会解析一次 AST。

import { compile } from '@idooel/expression'

// 预编译表达式
const isAdult = compile('age >= 18')

console.log(isAdult({ age: 20 })) // true
console.log(isAdult({ age: 10 })) // false

严格模式

默认情况下，访问未定义的属性会返回 undefined。启用 strict 模式后，访问不存在的属性将抛出错误。

import { parse } from '@idooel/expression'

try {
  parse('user.address.city', { user: {} }, { strict: true })
} catch (e) {
  // 抛出 EvalError: Failed to access property "city": ...
  console.error(e.message)
}

支持的语法

• 字面量: 数字, 字符串, 布尔值, null, undefined
• 属性访问: a.b, a['b'], arr[0]
• 运算符:
  • 数学: +, -, *, /, %
  • 比较: ==, !=, ===, !==, >, <, >=, <=
  • 逻辑: &&, ||, !, ?? (空值合并)
• 函数调用: fn(a, b), obj.method()
• 构造结构: [1, 2, 3], { a: 1, b: 2 }
• 条件判断: condition ? trueVal : falseVal

安全性

引擎显式禁止访问以下属性，以防止原型污染攻击和任意代码执行漏洞（这是 eval() 类方案的常见问题）：

• constructor
• __proto__
• prototype

License

ISC