@cloudpss/expression 0.6.0-alpha.1

package/src/analyze.ts

@@ -0,0 +1,44 @@
+import type { Context } from './context.js';
+import type { ExpressionCache } from './parser.js';
+
+/**
+ * 分析依赖
+ */
+export function analyze(context: Context, expression: ExpressionCache): string[][] {
+    // TODO:
+    return [];
+    // if (expression.ast == null) return [];
+
+    // const deps: string[][] = [];
+
+    // const analyzeNode = (node: MathNode): string[] | undefined => {
+    //     if (isSymbolNode(node) && node.name) {
+    //         return [node.name];
+    //     }
+    //     if (isAccessorNode(node)) {
+    //         const { index } = node;
+    //         if (index.dimensions.length !== 1 || !isConstantNode(index.dimensions[0])) {
+    //             return undefined;
+    //         }
+    //         const indexValue = index.dimensions[0].value;
+    //         // 暂时不考虑，两边索引 base 不一致
+    //         if (typeof indexValue != 'string' /*&& typeof indexValue != 'number'*/) {
+    //             return undefined;
+    //         }
+    //         const deps = analyzeNode(node.object);
+    //         if (!deps) return undefined;
+
+    //         return [...deps, indexValue];
+    //     }
+    //     return undefined;
+    // };
+
+    // const analyzeAndPush = (node: MathNode): void => {
+    //     const dep = analyzeNode(node);
+    //     if (dep) deps.push(dep);
+    //     // eslint-disable-next-line unicorn/no-array-for-each
+    //     else node.forEach(analyzeAndPush);
+    // };
+    // analyzeAndPush(expression.ast);
+    // return deps;
+}

package/src/context.ts

@@ -0,0 +1,54 @@
+import { LRUCache } from 'lru-cache';
+import type { ExpressionCache } from './parser.js';
+import type { VmValue } from '@mirascript/mirascript';
+
+/** 日志 */
+export interface Logger {
+    /**
+     * error
+     */
+    error(...args: unknown[]): void;
+    /**
+     * warning
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * info
+     */
+    info(...args: unknown[]): void;
+    /**
+     * debug
+     */
+    debug(...args: unknown[]): void;
+}
+
+/** 选项 */
+export interface Options {
+    /** 日志 */
+    logger: Logger;
+    /** 表达式缓存 */
+    expressionCacheSize: number;
+}
+
+const defaultOptions: Options = {
+    logger: console,
+    expressionCacheSize: 50,
+};
+
+/** 执行上下文 */
+export class Context {
+    constructor(options?: Partial<Options>) {
+        this.options = { ...options, ...defaultOptions };
+        this.expressionCache = new LRUCache<string, ExpressionCache>({ max: this.options.expressionCacheSize });
+    }
+    readonly imported = new Map<string, VmValue>();
+    /** Logger */
+    get logger(): Logger {
+        return this.options.logger ?? console;
+    }
+    /** 选项 */
+    readonly options: Options;
+
+    /** 表达式缓存 */
+    readonly expressionCache;
+}

package/src/definitions/argument.ts

