@cloudpss/expression 0.6.0-alpha.1

package/src/scope.ts

@@ -0,0 +1,208 @@
+import { createVmContext, isVmExtern, type VmAny, type VmContext, type VmValue } from '@mirascript/mirascript';
+import type { Context } from './context.js';
+import {
+    type CompiledExpression,
+    type Expression,
+    type ExpressionOrValue,
+    ExpressionTag,
+    isExpression,
+} from './expression.js';
+import { DEFAULTS, evaluateEval } from './eval.js';
+import { parse } from './parser.js';
+import { TypeInfo } from './type.js';
+const { hasOwn } = Object;
+
+const RAW = Symbol.for('@private/expression:raw');
+
+/** 是否需要创建代理对象 */
+function needsProxy(value: unknown): value is Expression | object {
+    return isExpression(value) || (value != null && typeof value == 'object');
+}
+
+/** 创建代理对象 */
+function createProxy(value: Expression | object, scope: Scope, path: readonly PropertyKey[]): unknown {
+    // 先检查 isExpression，因为 'function' 也有可能是 Expression
+    if (isExpression(value)) {
+        return scope.eval(value, path);
+    }
+    if (typeof value != 'object' || value == null) {
+        return value;
+    }
+    if (
+        value instanceof Date ||
+        value instanceof Promise ||
+        value instanceof RegExp ||
+        ArrayBuffer.isView(value) ||
+        value instanceof ArrayBuffer ||
+        (typeof SharedArrayBuffer != 'undefined' && value instanceof SharedArrayBuffer)
+    ) {
+        return value;
+    }
+    return new Proxy(value, new ScopeProxyHandler(scope, path));
+}
+/** 函数的执行环境 */
+class ScopeProxyHandler implements ProxyHandler<object> {
+    constructor(
+        readonly scope: Scope,
+        readonly path: readonly PropertyKey[],
+    ) {}
+    /**
+     * @inheritdoc
+     */
+    get(target: object, p: string | symbol): unknown {
+        if (p === RAW) {
+            return target;
+        }
+        const value = Reflect.get(target, p) as unknown;
+        if (!needsProxy(value)) {
+            return value;
+        }
+        if (isVmExtern(target)) {
+            return createProxy(value, this.scope, this.path);
+        }
+        return createProxy(value, this.scope, [...this.path, p]);
+    }
+}
+
+/** 函数的执行环境 */
+export class Scope {
+    /** 最大求值计数 */
+    static readonly MAX_RECURSION = 500;
+    constructor(
+        /** 生成环境的工厂函数 */
+        readonly scope?:
+            | ((key: string) => ExpressionOrValue | undefined)
+            | Record<string, ExpressionOrValue | undefined>,
+        /** 求值失败是否抛异常 */
+        readonly throws = true,
+        /** 执行环境名称 */
+        readonly name = '<anonymous>',
+    ) {
+        if (scope == null) {
+            this.getter = (key) => this.context?.imported.get(key);
+        } else if (typeof scope == 'function') {
+            this.getter = (key) => {
+                const v = scope(key);
+                if (v === undefined) return this.context?.imported.get(key);
+                if (!needsProxy(v)) return v;
+                return createProxy(v, this, [key]) as VmValue;
+            };
+        } else {
+            this.getter = (key) => {
+                if (!hasOwn(scope, key)) return this.context?.imported.get(key);
+                const v = scope[key];
+                if (!needsProxy(v)) return v;
+                return createProxy(v, this, [key]) as VmValue;
+            };
+        }
+    }
+
+    protected readonly getter: (key: string) => VmAny;
+    /** 上下文 */
+    protected context: Context | null = null;
+    /** 求值计数 */
+    protected evalCounter = 0;
+    /** 重置执行环境 */
+    reset(context: Context | null): () => void {
+        const oldContext = this.context;
+        const oldCounter = this.evalCounter;
+        this.context = context;
+        this.evalCounter = 0;
+        return () => {
+            this.context = oldContext;
+            this.evalCounter = oldCounter;
+        };
+    }
+    /** 函数的执行环境，惰性求值 */
+    protected _proxy?: VmContext;
+    /** 函数的执行环境，惰性求值 */
+    get proxy(): VmContext {
+        this._proxy ??= createVmContext(this.getter);
+        return this._proxy;
+    }
+
+    /** 检查环境中是否有值 */
+    has(key: string): boolean {
+        const { scope } = this;
+        if (scope == null) return false;
+        let v;
+        if (typeof scope == 'function') {
+            v = scope(key);
+        } else if (hasOwn(scope, key)) {
+            v = scope[key];
+        }
+        return v !== undefined;
+    }
+
+    /** 获取环境中的值 */
+    get(key: string): VmAny {
+        const { scope } = this;
+        if (scope == null) return undefined;
+        let v;
+        if (typeof scope == 'function') {
+            v = scope(key);
+        } else if (hasOwn(scope, key)) {
+            v = scope[key];
+        }
+        if (!isExpression(v)) return v;
+        return this.eval(v, [key]);
+    }
+
+    /**
+     * 表达式递归求值
+     */
+    eval(expression: Expression | CompiledExpression, path: readonly PropertyKey[]): VmValue {
+        if (this.evalCounter >= Scope.MAX_RECURSION) {
+            throw new Error(`Execution recursion exceeds limit`);
+        }
+
+        this.evalCounter++;
+        try {
+            let result;
+            if (typeof expression == 'function') {
+                result = expression(this) as VmValue;
+            } else {
+                const { context } = this;
+                if (!context) {
+                    throw new Error(`Undefined context`);
+                }
+                const exp = parse(context, expression.source, this.throws);
+                if (exp.func != null) {
+                    result = evaluateEval(context, exp, this);
+                } else if (exp.error != null) {
+                    throw exp.error;
+                } else {
+                    result = DEFAULTS;
+                }
+            }
+            if (result === DEFAULTS) return null;
+            const tag = expression[ExpressionTag];
+            if (!tag) return result;
+            return TypeInfo.to(result, TypeInfo.parse(tag));
+        } catch (ex) {
+            throw new Error(`${(ex as Error).message || String(ex)}\nIn ${this.name}: @ ${path.join('/')}`);
+        }
+    }
+}
+
+/** 移除 PROXY */
+function unwrapCore<T>(value: T): T | undefined {
+    if (value == null || (typeof value != 'object' && typeof value != 'function')) {
+        return undefined;
+    }
+    const raw = (value as T & { [RAW]?: T })[RAW];
+    const obj = raw ?? value;
+    for (const key in obj) {
+        if (!hasOwn(obj, key)) continue;
+        const unwrapped = unwrapCore(obj[key]);
+        if (unwrapped !== undefined) {
+            obj[key] = unwrapped;
+        }
+    }
+    return raw;
+}
+
+/** 移除 PROXY */
+export function unwrap<T>(value: T): T {
+    return unwrapCore(value) ?? value;
+}

