@cloudpss/expression 0.6.0-alpha.8 → 0.6.0-beta.1

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，当其值为数字时，默认值为其在数组中的索引 */
-export type ChoiceKey<V extends ChoiceArgumentValue = ChoiceArgumentValue> = V extends number ? number | null : V;
-
 /** 表示一个选项 */
 export type Choice<V extends ChoiceArgumentValue = ChoiceArgumentValue> = {
-    /** 选中该选项将存储的参数值 */
-    key: ChoiceKey<V>;
+    /** 选中该选项将存储的参数值，默认值为其在数组中的索引 */
+    key: V;
     /** 选项名称 */
     name: string;
     /** 选项详细描述 */
@@ -84,47 +81,60 @@ export type Choice<V extends ChoiceArgumentValue = ChoiceArgumentValue> = {
 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);
+    return (
+        typeof c.name === 'string' &&
+        typeof c.description == 'string' &&
+        !('items' in c) &&
+        !('value' in c) &&
+        !('span' in c)
+    );
 }
 /**
  * 表示值为选择项的参数定义
  */
-export interface ChoiceParameter<V extends ChoiceArgumentValue = 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[] = readonly ChoiceArgumentValue[]>
-    extends ParameterBase<'multiSelect', V> {
+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 = 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[] = readonly ArgumentValue[]>
-    extends ParameterBase<'table', V> {
+export interface TableParameter<V extends readonly ArgumentValue[] = readonly ArgumentValue[]> extends ParameterBase<
+    'table',
+    V
+> {
     /** 最小行数 */
     minRowCount?: number;
     /** 最大行数 */
@@ -138,7 +148,15 @@ export interface TableParameter<V extends readonly ArgumentValue[] = readonly Ar
      *
      * 否则，表格参数的值为记录类型数组，每个记录包含各列定义的键值
      */
-    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);
 }
 
 /**
@@ -219,13 +237,13 @@ export interface ParameterMap {
     /** 整数参数 */
     integer: IntegerParameter;
     /** 选择参数 */
-    choice: ChoiceParameter<string> | ChoiceParameter<number> | ChoiceParameter<boolean>;
+    choice: ChoiceParameter;
     /** 多选参数 */
-    multiSelect: MultiSelectParameter<string[]> | MultiSelectParameter<number[]> | MultiSelectParameter<boolean[]>;
+    multiSelect: MultiSelectParameter;
     /** 布尔参数 */
-    logical: LogicalParameter<string> | LogicalParameter<number> | LogicalParameter<boolean>;
+    logical: LogicalParameter;
     /** 表格参数 */
-    table: TableParameter<ArgumentValue[]>;
+    table: TableParameter;
     /** 文本参数 */
     text: TextParameter;
     /** 代码参数 */
@@ -244,6 +262,11 @@ 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];
+
 /**
  * 是否为参数定义
  */

package/src/definitions/utils.ts