@@ -0,0 +1,40 @@
+import type { VmConst, VmValue } from '@mirascript/mirascript';
+import type { ExpressionOrValue, ExpressionSource } from '../expression.js';
+import type { Scope } from '../scope.js';
+import type { Evaluator } from '../main.js';
+
+/**
+ * 表示一个具有类似表达式功能的 JS 函数，与某个 {@link ArgumentValue} 相关联，在其之后求值
+ */
+export type ExpressionFunction<R, V extends VmValue = ArgumentValue> = (
+    /** 相关联的参数值 */
+    value: V,
+    /** 当前作用域 */
+    scope: Scope,
+    /** 当前求值器 */
+    evaluator: Evaluator,
+) => R;
+
+/**
+ * 表示一个具有类似表达式功能的 JS 函数，与某个 {@link ArgumentValue} 相关联，在其之前求值
+ */
+export type ParameterFunction<R> = (
+    /** 当前作用域 */
+    scope: Scope,
+    /** 当前求值器 */
+    evaluator: Evaluator,
+) => R;
+
+/** 条件表达式 */
+export type ConditionExpression = boolean | ExpressionSource<boolean>;
+
+/** 条件函数 */
+export type ConditionFunction<V extends VmValue = ArgumentValue> = ExpressionFunction<boolean, V>;
+
+/** 参数值 */
+export type ArgumentValue = NonNullable<VmConst>;
+
+/** 未求值的参数表 */
+export type ArgumentMap<T extends Record<string, ArgumentValue> = Record<string, ArgumentValue>> = {
+    [K in keyof T & string]?: ExpressionOrValue<NonNullable<T[K]>>;
+};

package/src/definitions/constraint.ts

@@ -0,0 +1,49 @@
+import type { VmRecord, VmValue } from '@mirascript/mirascript';
+import type { ArgumentValue, ConditionExpression, ConditionFunction, ExpressionFunction } from './argument.js';
+import type { ExpressionSource } from '../expression.js';
+
+export const ConstraintLevel = Object.freeze(['info', 'warning', 'error'] as const);
+/** 约束条件的级别 */
+export type ConstraintLevel = (typeof ConstraintLevel)[number];
+
+/** 表示参数值需要满足的约束条件 */
+export interface Constraint<V extends VmValue = ArgumentValue> {
+    /**
+     * 指定约束条件检查顺序，顺序为 `'pre'` `(builtin)` `undefined` `'post'`
+     */
+    order?: 'pre' | 'post';
+    /**
+     * 不满足条件的提示
+     */
+    message: string;
+    /**
+     * 不满足条件的提示级别，仅 `'error'` 会导致参数无效，且后续约束不再检查
+     */
+    level?: ConstraintLevel;
+    /**
+     * 不满足条件的提示附加参数
+     */
+    messageData?: ExpressionSource<VmRecord> | VmRecord | ExpressionFunction<VmRecord, V>;
+    /**
+     * 约束条件
+     */
+    condition: ConditionExpression | ConditionFunction<V>;
+}
+
+/** 检查是否为 Constraint */
+export function isConstraint(value: unknown): value is Constraint {
+    if (value == null || typeof value !== 'object') return false;
+    if ('key' in value || 'description' in value) return false;
+
+    const v = value as Constraint;
+    if (typeof v.message != 'string') return false;
+    if (typeof v.condition != 'function' && typeof v.condition != 'string') return false;
+    if (
+        v.messageData != null &&
+        typeof v.messageData != 'string' &&
+        typeof v.messageData != 'object' &&
+        typeof v.messageData != 'function'
+    )
+        return false;
+    return true;
+}

package/src/definitions/parameter-decoration.ts

@@ -0,0 +1,42 @@
+import type { ConditionExpression } from './argument.js';
+
+/** 参数界面装饰 */
+export interface ParameterDecorationBase<T extends string> {
+    /** 参数装饰类型 */
+    type: T;
+    /** 布局时占用的位置 */
+    span?: number;
+    /** 装饰可见的条件表达式 */
+    condition?: ConditionExpression;
+}
+
+/** 参数标签装饰 */
+export interface ParameterLabelDecoration extends ParameterDecorationBase<'label'> {
+    /** 标签文本 */
+    label: string;
+}
+
+/** 参数界面装饰映射 */
+export interface ParameterDecorationMap {
+    /** 参数标签装饰 */
+    label: ParameterLabelDecoration;
+}
+
+/** 参数界面装饰 */
+export type ParameterDecoration = ParameterDecorationMap[keyof ParameterDecorationMap];
+
+/** 是否为参数界面装饰 */
+export function isParameterDecoration(value: unknown): value is ParameterDecoration {
+    if (value == null || typeof value != 'object') return false;
+    const v = value as ParameterDecoration;
+    if ('key' in v || 'name' in v || 'description' in v) return false;
+    return typeof v.type == 'string' && v.type.length > 0;
+}
+
+/** 创建参数界面装饰 */
+export function ParameterDecoration(): ParameterLabelDecoration {
+    return {
+        type: 'label',
+        label: '',
+    };
+}