package/src/type.ts

@@ -0,0 +1,66 @@
+import type { TypeName, VmValue, VmValueMap } from '@mirascript/mirascript';
+import { lib } from '@mirascript/mirascript/subtle';
+
+/** 类型信息 */
+export type TypeInfo = 'string' | 'number' | 'boolean';
+
+const x: TypeInfo = 'boolean';
+x satisfies TypeName;
+
+/** 类型映射 */
+type TypeMap = VmValueMap & {
+    s: string;
+    f: number;
+    b: boolean;
+};
+
+/** Ts 类型 */
+export type TsTypeOf<T extends TypeInfo | LegacyType> = TypeMap[T];
+
+/** 兼容的旧类型 */
+export type LegacyType = 's' | 'f' | 'b';
+
+/** 类型信息 */
+export const TypeInfo = {
+    parse: (type: TypeInfo | LegacyType): TypeInfo => {
+        if (type === 's' || type === 'string') return 'string';
+        if (type === 'f' || type === 'number') return 'number';
+        if (type === 'b' || type === 'boolean') return 'boolean';
+        throw new TypeError(`Invalid type '${String(type)}'`);
+    },
+    is: <T extends TypeInfo | LegacyType>(value: VmValue | undefined, type: T): value is TsTypeOf<T> => {
+        switch (type) {
+            case 'b':
+            case 'boolean':
+                return typeof value === 'boolean';
+            case 'f':
+            case 'number':
+                return typeof value === 'number';
+            case 's':
+            case 'string':
+                return typeof value === 'string';
+            default:
+                (type) satisfies never;
+                return false;
+        }
+    },
+    to: <T extends TypeInfo | LegacyType>(value: VmValue | undefined, type: T): TsTypeOf<T> => {
+        /** 返回类型 */
+        type R = TsTypeOf<T>;
+        if (!type) return value as R;
+        switch (type) {
+            case 'b':
+            case 'boolean':
+                return lib.to_boolean(value) as R;
+            case 'f':
+            case 'number':
+                return lib.to_number(value) as R;
+            case 's':
+            case 'string':
+                return lib.to_string(value) as R;
+            default:
+                (type) satisfies never;
+                return value as R;
+        }
+    },
+};

