@flowgram.ai/variable-core 0.1.24 → 0.1.26

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { ContainerModule, interfaces } from 'inversify';
 import * as _flowgram_ai_utils from '@flowgram.ai/utils';
-import { DisposableCollection, Event, Disposable, Emitter } from '@flowgram.ai/utils';
-import { BehaviorSubject, Subject, Observable, Observer as Observer$1 } from 'rxjs';
+import { Disposable, Emitter, DisposableCollection, Event } from '@flowgram.ai/utils';
+import { Subject, Observable, BehaviorSubject, Observer as Observer$1 } from 'rxjs';
 export { Observer } from 'rxjs';
 import * as react from 'react';
 
@@ -10,6 +10,164 @@ declare const VariableContainerModule: ContainerModule;
 declare const VariableEngineProvider: unique symbol;
 type VariableEngineProvider = () => VariableEngine;
 
+/**
+ * 作用域输出
+ */
+declare class ScopeOutputData {
+    readonly scope: Scope;
+    protected variableTable: IVariableTable;
+    protected memo: {
+        <T>(key: string | symbol, fn: () => T): T;
+        clear: (key?: (string | symbol) | undefined) => void;
+    };
+    get variableEngine(): VariableEngine;
+    get globalVariableTable(): IVariableTable;
+    get onDataChange(): _flowgram_ai_utils.Event<void>;
+    get onAnyVariableChange(): (observer: (changedVariable: VariableDeclaration<any>) => void) => _flowgram_ai_utils.Disposable;
+    protected _hasChanges: boolean;
+    constructor(scope: Scope);
+    /**
+     * Scope Output Variable Declarations
+     */
+    get variables(): VariableDeclaration[];
+    /**
+     * Output Variable Keys
+     */
+    get variableKeys(): string[];
+    addVariableToTable(variable: VariableDeclaration): void;
+    removeVariableFromTable(key: string): void;
+    getVariableByKey(key: string): VariableDeclaration<any> | undefined;
+    /**
+     *
+     */
+    notifyCoversChange(): void;
+}
+
+/**
+ * 作用域可用变量
+ */
+declare class ScopeAvailableData {
+    readonly scope: Scope;
+    protected memo: {
+        <T>(key: string | symbol, fn: () => T): T;
+        clear: (key?: (string | symbol) | undefined) => void;
+    };
+    get globalVariableTable(): IVariableTable;
+    protected refresh$: Subject<void>;
+    protected _variables: VariableDeclaration[];
+    refresh(): void;
+    /**
+     * 监听
+     */
+    protected variables$: Observable<VariableDeclaration[]>;
+    protected anyVariableChange$: Observable<VariableDeclaration>;
+    /**
+     * 监听任意变量变化
+     * @param observer 监听器，变量变化时会吐出值
+     * @returns
+     */
+    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    /**
+     * 监听变量列表变化
+     * @param observer
+     * @returns
+     */
+    onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
+    protected onDataChangeEmitter: Emitter<VariableDeclaration<any>[]>;
+    /**
+     * 监听变量列表变化 + 任意子变量变化
+     */
+    onDataChange: _flowgram_ai_utils.Event<VariableDeclaration<any>[]>;
+    constructor(scope: Scope);
+    /**
+     * 获取可消费变量
+     */
+    get variables(): VariableDeclaration[];
+    /**
+     * 获取可访问的变量 keys
+     */
+    get variableKeys(): string[];
+    /**
+     * 返回依赖的作用域
+     */
+    get depScopes(): Scope[];
+    /**
+     * 通过 keyPath 找到可用变量
+     * @param keyPath
+     * @returns
+     */
+    getByKeyPath(keyPath?: string[]): VariableDeclaration | Property | undefined;
+}
+
+type Observer<ActionType extends GlobalEventActionType = GlobalEventActionType> = (action: ActionType) => void;
+declare class ScopeEventData {
+    readonly scope: Scope;
+    event$: Subject<GlobalEventActionType>;
+    dispatch<ActionType extends GlobalEventActionType = GlobalEventActionType>(action: ActionType): void;
+    subscribe<ActionType extends GlobalEventActionType = GlobalEventActionType>(observer: Observer<ActionType>): Disposable;
+    on<ActionType extends GlobalEventActionType = GlobalEventActionType>(type: ActionType['type'], observer: Observer<ActionType>): Disposable;
+    constructor(scope: Scope);
+}
+
+interface IScopeConstructor {
+    new (options: {
+        id: string | symbol;
+        variableEngine: VariableEngine;
+        meta?: Record<string, any>;
+    }): Scope;
+}
+declare class Scope<ScopeMeta extends Record<string, any> = Record<string, any>> {
+    /**
+     * Scope 唯一索引
+     */
+    readonly id: string | symbol;
+    /**
+     * Scope 依赖变量引擎
+     */
+    readonly variableEngine: VariableEngine;
+    /**
+     * 作用域的基本元信息，包括作用域所在节点及一些 flag 信息，上层业务可以额外扩展
+     */
+    readonly meta: ScopeMeta;
+    /**
+     * 作用域 AST 根节点
+     * - Map<formItemKey, formItemValue>
+     */
+    readonly ast: MapNode;
+    /**
+     * 可用变量数据管理
+     */
+    readonly available: ScopeAvailableData;
+    /**
+     * 输出变量数据管理
+     */
+    readonly output: ScopeOutputData;
+    /**
+     * 作用域事件管理
+     */
+    readonly event: ScopeEventData;
+    /**
+     * 数据缓存
+     */
+    protected memo: {
+        <T>(key: string | symbol, fn: () => T): T;
+        clear: (key?: (string | symbol) | undefined) => void;
+    };
+    toDispose: DisposableCollection;
+    constructor(options: {
+        id: string | symbol;
+        variableEngine: VariableEngine;
+        meta?: ScopeMeta;
+    });
+    refreshCovers(): void;
+    refreshDeps(): void;
+    get depScopes(): Scope[];
+    get coverScopes(): Scope[];
+    dispose(): void;
+    onDispose: _flowgram_ai_utils.Event<void>;
+    get disposed(): boolean;
+}
+
 /**
  * 作用域依赖关系管理数据结构
  * - ScopeOrder 可能存在多种实现方式，因此采取抽象类的方式，具体的实现由子类实现
@@ -31,26 +189,6 @@ declare abstract class ScopeChain {
     get onDispose(): Event<void>;
 }
 
-declare enum ASTNodeFlags {
-    None = 0,
-    /**
-     * 变量字段
-     */
-    VariableField = 1,
-    /**
-     * 表达式
-     */
-    Expression = 4,
-    /**
-     * 变量类型
-     */
-    BasicType = 8,
-    DrilldownType = 16,
-    EnumerateType = 32,
-    UnionType = 64,
-    VariableType = 120
-}
-
 interface ASTNodeRegistry<JSON extends ASTNodeJSON = any, InjectOpts = any> {
     kind: string;
     new (params: CreateASTParams, injectOpts: InjectOpts): ASTNode<JSON>;
@@ -186,72 +324,197 @@ declare abstract class ASTNode<JSON extends ASTNodeJSON = any, InjectOpts = any>
     [key: string]: unknown;
 }
 