package/src/definitions/parameter-group.ts

@@ -0,0 +1,62 @@
+import type { ConditionExpression } from './argument.js';
+import type { ParameterDecoration } from './parameter-decoration.js';
+import type { Parameter } from './parameter.js';
+
+/** 参数分组的公共属性 */
+interface ParameterGroupBase {
+    /** 分组可见的条件表达式 */
+    condition?: ConditionExpression;
+    /** 布局时占用的位置 */
+    span?: number;
+}
+
+/** 装饰分组 */
+export interface ParameterDecorationGroup extends ParameterGroupBase {
+    /** 装饰列表 */
+    items: ParameterDecoration[];
+}
+
+/** 创建装饰分组 */
+export function ParameterDecorationGroup(): ParameterDecorationGroup {
+    return {
+        items: [],
+    };
+}
+
+/** 判断是否为装饰分组 */
+export function isParameterDecorationGroup(value: unknown): value is ParameterDecorationGroup {
+    if (value == null || typeof value !== 'object') return false;
+    const v = value as ParameterDecorationGroup;
+    if ('key' in v || 'name' in v || 'description' in v) return false;
+    return Array.isArray(v.items);
+}
+
+/** 参数分组 */
+export interface ParameterGroup extends ParameterGroupBase {
+    /** 名称 */
+    name: string;
+    /** 详细描述 */
+    description: string;
+    /** 包含的参数列表 */
+    items: Parameter[];
+    /** 装饰 */
+    before?: ParameterDecorationGroup;
+    /** 装饰 */
+    after?: ParameterDecorationGroup;
+}
+
+/** 创建参数分组 */
+export function ParameterGroup(): ParameterGroup {
+    return {
+        name: '',
+        description: '',
+        items: [],
+    };
+}
+
+/** 判断是否为参数分组 */
+export function isParameterGroup(item: unknown): item is ParameterGroup {
+    if (item == null || typeof item !== 'object') return false;
+    const group = item as ParameterGroup;
+    return typeof group.name === 'string' && typeof group.description === 'string' && Array.isArray(group.items);
+}

package/src/definitions/parameter.ts

