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

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