package/tests/analyze.ts

@@ -0,0 +1,15 @@
+import { Evaluator, Expression, Scope } from '../dist/index.js';
+
+const e = new Evaluator();
+const s = new Scope({}, false);
+
+describe.skip('Analyze', () => {
+    it('simple', () => {
+        expect(e.analyze(Expression('a+b'), s)).toEqual([['a'], ['b']]);
+    });
+    it('access', () => {
+        expect(e.analyze(Expression('a.b[1]+b'), s)).toEqual([['a', 'b'], ['b']]);
+        expect(e.analyze(Expression('a.b["x"]+b'), s)).toEqual([['a', 'b', 'x'], ['b']]);
+        expect(e.analyze(Expression('a.b[x]+b'), s)).toEqual([['a', 'b'], ['x'], ['b']]);
+    });
+});

package/tests/condition.ts

@@ -0,0 +1,49 @@
+import { Evaluator, type ExpressionSource, Scope } from '../dist/index.js';
+
+const e = new Evaluator();
+const s = new Scope(undefined, false);
+
+describe('Evaluate conditions', () => {
+    it('can evaluate boolean literals', () => {
+        expect(e.evaluateCondition(true, s)).toBe(true);
+        expect(e.evaluateCondition(false, s)).toBe(false);
+    });
+    it('can evaluate empty literals', () => {
+        // @ts-expect-error null
+        expect(e.evaluateCondition(null, s)).toBe(true);
+        expect(e.evaluateCondition(undefined, s)).toBe(true);
+    });
+    it('can evaluate well known strings', () => {
+        expect(e.evaluateCondition('' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('true' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('false' as ExpressionSource<boolean>, s)).toBe(false);
+    });
+    it('can convert to boolean', () => {
+        expect(e.evaluateCondition('""' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('nil' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('undefined' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('0' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('nan' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('(false)' as ExpressionSource<boolean>, s)).toBe(false);
+
+        expect(e.evaluateCondition('""' as ExpressionSource<boolean>, s, false)).toBe(true);
+        expect(e.evaluateCondition('nil' as ExpressionSource<boolean>, s, false)).toBe(false);
+        expect(e.evaluateCondition('undefined' as ExpressionSource<boolean>, s, false)).toBe(false);
+        expect(e.evaluateCondition('0' as ExpressionSource<boolean>, s, false)).toBe(true);
+        expect(e.evaluateCondition('nan' as ExpressionSource<boolean>, s, false)).toBe(true);
+        expect(e.evaluateCondition('(false)' as ExpressionSource<boolean>, s, false)).toBe(false);
+    });
+    it('can evaluate complex', () => {
+        expect(e.evaluateCondition('12>3' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('12<3' as ExpressionSource<boolean>, s)).toBe(false);
+        expect(e.evaluateCondition('12==3' as ExpressionSource<boolean>, s)).toBe(false);
+        expect(e.evaluateCondition('12!=3' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('12>=3' as ExpressionSource<boolean>, s)).toBe(true);
+        expect(e.evaluateCondition('12<=3' as ExpressionSource<boolean>, s)).toBe(false);
+    });
+    it('can return default on error', () => {
+        expect(e.evaluateCondition('12>>3' as ExpressionSource<boolean>, undefined, true)).toBe(true);
+        // @ts-expect-error null
+        expect(e.evaluateCondition('12>>3' as ExpressionSource<boolean>, null, false)).toBe(false);
+    });
+});

package/tests/definition.ts

@@ -0,0 +1,42 @@
+import * as def from '../dist/definitions.js';
+
+describe('definitions', () => {
+    it('should handle parameter', () => {
+        expect(def.Parameter()).toBeDefined();
+        expect(def.isParameter(def.Parameter())).toBe(true);
+    });
+
+    it('should handle parameter group', () => {
+        expect(def.ParameterGroup()).toBeDefined();
+        expect(def.isParameterGroup(def.ParameterGroup())).toBe(true);
+    });
+
+    it('should handle parameter decoration', () => {
+        expect(def.ParameterDecoration()).toBeDefined();
+        expect(def.isParameterDecoration(def.ParameterDecoration())).toBe(true);
+    });
+
+    it('should handle parameter decoration group', () => {
+        expect(def.ParameterDecorationGroup()).toBeDefined();
+        expect(def.isParameterDecorationGroup(def.ParameterDecorationGroup())).toBe(true);
+    });
+
+    it('should handle variable', () => {
+        expect(def.Variable()).toBeDefined();
+        expect(def.isVariable(def.Variable())).toBe(true);
+    });
+
+    it('should handle choice', () => {
+        expect(def.Choice()).toBeDefined();
+        expect(def.isChoice(def.Choice())).toBe(true);
+
+        expect(def.Choice('x').key).toBe('x');
+        expect(def.isChoice(def.Choice('x'))).toBe(true);
+
+        expect(def.Choice(0).key).toBe(0);
+        expect(def.isChoice(def.Choice(0))).toBe(true);
+
+        expect(def.Choice(false).key).toBe(false);
+        expect(def.isChoice(def.Choice(false))).toBe(true);
+    });
+});

package/tests/eval-complex.ts

@@ -0,0 +1,150 @@
+import { VmExtern } from '@mirascript/mirascript';
+import { Evaluator, Expression, Scope } from '../dist/index.js';
+
+const e = new Evaluator();
+
+describe('Evaluator should work correctly', () => {
+    it('should eval deep', () => {
+        const s = new Scope(
+            (k) =>
+                ({
+                    a: Expression('b+d'),
+                    b: Expression('c+d'),
+                    c: 12,
+                    d: Expression('c'),
+                })[k],
+            false,
+        );
+        const result = e.evaluate(Expression('a'), s);
+        expect(result).toBe(36);
+    });
+    it('should eval deep with object', () => {
+        const s = new Scope(
+            {
+                a: { a: Expression('b.b + d.d') },
+                b: { b: Expression('c.c + d.d') },
+                c: { c: 12 },
+                d: { d: Expression('c.c') },
+            },
+            false,
+        );
+        const result = e.evaluate(Expression('a.a'), s);
+        expect(result).toBe(36);
+    });
+    it('should eval deep with array', () => {
+        const s = new Scope(
+            {
+                a: [Expression('b.0 + d.0')],
+                b: [Expression('c.0 + d.0')],
+                c: [12],
+                d: [Expression('c.0')],
+            },
+            false,
+        );
+        const result = e.evaluate(Expression('a.0'), s);
+        expect(result).toBe(36);
+    });
+    it('should eval deep with extern', () => {
+        const s = new Scope(
+            {
+                a: new VmExtern([Expression('b.0 + d.0')]),
+                b: new VmExtern([Expression('c.0 + d.0')]),
+                c: new VmExtern([12]),
+                d: new VmExtern([Expression('c.0')]),
+            },
+            false,
+        );
+        const result = e.evaluate(Expression('a.0'), s);
+        expect(result).toBe(36);
+    });
+    it('should eval deep with compiled expression', () => {
+        const s = new Scope(
+            {
+                a: Expression('b+d'),
+                b: e.compile(Expression('c+d')),
+                c: 12,
+                d: Expression('c'),
+            },
+            false,
+        );
+        const result = e.evaluate(Expression('a'), s);
+        expect(result).toBe(36);
+    });
+    it('should eval complex', () => {
+        const s = new Scope(
+            {
+                a: Expression('b'),
+                b: Expression('c'),
+                c: Expression('d'),
+                d: Expression('e'),
+                e: Expression('f'),
+                f: Expression('g'),
+                g: Expression('h'),
+                h: Expression('i'),
+                i: Expression('j'),
+                j: Expression('k'),
+                k: Expression('l'),
+                l: Expression('m'),
+                m: Expression('n'),
+                n: Expression('o'),
+                o: Expression('p'),
+                p: Expression('q'),
+                q: Expression('r'),
+                r: Expression('s'),
+                s: Expression('t'),
+                t: Expression('u'),
+                u: Expression('v'),
+                v: Expression('w'),
+                w: Expression('x'),
+                x: Expression('y'),
+                y: Expression('z'),
+                z: 1,
+            },
+            false,
+        );
+        const result = e.evaluate(Expression('a + a + a + a + a + a + a + a + a + a'), s);
+        expect(result).toBe(10);
+    });
+    it('should report loop', () => {
+        const s = new Scope(
+            {
+                a: Expression('b'),
+                b: Expression('c'),
+                c: Expression('a'),
+            },
+            true,
+        );
+        expect(() => e.evaluate(Expression('a'), s)).toThrow(/Maximum call depth exceeded/);
+    });
+
+    it('should not pass some special as proxy', () => {
+        expect.assertions(9);
+        const o = new VmExtern({
+            x: { p: 2 },
+            y: 1,
+            z: Expression('o.y+o.x.p'),
+            d: new Date(),
+            r: /r/,
+            f() {
+                return this.z;
+            },
+            p: Promise.resolve(1),
+            a: new ArrayBuffer(0),
+            v: new DataView(new ArrayBuffer(0)),
+            test() {
+                expect(this).toBeProxy();
+                expect(this.d).not.toBeProxy();
+                expect(this.r).not.toBeProxy();
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                expect(this.f).not.toBeProxy();
+                expect(this.p).not.toBeProxy();
+                expect(this.a).not.toBeProxy();
+                expect(this.v).not.toBeProxy();
+                return this.f();
+            },
+        });
+        const s = new Scope({ o }, true);
+        expect(e.evaluate(Expression('o.test()'), s)).toBe(3);
+        expect(e.evaluate(Expression('o.z'), s)).toBe(3);
+    });
+});

package/tests/eval.ts

@@ -0,0 +1,42 @@
+import { Evaluator, Expression, Scope } from '../dist/index.js';
+
+const e = new Evaluator();
+const s = new Scope({}, false);
+
+describe('Evaluator should work correctly', () => {
+    it('should eval const', () => {
+        const result = e.evaluate(Expression('12'), s);
+        expect(result).toBe(12);
+    });
+
+    it('should eval exp', () => {
+        const result = e.evaluate(Expression('exp(2)'), s);
+        expect(result).toBe(Math.exp(2));
+    });
+
+    it('should eval error', () => {
+        const result = e.evaluate(Expression('exp+++'), s);
+        expect(result).toBe(undefined);
+    });
+});
+
+describe('Evaluator should convert result', () => {
+    it('should eval const', () => {
+        const result = e.evaluate(Expression('12', 'string'), s);
+        expect(result).toBe('12');
+    });
+
+    it('should eval exp', () => {
+        const result = e.evaluate(Expression('exp(2)', 's'), s);
+        expect(result).toBe(Math.exp(2).toString());
+    });
+
+    it('should not convert when error', () => {
+        // syntax error
+        const result = e.evaluate(Expression('exp+++', 's'), s, 1);
+        expect(result).toBe(1);
+        // runtime error
+        const result2 = e.evaluate(Expression('x() + 1', 's'), s, 1);
+        expect(result2).toBe(1);
+    });
+});

package/tests/functions.ts

@@ -0,0 +1,22 @@
+import type { VmRecord } from '@mirascript/mirascript';
+import { Evaluator, Expression, Scope } from '../dist/index.js';
+
+const e = new Evaluator();
+const s = new Scope((k) => (k === 'v' ? ({ a: 2, b: 1, c: undefined } as unknown as VmRecord) : undefined));
+
+describe('Evaluator should provided functions', () => {
+    it('should eval keys/values/entries', () => {
+        expect(e.evaluate(Expression('keys(v)'), s)).toEqual(['a', 'b', 'c']);
+        expect(e.evaluate(Expression('values(v)'), s)).toEqual([2, 1, undefined]);
+        expect(e.evaluate(Expression('entries(v)'), s)).toEqual([
+            { 0: 'a', 1: 2 },
+            { 0: 'b', 1: 1 },
+            { 0: 'c', 1: null },
+        ]);
+    });
+
+    it('should eval type', () => {
+        expect(e.evaluate(Expression('type(exp) == "function"'), s)).toBe(true);
+        expect(e.evaluate(Expression('type(exp) == "function"'), s)).toBe(true);
+    });
+});

package/tests/import.ts

@@ -0,0 +1,31 @@
+import { VmFunction } from '@mirascript/mirascript';
+import { Evaluator, Expression, Scope } from '../dist/index.js';
+import { lib } from '@mirascript/mirascript/subtle';
+
+const e = new Evaluator();
+const e2 = new Evaluator();
+const s = new Scope(undefined, false);
+
+describe('Import should work correctly', () => {
+    it('can import modules', () => {
+        e.import({ add: (x: number, y: number) => x + y });
+        expect(e.evaluate(Expression('add(1,2)'), s)).toBe(3);
+        expect(e.evaluate(Expression('add::type()'), s)).toBe('extern');
+        expect(e2.evaluate(Expression('add(1,2)'), s)).toBe(undefined);
+        expect(e2.evaluate(Expression('add::type()'), s)).toBe('nil');
+    });
+
+    it('can remove modules', () => {
+        e.import({ add: (x: number, y: number) => x + y });
+        expect(e.evaluate(Expression('add(1,2)'), s)).toBe(3);
+        e.import({ add: undefined });
+        expect(e.evaluate(Expression('add(1,2)'), s)).toBe(undefined);
+    });
+
+    it('can replace modules', () => {
+        e.import({ add: (x: number, y: number) => x + y });
+        expect(e.evaluate(Expression('add::type()'), s)).toBe('extern');
+        e.import({ add: VmFunction((x, y) => lib.to_number(x) + lib.to_number(y)) });
+        expect(e.evaluate(Expression('add::type()'), s)).toBe('function');
+    });
+});

package/tests/scope.ts

@@ -0,0 +1,33 @@
+import { Evaluator, Expression, Scope } from '../dist/index.js';
+
+const e = new Evaluator();
+
+describe('Scope should work correctly', () => {
+    it('can create from undefined', () => {
+        const s = new Scope(undefined, false);
+        expect(e.evaluate(Expression('12'), s)).toBe(12);
+    });
+    it('can create from function', () => {
+        const s = new Scope((k) => (k === 'a' ? 12 : undefined), false);
+        expect(e.evaluate(Expression('a'), s)).toBe(12);
+        expect(e.evaluate(Expression('b'), s)).toBe(undefined);
+    });
+    it('can create from object', () => {
+        const s = new Scope({ a: 12, b: Expression('a + 1') }, false);
+        expect(e.evaluate(Expression('a'), s)).toBe(12);
+        expect(e.evaluate(Expression('b'), s)).toBe(13);
+    });
+});
+
+describe('Scope should not leak dangerous objects', () => {
+    it('should not access prototype fields', () => {
+        const s = new Scope({}, false);
+        expect(e.evaluate(Expression('__proto__'), s)).toBe(undefined);
+        expect(e.evaluate(Expression('toString'), s)).toBe(undefined);
+    });
+    it('should access same name props', () => {
+        const s = new Scope({ ['__proto__']: 12, toString: 'x' }, false);
+        expect(e.evaluate(Expression('__proto__'), s)).toBe(12);
+        expect(e.evaluate(Expression('toString'), s)).toBe('x');
+    });
+});