@pactor-app/expression 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,119 @@
+import { Registry } from '@pactor-app/core';
+
+/**
+ * 受控表达式 AST（设计文档第 16.1 节白名单节点）。
+ *
+ * 语法子集刻意保持最小：无赋值、无 new、无箭头函数、无数组字面量。
+ * 对象字面量（`{ name: state.x }`）仅作为白名单函数的参数载体开放
+ * （如 `t('key', { name: user.name })`），键仅允许标识符/字符串。
+ * 不支持的语法在 parse 阶段直接抛错，而不是解析后再黑名单过滤。
+ */
+type LiteralValue = string | number | boolean | null | undefined;
+interface Literal {
+    type: 'Literal';
+    value: LiteralValue;
+}
+interface Identifier {
+    type: 'Identifier';
+    name: string;
+}
+interface MemberExpression {
+    type: 'MemberExpression';
+    object: ExpressionNode;
+    property: ExpressionNode;
+    /** true: a[b]；false: a.b */
+    computed: boolean;
+}
+type BinaryOperator = '==' | '!=' | '===' | '!==' | '<' | '<=' | '>' | '>=' | '+' | '-' | '*' | '/' | '%';
+interface BinaryExpression {
+    type: 'BinaryExpression';
+    operator: BinaryOperator;
+    left: ExpressionNode;
+    right: ExpressionNode;
+}
+type LogicalOperator = '&&' | '||';
+interface LogicalExpression {
+    type: 'LogicalExpression';
+    operator: LogicalOperator;
+    left: ExpressionNode;
+    right: ExpressionNode;
+}
+type UnaryOperator = '!' | '-' | '+';
+interface UnaryExpression {
+    type: 'UnaryExpression';
+    operator: UnaryOperator;
+    argument: ExpressionNode;
+}
+interface ConditionalExpression {
+    type: 'ConditionalExpression';
+    test: ExpressionNode;
+    consequent: ExpressionNode;
+    alternate: ExpressionNode;
+}
+/**
+ * 白名单函数调用。callee 只允许直接 Identifier（如 `permission('x')`），
+ * 不允许成员方法调用（`obj.method()`），防止经原型链逃逸。
+ */
+interface CallExpression {
+    type: 'CallExpression';
+    callee: Identifier;
+    arguments: ExpressionNode[];
+}
+/**
+ * 对象字面量（`{ key: value, ... }`）：键为标识符或字符串，
+ * 值为任意表达式。主要作为白名单函数的参数表（如 t() 的插值参数）。
+ */
+interface ObjectExpression {
+    type: 'ObjectExpression';
+    properties: Array<{
+        key: string;
+        value: ExpressionNode;
+    }>;
+}
+type ExpressionNode = Literal | Identifier | MemberExpression | BinaryExpression | LogicalExpression | UnaryExpression | ConditionalExpression | CallExpression | ObjectExpression;
+
+/** 表达式语法 / 求值错误，携带源码位置信息 */
+declare class ExpressionError extends Error {
+    readonly pos?: number | undefined;
+    constructor(message: string, pos?: number | undefined);
+}
+
+/**
+ * Recursive descent parser。
+ *
+ * 优先级（低 → 高）：
+ *   conditional → logicalOr → logicalAnd → equality → relational
+ *   → additive → multiplicative → unary → member/call → primary
+ */
+declare function parseExpression(source: string): ExpressionNode;
+
+/** 白名单函数签名 */
+type ExpressionFunction = (...args: unknown[]) => unknown;
+/** 求值作用域：由调用方组装的普通对象（state/data/form/row/route/user 等） */
+type ExpressionScope = Record<string, unknown>;
+interface EvaluateOptions {
+    /** 额外的白名单函数表（Record 或 @pactor-app/core Registry） */
+    functions?: Record<string, ExpressionFunction> | Registry<ExpressionFunction>;
+}
+/**
+ * 解析并求值表达式。
+ *
+ * @param source 表达式源码（不含 `${}` 定界符）或已解析的 AST
+ * @param scope 求值作用域，由调用方组装
+ */
+declare function evaluateExpression(source: string | ExpressionNode, scope?: ExpressionScope, options?: EvaluateOptions): unknown;
+
+/** 字符串中是否包含 `${...}` 表达式 */
+declare function hasExpression(value: string): boolean;
+/**
+ * 求值 DSL 模板字符串。
+ *
+ * - 字符串整体恰好是一个 `${...}`：返回表达式的原始类型值
+ *   （保留 boolean / number / object / array）。
+ * - 内嵌 `${...}` 与其他文本混合：各表达式结果字符串化后拼接，
+ *   null / undefined 渲染为空串。
+ * - 不含 `${` 的普通字符串：原样返回。
+ */
+declare function resolveTemplate(value: string, scope?: ExpressionScope, options?: EvaluateOptions): unknown;
+
+export { type BinaryExpression, type BinaryOperator, type CallExpression, type ConditionalExpression, type EvaluateOptions, ExpressionError, type ExpressionFunction, type ExpressionNode, type ExpressionScope, type Identifier, type Literal, type LiteralValue, type LogicalExpression, type LogicalOperator, type MemberExpression, type UnaryExpression, type UnaryOperator, evaluateExpression, hasExpression, parseExpression, resolveTemplate };

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+import { Registry } from '@pactor-app/core';
+
+/**
+ * 受控表达式 AST（设计文档第 16.1 节白名单节点）。
+ *
+ * 语法子集刻意保持最小：无赋值、无 new、无箭头函数、无数组字面量。
+ * 对象字面量（`{ name: state.x }`）仅作为白名单函数的参数载体开放
+ * （如 `t('key', { name: user.name })`），键仅允许标识符/字符串。
+ * 不支持的语法在 parse 阶段直接抛错，而不是解析后再黑名单过滤。
+ */
+type LiteralValue = string | number | boolean | null | undefined;
+interface Literal {
+    type: 'Literal';
+    value: LiteralValue;
+}
+interface Identifier {
+    type: 'Identifier';
+    name: string;
+}
+interface MemberExpression {
+    type: 'MemberExpression';
+    object: ExpressionNode;
+    property: ExpressionNode;
+    /** true: a[b]；false: a.b */
+    computed: boolean;
+}
+type BinaryOperator = '==' | '!=' | '===' | '!==' | '<' | '<=' | '>' | '>=' | '+' | '-' | '*' | '/' | '%';
+interface BinaryExpression {
+    type: 'BinaryExpression';
+    operator: BinaryOperator;
+    left: ExpressionNode;
+    right: ExpressionNode;
+}
+type LogicalOperator = '&&' | '||';
+interface LogicalExpression {
+    type: 'LogicalExpression';
+    operator: LogicalOperator;
+    left: ExpressionNode;
+    right: ExpressionNode;
+}
+type UnaryOperator = '!' | '-' | '+';
+interface UnaryExpression {
+    type: 'UnaryExpression';
+    operator: UnaryOperator;
+    argument: ExpressionNode;
+}
+interface ConditionalExpression {
+    type: 'ConditionalExpression';
+    test: ExpressionNode;
+    consequent: ExpressionNode;
+    alternate: ExpressionNode;
+}
+/**
+ * 白名单函数调用。callee 只允许直接 Identifier（如 `permission('x')`），
+ * 不允许成员方法调用（`obj.method()`），防止经原型链逃逸。
+ */
+interface CallExpression {
+    type: 'CallExpression';
+    callee: Identifier;
+    arguments: ExpressionNode[];
+}
+/**
+ * 对象字面量（`{ key: value, ... }`）：键为标识符或字符串，
+ * 值为任意表达式。主要作为白名单函数的参数表（如 t() 的插值参数）。
+ */
+interface ObjectExpression {
+    type: 'ObjectExpression';
+    properties: Array<{
+        key: string;
+        value: ExpressionNode;
+    }>;
+}
+type ExpressionNode = Literal | Identifier | MemberExpression | BinaryExpression | LogicalExpression | UnaryExpression | ConditionalExpression | CallExpression | ObjectExpression;
+
+/** 表达式语法 / 求值错误，携带源码位置信息 */
+declare class ExpressionError extends Error {
+    readonly pos?: number | undefined;
+    constructor(message: string, pos?: number | undefined);
+}
+
+/**
+ * Recursive descent parser。
+ *
+ * 优先级（低 → 高）：
+ *   conditional → logicalOr → logicalAnd → equality → relational
+ *   → additive → multiplicative → unary → member/call → primary
+ */
+declare function parseExpression(source: string): ExpressionNode;
+
+/** 白名单函数签名 */
+type ExpressionFunction = (...args: unknown[]) => unknown;
+/** 求值作用域：由调用方组装的普通对象（state/data/form/row/route/user 等） */
+type ExpressionScope = Record<string, unknown>;
+interface EvaluateOptions {
+    /** 额外的白名单函数表（Record 或 @pactor-app/core Registry） */
+    functions?: Record<string, ExpressionFunction> | Registry<ExpressionFunction>;
+}
+/**
+ * 解析并求值表达式。
+ *
+ * @param source 表达式源码（不含 `${}` 定界符）或已解析的 AST
+ * @param scope 求值作用域，由调用方组装
+ */
+declare function evaluateExpression(source: string | ExpressionNode, scope?: ExpressionScope, options?: EvaluateOptions): unknown;
+
+/** 字符串中是否包含 `${...}` 表达式 */
+declare function hasExpression(value: string): boolean;
+/**
+ * 求值 DSL 模板字符串。
+ *
+ * - 字符串整体恰好是一个 `${...}`：返回表达式的原始类型值
+ *   （保留 boolean / number / object / array）。
+ * - 内嵌 `${...}` 与其他文本混合：各表达式结果字符串化后拼接，
+ *   null / undefined 渲染为空串。
+ * - 不含 `${` 的普通字符串：原样返回。
+ */
+declare function resolveTemplate(value: string, scope?: ExpressionScope, options?: EvaluateOptions): unknown;
+
+export { type BinaryExpression, type BinaryOperator, type CallExpression, type ConditionalExpression, type EvaluateOptions, ExpressionError, type ExpressionFunction, type ExpressionNode, type ExpressionScope, type Identifier, type Literal, type LiteralValue, type LogicalExpression, type LogicalOperator, type MemberExpression, type UnaryExpression, type UnaryOperator, evaluateExpression, hasExpression, parseExpression, resolveTemplate };