@@ -0,0 +1,288 @@
+import { klona } from 'klona';
+import { isVmArray, isVmConst, isVmRecord, type VmConst, type VmRecord, type VmValue } from '@mirascript/mirascript';
+import { Expression, isExpression, type ExpressionOrValue } 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 type ArgumentConverter<out R extends ArgumentValue = ArgumentValue> = <const D = undefined>(
+    value: VmValue | null | undefined,
+    defaults?: D,
+) => R | Exclude<D, undefined>;
+
+/** 回退值 */
+function toFallback<F>(fallback: F | undefined): Exclude<F, undefined> {
+    if (fallback === undefined) {
+        throw new TypeError('Conversion failed and no fallback value provided');
+    }
+    return fallback as Exclude<F, undefined>;
+}
+/**
+ * 通过枚举参数定义推测枚举类型
+ */
+export function choiceParameterType(
+    definition: Pick<ParameterMap[ChoiceParameterType], 'type' | 'value' | 'choices'>,
+): TypeInfo {
+    // 首先根据参数类型确定默认类型
+    let defaultType: TypeInfo = definition.type === 'logical' ? 'boolean' : 'number';
+    // 然后根据默认值调整默认类型
+    const { value, choices } = definition;
+    if (definition.type === 'multiSelect' && Array.isArray(value)) {
+        const v: unknown = value[0];
+        if (isChoiceValue(v)) {
+            defaultType = typeof v as TypeInfo;
+        }
+    } else {
+        if (isChoiceValue(value)) {
+            defaultType = typeof value as TypeInfo;
+        }
+    }
+
+    if (choices == null || typeof choices == 'function' || isExpression(choices) || !choices.length) {
+        return defaultType;
+    }
+
+    // 认为枚举选项值类型一致，推测枚举类型
+    for (const choice of choices) {
+        const v = choice?.key;
+        if (!isChoiceValue(v)) continue;
+        return typeof v as TypeInfo;
+    }
+    return defaultType;
+}
+
+/** 是否为枚举值类型 */
+export function isChoiceValue(value: unknown): value is ChoiceParameterType {
+    return typeof value == 'string' || typeof value == 'number' || typeof value == 'boolean';
+}
+
+const defaultConverter: ArgumentConverter = (value, defaults) => {
+    if (value != null) return value as ArgumentValue;
+    return toFallback(defaults);
+};
+
+/** 转换数组参数类型 */
+function createArrayConverter<T extends ArgumentValue>(
+    itemConverter: ArgumentConverter<T> | null = null,
+): ArgumentConverter<readonly T[]> {
+    if (itemConverter == null) {
+        return (value, defaults) => {
+            if (value == null) return [];
+            if (isVmArray(value)) return value as T[];
+            if (isVmConst(value)) return [value] as T[];
+            return toFallback(defaults);
+        };
+    }
+    return (value, defaults) => {
+        if (value == null) return [];
+        let arr: ArgumentValue[];
+        if (isVmArray(value)) arr = value as ArgumentValue[];
+        else if (isVmConst(value)) arr = [value];
+        else return toFallback(defaults);
+        if (arr.length === 0) return arr as T[];
+        let ret: T[] | null = null;
+        for (let i = 0; i < arr.length; i++) {
+            const el = arr[i];
+            const r = itemConverter(el, FALLBACK);
+            if (r === FALLBACK) return toFallback(defaults);
+            if (!Object.is(r, el)) {
+                ret ??= [...(arr as T[])];
+                ret[i] = r;
+            }
+        }
+        return ret ?? (arr as T[]);
+    };
+}
+
+/** 转换记录参数类型 */
+function createRecordConverter<T extends Record<string, VmConst | undefined> = VmRecord>(
+    fieldConverters: ReadonlyArray<[key: keyof T, converter: ArgumentConverter | null]> | null = null,
+): ArgumentConverter<T> {
+    if (fieldConverters == null) {
+        return (value, defaults) => {
+            if (isVmRecord(value)) return value as T;
+            if (isVmArray(value)) {
+                const obj: Record<string, VmConst> = {};
+                for (let i = 0; i < value.length; i++) {
+                    obj[i] = value[i] ?? null;
+                }
+                return obj as T;
+            }
+            return toFallback(defaults);
+        };
+    }
+    return (value, defaults) => {
+        let record: VmRecord;
+        if (isVmRecord(value)) record = value;
+        else if (isVmArray(value)) {
+            const obj: Record<string, VmConst> = {};
+            for (let i = 0; i < value.length; i++) {
+                obj[i] = value[i] ?? null;
+            }
+            record = obj;
+        } else return toFallback(defaults);
+        let ret: T | null = null;
+        for (const [key, converter] of fieldConverters) {
+            if (typeof converter != 'function') continue;
+            const fieldValue = record[key as string];
+            const r = converter(fieldValue, FALLBACK);
+            if (r === FALLBACK) return toFallback(defaults);
+            if (!Object.is(r, fieldValue)) {
+                ret ??= { ...(record as T) };
+                ret[key] = r as T[typeof key];
+            }
+        }
+        return ret ?? (record as T);
+    };
+}
+
+const FALLBACK = Symbol('FALLBACK');
+/** 转换推测参数类型，不回退到 {@link Parameter.value} 提供的默认值 */
+export function argumentConverter(definition: Parameter): ArgumentConverter {
+    switch (definition.type) {
+        case 'real':
+        case 'integer':
+            return TypeInfo.converter('number');
+        case 'text':
+        case 'file':
+        case 'code':
+        case 'pinLike' as never:
+        case 'cssColor' as never:
+        case 'cssBackground' as never:
+        case 'resourceId' as never:
+            return TypeInfo.converter('string');
+
+        case 'choice':
+        case 'logical': {
+            const type = choiceParameterType(definition);
+            return TypeInfo.converter(type);
+        }
+
+        case 'multiSelect': {
+            const type = choiceParameterType(definition);
+            const to = TypeInfo.converter(type);
+            return createArrayConverter(to);
+        }
+
+        case 'table': {
+            const { columns } = definition;
+            if (!isArray(columns) || !columns.length) {
+                return createArrayConverter();
+            }
+            if (columns.length === 1) {
+                const item = argumentConverter(columns[0]!);
+                return createArrayConverter(item);
+            } else {
+                return createArrayConverter(
+                    createRecordConverter(
+                        columns.map((col, index) => [col.key || String(index), argumentConverter(col)] as const),
+                    ),
+                );
+            }
+        }
+
+        case 'grouped':
+        case 'record': {
+            return createRecordConverter();
+        }
+        default:
+            return defaultConverter;
+    }
+}
+
+/**
+ * 转换参数值的类型，不回退到 {@link Parameter.value} 提供的默认值
+ * 转换失败时返回 null
+ */
+export function toArgumentValue(value: VmValue | null | undefined, definition: Parameter): ArgumentValue | null {
+    const converter = argumentConverter(definition);
+    return converter(value, null);
+}
+
+/** 参数定义数组 */
+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;
+    /** 参数值的类型 */
+    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 as ExpressionOrValue<V>;
+                if (isExpression(defaultValue)) {
+                    args[key] = Expression<V>(defaultValue.source);
+                } else {
+                    const value =
+                        defaultValue != null && typeof defaultValue == 'object' ? klona(defaultValue) : defaultValue;
+                    args[key] = (toArgumentValue(value, param) as V | null) ?? value;
+                }
+            } else {
+                // 已存在的参数值
+                if (isExpression(currentValue)) {
+                    // 保留表达式
+                } else {
+                    // 修复现有的参数值
+                    const castedValue = toArgumentValue(currentValue, param) as V | null;
+                    if (castedValue != null && castedValue !== currentValue) {
+                        args[key] = castedValue;
+                    }
+                }
+            }
+            keys.delete(key);
+        }
+    }
+
+    // 删除多余的参数
+    for (const key of keys) {
+        // 保留特殊参数和私有字段
+        if (typeof key != 'string') continue;
+        const k0 = key[0];
+        if (k0 === '_' || k0 === '$' || k0 === '@' || k0 === 'ɵ') continue;
+        delete args[key];
+    }
+    return args;
+}

