@cloudpss/expression 0.6.0-alpha.1 → 0.6.0-alpha.10

package/src/definitions/parameter.ts

@@ -1,6 +1,6 @@
 import type { VmPrimitive, VmRecord } from '@mirascript/mirascript';
-import type { ExpressionOrValue } from '../expression.js';
-import type { ArgumentMap, ArgumentValue, ConditionExpression, ParameterFunction } from './argument.js';
+import type { ExpressionFunction, ExpressionOrValue } from '../expression.js';
+import type { ArgumentMap, ArgumentValue, ConditionExpression } from './argument.js';
 import type { Constraint } from './constraint.js';
 import type { ParameterDecoration } from './parameter-decoration.js';
 import type { ParameterGroup } from './parameter-group.js';
@@ -65,13 +65,10 @@ 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>;
+export type Choice<V extends ChoiceArgumentValue = ChoiceArgumentValue> = {
+    /** 选中该选项将存储的参数值，默认值为其在数组中的索引 */
+    key: V;
     /** 选项名称 */
     name: string;
     /** 选项详细描述 */
@@ -81,64 +78,56 @@ export type Choice<V extends ChoiceArgumentValue> = {
 };
 
 /** 是否为选项 */
-export function isChoice<V extends NonNullable<VmPrimitive>>(value: unknown): value is Choice<V> {
+export function isChoice<V extends ChoiceArgumentValue = ChoiceArgumentValue>(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: '',
-    };
+    return (
+        typeof c.name === 'string' &&
+        typeof c.description == 'string' &&
+        !('items' in c) &&
+        !('value' in c) &&
+        !('span' in c)
+    );
 }
-
 /**
  * 表示值为选择项的参数定义
  */
-export interface ChoiceParameter<V extends ChoiceArgumentValue> extends ParameterBase<'choice', V> {
+export interface ChoiceParameter<V extends ChoiceArgumentValue = ChoiceArgumentValue>
+    extends ParameterBase<'choice', V> {
     /**
      * 可选取值及其对应的说明文本
      */
-    choices: ExpressionOrValue<Array<Choice<V>>> | ParameterFunction<Array<Choice<V>>>;
+    choices: ExpressionOrValue<Array<Choice<V>>> | ExpressionFunction<ReadonlyArray<Choice<V>>>;
 }
 /**
  * 表示值为多选选择项的参数定义
  */
-export interface MultiSelectParameter<V extends readonly ChoiceArgumentValue[]>
+export interface MultiSelectParameter<V extends readonly ChoiceArgumentValue[] = readonly ChoiceArgumentValue[]>
     extends ParameterBase<'multiSelect', V> {
     /**
      * 可选取值及其对应的说明文本
      */
-    choices: ExpressionOrValue<Array<Choice<V[number]>>> | ParameterFunction<Array<Choice<V[number]>>>;
+    choices: ExpressionOrValue<Array<Choice<V[number]>>> | ExpressionFunction<ReadonlyArray<Choice<V[number]>>>;
 }
 
 /**
  * 表示值为布尔量的参数定义
  */
-export interface LogicalParameter<V extends ChoiceArgumentValue> extends ParameterBase<'logical', V> {
+export interface LogicalParameter<V extends ChoiceArgumentValue = ChoiceArgumentValue>
+    extends ParameterBase<'logical', V> {
     /**
      * 可选取值及其对应的说明文本
      */
     choices?:
         | ExpressionOrValue<[false: Choice<V>, true: Choice<V>]>
-        | ParameterFunction<[false: Choice<V>, true: Choice<V>]>;
+        | ExpressionFunction<readonly [false: Choice<V>, true: Choice<V>]>;
 }
 
 /**
  * 表示值为表格的参数定义
  */
-export interface TableParameter<V extends readonly ArgumentValue[]> extends ParameterBase<'table', V> {
+export interface TableParameter<V extends readonly ArgumentValue[] = readonly ArgumentValue[]>
+    extends ParameterBase<'table', V> {
     /** 最小行数 */
     minRowCount?: number;
     /** 最大行数 */
@@ -152,7 +141,15 @@ export interface TableParameter<V extends readonly ArgumentValue[]> extends Para
      *
      * 否则，表格参数的值为记录类型数组，每个记录包含各列定义的键值
      */
-    columns: Parameter[] | ParameterFunction<Parameter[]>;
+    columns: Parameter[] | ExpressionFunction<readonly Parameter[]>;
+    /** 添加额外属性以跟踪表格行 */
+    trackTag?: string;
+}
+
+/** 生成用于跟踪的额外属性值 */
+export function generateTrackId(): number {
+    // 生成 1 ~ 2^31-1 之间的随机整数
+    return Math.trunc(1 + Math.random() * 0x7fff_ffff);
 }
 
 /**
@@ -162,7 +159,7 @@ export interface TableParameter<V extends readonly ArgumentValue[]> extends Para
  *
  * 字段中可包含占位符，占位符在主轴上尺寸可自定义。
  */
-export interface RecordParameter<V extends VmRecord> extends ParameterBase<'record', V> {
+export interface RecordParameter<V extends VmRecord = VmRecord> extends ParameterBase<'record', V> {
     /** 主轴的优先方向 */
     direction?: 'row' | 'column';
     /** 包含的元素 */
@@ -176,7 +173,7 @@ export interface RecordParameter<V extends VmRecord> extends ParameterBase<'reco
  *
  * 各分组沿主轴排列时占据位置由 span 定义。
  */
-export interface GroupedParameter<V extends VmRecord> extends ParameterBase<'grouped', V> {
+export interface GroupedParameter<V extends VmRecord = VmRecord> extends ParameterBase<'grouped', V> {
     /** 主轴的优先方向 */
     direction?: 'row' | 'column';
     /** 包含的元素 */
@@ -227,23 +224,41 @@ export interface FileParameter extends ParameterBase<'file', string> {
 /**
  * 已定义的参数类型
  */
-export type ParameterMap = {
+export interface 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[]>;
+    /** 选择参数 */
+    choice: ChoiceParameter;
+    /** 多选参数 */
+    multiSelect: MultiSelectParameter;
+    /** 布尔参数 */
+    logical: LogicalParameter;
+    /** 表格参数 */
+    table: TableParameter;
+    /** 文本参数 */
     text: TextParameter;
+    /** 代码参数 */
     code: CodeParameter;
+    /** 文件参数 */
     file: FileParameter;
+    /** 记录参数 */
     record: RecordParameter<VmRecord>;
+    /** 分组记录参数 */
     grouped: GroupedParameter<VmRecord>;
-};
-/**
- * 已定义的参数类型
- */
-export type Parameter = ParameterMap[keyof ParameterMap];
+}
+
+/** 已定义的参数类型 type */
+export type ParameterType = keyof ParameterMap;
+
+/** 已定义的参数类型 */
+export type Parameter = ParameterMap[ParameterType];
+
+/** 已定义的选择参数类型 */
+export type ChoiceParameterType = {
+    [K in keyof ParameterMap]: ParameterMap[K] extends { choices?: infer _ } ? ParameterMap[K]['type'] : never;
+}[keyof ParameterMap];
 
 /**
  * 是否为参数定义
@@ -260,17 +275,3 @@ export function isParameter(value: unknown): value is Parameter {
         'value' in v
     );
 }
-
-/**
- * 创建参数定义
- */
-export function Parameter(): RealParameter {
-    return {
-        key: '',
-        name: '',
-        description: '',
-        condition: '' as ConditionExpression,
-        type: 'real',
-        value: 0,
-    };
-}

package/src/definitions/utils.ts

@@ -0,0 +1,175 @@
+import { klona } from 'klona';
+import { isVmArray, type VmPrimitive, type VmValue } from '@mirascript/mirascript';
+import { Expression, isExpression } from '../expression.js';
+import type { ChoiceParameterType, Parameter, ParameterMap } from './parameter.js';
+import { TypeInfo } from '../type.js';
+import type { ArgumentMap, ArgumentValue } from './argument.js';
+import type { ParameterGroup } from './parameter-group.js';
+const { isArray } = Array;
+
+/** 推测枚举类型 */
+export function enumType(definition: Pick<ParameterMap[ChoiceParameterType], 'type' | 'choices'>): TypeInfo | null {
+    const { choices } = definition;
+    if (typeof choices == 'function' || isExpression(choices)) return null;
+    let defaultType: TypeInfo = definition.type === 'logical' ? 'boolean' : 'number';
+    if ('value' in definition) {
+        const { value } = definition;
+        if (typeof value == 'boolean') defaultType = 'boolean';
+        else if (typeof value == 'number') defaultType = 'number';
+        else if (typeof value == 'string') defaultType = 'string';
+    }
+    if (choices == null || choices.length === 0) return defaultType;
+
+    let type: TypeInfo | null = null;
+    for (const choice of choices) {
+        const v = choice?.key;
+        const t = v == null ? defaultType : typeof v;
+        if (t === 'string') {
+            if (type == null) type = 'string';
+            else if (type !== 'string') return null;
+        } else if (t === 'number') {
+            if (type == null) type = 'number';
+            else if (type !== 'number') return null;
+        } else if (t === 'boolean') {
+            if (type == null) type = 'boolean';
+            else if (type !== 'boolean') return null;
+        } else {
+            return null;
+        }
+    }
+    return type;
+}
+
+/**
+ * 转换参数值的类型，不回退到 {@link Parameter.value} 提供的默认值
+ */
+export function toArgumentValue<V extends ArgumentValue>(value: VmValue, definition: Parameter): V {
+    // 避免无效的 VmValue 导致错误
+    value ??= null;
+
+    switch (definition.type) {
+        case 'real':
+        case 'integer':
+            return TypeInfo.toNumber(value) as V;
+        case 'text':
+        case 'file':
+        case 'code':
+        case 'pinLike' as never:
+        case 'cssColor' as never:
+        case 'cssBackground' as never:
+        case 'resourceId' as never:
+            return TypeInfo.toString(value) as V;
+
+        case 'choice':
+        case 'logical': {
+            if (value == null && Array.isArray(definition.choices) && definition.choices.length > 0) {
+                value = definition.choices[0]?.key;
+            }
+            const type = enumType(definition);
+            if (!type) return value as V;
+            return TypeInfo.to(value, type) as V;
+        }
+
+        case 'multiSelect': {
+            const v = isVmArray(value) ? value : value != null ? ([value] as const) : [];
+            if (v.length === 0) return v as V;
+            const type = enumType(definition);
+            if (!type) return v as V;
+            return v.map((x) => TypeInfo.to(x, type)) as readonly VmPrimitive[] as V;
+        }
+
+        case 'table': {
+            const v = isVmArray(value) ? value : value != null ? ([value] as const) : [];
+            return v as V;
+        }
+
+        case 'grouped':
+        case 'record':
+        default:
+            return value as V;
+    }
+}
+
+/** 参数定义数组 */
+type ParameterDefinitions = ReadonlyArray<Pick<ParameterGroup, 'items'>>;
+/** 是否为包含参数组的参数定义数组 */
+function checkParameterDefinitions(value: ParameterDefinitions | undefined): value is ParameterDefinitions {
+    return value != null && isArray(value as unknown[]) && value.length > 0;
+}
+
+/** 查找指定参数 */
+function findParameterImpl(items: readonly Parameter[], key: string): Parameter | undefined {
+    if (items.length === 0) return undefined;
+    for (const item of items) {
+        if (item == null) continue;
+        if (item.key === key) return item;
+    }
+    return undefined;
+}
+
+/** 查找指定参数 */
+export function findParameter(definition: ParameterDefinitions | undefined, key: string): Parameter | undefined {
+    if (!checkParameterDefinitions(definition)) return undefined;
+    for (const group of definition) {
+        if (group == null || !isArray(group.items)) continue;
+        const found = findParameterImpl(group.items, key);
+        if (found) return found;
+    }
+    return undefined;
+}
+
+/** 获取参数默认值，修复现有的参数，填充缺失的参数，删除未定义的参数 */
+export function fillArgumentMap<T extends Record<string, ArgumentValue>>(
+    definition: ParameterDefinitions | undefined,
+    args?: ArgumentMap<T> | null,
+): ArgumentMap<T> {
+    args ??= {} as ArgumentMap<T>;
+    if (!checkParameterDefinitions(definition)) return args;
+
+    /** 参数键的类型 */
+    type K = keyof T & string;
+    /** 参数值的类型 */
+    type V = NonNullable<T[K]>;
+    const keys = new Set(Object.keys(args) as K[]);
+
+    // 根据定义填充或修复参数
+    for (const group of definition) {
+        for (const param of group.items) {
+            const key = param.key as K;
+            if (!key) continue;
+            const currentValue = keys.has(key) ? args[key] : undefined;
+            if (currentValue == null) {
+                // 使用默认值填充
+                const defaultValue = param.value;
+                if (isExpression(defaultValue)) {
+                    args[key] = Expression<V>(defaultValue.source);
+                } else {
+                    const value =
+                        defaultValue != null && typeof defaultValue == 'object' ? klona(defaultValue) : defaultValue;
+                    args[key] = toArgumentValue<V>(value, param);
+                }
+            } else {
+                // 已存在的参数值
+                if (isExpression(currentValue)) {
+                    // 保留表达式
+                } else {
+                    // 修复现有的参数值
+                    const castedValue = toArgumentValue<V>(currentValue, param);
+                    if (castedValue != null && castedValue !== currentValue) {
+                        args[key] = castedValue;
+                    }
+                }
+            }
+            keys.delete(key);
+        }
+    }
+
+    // 删除多余的参数
+    for (const key of keys) {
+        // 保留特殊参数和私有字段
+        const k0 = key[0];
+        if (k0 === '_' || k0 === '$' || k0 === '@' || k0 === 'ɵ') continue;
+        delete args[key];
+    }
+    return args;
+}

package/src/definitions/variable.ts

@@ -12,12 +12,7 @@ export type Variable<T extends ArgumentValue = ArgumentValue> = {
 /** 检查是否为 `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;
+    if ('condition' in obj || 'description' in obj || 'type' 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

@@ -4,3 +4,4 @@ export * from './definitions/parameter.js';
 export * from './definitions/parameter-group.js';
 export * from './definitions/parameter-decoration.js';
 export * from './definitions/variable.js';
+export * from './definitions/utils.js';

package/src/eval.ts

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

package/src/expression.ts

@@ -2,6 +2,7 @@ import type { VmValue } from '@mirascript/mirascript';
 import type { Tagged } from 'type-fest';
 import type { LegacyType, TsTypeOf, TypeInfo } from './type.js';
 import type { Scope } from './scope.js';
+import type { Evaluator } from './main.js';
 
 /** 表达式的标记属性 */
 export const ExpressionTag = 'ɵexp' as const;
@@ -18,10 +19,7 @@ export type Expression<T extends VmValue = VmValue> = {
 /**
  * 编译后的表达式
  */
-export interface CompiledExpression<T extends VmValue = VmValue> extends Expression<T> {
-    (scope: Scope, defaults: T): T;
-    (scope?: Scope): T | undefined;
-}
+export type CompiledExpression<T extends VmValue = VmValue> = Expression<T> & ExpressionFunction<T>;
 
 /** 表示一个表达式内容 */
 export type ExpressionSource<T extends VmValue = VmValue> = Tagged<string, 'ExpressionResult', T>;
@@ -41,9 +39,9 @@ export function Expression<T extends VmValue = VmValue>(
     source: string | Expression<T>,
     returnType: TypeInfo | LegacyType | '' = '',
 ): Expression<T> {
-    if (!source) throw new Error(`Invalid expression ${String(source)}`);
+    if (source == null) throw new TypeError(`Invalid expression ${String(source)}`);
     const s = isExpression(source) ? source.source : source;
-    if (!s || typeof s != 'string') throw new Error(`Invalid expression ${String(s)}`);
+    if (typeof s != 'string') throw new TypeError(`Invalid expression ${String(s)}`);
     return { [ExpressionTag]: returnType, source: s as ExpressionSource<T> };
 }
 
@@ -60,3 +58,13 @@ export type ExpressionResult<T> = T extends Expression<infer R> ? R : T;
 export type ExpressionResultObject<T> = {
     [K in keyof T]: ExpressionResult<T[K]>;
 };
+
+/**
+ * 表示一个具有类似表达式功能的 JS 函数
+ */
+export type ExpressionFunction<out T> = (
+    /** 当前作用域 */
+    scope: Scope,
+    /** 当前求值器 */
+    evaluator: Evaluator,
+) => T | null;

package/src/index.ts

@@ -1,5 +1,7 @@
-export type { Options, Context } from './context.js';
+export type { Options, Logger } from './interface.js';
 export { Scope } from './scope.js';
 export { Evaluator } from './main.js';
+export type { AccessChain } from './analyze.js';
 export * from './expression.js';
 export * from './type.js';
+export * from './re-exports.js';

package/src/interface.ts

@@ -0,0 +1,35 @@
+/** 日志 */
+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;
+    /** 模板缓存 */
+    templateCacheSize: number;
+}
+
+export const defaultOptions: Options = {
+    logger: console,
+    expressionCacheSize: 50,
+    templateCacheSize: 50,
+};