@@ -0,0 +1,276 @@
+import type { VmPrimitive, VmRecord } from '@mirascript/mirascript';
+import type { ExpressionOrValue } from '../expression.js';
+import type { ArgumentMap, ArgumentValue, ConditionExpression, ParameterFunction } from './argument.js';
+import type { Constraint } from './constraint.js';
+import type { ParameterDecoration } from './parameter-decoration.js';
+import type { ParameterGroup } from './parameter-group.js';
+
+export type { ArgumentMap };
+/** 参数定义 */
+export interface ParameterBase<T extends string, V extends ArgumentValue> {
+    /** 参数类型 */
+    type: T;
+    /** 实现阶段用于索引的键值，即 {@link ArgumentMap} 的 key */
+    key: string;
+    /** 名称 */
+    name: string;
+    /** 详细描述 */
+    description: string;
+    /** 参数可用的条件表达式 */
+    condition?: ConditionExpression;
+    /** 参数初始值（默认值） */
+    value: ExpressionOrValue<V>;
+    /** 需要满足的其他约束 */
+    constraints?: Array<Constraint<V>>;
+    /** 布局时占用的位置 */
+    span?: number;
+    /** 装饰 */
+    before?: ParameterDecoration;
+    /** 装饰 */
+    after?: ParameterDecoration;
+}
+
+export const NumericParameterInterval = Object.freeze(['open', 'left-open', 'right-open', 'closed'] as const);
+/**
+ * 区间类型
+ */
+export type NumericParameterInterval = (typeof NumericParameterInterval)[number];
+
+/**
+ * 数值类型参数定义
+ */
+export interface NumericParameter<T extends string> extends ParameterBase<T, number> {
+    /** 允许的最小值 */
+    minimum?: number;
+    /** 允许的最大值 */
+    maximum?: number;
+    /** 区间选项 */
+    interval?: NumericParameterInterval;
+    /** 数值单位 */
+    unit?: string;
+}
+
+/**
+ * 实数类型参数定义
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RealParameter extends NumericParameter<'real'> {}
+
+/**
+ * 整数类型参数定义
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface IntegerParameter extends NumericParameter<'integer'> {}
+
+/** 可用于选项的值 */
+export type ChoiceArgumentValue = NonNullable<VmPrimitive>;
+
+/** 表示一个选项 Key，当其值为数字时，默认值为其在数组中的索引 */
+type ChoiceKey<V extends ChoiceArgumentValue> = V extends number ? number | null : V;
+
+/** 表示一个选项 */
+export type Choice<V extends ChoiceArgumentValue> = {
+    /** 选中该选项将存储的参数值 */
+    key: ChoiceKey<V>;
+    /** 选项名称 */
+    name: string;
+    /** 选项详细描述 */
+    description: string;
+    /** 选项可用的条件表达式 */
+    condition?: ConditionExpression;
+};
+
+/** 是否为选项 */
+export function isChoice<V extends NonNullable<VmPrimitive>>(value: unknown): value is Choice<V> {
+    if (value == null || typeof value != 'object') return false;
+    const c = value as Choice<V>;
+    return typeof c.name === 'string' && typeof c.description == 'string' && !('items' in c) && !('value' in c);
+}
+/** 创建数值选项 */
+export function Choice(key?: ChoiceKey<number>): Choice<number>;
+/** 创建布尔选项 */
+export function Choice(key: ChoiceKey<boolean>): Choice<boolean>;
+/** 创建字符串选项 */
+export function Choice(key: ChoiceKey<string>): Choice<string>;
+/** 创建选项 */
+export function Choice<V extends NonNullable<VmPrimitive> = number>(key: ChoiceKey<V>): Choice<V>;
+/** 创建选项 */
+export function Choice<V extends NonNullable<VmPrimitive> = number>(key: ChoiceKey<V>): Choice<V> {
+    return {
+        key: key ?? (null as never),
+        name: '',
+        description: '',
+    };
+}
+
+/**
+ * 表示值为选择项的参数定义
+ */
+export interface ChoiceParameter<V extends ChoiceArgumentValue> extends ParameterBase<'choice', V> {
+    /**
+     * 可选取值及其对应的说明文本
+     */
+    choices: ExpressionOrValue<Array<Choice<V>>> | ParameterFunction<Array<Choice<V>>>;
+}
+/**
+ * 表示值为多选选择项的参数定义
+ */
+export interface MultiSelectParameter<V extends readonly ChoiceArgumentValue[]>
+    extends ParameterBase<'multiSelect', V> {
+    /**
+     * 可选取值及其对应的说明文本
+     */
+    choices: ExpressionOrValue<Array<Choice<V[number]>>> | ParameterFunction<Array<Choice<V[number]>>>;
+}
+
+/**
+ * 表示值为布尔量的参数定义
+ */
+export interface LogicalParameter<V extends ChoiceArgumentValue> extends ParameterBase<'logical', V> {
+    /**
+     * 可选取值及其对应的说明文本
+     */
+    choices?:
+        | ExpressionOrValue<[false: Choice<V>, true: Choice<V>]>
+        | ParameterFunction<[false: Choice<V>, true: Choice<V>]>;
+}
+
+/**
+ * 表示值为表格的参数定义
+ */
+export interface TableParameter<V extends readonly ArgumentValue[]> extends ParameterBase<'table', V> {
+    /** 最小行数 */
+    minRowCount?: number;
+    /** 最大行数 */
+    maxRowCount?: number;
+    /**
+     * 各列的定义
+     *
+     * `key` 默认为列定义在 {@link columns} 中的索引
+     *
+     * 当仅包含一列时，表格参数的值为该列定义的数组；
+     *
+     * 否则，表格参数的值为记录类型数组，每个记录包含各列定义的键值
+     */
+    columns: Parameter[] | ParameterFunction<Parameter[]>;
+}
+
+/**
+ * 表示值为简单记录类型的定义
+ *
+ * 简单记录类型包含一组字段，其编辑界面按字段顺序线性排列，可以沿行或列排列。
+ *
+ * 字段中可包含占位符，占位符在主轴上尺寸可自定义。
+ */
+export interface RecordParameter<V extends VmRecord> extends ParameterBase<'record', V> {
+    /** 主轴的优先方向 */
+    direction?: 'row' | 'column';
+    /** 包含的元素 */
+    items: Parameter[];
+}
+
+/**
+ * 表示值为包含分组的复杂记录的定义
+ *
+ * 每个分组包含一组字段，与简单记录类似。在编辑界面，分组名和内容沿正交轴线型排列。当所有分组都没有名字时，分组名会被隐藏。
+ *
+ * 各分组沿主轴排列时占据位置由 span 定义。
+ */
+export interface GroupedParameter<V extends VmRecord> extends ParameterBase<'grouped', V> {
+    /** 主轴的优先方向 */
+    direction?: 'row' | 'column';
+    /** 包含的元素 */
+    items: ParameterGroup[];
+}
+
+/** 表示值为文本的参数定义 */
+export interface TextParameter extends ParameterBase<'text', string> {
+    /** 验证有效性的正则表达式 */
+    pattern?: string;
+    /** 验证未通过的提示信息 */
+    patternErrorMessage?: string;
+    /** 最小长度 */
+    minLength?: number;
+    /** 最大长度 */
+    maxLength?: number;
+}
+
+/** 表示值为代码的参数定义 */
+export interface CodeParameter extends ParameterBase<'code', string> {
+    /** 代码的语言 */
+    language?: string;
+}
+
+/**
+ * 文件类型说明符
+ * @example ".png" "image/*"
+ */
+export type FileTypeDescriptor = `.${string}` | `${string}/${string}`;
+
+/** 接受的文件内容格式 */
+export type FileUrlCategory =
+    // data url
+    | 'embed'
+    // cloudpss-storage url
+    | 'storage'
+    // http/https url
+    | 'link';
+
+/** 表示值为文件的参数定义 */
+export interface FileParameter extends ParameterBase<'file', string> {
+    /** 支持的文件类型 */
+    accept?: FileTypeDescriptor | FileTypeDescriptor[];
+    /** 首选的文件处理方式 */
+    preference?: FileUrlCategory;
+}
+
+/**
+ * 已定义的参数类型
+ */
+export type ParameterMap = {
+    real: RealParameter;
+    integer: IntegerParameter;
+    choice: ChoiceParameter<string> | ChoiceParameter<number> | ChoiceParameter<boolean>;
+    multiSelect: MultiSelectParameter<string[]> | MultiSelectParameter<number[]> | MultiSelectParameter<boolean[]>;
+    logical: LogicalParameter<string> | LogicalParameter<number> | LogicalParameter<boolean>;
+    table: TableParameter<ArgumentValue[]>;
+    text: TextParameter;
+    code: CodeParameter;
+    file: FileParameter;
+    record: RecordParameter<VmRecord>;
+    grouped: GroupedParameter<VmRecord>;
+};
+/**
+ * 已定义的参数类型
+ */
+export type Parameter = ParameterMap[keyof ParameterMap];
+
+/**
+ * 是否为参数定义
+ */
+export function isParameter(value: unknown): value is Parameter {
+    if (value == null || typeof value != 'object') return false;
+    const v = value as Parameter;
+    return (
+        typeof v.key === 'string' &&
+        typeof v.type == 'string' &&
+        v.type.length > 0 &&
+        typeof v.name === 'string' &&
+        typeof v.description == 'string' &&
+        'value' in v
+    );
+}
+
+/**
+ * 创建参数定义
+ */
+export function Parameter(): RealParameter {
+    return {
+        key: '',
+        name: '',
+        description: '',
+        condition: '' as ConditionExpression,
+        type: 'real',
+        value: 0,
+    };
+}