+type ASTKindType = string;
+type Identifier = string;
+interface ASTNodeJSON {
+    kind?: ASTKindType;
+    key?: Identifier;
+    [key: string]: any;
+}
 /**
- * 声明类 AST 节点
+ * 核心 AST 节点类型
  */
-type VariableDeclarationJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
-    order?: number;
-};
-declare class VariableDeclaration<VariableMeta = any> extends BaseVariableField<VariableMeta> {
-    static kind: string;
-    protected _order: number;
-    get order(): number;
-    constructor(params: CreateASTParams);
+declare enum ASTKind {
     /**
-     * 解析 VariableDeclarationJSON 从而生成变量声明节点
+     * 类型相关
+     * - 内部默认实现一套基于 JSON 类型的类型 AST 节点
      */
-    fromJSON({ order, ...rest }: VariableDeclarationJSON<VariableMeta>): void;
-    updateOrder(order?: number): void;
-    onTypeChange(observer: (type: ASTNode | undefined) => void): Disposable;
-}
-
-interface VariableDeclarationListJSON<VariableMeta = any> {
+    String = "String",
+    Number = "Number",
+    Integer = "Integer",
+    Boolean = "Boolean",
+    Object = "Object",
+    Array = "Array",
+    Map = "Map",
+    Union = "Union",
+    Any = "Any",
+    CustomType = "CustomType",
     /**
-     *  declarations 一定是 VariableDeclaration 类型，因此业务可以不用填 kind
+     * 声明
      */
-    declarations?: VariableDeclarationJSON<VariableMeta>[];
-    startOrder?: number;
-}
-type VariableDeclarationListChangeAction = GlobalEventActionType<'VariableListChange', {
-    prev: VariableDeclaration[];
-    next: VariableDeclaration[];
-}, VariableDeclarationList>;
-declare class VariableDeclarationList extends ASTNode<VariableDeclarationListJSON> {
-    static kind: string;
-    declarationTable: Map<string, VariableDeclaration>;
-    declarations: VariableDeclaration[];
-    fromJSON({ declarations, startOrder }: VariableDeclarationListJSON): void;
-    toJSON(): ASTNodeJSON;
-}
-
-type PropertyJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
-    key: string;
-};
-declare class Property<VariableMeta = any> extends BaseVariableField<VariableMeta> {
-    static kind: string;
-}
-
-declare abstract class BaseType<JSON extends ASTNodeJSON = any, InjectOpts = any> extends ASTNode<JSON, InjectOpts> {
-    flags: number;
+    Property = "Property",
+    VariableDeclaration = "VariableDeclaration",
+    VariableDeclarationList = "VariableDeclarationList",
     /**
-     * 类型是否一致，节点有额外信息判断，请参考 extraTypeInfoEqual
-     * @param targetTypeJSON
+     * 表达式
      */
-    isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
+    KeyPathExpression = "KeyPathExpression",
+    EnumerateExpression = "EnumerateExpression",
+    ExpressionList = "ExpressionList",
     /**
-     * 可下钻类型需实现
-     * @param keyPath
+     * 通用 AST 节点
      */
-    getByKeyPath(keyPath?: string[]): BaseVariableField | undefined;
-    toJSON(): ASTNodeJSON;
+    ListNode = "ListNode",
+    DataNode = "DataNode",
+    MapNode = "MapNode"
 }