package/src/definitions/variable.ts

@@ -12,7 +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;
 }

package/src/definitions.ts

@@ -4,31 +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 {
-    isVmAny,
-    isVmArray,
-    isVmConst,
-    isVmContext,
-    isVmExtern,
-    isVmFunction,
-    isVmImmutable,
-    isVmModule,
-    isVmPrimitive,
-    isVmRecord,
-    isVmValue,
-} from '@mirascript/mirascript';
-export type {
-    VmExtern,
-    VmFunction,
-    VmModule,
-    VmAny,
-    VmArray,
-    VmConst,
-    VmContext,
-    VmImmutable,
-    VmPrimitive,
-    VmRecord,
-    VmUninitialized,
-    VmValue,
-} from '@mirascript/mirascript';
+export * from './definitions/utils.js';

package/src/eval.ts

@@ -1,64 +1,55 @@
 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 | null,
     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 ?? console).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,
+export function evaluate<T extends VmValue>(
+    evaluator: Evaluator | null,
     expression: ExpressionCache,
-    returnType: TypeInfo | null,
-    scope: Scope | undefined,
-    defaults: D,
-): D | T {
-    let ret: T | typeof DEFAULTS;
+    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,16 +39,16 @@ 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)}`);
-    return { [ExpressionTag]: returnType, source: s as ExpressionSource<T> };
+    if (typeof s != 'string') throw new TypeError(`Invalid expression ${String(s)}`);
+    return { [ExpressionTag]: returnType || '', source: s as ExpressionSource<T> };
 }
 
 /** 检查是否为表达式 */
 export function isExpression<T extends VmValue>(value: unknown): value is Expression<T> | CompiledExpression<T> {
     if (value == null || (typeof value != 'object' && typeof value != 'function')) return false;
-    return ExpressionTag in value;
+    return typeof (value as Expression<T>)[ExpressionTag] == 'string';
 }
 
 /** 表示一个表达式求值的结果 */
@@ -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 { GlobalReferenceChain } 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,
+};