package/src/definitions/variable.ts

@@ -0,0 +1,23 @@
+import type { ExpressionOrValue } from '../expression.js';
+import type { ArgumentValue } from './argument.js';
+
+/** 表示一个全局变量 */
+export type Variable<T extends ArgumentValue = ArgumentValue> = {
+    /** 唯一 key */
+    key: string;
+    /** 变量值 */
+    value: ExpressionOrValue<T>;
+};
+
+/** 检查是否为 `Variable` */
+export function isVariable(obj: unknown): obj is Variable {
+    if (obj == null || typeof obj != 'object') return false;
+    if ('condition' in obj || 'description' in obj) return false;
+    const v = obj as Variable;
+    return typeof v.key == 'string' && 'value' in v;
+}
+
+/** 创建空白 `Variable` */
+export function Variable(): Variable {
+    return { key: '', value: '' };
+}

package/src/definitions.ts

@@ -0,0 +1,6 @@
+export * from './definitions/argument.js';
+export * from './definitions/constraint.js';
+export * from './definitions/parameter.js';
+export * from './definitions/parameter-group.js';
+export * from './definitions/parameter-decoration.js';
+export * from './definitions/variable.js';

package/src/eval.ts

@@ -0,0 +1,64 @@
+import type { VmValue } from '@mirascript/mirascript';
+import type { Context } from './context.js';
+import type { EvalExpressionCache, ExpressionCache } from './parser.js';
+import { Scope, unwrap } from './scope.js';
+import { TypeInfo } from './type.js';
+
+export const DEFAULTS = Symbol('defaults');
+
+/**
+ * 表达式求值
+ */
+export function evaluateEval<T extends VmValue>(
+    context: Context,
+    expression: EvalExpressionCache,
+    scope: Scope,
+): T | typeof DEFAULTS {
+    try {
+        const result = expression.func(scope.proxy);
+        if (result == null) return DEFAULTS;
+        return unwrap(result as T);
+    } catch (error: unknown) {
+        if (scope.throws) throw error;
+        context.logger.warn(
+            `Failed to execute expression "${expression.source}": ${(error as Error).message || String(error)}.`,
+            {
+                error,
+                scope,
+            },
+        );
+        return DEFAULTS;
+    }
+}
+
+/**
+ * 表达式求值
+ */
+export function evaluate<T extends VmValue, D = T>(
+    context: Context,
+    expression: ExpressionCache,
+    returnType: TypeInfo | null,
+    scope: Scope | undefined,
+    defaults: D,
+): D | T {
+    let ret: T | typeof DEFAULTS;
+    if (expression.func != null) {
+        scope ??= new Scope();
+        const reset = scope.reset(context);
+        try {
+            ret = evaluateEval<T>(context, expression, scope);
+        } finally {
+            reset();
+        }
+    } else if (expression.error != null) {
+        if (scope?.throws ?? true) {
+            throw expression.error;
+        }
+        ret = DEFAULTS;
+    } else {
+        ret = DEFAULTS;
+    }
+    if (ret === DEFAULTS) return defaults;
+    if (!returnType) return ret;
+    return TypeInfo.to(ret, returnType) as T;
+}