-
-declare class StringType extends BaseType {
-    flags: ASTNodeFlags;
-    static kind: string;
-    fromJSON(): void;
+interface CreateASTParams {
+    scope: Scope;
+    key?: Identifier;
+    parent?: ASTNode;
 }
-
+type ASTNodeJSONOrKind = string | ASTNodeJSON;
+type ObserverOrNext<T> = Partial<Observer$1<T>> | ((value: T) => void);
+interface SubscribeConfig<This, Data> {
+    debounceAnimation?: boolean;
+    triggerOnInit?: boolean;
+    selector?: (curr: This) => Data;
+}
+type GetKindJSON<KindType extends string, JSON extends ASTNodeJSON> = {
+    kind: KindType;
+    key?: Identifier;
+} & JSON;
+type GetKindJSONOrKind<KindType extends string, JSON extends ASTNodeJSON> = ({
+    kind: KindType;
+    key?: Identifier;
+} & JSON) | KindType;
+interface GlobalEventActionType<Type = string, Payload = any, AST extends ASTNode = ASTNode> {
+    type: Type;
+    payload?: Payload;
+    ast?: AST;
+}
+
+type DataInjector = () => Record<string, any>;
+declare class ASTRegisters {
+    protected injectors: Map<ASTKindType, DataInjector>;
+    protected astMap: Map<ASTKindType, ASTNodeRegistry>;
+    /**
+     * 核心 AST 节点注册
+     */
+    constructor();
+    /**
+     * 创建 AST 节点
+     * @param param 创建参数
+     * @returns
+     */
+    createAST<ReturnNode extends ASTNode = ASTNode>(json: ASTNodeJSON, { parent, scope }: CreateASTParams): ReturnNode;
+    /**
+     * 根据 AST 节点类型获取节点 Registry
+     * @param kind
+     * @returns
+     */
+    getASTRegistryByKind(kind: ASTKindType): ASTNodeRegistry<any, any> | undefined;
+    /**
+     * 注册 AST 节点
+     * @param ASTNode
+     * @param injector
+     */
+    registerAST(ASTNode: ASTNodeRegistry, injector?: DataInjector): void;
+}
+
+declare enum ASTNodeFlags {
+    None = 0,
+    /**
+     * 变量字段
+     */
+    VariableField = 1,
+    /**
+     * 表达式
+     */
+    Expression = 4,
+    /**
+     * 变量类型
+     */
+    BasicType = 8,
+    DrilldownType = 16,
+    EnumerateType = 32,
+    UnionType = 64,
+    VariableType = 120
+}
+
+/**
+ * 通用数据 AST 节点，无子节点
+ */
+declare class DataNode<Data = any> extends ASTNode {
+    static kind: string;
+    protected _data: Data;
+    get data(): Data;
+    fromJSON(json: Data): void;
+    toJSON(): {
+        kind: ASTKind;
+    } & Data;
+    partialUpdate(nextData: Data): void;
+}
+
+interface ListNodeJSON {
+    list: ASTNodeJSON[];
+}
+declare class ListNode extends ASTNode<ListNodeJSON> {
+    static kind: string;
+    protected _list: ASTNode[];
+    get list(): ASTNode[];
+    fromJSON({ list }: ListNodeJSON): void;
+    toJSON(): ASTNodeJSON;
+}
+
+interface MapNodeJSON {
+    map: [string, ASTNodeJSON][];
+}
+declare class MapNode extends ASTNode<MapNodeJSON> {
+    static kind: string;
+    protected map: Map<string, ASTNode>;
+    fromJSON({ map }: MapNodeJSON): void;
+    toJSON(): ASTNodeJSON;
+    /**
+     * 往 Map 中设置 ASTNode
+     * @param key ASTNode 的索引，
+     * @param json
+     */
+    set<Node extends ASTNode = ASTNode>(key: string, nextJSON: ASTNodeJSON): Node;
+    /**
+     * 移除指定 ASTNode
+     * @param key
+     */
+    remove(key: string): void;
+    /**
+     * 获取 ASTNode
+     * @param key
+     * @returns
+     */
+    get(key: string): ASTNode | undefined;
+}
+
+declare abstract class BaseType<JSON extends ASTNodeJSON = any, InjectOpts = any> extends ASTNode<JSON, InjectOpts> {
+    flags: number;
+    /**
+     * 类型是否一致，节点有额外信息判断，请参考 extraTypeInfoEqual
+     * @param targetTypeJSON
+     */
+    isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
+    /**
+     * 可下钻类型需实现
+     * @param keyPath
+     */
+    getByKeyPath(keyPath?: string[]): BaseVariableField | undefined;
+    toJSON(): ASTNodeJSON;
+}
+
+declare class StringType extends BaseType {
+    flags: ASTNodeFlags;
+    static kind: string;
+    fromJSON(): void;
+}
+
 declare class IntegerType extends BaseType {
     flags: ASTNodeFlags;
     static kind: string;
@@ -307,6 +570,13 @@ declare class MapType extends BaseType<MapJSON> {
     toJSON(): ASTNodeJSON;
 }
 
+type PropertyJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
+    key: string;
+};
+declare class Property<VariableMeta = any> extends BaseVariableField<VariableMeta> {
+    static kind: string;
+}
+
 interface ObjectJSON<VariableMeta = any> {
     /**
      *  Object 的 properties 一定是 Property 类型，因此业务可以不用填 kind
@@ -360,7 +630,7 @@ declare abstract class BaseExpression<JSON extends ASTNodeJSON = any, InjectOpts
     /**
      * 获取全局变量表，方便表达式获取引用变量
      */
-    get globalVariableTable(): VariableTable;
+    get globalVariableTable(): IVariableTable;
     /**
      * 父变量字段，通过由近而远的方式进行排序
      */
@@ -373,444 +643,186 @@ declare abstract class BaseExpression<JSON extends ASTNodeJSON = any, InjectOpts
     /**
      * 表达式返回的数据类型
      */
-    abstract returnType: BaseType | undefined;
-    /**
-     * 引用变量
-     */
-    protected _refs: ExpressionRefs;
-    get refs(): ExpressionRefs;
-    protected refreshRefs$: Subject<void>;
-    /**
-     * 刷新变量引用
-     */
-    refreshRefs(): void;
-    /**
-     * 监听引用变量变化
-     * 监听 [a.b.c] -> [a.b]
-     */
-    refs$: Observable<ExpressionRefs>;
-    constructor(params: CreateASTParams, opts?: InjectOpts);
-}
-
-interface ExpressionListJSON {
-    expressions: ASTNodeJSON[];
-}
-declare class ExpressionList extends ASTNode<ExpressionListJSON> {
-    static kind: string;
-    expressions: ASTNode[];
-    fromJSON({ expressions }: ExpressionListJSON): void;
-    toJSON(): ASTNodeJSON;
-}
-
-interface KeyPathExpressionJSON$1 {
-    keyPath: string[];
-}
-declare class KeyPathExpression<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON$1> extends BaseExpression<CustomPathJSON> {
-    static kind: string;
-    protected _keyPath: string[];
-    get keyPath(): string[];
-    getRefFields(): BaseVariableField[];
-    get returnType(): BaseType | undefined;
-    /**
-     * 业务重改该方法可快速定制自己的 Path 表达式
-     * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-     * @param json 业务定义的 Path 表达式
-     * @returns
-     */
-    protected parseToKeyPath(json: CustomPathJSON): string[];
-    fromJSON(json: CustomPathJSON): void;
-    constructor(params: CreateASTParams, opts: any);
-    toJSON(): ASTNodeJSON;
-}
-
-interface EnumerateExpressionJSON {
-    enumerateFor: ASTNodeJSON;
-}
-/**
- * 遍历表达式，对列表进行遍历，获取遍历后的变量类型
- */
-declare class EnumerateExpression extends BaseExpression<EnumerateExpressionJSON> {
-    static kind: string;
-    protected _enumerateFor: BaseExpression | undefined;
-    get enumerateFor(): BaseExpression<any, any> | undefined;
-    get returnType(): BaseType | undefined;
-    getRefFields(): [];
-    fromJSON({ enumerateFor: expression }: EnumerateExpressionJSON): void;
-    toJSON(): ASTNodeJSON;
-}
-
-interface KeyPathExpressionJSON {
-    keyPath: string[];
-}
-/**
- * 新版 KeyPathExpressionV2，相比旧版：
- * - returnType 拷贝新一份，避免引用问题
- * - 引入成环检测
- */
-declare class KeyPathExpressionV2<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON> extends BaseExpression<CustomPathJSON> {
-    static kind: string;
-    protected _keyPath: string[];
-    get keyPath(): string[];
-    getRefFields(): BaseVariableField[];
-    _returnType: BaseType;
-    get returnType(): BaseType<any, any>;
-    /**
-     * 业务重改该方法可快速定制自己的 Path 表达式
-     * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-     * @param json 业务定义的 Path 表达式
-     * @returns
-     */
-    protected parseToKeyPath(json: CustomPathJSON): string[];
-    fromJSON(json: CustomPathJSON): void;
-    getReturnTypeJSONByRef(_ref: BaseVariableField | undefined): ASTNodeJSON | undefined;
-    protected prevRefTypeHash: string | undefined;
-    constructor(params: CreateASTParams, opts: any);
-    toJSON(): ASTNodeJSON;
-}
-
-/**
- * 声明类 AST 节点
- */
-type BaseVariableFieldJSON<VariableMeta = any> = {
-    key?: Identifier;
-    type?: ASTNodeJSONOrKind;
-    initializer?: ASTNodeJSON;
-    meta?: VariableMeta;
-};
-declare abstract class BaseVariableField<VariableMeta = any> extends ASTNode<BaseVariableFieldJSON<VariableMeta>> {
-    flags: ASTNodeFlags;
-    protected _type?: BaseType;
-    protected _meta: VariableMeta;
-    protected _initializer?: BaseExpression;
-    /**
-     * 父变量字段，通过由近而远的方式进行排序
-     */
-    get parentFields(): BaseVariableField[];
-    get meta(): VariableMeta;
-    get type(): BaseType;
-    get initializer(): BaseExpression | undefined;
-    /**
-     * 解析 VariableDeclarationJSON 从而生成变量声明节点
-     */
-    fromJSON({ type, initializer, meta }: BaseVariableFieldJSON<VariableMeta>): void;
-    updateType(type: BaseVariableFieldJSON['type']): void;
-    updateInitializer(nextInitializer?: BaseVariableFieldJSON['initializer']): void;
-    updateMeta(nextMeta: VariableMeta): void;
-    /**
-     * 根据 keyPath 去找下钻的变量字段
-     * @param keyPath
-     * @returns
-     */
-    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
-    /**
-     * 监听类型变化
-     * @param observer
-     * @returns
-     */
-    onTypeChange(observer: (type: ASTNode | undefined) => void): _flowgram_ai_utils.Disposable;
-    /**
-     * 转换为 JSON
-     * @returns
-     */
-    toJSON(): BaseVariableFieldJSON<VariableMeta> & {
-        kind: string;
-    };
-}
-
-declare class VariableTable implements Disposable {
-    parentTable?: VariableTable | undefined;
-    protected table: Map<string, VariableDeclaration>;
-    protected onDataChangeEmitter: Emitter<void>;
-    protected variables$: Subject<VariableDeclaration[]>;
-    protected anyVariableChange$: Observable<VariableDeclaration>;
-    /**
-     * 监听任意变量变化
-     * @param observer 监听器，变量变化时会吐出值
-     * @returns
-     */
-    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
-    /**
-     * 列表或者任意变量变化
-     * @param observer
-     */
-    onAnyChange(observer: () => void): DisposableCollection;
-    onDataChange: _flowgram_ai_utils.Event<void>;
-    protected _version: number;
-    fireChange(): void;
-    get version(): number;
-    constructor(parentTable?: VariableTable | undefined);
-    get variables(): VariableDeclaration[];
-    get variableKeys(): string[];
-    /**
-     * 根据 keyPath 找到对应的变量，或 Property 节点
-     * @param keyPath
-     * @returns
-     */
-    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
-    /**
-     * 根据 key 值找到相应的变量
-     * @param key
-     * @returns
-     */
-    getVariableByKey(key: string): VariableDeclaration<any> | undefined;
-    /**
-     * 往 variableTable 添加输出变量
-     * @param variable
-     */
-    addVariableToTable(variable: VariableDeclaration): void;
-    /**
-     * 从 variableTable 中移除变量
-     * @param key
-     */
-    removeVariableFromTable(key: string): void;
-    dispose(): void;
-}
-
-/**
- * 作用域输出
- */
-declare class ScopeOutputData {
-    readonly scope: Scope;
-    protected variableTable: VariableTable;
-    protected memo: {
-        <T>(key: string | symbol, fn: () => T): T;
-        clear: (key?: (string | symbol) | undefined) => void;
-    };
-    get variableEngine(): VariableEngine;
-    get globalVariableTable(): VariableTable;
-    get onDataChange(): _flowgram_ai_utils.Event<void>;
-    get onAnyVariableChange(): (observer: (changedVariable: VariableDeclaration<any>) => void) => _flowgram_ai_utils.Disposable;
-    protected _hasChanges: boolean;
-    constructor(scope: Scope);
-    /**
-     * 作用域输出变量
-     */
-    get variables(): VariableDeclaration[];
-    /**
-     * 输出的变量 keys
-     */
-    get variableKeys(): string[];
-    addVariableToTable(variable: VariableDeclaration): void;
-    setHasChanges(): void;
-    removeVariableFromTable(key: string): void;
-    getVariableByKey(key: string): VariableDeclaration<any> | undefined;
-    notifyCoversChange(): void;
-}
-
-/**
- * 作用域可用变量
- */
-declare class ScopeAvailableData {
-    readonly scope: Scope;
-    protected memo: {
-        <T>(key: string | symbol, fn: () => T): T;
-        clear: (key?: (string | symbol) | undefined) => void;
-    };
-    get globalVariableTable(): VariableTable;
-    protected refresh$: Subject<void>;
-    protected _variables: VariableDeclaration[];
-    refresh(): void;
-    /**
-     * 监听
-     */
-    protected variables$: Observable<VariableDeclaration[]>;
-    protected anyVariableChange$: Observable<VariableDeclaration>;
-    /**
-     * 监听任意变量变化
-     * @param observer 监听器，变量变化时会吐出值
-     * @returns
-     */
-    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
-    /**
-     * 监听变量列表变化
-     * @param observer
-     * @returns
-     */
-    onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
-    protected onDataChangeEmitter: Emitter<VariableDeclaration<any>[]>;
-    /**
-     * 监听变量列表变化 + 任意子变量变化
-     */
-    onDataChange: _flowgram_ai_utils.Event<VariableDeclaration<any>[]>;
-    constructor(scope: Scope);
-    /**
-     * 获取可消费变量
-     */
-    get variables(): VariableDeclaration[];
-    /**
-     * 获取可访问的变量 keys
-     */
-    get variableKeys(): string[];
-    /**
-     * 返回依赖的作用域
-     */
-    get depScopes(): Scope[];
-    /**
-     * 通过 keyPath 找到可用变量
-     * @param keyPath
-     * @returns
-     */
-    getByKeyPath(keyPath?: string[]): VariableDeclaration | Property | undefined;
-}
-
-type Observer<ActionType extends GlobalEventActionType = GlobalEventActionType> = (action: ActionType) => void;
-declare class ScopeEventData {
-    readonly scope: Scope;
-    event$: Subject<GlobalEventActionType>;
-    dispatch<ActionType extends GlobalEventActionType = GlobalEventActionType>(action: ActionType): void;
-    subscribe<ActionType extends GlobalEventActionType = GlobalEventActionType>(observer: Observer<ActionType>): Disposable;
-    on<ActionType extends GlobalEventActionType = GlobalEventActionType>(type: ActionType['type'], observer: Observer<ActionType>): Disposable;
-    constructor(scope: Scope);
-}
-
-type ASTKindType = string;
-type Identifier = string;
-interface ASTNodeJSON {
-    kind?: ASTKindType;
-    key?: Identifier;
-    [key: string]: any;
-}
-/**
- * 核心 AST 节点类型
- */
-declare enum ASTKind {
-    /**
-     * 类型相关
-     * - 内部默认实现一套基于 JSON 类型的类型 AST 节点
-     */
-    String = "String",
-    Number = "Number",
-    Integer = "Integer",
-    Boolean = "Boolean",
-    Object = "Object",
-    Array = "Array",
-    Map = "Map",
-    Union = "Union",
-    Any = "Any",
-    CustomType = "CustomType",
-    /**
-     * 声明
-     */
-    Property = "Property",
-    VariableDeclaration = "VariableDeclaration",
-    VariableDeclarationList = "VariableDeclarationList",
-    /**
-     * 表达式
-     */
-    KeyPathExpression = "KeyPathExpression",
-    EnumerateExpression = "EnumerateExpression",
-    ExpressionList = "ExpressionList",
-    /**
-     * 通用 AST 节点
-     */
-    ListNode = "ListNode",
-    DataNode = "DataNode",
-    MapNode = "MapNode"
-}
-interface CreateASTParams {
-    scope: Scope;
-    key?: Identifier;
-    parent?: ASTNode;
-}
-type ASTNodeJSONOrKind = string | ASTNodeJSON;
-type ObserverOrNext<T> = Partial<Observer$1<T>> | ((value: T) => void);
-interface SubscribeConfig<This, Data> {
-    debounceAnimation?: boolean;
-    triggerOnInit?: boolean;
-    selector?: (curr: This) => Data;
-}
-type GetKindJSON<KindType extends string, JSON extends ASTNodeJSON> = {
-    kind: KindType;
-    key?: Identifier;
-} & JSON;
-type GetKindJSONOrKind<KindType extends string, JSON extends ASTNodeJSON> = ({
-    kind: KindType;
-    key?: Identifier;
-} & JSON) | KindType;
-interface GlobalEventActionType<Type = string, Payload = any, AST extends ASTNode = ASTNode> {
-    type: Type;
-    payload?: Payload;
-    ast?: AST;
-}
-
-type DataInjector = () => Record<string, any>;
-declare class ASTRegisters {
-    protected injectors: Map<ASTKindType, DataInjector>;
-    protected astMap: Map<ASTKindType, ASTNodeRegistry>;
-    /**
-     * 核心 AST 节点注册
-     */
-    constructor();
+    abstract returnType: BaseType | undefined;
     /**
-     * 创建 AST 节点
-     * @param param 创建参数
-     * @returns
+     * 引用变量
      */
-    createAST<ReturnNode extends ASTNode = ASTNode>(json: ASTNodeJSON, { parent, scope }: CreateASTParams): ReturnNode;
+    protected _refs: ExpressionRefs;
+    get refs(): ExpressionRefs;
+    protected refreshRefs$: Subject<void>;
     /**
-     * 根据 AST 节点类型获取节点 Registry
-     * @param kind
-     * @returns
+     * 刷新变量引用
      */
-    getASTRegistryByKind(kind: ASTKindType): ASTNodeRegistry<any, any> | undefined;
+    refreshRefs(): void;
     /**
-     * 注册 AST 节点
-     * @param ASTNode
-     * @param injector
+     * 监听引用变量变化
+     * 监听 [a.b.c] -> [a.b]
      */
-    registerAST(ASTNode: ASTNodeRegistry, injector?: DataInjector): void;
+    refs$: Observable<ExpressionRefs>;
+    constructor(params: CreateASTParams, opts?: InjectOpts);
 }
 
-/**
- * 通用数据 AST 节点，无子节点
- */
-declare class DataNode<Data = any> extends ASTNode {
+interface ExpressionListJSON {
+    expressions: ASTNodeJSON[];
+}
+declare class ExpressionList extends ASTNode<ExpressionListJSON> {
     static kind: string;
-    protected _data: Data;
-    get data(): Data;
-    fromJSON(json: Data): void;
-    toJSON(): {
-        kind: ASTKind;
-    } & Data;
-    partialUpdate(nextData: Data): void;
+    expressions: ASTNode[];
+    fromJSON({ expressions }: ExpressionListJSON): void;
+    toJSON(): ASTNodeJSON;
 }
 
-interface ListNodeJSON {
-    list: ASTNodeJSON[];
+interface KeyPathExpressionJSON$1 {
+    keyPath: string[];
 }
-declare class ListNode extends ASTNode<ListNodeJSON> {
+declare class KeyPathExpression<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON$1> extends BaseExpression<CustomPathJSON> {
     static kind: string;
-    protected _list: ASTNode[];
-    get list(): ASTNode[];
-    fromJSON({ list }: ListNodeJSON): void;
+    protected _keyPath: string[];
+    get keyPath(): string[];
+    getRefFields(): BaseVariableField[];
+    get returnType(): BaseType | undefined;
+    /**
+     * 业务重改该方法可快速定制自己的 Path 表达式
+     * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
+     * @param json 业务定义的 Path 表达式
+     * @returns
+     */
+    protected parseToKeyPath(json: CustomPathJSON): string[];
+    fromJSON(json: CustomPathJSON): void;
+    constructor(params: CreateASTParams, opts: any);
     toJSON(): ASTNodeJSON;
 }
 
-interface MapNodeJSON {
-    map: [string, ASTNodeJSON][];
+interface EnumerateExpressionJSON {
+    enumerateFor: ASTNodeJSON;
 }
-declare class MapNode extends ASTNode<MapNodeJSON> {
+/**
+ * 遍历表达式，对列表进行遍历，获取遍历后的变量类型
+ */
+declare class EnumerateExpression extends BaseExpression<EnumerateExpressionJSON> {
     static kind: string;
-    protected map: Map<string, ASTNode>;
-    fromJSON({ map }: MapNodeJSON): void;
+    protected _enumerateFor: BaseExpression | undefined;
+    get enumerateFor(): BaseExpression<any, any> | undefined;
+    get returnType(): BaseType | undefined;
+    getRefFields(): [];
+    fromJSON({ enumerateFor: expression }: EnumerateExpressionJSON): void;
     toJSON(): ASTNodeJSON;
+}
+
+interface KeyPathExpressionJSON {
+    keyPath: string[];
+}
+/**
+ * 新版 KeyPathExpressionV2，相比旧版：
+ * - returnType 拷贝新一份，避免引用问题
+ * - 引入成环检测
+ */
+declare class KeyPathExpressionV2<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON> extends BaseExpression<CustomPathJSON> {
+    static kind: string;
+    protected _keyPath: string[];
+    get keyPath(): string[];
+    getRefFields(): BaseVariableField[];
+    _returnType: BaseType;
+    get returnType(): BaseType<any, any>;
     /**
-     * 往 Map 中设置 ASTNode
-     * @param key ASTNode 的索引，
-     * @param json
+     * 业务重改该方法可快速定制自己的 Path 表达式
+     * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
+     * @param json 业务定义的 Path 表达式
+     * @returns
      */
-    set<Node extends ASTNode = ASTNode>(key: string, nextJSON: ASTNodeJSON): Node;
+    protected parseToKeyPath(json: CustomPathJSON): string[];
+    fromJSON(json: CustomPathJSON): void;
+    getReturnTypeJSONByRef(_ref: BaseVariableField | undefined): ASTNodeJSON | undefined;
+    protected prevRefTypeHash: string | undefined;
+    constructor(params: CreateASTParams, opts: any);
+    toJSON(): ASTNodeJSON;
+}
+
+/**
+ * 声明类 AST 节点
+ */
+type BaseVariableFieldJSON<VariableMeta = any> = {
+    key?: Identifier;
+    type?: ASTNodeJSONOrKind;
+    initializer?: ASTNodeJSON;
+    meta?: VariableMeta;
+};
+declare abstract class BaseVariableField<VariableMeta = any> extends ASTNode<BaseVariableFieldJSON<VariableMeta>> {
+    flags: ASTNodeFlags;
+    protected _type?: BaseType;
+    protected _meta: VariableMeta;
+    protected _initializer?: BaseExpression;
     /**
-     * 移除指定 ASTNode
-     * @param key
+     * 父变量字段，通过由近而远的方式进行排序
      */
-    remove(key: string): void;
+    get parentFields(): BaseVariableField[];
+    get meta(): VariableMeta;
+    get type(): BaseType;
+    get initializer(): BaseExpression | undefined;
     /**
-     * 获取 ASTNode
-     * @param key
+     * 解析 VariableDeclarationJSON 从而生成变量声明节点
+     */
+    fromJSON({ type, initializer, meta }: BaseVariableFieldJSON<VariableMeta>): void;
+    updateType(type: BaseVariableFieldJSON['type']): void;
+    updateInitializer(nextInitializer?: BaseVariableFieldJSON['initializer']): void;
+    updateMeta(nextMeta: VariableMeta): void;
+    /**
+     * 根据 keyPath 去找下钻的变量字段
+     * @param keyPath
      * @returns
      */
-    get(key: string): ASTNode | undefined;
+    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    /**
+     * 监听类型变化
+     * @param observer
+     * @returns
+     */
+    onTypeChange(observer: (type: ASTNode | undefined) => void): _flowgram_ai_utils.Disposable;
+    /**
+     * 转换为 JSON
+     * @returns
+     */
+    toJSON(): BaseVariableFieldJSON<VariableMeta> & {
+        kind: string;
+    };
+}
+
+/**
+ * 声明类 AST 节点
+ */
+type VariableDeclarationJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
+    order?: number;
+};
+declare class VariableDeclaration<VariableMeta = any> extends BaseVariableField<VariableMeta> {
+    static kind: string;
+    protected _order: number;
+    get order(): number;
+    constructor(params: CreateASTParams);
+    /**
+     * 解析 VariableDeclarationJSON 从而生成变量声明节点
+     */
+    fromJSON({ order, ...rest }: VariableDeclarationJSON<VariableMeta>): void;
+    updateOrder(order?: number): void;
+    onTypeChange(observer: (type: ASTNode | undefined) => void): _flowgram_ai_utils.Disposable;
+}
+
+interface VariableDeclarationListJSON<VariableMeta = any> {
+    /**
+     *  declarations 一定是 VariableDeclaration 类型，因此业务可以不用填 kind
+     */
+    declarations?: VariableDeclarationJSON<VariableMeta>[];
+    startOrder?: number;
+}
+type VariableDeclarationListChangeAction = GlobalEventActionType<'VariableListChange', {
+    prev: VariableDeclaration[];
+    next: VariableDeclaration[];
+}, VariableDeclarationList>;
+declare class VariableDeclarationList extends ASTNode<VariableDeclarationListJSON> {
+    static kind: string;
+    declarationTable: Map<string, VariableDeclaration>;
+    declarations: VariableDeclaration[];
+    fromJSON({ declarations, startOrder }: VariableDeclarationListJSON): void;
+    toJSON(): ASTNodeJSON;
 }
 
 declare namespace ASTFactory {
@@ -943,62 +955,23 @@ declare function isMatchAST<TargetASTNode extends ASTNode>(node?: ASTNode, targe
     new (...args: any[]): TargetASTNode;
 }): node is TargetASTNode;
 
-declare class Scope<ScopeMeta extends Record<string, any> = Record<string, any>> {
-    /**
-     * Scope 唯一索引
-     */
-    readonly id: string;
-    /**
-     * Scope 依赖变量引擎
-     */
-    readonly variableEngine: VariableEngine;
-    /**
-     * 作用域的基本元信息，包括作用域所在节点及一些 flag 信息，上层业务可以额外扩展
-     */
-    readonly meta: ScopeMeta;
-    /**
-     * 作用域 AST 根节点
-     * - Map<formItemKey, formItemValue>
-     */
-    readonly ast: MapNode;
-    /**
-     * 可用变量数据管理
-     */
-    readonly available: ScopeAvailableData;
-    /**
-     * 输出变量数据管理
-     */
-    readonly output: ScopeOutputData;
-    /**
-     * 作用域事件管理
-     */
-    readonly event: ScopeEventData;
-    /**
-     * 数据缓存
-     */
-    protected memo: {
-        <T>(key: string | symbol, fn: () => T): T;
-        clear: (key?: (string | symbol) | undefined) => void;
-    };
-    toDispose: DisposableCollection;
-    constructor(options: {
-        id: string;
-        variableEngine: VariableEngine;
-        meta?: ScopeMeta;
-    });
-    refreshCovers(): void;
-    refreshDeps(): void;
-    get depScopes(): Scope[];
-    get coverScopes(): Scope[];
-    dispose(): void;
-    onDispose: _flowgram_ai_utils.Event<void>;
-    get disposed(): boolean;
-}
-
 interface ScopeChangeAction {
     type: 'add' | 'delete' | 'update' | 'available';
     scope: Scope;
 }
+interface IVariableTable extends Disposable {
+    parentTable?: IVariableTable;
+    onDataChange: Event<void>;
+    version: number;
+    variables: VariableDeclaration[];
+    variableKeys: string[];
+    fireChange(): void;
+    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    getVariableByKey(key: string): VariableDeclaration | undefined;
+    dispose(): void;
+    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    onAnyChange(observer: () => void): Disposable;
+}
 
 declare class VariableEngine implements Disposable {
     readonly chain: ScopeChain;
@@ -1008,19 +981,28 @@ declare class VariableEngine implements Disposable {
         <T>(key: string | symbol, fn: () => T): T;
         clear: (key?: (string | symbol) | undefined) => void;
     };
-    protected scopeMap: Map<string, Scope<Record<string, any>>>;
+    protected scopeMap: Map<string | symbol, Scope<Record<string, any>>>;
     globalEvent$: Subject<GlobalEventActionType>;
     protected onScopeChangeEmitter: Emitter<ScopeChangeAction>;
-    globalVariableTable: VariableTable;
+    globalVariableTable: IVariableTable;
     onScopeChange: _flowgram_ai_utils.Event<ScopeChangeAction>;
     private readonly containerProvider;
     get container(): interfaces.Container;
     constructor(chain: ScopeChain, // 作用域依赖关系偏序集
     astRegisters: ASTRegisters);
     dispose(): void;
-    getScopeById(scopeId: string): Scope | undefined;
-    removeScopeById(scopeId: string): void;
-    createScope(id: string, meta?: Record<string, any>): Scope;
+    getScopeById(scopeId: string | symbol): Scope | undefined;
+    removeScopeById(scopeId: string | symbol): void;
+    /**
+     * Get Scope, if Scope exists and type is same, will use it directly
+     * @param id scope id
+     * @param meta scope meta, defined by user
+     * @param ScopeConstructor scope constructor, default is Scope. you can extends Scope to create your own scope
+     * @returns
+     */
+    createScope(id: string | symbol, meta?: Record<string, any>, options?: {
+        ScopeConstructor?: IScopeConstructor;
+    }): Scope;
     getAllScopes({ sort, }?: {
         sort?: boolean;
     }): Scope[];
@@ -1062,4 +1044,4 @@ declare class VariableFieldKeyRenameService {
     dispose(): void;
 }
 
-export { ASTFactory, ASTKind, ASTMatch, ASTNode, ASTNodeFlags, type ASTNodeJSON, type ASTNodeRegistry, ASTRegisters, ArrayType, BaseExpression, BaseType, BaseVariableField, BooleanType, type CreateASTParams, CustomType, type CustomTypeJSON, DataNode, EnumerateExpression, type EnumerateExpressionJSON, ExpressionList, type ExpressionListJSON, type GetKindJSON, type GetKindJSONOrKind, type GlobalEventActionType, IntegerType, KeyPathExpression, type KeyPathExpressionJSON$1 as KeyPathExpressionJSON, KeyPathExpressionV2, ListNode, type ListNodeJSON, MapNode, type MapNodeJSON, MapType, NumberType, type ObjectJSON, type ObjectPropertiesChangeAction, ObjectType, Property, type PropertyJSON, Scope, ScopeChain, ScopeOutputData, ScopeProvider, StringType, type UnionJSON, VariableContainerModule, VariableDeclaration, type VariableDeclarationJSON, VariableDeclarationList, type VariableDeclarationListChangeAction, type VariableDeclarationListJSON, VariableEngine, VariableEngineProvider, VariableFieldKeyRenameService, VariableTable, injectToAST, isMatchAST, postConstructAST, useAvailableVariables, useCurrentScope, useScopeAvailable, useScopeContext };
+export { ASTFactory, ASTKind, ASTMatch, ASTNode, ASTNodeFlags, type ASTNodeJSON, type ASTNodeRegistry, ASTRegisters, ArrayType, BaseExpression, BaseType, BaseVariableField, BooleanType, type CreateASTParams, CustomType, type CustomTypeJSON, DataNode, EnumerateExpression, type EnumerateExpressionJSON, ExpressionList, type ExpressionListJSON, type GetKindJSON, type GetKindJSONOrKind, type GlobalEventActionType, type IVariableTable, IntegerType, KeyPathExpression, type KeyPathExpressionJSON$1 as KeyPathExpressionJSON, KeyPathExpressionV2, ListNode, type ListNodeJSON, MapNode, type MapNodeJSON, MapType, NumberType, type ObjectJSON, type ObjectPropertiesChangeAction, ObjectType, Property, type PropertyJSON, Scope, ScopeChain, ScopeOutputData, ScopeProvider, StringType, type UnionJSON, VariableContainerModule, VariableDeclaration, type VariableDeclarationJSON, VariableDeclarationList, type VariableDeclarationListChangeAction, type VariableDeclarationListJSON, VariableEngine, VariableEngineProvider, VariableFieldKeyRenameService, injectToAST, isMatchAST, postConstructAST, useAvailableVariables, useCurrentScope, useScopeAvailable, useScopeContext };