@flowgram.ai/variable-core 0.1.0-alpha.3 → 0.1.0-alpha.31

package/dist/index.d.mts

@@ -1,18 +1,331 @@
 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';
+import React from 'react';
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * An InversifyJS container module that binds all the necessary services for the variable engine.
+ * This module sets up the dependency injection for the core components of the variable engine.
+ */
 declare const VariableContainerModule: ContainerModule;
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * A provider for dynamically obtaining the `VariableEngine` instance.
+ * This is used to prevent circular dependencies when injecting `VariableEngine`.
+ */
 declare const VariableEngineProvider: unique symbol;
 type VariableEngineProvider = () => VariableEngine;
 
 /**
- * 作用域依赖关系管理数据结构
- * - ScopeOrder 可能存在多种实现方式，因此采取抽象类的方式，具体的实现由子类实现
+ * Manages the output variables of a scope.
+ */
+declare class ScopeOutputData {
+    readonly scope: Scope;
+    protected variableTable: IVariableTable;
+    protected memo: {
+        <T>(key: string | symbol, fn: () => T): T;
+        clear: (key?: string | symbol) => void;
+    };
+    /**
+     * The variable engine instance.
+     */
+    get variableEngine(): VariableEngine;
+    /**
+     * The global variable table from the variable engine.
+     */
+    get globalVariableTable(): IVariableTable;
+    /**
+     * The current version of the output data, which increments on each change.
+     */
+    get version(): number;
+    /**
+     * @deprecated use onListOrAnyVarChange instead
+     */
+    get onDataChange(): _flowgram_ai_utils.Event<void>;
+    /**
+     * An event that fires when the list of output variables changes.
+     */
+    get onVariableListChange(): (observer: (variables: VariableDeclaration[]) => void) => _flowgram_ai_utils.Disposable;
+    /**
+     * An event that fires when any output variable's value changes.
+     */
+    get onAnyVariableChange(): (observer: (changedVariable: VariableDeclaration) => void) => _flowgram_ai_utils.Disposable;
+    /**
+     * An event that fires when the output variable list changes or any variable's value is updated.
+     */
+    get onListOrAnyVarChange(): (observer: () => void) => _flowgram_ai_utils.Disposable;
+    protected _hasChanges: boolean;
+    constructor(scope: Scope);
+    /**
+     * The output variable declarations of the scope, sorted by order.
+     */
+    get variables(): VariableDeclaration[];
+    /**
+     * The keys of the output variables.
+     */
+    get variableKeys(): string[];
+    protected addVariableToTable(variable: VariableDeclaration): void;
+    protected removeVariableFromTable(key: string): void;
+    /**
+     * Retrieves a variable declaration by its key.
+     * @param key The key of the variable.
+     * @returns The `VariableDeclaration` or `undefined` if not found.
+     */
+    getVariableByKey(key: string): VariableDeclaration<any> | undefined;
+    /**
+     * Notifies the covering scopes that the available variables have changed.
+     */
+    notifyCoversChange(): void;
+}
+
+/**
+ * Manages the available variables within a scope.
+ */
+declare class ScopeAvailableData {
+    readonly scope: Scope;
+    protected memo: {
+        <T>(key: string | symbol, fn: () => T): T;
+        clear: (key?: string | symbol) => void;
+    };
+    /**
+     * The global variable table from the variable engine.
+     */
+    get globalVariableTable(): IVariableTable;
+    protected _version: number;
+    protected refresh$: Subject<void>;
+    protected _variables: VariableDeclaration[];
+    /**
+     * The current version of the available data, which increments on each change.
+     */
+    get version(): number;
+    protected bumpVersion(): void;
+    /**
+     * Refreshes the list of available variables.
+     * This should be called when the dependencies of the scope change.
+     */
+    refresh(): void;
+    /**
+     * An observable that emits when the list of available variables changes.
+     */
+    protected variables$: Observable<VariableDeclaration[]>;
+    /**
+     * An observable that emits when any variable in the available list changes its value.
+     */
+    protected anyVariableChange$: Observable<VariableDeclaration>;
+    /**
+     * Subscribes to changes in any variable's value in the available list.
+     * @param observer A function to be called with the changed variable.
+     * @returns A disposable to unsubscribe from the changes.
+     */
+    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    /**
+     * Subscribes to changes in the list of available variables.
+     * @param observer A function to be called with the new list of variables.
+     * @returns A disposable to unsubscribe from the changes.
+     */
+    onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
+    /**
+     * @deprecated
+     */
+    protected onDataChangeEmitter: Emitter<VariableDeclaration<any>[]>;
+    protected onListOrAnyVarChangeEmitter: Emitter<VariableDeclaration<any>[]>;
+    /**
+     * @deprecated use available.onListOrAnyVarChange instead
+     */
+    onDataChange: _flowgram_ai_utils.Event<VariableDeclaration<any>[]>;
+    /**
+     * An event that fires when the variable list changes or any variable's value is updated.
+     */
+    onListOrAnyVarChange: _flowgram_ai_utils.Event<VariableDeclaration<any>[]>;
+    constructor(scope: Scope);
+    /**
+     * Gets the list of available variables.
+     */
+    get variables(): VariableDeclaration[];
+    /**
+     * Gets the keys of the available variables.
+     */
+    get variableKeys(): string[];
+    /**
+     * Gets the dependency scopes.
+     */
+    get depScopes(): Scope[];
+    /**
+     * Retrieves a variable field by its key path from the available variables.
+     * @param keyPath The key path to the variable field.
+     * @returns The found `BaseVariableField` or `undefined`.
+     */
+    getByKeyPath(keyPath?: string[]): BaseVariableField | undefined;
+    /**
+     * Tracks changes to a variable field by its key path.
+     * This includes changes to its type, value, or any nested properties.
+     * @param keyPath The key path to the variable field to track.
+     * @param cb The callback to execute when the variable changes.
+     * @param opts Configuration options for the subscription.
+     * @returns A disposable to unsubscribe from the tracking.
+     */
+    trackByKeyPath<Data = BaseVariableField | undefined>(keyPath: string[] | undefined, cb: (variable?: Data) => void, opts?: SubscribeConfig<BaseVariableField | undefined, Data>): Disposable;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+type Observer<ActionType extends GlobalEventActionType = GlobalEventActionType> = (action: ActionType) => void;
+/**
+ * Manages global events within a scope.
+ */
+declare class ScopeEventData {
+    readonly scope: Scope;
+    event$: Subject<GlobalEventActionType>;
+    /**
+     * Dispatches a global event.
+     * @param action The event action to dispatch.
+     */
+    dispatch<ActionType extends GlobalEventActionType = GlobalEventActionType>(action: ActionType): void;
+    /**
+     * Subscribes to all global events.
+     * @param observer The observer function to call with the event action.
+     * @returns A disposable to unsubscribe from the events.
+     */
+    subscribe<ActionType extends GlobalEventActionType = GlobalEventActionType>(observer: Observer<ActionType>): Disposable;
+    /**
+     * Subscribes to a specific type of global event.
+     * @param type The type of the event to subscribe to.
+     * @param observer The observer function to call with the event action.
+     * @returns A disposable to unsubscribe from the event.
+     */
+    on<ActionType extends GlobalEventActionType = GlobalEventActionType>(type: ActionType['type'], observer: Observer<ActionType>): Disposable;
+    constructor(scope: Scope);
+}
+
+/**
+ * Interface for the Scope constructor.
+ */
+interface IScopeConstructor {
+    new (options: {
+        id: string | symbol;
+        variableEngine: VariableEngine;
+        meta?: Record<string, any>;
+    }): Scope;
+}
+/**
+ * Represents a variable scope, which manages its own set of variables and their lifecycle.
+ * - `scope.output` represents the variables declared within this scope.
+ * - `scope.available` represents all variables accessible from this scope, including those from parent scopes.
+ */
+declare class Scope<ScopeMeta extends Record<string, any> = Record<string, any>> {
+    /**
+     * A unique identifier for the scope.
+     */
+    readonly id: string | symbol;
+    /**
+     * The variable engine instance this scope belongs to.
+     */
+    readonly variableEngine: VariableEngine;
+    /**
+     * Metadata associated with the scope, which can be extended by higher-level business logic.
+     */
+    readonly meta: ScopeMeta;
+    /**
+     * The root AST node for this scope, which is a MapNode.
+     * It stores various data related to the scope, such as `outputs`.
+     */
+    readonly ast: MapNode;
+    /**
+     * Manages the available variables for this scope.
+     */
+    readonly available: ScopeAvailableData;
+    /**
+     * Manages the output variables for this scope.
+     */
+    readonly output: ScopeOutputData;
+    /**
+     * Manages event dispatching and handling for this scope.
+     */
+    readonly event: ScopeEventData;
+    /**
+     * A memoization utility for caching computed values.
+     */
+    protected memo: {
+        <T>(key: string | symbol, fn: () => T): T;
+        clear: (key?: string | symbol) => void;
+    };
+    toDispose: DisposableCollection;
+    constructor(options: {
+        id: string | symbol;
+        variableEngine: VariableEngine;
+        meta?: ScopeMeta;
+    });
+    /**
+     * Refreshes the covering scopes.
+     */
+    refreshCovers(): void;
+    /**
+     * Refreshes the dependency scopes and the available variables.
+     */
+    refreshDeps(): void;
+    /**
+     * Gets the scopes that this scope depends on.
+     */
+    get depScopes(): Scope[];
+    /**
+     * Gets the scopes that are covered by this scope.
+     */
+    get coverScopes(): Scope[];
+    /**
+     * Disposes of the scope and its resources.
+     * This will also trigger updates in dependent and covering scopes.
+     */
+    dispose(): void;
+    onDispose: _flowgram_ai_utils.Event<void>;
+    get disposed(): boolean;
+    /**
+     * Sets a variable in the scope with the default key 'outputs'.
+     *
+     * @param json The JSON representation of the AST node to set.
+     * @returns The created or updated AST node.
+     */
+    setVar<Node extends ASTNode = ASTNode>(json: ASTNodeJSON): Node;
+    /**
+     * Sets a variable in the scope with a specified key.
+     *
+     * @param key The key of the variable to set.
+     * @param json The JSON representation of the AST node to set.
+     * @returns The created or updated AST node.
+     */
+    setVar<Node extends ASTNode = ASTNode>(key: string, json: ASTNodeJSON): Node;
+    /**
+     * Retrieves a variable from the scope by its key.
+     *
+     * @param key The key of the variable to retrieve. Defaults to 'outputs'.
+     * @returns The AST node for the variable, or `undefined` if not found.
+     */
+    getVar<Node extends ASTNode = ASTNode>(key?: string): Node | undefined;
+    /**
+     * Clears a variable from the scope by its key.
+     *
+     * @param key The key of the variable to clear. Defaults to 'outputs'.
+     */
+    clearVar(key?: string): void;
+}
+
+/**
+ * Manages the dependency relationships between scopes.
+ * This is an abstract class, and specific implementations determine how the scope order is managed.
  */
 declare abstract class ScopeChain {
     readonly toDispose: DisposableCollection;
@@ -20,1007 +333,1948 @@ declare abstract class ScopeChain {
     get variableEngine(): VariableEngine;
     constructor();
     /**
-     * 所有作用域依赖关系刷新
+     * Refreshes the dependency and coverage relationships for all scopes.
      */
     refreshAllChange(): void;
-    abstract getDeps(scope: Scope): Scope[];
-    abstract getCovers(scope: Scope): Scope[];
-    abstract sortAll(): Scope[];
-    dispose(): void;
-    get disposed(): boolean;
-    get onDispose(): Event<void>;
-}
-
-declare enum ASTNodeFlags {
-    None = 0,
     /**
-     * 变量字段
+     * Gets the dependency scopes for a given scope.
+     * @param scope The scope to get dependencies for.
+     * @returns An array of dependency scopes.
      */
-    VariableField = 1,
+    abstract getDeps(scope: Scope): Scope[];
     /**
-     * 表达式
+     * Gets the covering scopes for a given scope.
+     * @param scope The scope to get covers for.
+     * @returns An array of covering scopes.
      */
-    Expression = 4,
+    abstract getCovers(scope: Scope): Scope[];
     /**
-     * 变量类型
+     * Sorts all scopes based on their dependency relationships.
+     * @returns A sorted array of all scopes.
      */
-    BasicType = 8,
-    DrilldownType = 16,
-    EnumerateType = 32,
-    UnionType = 64,
-    VariableType = 120
+    abstract sortAll(): Scope[];
+    dispose(): void;
+    get disposed(): boolean;
+    get onDispose(): Event<void>;
 }
 
-interface ASTNodeRegistry<JSON extends ASTNodeJSON = any, InjectOpts = any> {
+interface ASTNodeRegistry<JSON extends ASTNodeJSON = any> {
     kind: string;
-    new (params: CreateASTParams, injectOpts: InjectOpts): ASTNode<JSON>;
+    new (params: CreateASTParams, injectOpts: any): ASTNode<JSON>;
 }
-declare abstract class ASTNode<JSON extends ASTNodeJSON = any, InjectOpts = any> implements Disposable {
+/**
+ * An `ASTNode` represents a fundamental unit of variable information within the system's Abstract Syntax Tree.
+ * It can model various constructs, for example:
+ * - **Declarations**: `const a = 1`
+ * - **Expressions**: `a.b.c`
+ * - **Types**: `number`, `string`, `boolean`
+ *
+ * Here is some characteristic of ASTNode:
+ * - **Tree-like Structure**: ASTNodes can be nested to form a tree, representing complex variable structures.
+ * - **Extendable**: New features can be added by extending the base ASTNode class.
+ * - **Reactive**: Changes in an ASTNode's value trigger events, enabling reactive programming patterns.
+ * - **Serializable**: ASTNodes can be converted to and from a JSON format (ASTNodeJSON) for storage or transmission.
+ */
+declare abstract class ASTNode<JSON extends ASTNodeJSON = any> implements Disposable {
     /**
      * @deprecated
-     * 获取 ASTNode 注入的 opts
+     * Get the injected options for the ASTNode.
      *
-     * 请使用 @injectToAst(XXXService) declare xxxService: XXXService 实现外部依赖注入
+     * Please use `@injectToAst(XXXService) declare xxxService: XXXService` to achieve external dependency injection.
      */
-    readonly opts?: InjectOpts;
+    readonly opts?: any;
     /**
-     * 节点的唯一标识符，节点不指定则默认由 nanoid 生成，不可更改
-     * - 如需要生成新 key，则销毁当前节点并生成新的节点
+     * The unique identifier of the ASTNode, which is **immutable**.
+     * - Immutable: Once assigned, the key cannot be changed.
+     * - Automatically generated if not specified, and cannot be changed as well.
+     * - If a new key needs to be generated, the current ASTNode should be destroyed and a new ASTNode should be generated.
      */
     readonly key: Identifier;
     /**
-     * 节点类型
+     * The kind of the ASTNode.
      */
     static readonly kind: ASTKindType;
     /**
-     * 节点 Flags，记录一些 Flag 信息
+     * Node flags, used to record some flag information.
      */
     readonly flags: number;
     /**
-     * 节点所处的作用域
+     * The scope in which the ASTNode is located.
      */
     readonly scope: Scope;
     /**
-     * 父节点
+     * The parent ASTNode.
      */
     readonly parent: ASTNode | undefined;
     /**
-     * 节点的版本号，每 fireChange 一次 version + 1
+     * The version number of the ASTNode, which increments by 1 each time `fireChange` is called.
      */
-    private _version;
+    protected _version: number;
     /**
-     * 更新锁
+     * Update lock.
+     * - When set to `true`, `fireChange` will not trigger any events.
+     * - This is useful when multiple updates are needed, and you want to avoid multiple triggers.
      */
     changeLocked: boolean;
     /**
-     * Batch Update 相关参数
+     * Parameters related to batch updates.
      */
     private _batch;
     /**
-     * AST 节点变化事件，基于 Rxjs 实现
-     * - 使用了 BehaviorSubject, 在订阅时会自动触发一次事件，事件为当前值
+     * AST node change Observable events, implemented based on RxJS.
+     * - Emits the current ASTNode value upon subscription.
+     * - Emits a new value whenever `fireChange` is called.
      */
     readonly value$: BehaviorSubject<ASTNode>;
     /**
-     * 子节点
+     * Child ASTNodes.
      */
-    protected _children: Set<ASTNode<any, any>>;
+    protected _children: Set<ASTNode<any>>;
     /**
-     * 删除节点处理事件列表
+     * List of disposal handlers for the ASTNode.
      */
     readonly toDispose: DisposableCollection;
     /**
-     * 销毁时触发的回调
+     * Callback triggered upon disposal.
      */
     onDispose: _flowgram_ai_utils.Event<void>;
     /**
-     * 构造函数
-     * @param createParams 创建 ASTNode 的必要参数
-     * @param injectOptions 依赖注入各种模块
+     * Constructor.
+     * @param createParams Necessary parameters for creating an ASTNode.
+     * @param injectOptions Dependency injection for various modules.
      */
-    constructor({ key, parent, scope }: CreateASTParams, opts?: InjectOpts);
+    constructor({ key, parent, scope }: CreateASTParams, opts?: any);
     /**
-     * AST 节点的类型
+     * The type of the ASTNode.
      */
     get kind(): string;
     /**
-     * 解析 AST JSON 数据
-     * @param json AST JSON 数据
+     * Parses AST JSON data.
+     * @param json AST JSON data.
      */
     abstract fromJSON(json: JSON): void;
     /**
-     * 获取当前节点所有子节点
+     * Gets all child ASTNodes of the current ASTNode.
      */
     get children(): ASTNode[];
     /**
-     * 转化为 ASTNodeJSON
+     * Serializes the current ASTNode to ASTNodeJSON.
      * @returns
      */
-    toJSON(): ASTNodeJSON;
+    abstract toJSON(): JSON;
     /**
-     * 创建子节点
-     * @param json 子节点的 AST JSON
+     * Creates a child ASTNode.
+     * @param json The AST JSON of the child ASTNode.
      * @returns
      */
     protected createChildNode<ChildNode extends ASTNode = ASTNode>(json: ASTNodeJSON): ChildNode;
     /**
-     * 更新子节点，快速实现子节点更新消费逻辑
-     * @param keyInThis 当前对象上的指定 key
+     * Updates a child ASTNode, quickly implementing the consumption logic for child ASTNode updates.
+     * @param keyInThis The specified key on the current object.
      */
     protected updateChildNodeByKey(keyInThis: keyof this, nextJSON?: ASTNodeJSON): void;
     /**
-     * 批处理更新，批处理函数内所有的 fireChange 都合并成一个
-     * @param updater 批处理函数
+     * Batch updates the ASTNode, merging all `fireChange` calls within the batch function into one.
+     * @param updater The batch function.
      * @returns
      */
     protected withBatchUpdate<ParamTypes extends any[], ReturnType>(updater: (...args: ParamTypes) => ReturnType): (...args: ParamTypes) => ReturnType;
     /**
-     * 触发当前节点更新
+     * Triggers an update for the current node.
      */
     fireChange(): void;
     /**
-     * 节点的版本值
-     * - 通过 NodeA === NodeB && versionA === versionB 可以比较两者是否相等
+     * The version value of the ASTNode.
+     * - You can used to check whether ASTNode are updated.
      */
     get version(): number;
     /**
-     * 节点唯一 hash 值
+     * The unique hash value of the ASTNode.
+     * - It will update when the ASTNode is updated.
+     * - You can used to check two ASTNode are equal.
      */
     get hash(): string;
     /**
-     * 监听 AST 节点的变化
-     * @param observer 监听回调
-     * @param selector 监听指定数据
+     * Listens for changes to the ASTNode.
+     * @param observer The listener callback.
+     * @param selector Listens for specified data.
      * @returns
      */
     subscribe<Data = this>(observer: ObserverOrNext<Data>, { selector, debounceAnimation, triggerOnInit }?: SubscribeConfig<this, Data>): Disposable;
+    /**
+     * Dispatches a global event for the current ASTNode.
+     * @param event The global event.
+     */
     dispatchGlobalEvent<ActionType extends GlobalEventActionType = GlobalEventActionType>(event: Omit<ActionType, 'ast'>): void;
     /**
-     * 销毁
+     * Disposes the ASTNode.
      */
     dispose(): void;
     get disposed(): boolean;
     /**
-     * 节点扩展信息
+     * Extended information of the ASTNode.
      */
     [key: string]: unknown;
 }
 
 /**
- * 声明类 AST 节点
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
  */
-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);
+
+type ASTKindType = string;
+type Identifier = string;
+/**
+ * ASTNodeJSON is the JSON representation of an ASTNode.
+ */
+interface ASTNodeJSON {
     /**
-     * 解析 VariableDeclarationJSON 从而生成变量声明节点
+     * Kind is the type of the AST node.
      */
-    fromJSON({ order, ...rest }: VariableDeclarationJSON<VariableMeta>): void;
-    updateOrder(order?: number): void;
-    onTypeChange(observer: (type: ASTNode | undefined) => void): Disposable;
-}
-
-interface VariableDeclarationListJSON<VariableMeta = any> {
+    kind?: ASTKindType;
     /**
-     *  declarations 一定是 VariableDeclaration 类型，因此业务可以不用填 kind
+     * Key is the unique identifier of the node.
+     * If not provided, the node will generate a default key value.
      */
-    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;
+    key?: Identifier;
+    [key: string]: any;
+}
+/**
+ * Core AST node types.
+ */
+declare enum ASTKind {
+    /**
+     * # Type-related.
+     * - A set of type AST nodes based on JSON types is implemented internally by default.
+     */
+    /**
+     * String type.
+     */
+    String = "String",
+    /**
+     * Number type.
+     */
+    Number = "Number",
+    /**
+     * Integer type.
+     */
+    Integer = "Integer",
+    /**
+     * Boolean type.
+     */
+    Boolean = "Boolean",
+    /**
+     * Object type.
+     */
+    Object = "Object",
+    /**
+     * Array type.
+     */
+    Array = "Array",
+    /**
+     * Map type.
+     */
+    Map = "Map",
+    /**
+     * Union type.
+     * Commonly used for type checking, generally not exposed to the business.
+     */
+    Union = "Union",
+    /**
+     * Any type.
+     * Commonly used for business logic.
+     */
+    Any = "Any",
+    /**
+     * Custom type.
+     * For business-defined types.
+     */
+    CustomType = "CustomType",
+    /**
+     * # Declaration-related.
+     */
+    /**
+     * Field definition for Object drill-down.
+     */
+    Property = "Property",
+    /**
+     * Variable declaration.
+     */
+    VariableDeclaration = "VariableDeclaration",
+    /**
+     * Variable declaration list.
+     */
+    VariableDeclarationList = "VariableDeclarationList",
+    /**
+     * # Expression-related.
+     */
+    /**
+     * Access fields on variables through the path system.
+     */
+    KeyPathExpression = "KeyPathExpression",
+    /**
+     * Iterate over specified data.
+     */
+    EnumerateExpression = "EnumerateExpression",
+    /**
+     * Wrap with Array Type.
+     */
+    WrapArrayExpression = "WrapArrayExpression",
+    /**
+     * # General-purpose AST nodes.
+     */
+    /**
+     * General-purpose List<ASTNode> storage node.
+     */
+    ListNode = "ListNode",
+    /**
+     * General-purpose data storage node.
+     */
+    DataNode = "DataNode",
+    /**
+     * General-purpose Map<string, ASTNode> storage node.
+     */
+    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;
+}
+/**
+ * TypeUtils to get the JSON representation of an AST node with a specific kind.
+ */
+type GetKindJSON<KindType extends string, JSON extends ASTNodeJSON> = {
+    kind: KindType;
+    key?: Identifier;
+} & JSON;
+/**
+ * TypeUtils to get the JSON representation of an AST node with a specific kind or just the kind string.
+ */
+type GetKindJSONOrKind<KindType extends string, JSON extends ASTNodeJSON> = ({
+    kind: KindType;
+    key?: Identifier;
+} & JSON) | KindType;
+/**
+ * Global event action type.
+ * - Global event might be dispatched from `ASTNode` or `Scope`.
+ */
+interface GlobalEventActionType<Type = string, Payload = any, AST extends ASTNode = ASTNode> {
+    type: Type;
+    payload?: Payload;
+    ast?: AST;
 }
 
-type PropertyJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
-    key: string;
-};
-declare class Property<VariableMeta = any> extends BaseVariableField<VariableMeta> {
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+type DataInjector = () => Record<string, any>;
+/**
+ * Register the AST node to the engine.
+ */
+declare class ASTRegisters {
+    /**
+     * @deprecated Please use `@injectToAst(XXXService) declare xxxService: XXXService` to achieve external dependency injection.
+     */
+    protected injectors: Map<ASTKindType, DataInjector>;
+    protected astMap: Map<ASTKindType, ASTNodeRegistry>;
+    /**
+     * Core AST node registration.
+     */
+    constructor();
+    /**
+     * Creates an AST node.
+     * @param param Creation parameters.
+     * @returns
+     */
+    createAST<ReturnNode extends ASTNode = ASTNode>(json: ASTNodeJSON, { parent, scope }: CreateASTParams): ReturnNode;
+    /**
+     * Gets the node Registry by AST node type.
+     * @param kind
+     * @returns
+     */
+    getASTRegistryByKind(kind: ASTKindType): ASTNodeRegistry<any> | undefined;
+    /**
+     * Registers an AST node.
+     * @param ASTNode
+     */
+    registerAST(ASTNode: ASTNodeRegistry, 
+    /**
+     * @deprecated Please use `@injectToAst(XXXService) declare xxxService: XXXService` to achieve external dependency injection.
+     */
+    injector?: DataInjector): void;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * ASTNode flags. Stored in the `flags` property of the `ASTNode`.
+ */
+declare enum ASTNodeFlags {
+    /**
+     * None.
+     */
+    None = 0,
+    /**
+     * Variable Field.
+     */
+    VariableField = 1,
+    /**
+     * Expression.
+     */
+    Expression = 4,
+    /**
+     * # Variable Type Flags
+     */
+    /**
+     *  Basic type.
+     */
+    BasicType = 8,
+    /**
+     * Drillable variable type.
+     */
+    DrilldownType = 16,
+    /**
+     * Enumerable variable type.
+     */
+    EnumerateType = 32,
+    /**
+     * Composite type, currently not in use.
+     */
+    UnionType = 64,
+    /**
+     * Variable type.
+     */
+    VariableType = 120
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Represents a general data node with no child nodes.
+ */
+declare class DataNode<Data = any> extends ASTNode {
+    static kind: string;
+    protected _data: Data;
+    /**
+     * The data of the node.
+     */
+    get data(): Data;
+    /**
+     * Deserializes the `DataNodeJSON` to the `DataNode`.
+     * @param json The `DataNodeJSON` to deserialize.
+     */
+    fromJSON(json: Data): void;
+    /**
+     * Serialize the `DataNode` to `DataNodeJSON`.
+     * @returns The JSON representation of `DataNode`.
+     */
+    toJSON(): {
+        kind: ASTKind;
+    } & Data;
+    /**
+     * Partially update the data of the node.
+     * @param nextData The data to be updated.
+     */
+    partialUpdate(nextData: Data): void;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `ListNode`
+ */
+interface ListNodeJSON {
+    /**
+     * The list of nodes.
+     */
+    list: ASTNodeJSON[];
+}
+/**
+ * Represents a list of nodes.
+ */
+declare class ListNode extends ASTNode<ListNodeJSON> {
     static kind: string;
+    protected _list: ASTNode[];
+    /**
+     * The list of nodes.
+     */
+    get list(): ASTNode[];
+    /**
+     * Deserializes the `ListNodeJSON` to the `ListNode`.
+     * @param json The `ListNodeJSON` to deserialize.
+     */
+    fromJSON({ list }: ListNodeJSON): void;
+    /**
+     * Serialize the `ListNode` to `ListNodeJSON`.
+     * @returns The JSON representation of `ListNode`.
+     */
+    toJSON(): {
+        kind: ASTKind;
+        list: any[];
+    };
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `MapNode`
+ */
+interface MapNodeJSON {
+    /**
+     * The map of nodes.
+     */
+    map: [string, ASTNodeJSON][];
+}
+/**
+ * Represents a map of nodes.
+ */
+declare class MapNode extends ASTNode<MapNodeJSON> {
+    static kind: string;
+    protected map: Map<string, ASTNode>;
+    /**
+     * Deserializes the `MapNodeJSON` to the `MapNode`.
+     * @param json The `MapNodeJSON` to deserialize.
+     */
+    fromJSON({ map }: MapNodeJSON): void;
+    /**
+     * Serialize the `MapNode` to `MapNodeJSON`.
+     * @returns The JSON representation of `MapNode`.
+     */
+    toJSON(): {
+        kind: ASTKind;
+        map: [string, ASTNode<any>][];
+    };
+    /**
+     * Set a node in the map.
+     * @param key The key of the node.
+     * @param nextJSON The JSON representation of the node.
+     * @returns The node instance.
+     */
+    set<Node extends ASTNode = ASTNode>(key: string, nextJSON: ASTNodeJSON): Node;
+    /**
+     * Remove a node from the map.
+     * @param key The key of the node.
+     */
+    remove(key: string): void;
+    /**
+     * Get a node from the map.
+     * @param key The key of the node.
+     * @returns The node instance if found, otherwise `undefined`.
+     */
+    get<Node extends ASTNode = ASTNode>(key: string): Node | undefined;
 }
 
-declare abstract class BaseType<JSON extends ASTNodeJSON = any, InjectOpts = any> extends ASTNode<JSON, InjectOpts> {
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Base class for all types.
+ *
+ * All other types should extend this class.
+ */
+declare abstract class BaseType<JSON extends ASTNodeJSON = any> extends ASTNode<JSON> {
     flags: number;
     /**
-     * 类型是否一致，节点有额外信息判断，请参考 extraTypeInfoEqual
-     * @param targetTypeJSON
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
      */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
     /**
-     * 可下钻类型需实现
-     * @param keyPath
+     * Get a variable field by key path.
+     *
+     * This method should be implemented by drillable types.
+     * @param keyPath The key path to search for.
+     * @returns The variable field if found, otherwise `undefined`.
      */
     getByKeyPath(keyPath?: string[]): BaseVariableField | undefined;
-    toJSON(): ASTNodeJSON;
 }
 
-declare class StringType extends BaseType {
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of the `StringType`.
+ */
+interface StringJSON {
+    /**
+     * see https://json-schema.org/understanding-json-schema/reference/type#format
+     */
+    format?: string;
+}
+declare class StringType extends BaseType<StringJSON> {
     flags: ASTNodeFlags;
     static kind: string;
-    fromJSON(): void;
+    protected _format?: string;
+    /**
+     * see https://json-schema.org/understanding-json-schema/reference/string#format
+     */
+    get format(): string | undefined;
+    /**
+     * Deserialize the `StringJSON` to the `StringType`.
+     *
+     * @param json StringJSON representation of the `StringType`.
+     */
+    fromJSON(json?: StringJSON): void;
+    /**
+     * Serialize the `StringType` to `StringJSON`.
+     * @returns The JSON representation of `StringType`.
+     */
+    toJSON(): {
+        format: string | undefined;
+    };
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Represents an integer type.
+ */
 declare class IntegerType extends BaseType {
     flags: ASTNodeFlags;
     static kind: string;
+    /**
+     * Deserializes the `IntegerJSON` to the `IntegerType`.
+     * @param json The `IntegerJSON` to deserialize.
+     */
     fromJSON(): void;
+    toJSON(): {};
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Represents a boolean type.
+ */
 declare class BooleanType extends BaseType {
     static kind: string;
+    /**
+     * Deserializes the `BooleanJSON` to the `BooleanType`.
+     * @param json The `BooleanJSON` to deserialize.
+     */
     fromJSON(): void;
+    toJSON(): {};
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Represents a number type.
+ */
 declare class NumberType extends BaseType {
     static kind: string;
+    /**
+     * Deserializes the `NumberJSON` to the `NumberType`.
+     * @param json The `NumberJSON` to deserialize.
+     */
     fromJSON(): void;
+    toJSON(): {};
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `ArrayType`
+ */
 interface ArrayJSON {
+    /**
+     * The type of the items in the array.
+     */
     items?: ASTNodeJSONOrKind;
 }
+/**
+ * Represents an array type.
+ */
 declare class ArrayType extends BaseType<ArrayJSON> {
     flags: ASTNodeFlags;
     static kind: string;
+    /**
+     * The type of the items in the array.
+     */
     items: BaseType;
+    /**
+     * Deserializes the `ArrayJSON` to the `ArrayType`.
+     * @param json The `ArrayJSON` to deserialize.
+     */
     fromJSON({ items }: ArrayJSON): void;
+    /**
+     * Whether the items type can be drilled down.
+     */
     get canDrilldownItems(): boolean;
+    /**
+     * Get a variable field by key path.
+     * @param keyPath The key path to search for.
+     * @returns The variable field if found, otherwise `undefined`.
+     */
     getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    /**
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
+     */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
     /**
-     * Array 强比较
-     * @param targetTypeJSON
-     * @returns
+     * Array strong comparison.
+     * @param targetTypeJSON The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
      */
     protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
-    toJSON(): ASTNodeJSON;
+    /**
+     * Serialize the `ArrayType` to `ArrayJSON`
+     * @returns The JSON representation of `ArrayType`.
+     */
+    toJSON(): {
+        kind: ASTKind;
+        items: any;
+    };
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `MapType`
+ */
 interface MapJSON {
+    /**
+     * The type of the keys in the map.
+     */
     keyType?: ASTNodeJSONOrKind;
+    /**
+     * The type of the values in the map.
+     */
     valueType?: ASTNodeJSONOrKind;
 }
+/**
+ * Represents a map type.
+ */
 declare class MapType extends BaseType<MapJSON> {
     static kind: string;
+    /**
+     * The type of the keys in the map.
+     */
     keyType: BaseType;
+    /**
+     * The type of the values in the map.
+     */
     valueType: BaseType;
+    /**
+     * Deserializes the `MapJSON` to the `MapType`.
+     * @param json The `MapJSON` to deserialize.
+     */
     fromJSON({ keyType, valueType }: MapJSON): void;
+    /**
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
+     */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
     /**
-     * Map 强比较
-     * @param targetTypeJSON
-     * @returns
+     * Map strong comparison.
+     * @param targetTypeJSON The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
      */
     protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
-    toJSON(): ASTNodeJSON;
+    /**
+     * Serialize the node to a JSON object.
+     * @returns The JSON representation of the node.
+     */
+    toJSON(): {
+        kind: ASTKind;
+        keyType: any;
+        valueType: any;
+    };
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of the `Property`.
+ */
+type PropertyJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta>;
+/**
+ * `Property` is a variable field that represents a property of a `ObjectType`.
+ */
+declare class Property<VariableMeta = any> extends BaseVariableField<VariableMeta> {
+    static kind: string;
+}
+
+/**
+ * ASTNodeJSON representation of `ObjectType`
+ */
 interface ObjectJSON<VariableMeta = any> {
     /**
-     *  Object 的 properties 一定是 Property 类型，因此业务可以不用填 kind
+     * The properties of the object.
+     *
+     * The `properties` of an Object must be of type `Property`, so the business can omit the `kind` field.
      */
     properties?: PropertyJSON<VariableMeta>[];
 }
+/**
+ * Action type for object properties change.
+ */
 type ObjectPropertiesChangeAction = GlobalEventActionType<'ObjectPropertiesChange', {
     prev: Property[];
     next: Property[];
 }, ObjectType>;
+/**
+ * Represents an object type.
+ */
 declare class ObjectType extends BaseType<ObjectJSON> {
     flags: ASTNodeFlags;
     static kind: string;
+    /**
+     * A map of property keys to `Property` instances.
+     */
     propertyTable: Map<string, Property>;
+    /**
+     * An array of `Property` instances.
+     */
     properties: Property[];
+    /**
+     * Deserializes the `ObjectJSON` to the `ObjectType`.
+     * @param json The `ObjectJSON` to deserialize.
+     */
     fromJSON({ properties }: ObjectJSON): void;
-    toJSON(): ASTNodeJSON;
     /**
-     * 根据 KeyPath 找到对应的变量
-     * @param keyPath 变量路径
-     * @returns
+     * Serialize the `ObjectType` to `ObjectJSON`.
+     * @returns The JSON representation of `ObjectType`.
+     */
+    toJSON(): {
+        properties: BaseVariableFieldJSON<any>[];
+    };
+    /**
+     * Get a variable field by key path.
+     * @param keyPath The key path to search for.
+     * @returns The variable field if found, otherwise `undefined`.
      */
     getByKeyPath(keyPath: string[]): Property | undefined;
+    /**
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
+     */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
     /**
-     * Object 类型强比较
-     * @param targetTypeJSON
-     * @returns
+     * Object type strong comparison.
+     * @param targetTypeJSON The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
      */
     protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `UnionType`, which union multiple `BaseType`.
+ */
 interface UnionJSON {
     types?: ASTNodeJSONOrKind[];
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `CustomType`
+ */
 interface CustomTypeJSON {
+    /**
+     * The name of the custom type.
+     */
     typeName: string;
 }
+/**
+ * Represents a custom type.
+ */
 declare class CustomType extends BaseType<CustomTypeJSON> {
     static kind: string;
     protected _typeName: string;
+    /**
+     * The name of the custom type.
+     */
     get typeName(): string;
+    /**
+     * Deserializes the `CustomTypeJSON` to the `CustomType`.
+     * @param json The `CustomTypeJSON` to deserialize.
+     */
     fromJSON(json: CustomTypeJSON): void;
+    /**
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
+     */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
+    toJSON(): {
+        typeName: string;
+    };
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 type ExpressionRefs = (BaseVariableField | undefined)[];
-declare abstract class BaseExpression<JSON extends ASTNodeJSON = any, InjectOpts = any> extends ASTNode<JSON, InjectOpts> {
+/**
+ * Base class for all expressions.
+ *
+ * All other expressions should extend this class.
+ */
+declare abstract class BaseExpression<JSON extends ASTNodeJSON = any> extends ASTNode<JSON> {
     flags: ASTNodeFlags;
     /**
-     * 获取全局变量表，方便表达式获取引用变量
+     * Get the global variable table, which is used to access referenced variables.
      */
-    get globalVariableTable(): VariableTable;
+    get globalVariableTable(): IVariableTable;
     /**
-     * 父变量字段，通过由近而远的方式进行排序
+     * Parent variable fields, sorted from closest to farthest.
      */
     get parentFields(): BaseVariableField[];
     /**
-     * 获取表达式引用的变量字段
-     * - 通常是 变量 VariableDeclaration，或者 属性 Property 节点
+     * Get the variable fields referenced by the expression.
+     *
+     * This method should be implemented by subclasses.
+     * @returns An array of referenced variable fields.
      */
     abstract getRefFields(): ExpressionRefs;
     /**
-     * 表达式返回的数据类型
+     * The return type of the expression.
      */
     abstract returnType: BaseType | undefined;
     /**
-     * 引用变量
+     * The variable fields referenced by the expression.
      */
     protected _refs: ExpressionRefs;
+    /**
+     * The variable fields referenced by the expression.
+     */
     get refs(): ExpressionRefs;
     protected refreshRefs$: Subject<void>;
     /**
-     * 刷新变量引用
+     * Refresh the variable references.
      */
     refreshRefs(): void;
     /**
-     * 监听引用变量变化
-     * 监听 [a.b.c] -> [a.b]
+     * An observable that emits the referenced variable fields when they change.
      */
     refs$: Observable<ExpressionRefs>;
-    constructor(params: CreateASTParams, opts?: InjectOpts);
+    constructor(params: CreateASTParams, opts?: any);
 }
 
-interface ExpressionListJSON {
-    expressions: ASTNodeJSON[];
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `EnumerateExpression`
+ */
+interface EnumerateExpressionJSON {
+    /**
+     * The expression to be enumerated.
+     */
+    enumerateFor: ASTNodeJSON;
 }
-declare class ExpressionList extends ASTNode<ExpressionListJSON> {
+/**
+ * Represents an enumeration expression, which iterates over a list and returns the type of the enumerated variable.
+ */
+declare class EnumerateExpression extends BaseExpression<EnumerateExpressionJSON> {
     static kind: string;
-    expressions: ASTNode[];
-    fromJSON({ expressions }: ExpressionListJSON): void;
-    toJSON(): ASTNodeJSON;
+    protected _enumerateFor: BaseExpression | undefined;
+    /**
+     * The expression to be enumerated.
+     */
+    get enumerateFor(): BaseExpression<any> | undefined;
+    /**
+     * The return type of the expression.
+     */
+    get returnType(): BaseType | undefined;
+    /**
+     * Get the variable fields referenced by the expression.
+     * @returns An empty array, as this expression does not reference any variables.
+     */
+    getRefFields(): [];
+    /**
+     * Deserializes the `EnumerateExpressionJSON` to the `EnumerateExpression`.
+     * @param json The `EnumerateExpressionJSON` to deserialize.
+     */
+    fromJSON({ enumerateFor: expression }: EnumerateExpressionJSON): void;
+    /**
+     * Serialize the `EnumerateExpression` to `EnumerateExpressionJSON`.
+     * @returns The JSON representation of `EnumerateExpression`.
+     */
+    toJSON(): {
+        kind: ASTKind;
+        enumerateFor: any;
+    };
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `KeyPathExpression`
+ */
 interface KeyPathExpressionJSON$1 {
+    /**
+     * The key path of the variable.
+     */
     keyPath: string[];
 }
+/**
+ * Represents a key path expression, which is used to reference a variable by its key path.
+ *
+ * This is the V2 of `KeyPathExpression`, with the following improvements:
+ * - `returnType` is copied to a new instance to avoid reference issues.
+ * - Circular reference detection is introduced.
+ */
 declare class KeyPathExpression<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON$1> extends BaseExpression<CustomPathJSON> {
     static kind: string;
     protected _keyPath: string[];
+    protected _rawPathJson: CustomPathJSON;
+    /**
+     * The key path of the variable.
+     */
     get keyPath(): string[];
+    /**
+     * Get the variable fields referenced by the expression.
+     * @returns An array of referenced variable fields.
+     */
     getRefFields(): BaseVariableField[];
-    get returnType(): BaseType | undefined;
     /**
-     * 业务重改该方法可快速定制自己的 Path 表达式
-     * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-     * @param json 业务定义的 Path 表达式
-     * @returns
+     * The return type of the expression.
+     *
+     * A new `returnType` node is generated directly, instead of reusing the existing one, to ensure that different key paths do not point to the same field.
+     */
+    _returnType: BaseType;
+    /**
+     * The return type of the expression.
+     */
+    get returnType(): BaseType<any>;
+    /**
+     * Parse the business-defined path expression into a key path.
+     *
+     * Businesses can quickly customize their own path expressions by modifying this method.
+     * @param json The path expression defined by the business.
+     * @returns The key path.
      */
     protected parseToKeyPath(json: CustomPathJSON): string[];
+    /**
+     * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+     * @param json The `KeyPathExpressionJSON` to deserialize.
+     */
     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;
+    /**
+     * Get the return type JSON by reference.
+     * @param _ref The referenced variable field.
+     * @returns The JSON representation of the return type.
+     */
+    getReturnTypeJSONByRef(_ref: BaseVariableField | undefined): ASTNodeJSON | undefined;
+    constructor(params: CreateASTParams, opts: any);
+    /**
+     * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+     * @returns The JSON representation of `KeyPathExpression`.
+     */
+    toJSON(): CustomPathJSON;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `KeyPathExpression`
+ */
 interface KeyPathExpressionJSON {
+    /**
+     * The key path of the variable.
+     */
     keyPath: string[];
 }
 /**
- * 新版 KeyPathExpressionV2，相比旧版：
- * - returnType 拷贝新一份，避免引用问题
- * - 引入成环检测
+ * @deprecated Use `KeyPathExpression` instead.
+ * Represents a key path expression, which is used to reference a variable by its key path.
  */
-declare class KeyPathExpressionV2<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON> extends BaseExpression<CustomPathJSON> {
+declare class LegacyKeyPathExpression<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON> extends BaseExpression<CustomPathJSON> {
     static kind: string;
     protected _keyPath: string[];
+    protected _rawPathJson: CustomPathJSON;
+    /**
+     * The key path of the variable.
+     */
     get keyPath(): string[];
+    /**
+     * Get the variable fields referenced by the expression.
+     * @returns An array of referenced variable fields.
+     */
     getRefFields(): BaseVariableField[];
-    _returnType: BaseType;
-    get returnType(): BaseType<any, any>;
     /**
-     * 业务重改该方法可快速定制自己的 Path 表达式
-     * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-     * @param json 业务定义的 Path 表达式
-     * @returns
+     * The return type of the expression.
+     */
+    get returnType(): BaseType | undefined;
+    /**
+     * Parse the business-defined path expression into a key path.
+     *
+     * Businesses can quickly customize their own path expressions by modifying this method.
+     * @param json The path expression defined by the business.
+     * @returns The key path.
      */
     protected parseToKeyPath(json: CustomPathJSON): string[];
+    /**
+     * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+     * @param json The `KeyPathExpressionJSON` to deserialize.
+     */
     fromJSON(json: CustomPathJSON): void;
-    getReturnTypeJSONByRef(_ref: BaseVariableField | undefined): ASTNodeJSON | undefined;
-    protected prevRefTypeHash: string | undefined;
     constructor(params: CreateASTParams, opts: any);
-    toJSON(): ASTNodeJSON;
+    /**
+     * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+     * @returns The JSON representation of `KeyPathExpression`.
+     */
+    toJSON(): CustomPathJSON;
 }
 
 /**
- * 声明类 AST 节点
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
  */
-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;
+
+/**
+ * ASTNodeJSON representation of `WrapArrayExpression`
+ */
+interface WrapArrayExpressionJSON {
     /**
-     * 父变量字段，通过由近而远的方式进行排序
+     * The expression to be wrapped.
      */
-    get parentFields(): BaseVariableField[];
-    get meta(): VariableMeta;
-    get type(): BaseType;
-    get initializer(): BaseExpression | undefined;
+    wrapFor: ASTNodeJSON;
+}
+/**
+ * Represents a wrap expression, which wraps an expression with an array.
+ */
+declare class WrapArrayExpression extends BaseExpression<WrapArrayExpressionJSON> {
+    static kind: string;
+    protected _wrapFor: BaseExpression | undefined;
+    protected _returnType: BaseType | undefined;
     /**
-     * 解析 VariableDeclarationJSON 从而生成变量声明节点
+     * The expression to be wrapped.
      */
-    fromJSON({ type, initializer, meta }: BaseVariableFieldJSON<VariableMeta>): void;
-    updateType(type: BaseVariableFieldJSON['type']): void;
-    updateInitializer(nextInitializer?: BaseVariableFieldJSON['initializer']): void;
-    updateMeta(nextMeta: VariableMeta): void;
+    get wrapFor(): BaseExpression<any> | undefined;
     /**
-     * 根据 keyPath 去找下钻的变量字段
-     * @param keyPath
-     * @returns
+     * The return type of the expression.
      */
-    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    get returnType(): BaseType | undefined;
     /**
-     * 监听类型变化
-     * @param observer
-     * @returns
+     * Refresh the return type of the expression.
      */
-    onTypeChange(observer: (type: ASTNode | undefined) => void): _flowgram_ai_utils.Disposable;
+    refreshReturnType(): void;
     /**
-     * 转换为 JSON
-     * @returns
+     * Get the variable fields referenced by the expression.
+     * @returns An empty array, as this expression does not reference any variables.
      */
-    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>;
+    getRefFields(): [];
     /**
-     * 监听任意变量变化
-     * @param observer 监听器，变量变化时会吐出值
-     * @returns
+     * Deserializes the `WrapArrayExpressionJSON` to the `WrapArrayExpression`.
+     * @param json The `WrapArrayExpressionJSON` to deserialize.
      */
-    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    fromJSON({ wrapFor: expression }: WrapArrayExpressionJSON): void;
     /**
-     * 列表或者任意变量变化
-     * @param observer
+     * Serialize the `WrapArrayExpression` to `WrapArrayExpressionJSON`.
+     * @returns The JSON representation of `WrapArrayExpression`.
      */
-    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[];
+    toJSON(): {
+        kind: ASTKind;
+        wrapFor: any;
+    };
+    protected init(): void;
+}
+
+/**
+ * ASTNodeJSON representation of `BaseVariableField`
+ */
+interface BaseVariableFieldJSON<VariableMeta = any> extends ASTNodeJSON {
     /**
-     * 根据 keyPath 找到对应的变量，或 Property 节点
-     * @param keyPath
-     * @returns
+     * key of the variable field
+     * - For `VariableDeclaration`, the key should be global unique.
+     * - For `Property`, the key is the property name.
      */
-    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    key: Identifier;
     /**
-     * 根据 key 值找到相应的变量
-     * @param key
-     * @returns
+     * type of the variable field, similar to js code:
+     * `const v: string`
      */
-    getVariableByKey(key: string): VariableDeclaration<any> | undefined;
+    type?: ASTNodeJSONOrKind;
     /**
-     * 往 variableTable 添加输出变量
-     * @param variable
+     * initializer of the variable field, similar to js code:
+     * `const v = 'hello'`
+     *
+     * with initializer, the type of field will be inferred from the initializer.
      */
-    addVariableToTable(variable: VariableDeclaration): void;
+    initializer?: ASTNodeJSON;
     /**
-     * 从 variableTable 中移除变量
-     * @param key
+     * meta data of the variable field, you cans store information like `title`, `icon`, etc.
      */
-    removeVariableFromTable(key: string): void;
-    dispose(): void;
+    meta?: VariableMeta;
 }
-
 /**
- * 作用域输出
+ * Variable Field abstract class, which is the base class for `VariableDeclaration` and `Property`
+ *
+ * - `VariableDeclaration` is used to declare a variable in a block scope.
+ * - `Property` is used to declare a property in an object.
  */
-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[];
+declare abstract class BaseVariableField<VariableMeta = any> extends ASTNode<BaseVariableFieldJSON<VariableMeta>> {
+    flags: ASTNodeFlags;
+    protected _type?: BaseType;
+    protected _meta: VariableMeta;
+    protected _initializer?: BaseExpression;
     /**
-     * 输出的变量 keys
+     * Parent variable fields, sorted from closest to farthest
      */
-    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;
+    get parentFields(): BaseVariableField[];
     /**
-     * 监听
+     * KeyPath of the variable field, sorted from farthest to closest
      */
-    protected variables$: Observable<VariableDeclaration[]>;
-    protected anyVariableChange$: Observable<VariableDeclaration>;
+    get keyPath(): string[];
     /**
-     * 监听任意变量变化
-     * @param observer 监听器，变量变化时会吐出值
-     * @returns
+     * Metadata of the variable field, you cans store information like `title`, `icon`, etc.
      */
-    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    get meta(): VariableMeta;
     /**
-     * 监听变量列表变化
-     * @param observer
-     * @returns
+     * Type of the variable field, similar to js code:
+     * `const v: string`
      */
-    onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
-    protected onDataChangeEmitter: Emitter<VariableDeclaration<any>[]>;
+    get type(): BaseType;
     /**
-     * 监听变量列表变化 + 任意子变量变化
+     * Initializer of the variable field, similar to js code:
+     * `const v = 'hello'`
+     *
+     * with initializer, the type of field will be inferred from the initializer.
      */
-    onDataChange: _flowgram_ai_utils.Event<VariableDeclaration<any>[]>;
-    constructor(scope: Scope);
+    get initializer(): BaseExpression | undefined;
     /**
-     * 获取可消费变量
+     * The global unique hash of the field, and will be changed when the field is updated.
      */
-    get variables(): VariableDeclaration[];
+    get hash(): string;
     /**
-     * 获取可访问的变量 keys
+     * Deserialize the `BaseVariableFieldJSON` to the `BaseVariableField`.
+     * @param json ASTJSON representation of `BaseVariableField`
      */
-    get variableKeys(): string[];
+    fromJSON({ type, initializer, meta }: Omit<BaseVariableFieldJSON<VariableMeta>, 'key'>): void;
     /**
-     * 返回依赖的作用域
+     * Update the type of the variable field
+     * @param type type ASTJSON representation of Type
      */
-    get depScopes(): Scope[];
+    updateType(type: BaseVariableFieldJSON['type']): void;
     /**
-     * 通过 keyPath 找到可用变量
-     * @param keyPath
-     * @returns
+     * Update the initializer of the variable field
+     * @param nextInitializer initializer ASTJSON representation of Expression
      */
-    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 {
+    updateInitializer(nextInitializer?: BaseVariableFieldJSON['initializer']): void;
     /**
-     * 类型相关
-     * - 内部默认实现一套基于 JSON 类型的类型 AST 节点
+     * Update the meta data of the variable field
+     * @param nextMeta meta data of the variable field
      */
-    String = "String",
-    Number = "Number",
-    Integer = "Integer",
-    Boolean = "Boolean",
-    Object = "Object",
-    Array = "Array",
-    Map = "Map",
-    Union = "Union",
-    Any = "Any",
-    CustomType = "CustomType",
+    updateMeta(nextMeta: VariableMeta): void;
     /**
-     * 声明
+     * Get the variable field by keyPath, similar to js code:
+     * `v.a.b`
+     * @param keyPath
+     * @returns
      */
-    Property = "Property",
-    VariableDeclaration = "VariableDeclaration",
-    VariableDeclarationList = "VariableDeclarationList",
+    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
     /**
-     * 表达式
+     * Subscribe to type change of the variable field
+     * @param observer
+     * @returns
      */
-    KeyPathExpression = "KeyPathExpression",
-    EnumerateExpression = "EnumerateExpression",
-    ExpressionList = "ExpressionList",
+    onTypeChange(observer: (type: ASTNode | undefined) => void): _flowgram_ai_utils.Disposable;
     /**
-     * 通用 AST 节点
+     * Serialize the variable field to JSON
+     * @returns ASTNodeJSON representation of `BaseVariableField`
      */
-    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;
+    toJSON(): BaseVariableFieldJSON<VariableMeta>;
 }
 
-type DataInjector = () => Record<string, any>;
-declare class ASTRegisters {
-    protected injectors: Map<ASTKindType, DataInjector>;
-    protected astMap: Map<ASTKindType, ASTNodeRegistry>;
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of the `VariableDeclaration`.
+ */
+type VariableDeclarationJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
     /**
-     * 核心 AST 节点注册
+     * Variable sorting order, which is used to sort variables in `scope.outputs.variables`
      */
-    constructor();
+    order?: number;
+};
+/**
+ * `VariableDeclaration` is a variable field that represents a variable declaration.
+ */
+declare class VariableDeclaration<VariableMeta = any> extends BaseVariableField<VariableMeta> {
+    static kind: string;
+    protected _order: number;
     /**
-     * 创建 AST 节点
-     * @param param 创建参数
-     * @returns
+     * Variable sorting order, which is used to sort variables in `scope.outputs.variables`
      */
-    createAST<ReturnNode extends ASTNode = ASTNode>(json: ASTNodeJSON, { parent, scope }: CreateASTParams): ReturnNode;
+    get order(): number;
+    constructor(params: CreateASTParams);
     /**
-     * 根据 AST 节点类型获取节点 Registry
-     * @param kind
-     * @returns
+     * Deserialize the `VariableDeclarationJSON` to the `VariableDeclaration`.
      */
-    getASTRegistryByKind(kind: ASTKindType): ASTNodeRegistry<any, any> | undefined;
+    fromJSON({ order, ...rest }: Omit<VariableDeclarationJSON<VariableMeta>, 'key'>): void;
     /**
-     * 注册 AST 节点
-     * @param ASTNode
-     * @param injector
+     * Update the sorting order of the variable declaration.
+     * @param order Variable sorting order. Default is 0.
      */
-    registerAST(ASTNode: ASTNodeRegistry, injector?: DataInjector): void;
-}
-
-/**
- * 通用数据 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;
+    updateOrder(order?: number): void;
+    /**
+     * Serialize the `VariableDeclaration` to `VariableDeclarationJSON`.
+     * @returns The JSON representation of `VariableDeclaration`.
+     */
+    toJSON(): VariableDeclarationJSON<VariableMeta>;
 }
 
-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;
-}
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
 
-interface MapNodeJSON {
-    map: [string, ASTNodeJSON][];
+interface VariableDeclarationListJSON<VariableMeta = any> {
+    /**
+     * `declarations` must be of type `VariableDeclaration`, so the business can omit the `kind` field.
+     */
+    declarations?: VariableDeclarationJSON<VariableMeta>[];
+    /**
+     * The starting order number for variables.
+     */
+    startOrder?: number;
 }
-declare class MapNode extends ASTNode<MapNodeJSON> {
+type VariableDeclarationListChangeAction = GlobalEventActionType<'VariableListChange', {
+    prev: VariableDeclaration[];
+    next: VariableDeclaration[];
+}, VariableDeclarationList>;
+declare class VariableDeclarationList extends ASTNode<VariableDeclarationListJSON> {
     static kind: string;
-    protected map: Map<string, ASTNode>;
-    fromJSON({ map }: MapNodeJSON): void;
-    toJSON(): ASTNodeJSON;
     /**
-     * 往 Map 中设置 ASTNode
-     * @param key ASTNode 的索引，
-     * @param json
+     * Map of variable declarations, keyed by variable name.
      */
-    set<Node extends ASTNode = ASTNode>(key: string, nextJSON: ASTNodeJSON): Node;
+    declarationTable: Map<string, VariableDeclaration>;
     /**
-     * 移除指定 ASTNode
-     * @param key
+     * Variable declarations, sorted by `order`.
      */
-    remove(key: string): void;
+    declarations: VariableDeclaration[];
     /**
-     * 获取 ASTNode
-     * @param key
-     * @returns
+     * Deserialize the `VariableDeclarationListJSON` to the `VariableDeclarationList`.
+     * - VariableDeclarationListChangeAction will be dispatched after deserialization.
+     *
+     * @param declarations Variable declarations.
+     * @param startOrder The starting order number for variables. Default is 0.
      */
-    get(key: string): ASTNode | undefined;
+    fromJSON({ declarations, startOrder }: VariableDeclarationListJSON): void;
+    /**
+     * Serialize the `VariableDeclarationList` to the `VariableDeclarationListJSON`.
+     * @returns ASTJSON representation of `VariableDeclarationList`
+     */
+    toJSON(): {
+        kind: ASTKind;
+        declarations: VariableDeclarationJSON<any>[];
+    };
 }
 
+/**
+ * Variable-core ASTNode factories.
+ */
 declare namespace ASTFactory {
     /**
-     * 类型相关
-     * @returns
+     * Type-related factories.
+     */
+    /**
+     * Creates a `String` type node.
      */
-    const createString: () => {
+    const createString: (json?: StringJSON) => {
+        format?: string;
         kind: ASTKind;
     };
+    /**
+     * Creates a `Number` type node.
+     */
     const createNumber: () => {
         kind: ASTKind;
     };
+    /**
+     * Creates a `Boolean` type node.
+     */
     const createBoolean: () => {
         kind: ASTKind;
     };
+    /**
+     * Creates an `Integer` type node.
+     */
     const createInteger: () => {
         kind: ASTKind;
     };
+    /**
+     * Creates an `Object` type node.
+     */
     const createObject: (json: ObjectJSON) => {
         properties?: PropertyJSON<any>[] | undefined;
         kind: ASTKind;
     };
+    /**
+     * Creates an `Array` type node.
+     */
     const createArray: (json: ArrayJSON) => {
-        items?: ASTNodeJSONOrKind | undefined;
+        items?: ASTNodeJSONOrKind;
         kind: ASTKind;
     };
+    /**
+     * Creates a `Map` type node.
+     */
     const createMap: (json: MapJSON) => {
-        keyType?: ASTNodeJSONOrKind | undefined;
-        valueType?: ASTNodeJSONOrKind | undefined;
+        keyType?: ASTNodeJSONOrKind;
+        valueType?: ASTNodeJSONOrKind;
         kind: ASTKind;
     };
+    /**
+     * Creates a `Union` type node.
+     */
     const createUnion: (json: UnionJSON) => {
-        types?: ASTNodeJSONOrKind[] | undefined;
+        types?: ASTNodeJSONOrKind[];
         kind: ASTKind;
     };
+    /**
+     * Creates a `CustomType` node.
+     */
     const createCustomType: (json: CustomTypeJSON) => {
         typeName: string;
         kind: ASTKind;
     };
     /**
-     * 声明相关
+     * Declaration-related factories.
+     */
+    /**
+     * Creates a `VariableDeclaration` node.
      */
     const createVariableDeclaration: <VariableMeta = any>(json: VariableDeclarationJSON<VariableMeta>) => {
-        key?: string | undefined;
-        type?: ASTNodeJSONOrKind | undefined;
-        initializer?: ASTNodeJSON | undefined;
+        key: Identifier;
+        type?: ASTNodeJSONOrKind;
+        initializer?: ASTNodeJSON;
         meta?: VariableMeta | undefined;
-        order?: number | undefined;
-        kind: ASTKind;
+        kind: ASTKindType;
+        order?: number;
     };
+    /**
+     * Creates a `Property` node.
+     */
     const createProperty: <VariableMeta = any>(json: PropertyJSON<VariableMeta>) => {
-        key: string;
-        type?: ASTNodeJSONOrKind | undefined;
-        initializer?: ASTNodeJSON | undefined;
+        key: Identifier;
+        type?: ASTNodeJSONOrKind;
+        initializer?: ASTNodeJSON;
         meta?: VariableMeta | undefined;
-        kind: ASTKind;
+        kind: ASTKindType;
     };
+    /**
+     * Creates a `VariableDeclarationList` node.
+     */
     const createVariableDeclarationList: (json: VariableDeclarationListJSON) => {
         declarations?: VariableDeclarationJSON<any>[] | undefined;
-        startOrder?: number | undefined;
+        startOrder?: number;
         kind: ASTKind;
     };
     /**
-     * 表达式相关
+     * Expression-related factories.
+     */
+    /**
+     * Creates an `EnumerateExpression` node.
      */
     const createEnumerateExpression: (json: EnumerateExpressionJSON) => {
         enumerateFor: ASTNodeJSON;
         kind: ASTKind;
     };
+    /**
+     * Creates a `KeyPathExpression` node.
+     */
     const createKeyPathExpression: (json: KeyPathExpressionJSON$1) => {
         keyPath: string[];
         kind: ASTKind;
     };
     /**
-     * 通过 AST Class 创建
+     * Creates a `WrapArrayExpression` node.
+     */
+    const createWrapArrayExpression: (json: WrapArrayExpressionJSON) => {
+        wrapFor: ASTNodeJSON;
+        kind: ASTKind;
+    };
+    /**
+     * Create by AST Class.
+     */
+    /**
+     * Creates Type-Safe ASTNodeJSON object based on the provided AST class.
+     *
+     * @param targetType Target ASTNode class.
+     * @param json The JSON data for the node.
+     * @returns The ASTNode JSON object.
      */
-    const create: <JSON_1 extends ASTNodeJSON>(targetType: {
-        new (...args: any[]): ASTNode<JSON_1, any>;
+    const create: <JSON extends ASTNodeJSON>(targetType: {
         kind: string;
-    }, json: JSON_1) => {
+        new (...args: any[]): ASTNode<JSON>;
+    }, json: JSON) => {
+        kind: string;
+    } & JSON;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Variable-core ASTNode matchers.
+ *
+ * - Typescript code inside if statement will be type guarded.
+ */
+declare namespace ASTMatch {
+    /**
+     * # Type-related matchers.
+     */
+    /**
+     * Check if the node is a `StringType`.
+     */
+    const isString: (node?: ASTNode) => node is StringType;
+    /**
+     * Check if the node is a `NumberType`.
+     */
+    const isNumber: (node?: ASTNode) => node is NumberType;
+    /**
+     * Check if the node is a `BooleanType`.
+     */
+    const isBoolean: (node?: ASTNode) => node is BooleanType;
+    /**
+     * Check if the node is a `IntegerType`.
+     */
+    const isInteger: (node?: ASTNode) => node is IntegerType;
+    /**
+     * Check if the node is a `ObjectType`.
+     */
+    const isObject: (node?: ASTNode) => node is ObjectType;
+    /**
+     * Check if the node is a `ArrayType`.
+     */
+    const isArray: (node?: ASTNode) => node is ArrayType;
+    /**
+     * Check if the node is a `MapType`.
+     */
+    const isMap: (node?: ASTNode) => node is MapType;
+    /**
+     * Check if the node is a `CustomType`.
+     */
+    const isCustomType: (node?: ASTNode) => node is CustomType;
+    /**
+     * # Declaration-related matchers.
+     */
+    /**
+     * Check if the node is a `VariableDeclaration`.
+     */
+    const isVariableDeclaration: <VariableMeta = any>(node?: ASTNode) => node is VariableDeclaration<VariableMeta>;
+    /**
+     * Check if the node is a `Property`.
+     */
+    const isProperty: <VariableMeta = any>(node?: ASTNode) => node is Property<VariableMeta>;
+    /**
+     * Check if the node is a `BaseVariableField`.
+     */
+    const isBaseVariableField: (node?: ASTNode) => node is BaseVariableField;
+    /**
+     * Check if the node is a `VariableDeclarationList`.
+     */
+    const isVariableDeclarationList: (node?: ASTNode) => node is VariableDeclarationList;
+    /**
+     * # Expression-related matchers.
+     */
+    /**
+     * Check if the node is a `EnumerateExpression`.
+     */
+    const isEnumerateExpression: (node?: ASTNode) => node is EnumerateExpression;
+    /**
+     * Check if the node is a `WrapArrayExpression`.
+     */
+    const isWrapArrayExpression: (node?: ASTNode) => node is WrapArrayExpression;
+    /**
+     * Check if the node is a `KeyPathExpression`.
+     */
+    const isKeyPathExpression: (node?: ASTNode) => node is KeyPathExpression;
+    /**
+     * Check ASTNode Match by ASTClass
+     *
+     * @param node ASTNode to be checked.
+     * @param targetType Target ASTNode class.
+     * @returns Whether the node is of the target type.
+     */
+    function is<TargetASTNode extends ASTNode>(node?: ASTNode, targetType?: {
         kind: string;
-    } & JSON_1;
+        new (...args: any[]): TargetASTNode;
+    }): node is TargetASTNode;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 declare const injectToAST: (serviceIdentifier: interfaces.ServiceIdentifier) => (target: any, propertyKey: string) => any;
 declare const postConstructAST: () => (target: any, propertyKey: string) => void;
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * isMatchAST is same as ASTMatch.is
+ * @param node
+ * @param targetType
+ * @returns
+ */
 declare function isMatchAST<TargetASTNode extends ASTNode>(node?: ASTNode, targetType?: {
     kind: string;
     new (...args: any[]): TargetASTNode;
 }): node is TargetASTNode;
 
-declare class Scope<ScopeMeta extends Record<string, any> = Record<string, any>> {
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Action type for scope changes.
+ */
+interface ScopeChangeAction {
+    type: 'add' | 'delete' | 'update' | 'available';
+    scope: Scope;
+}
+/**
+ * Interface for a variable table.
+ */
+interface IVariableTable extends Disposable {
     /**
-     * Scope 唯一索引
+     * The parent variable table.
      */
-    readonly id: string;
+    parentTable?: IVariableTable;
     /**
-     * Scope 依赖变量引擎
+     * @deprecated Use `onVariableListChange` or `onAnyVariableChange` instead.
      */
-    readonly variableEngine: VariableEngine;
+    onDataChange: Event<void>;
     /**
-     * 作用域的基本元信息，包括作用域所在节点及一些 flag 信息，上层业务可以额外扩展
+     * The current version of the variable table.
      */
-    readonly meta: ScopeMeta;
+    version: number;
     /**
-     * 作用域 AST 根节点
-     * - Map<formItemKey, formItemValue>
+     * The list of variables in the table.
      */
-    readonly ast: MapNode;
+    variables: VariableDeclaration[];
     /**
-     * 可用变量数据管理
+     * The keys of the variables in the table.
      */
-    readonly available: ScopeAvailableData;
+    variableKeys: string[];
     /**
-     * 输出变量数据管理
+     * Fires a change event.
      */
-    readonly output: ScopeOutputData;
+    fireChange(): void;
     /**
-     * 作用域事件管理
+     * Gets a variable or property by its key path.
+     * @param keyPath The key path to the variable or property.
+     * @returns The found `BaseVariableField` or `undefined`.
      */
-    readonly event: ScopeEventData;
+    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
     /**
-     * 数据缓存
+     * Gets a variable by its key.
+     * @param key The key of the variable.
+     * @returns The found `VariableDeclaration` or `undefined`.
+     */
+    getVariableByKey(key: string): VariableDeclaration | undefined;
+    /**
+     * Disposes the variable table.
      */
-    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;
+    /**
+     * Subscribes to changes in the variable list.
+     * @param observer The observer function.
+     * @returns A disposable to unsubscribe.
+     */
+    onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
+    /**
+     * Subscribes to changes in any variable's value.
+     * @param observer The observer function.
+     * @returns A disposable to unsubscribe.
+     */
+    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    /**
+     * Subscribes to both variable list changes and any variable's value changes.
+     * @param observer The observer function.
+     * @returns A disposable to unsubscribe.
+     */
+    onListOrAnyVarChange(observer: () => void): Disposable;
 }
 
+/**
+ * The core of the variable engine system.
+ * It manages scopes, variables, and events within the system.
+ */
 declare class VariableEngine implements Disposable {
+    /**
+     * The scope chain, which manages the dependency relationships between scopes.
+     */
     readonly chain: ScopeChain;
+    /**
+     * The registry for all AST node types.
+     */
     readonly astRegisters: ASTRegisters;
     protected toDispose: DisposableCollection;
     protected memo: {
         <T>(key: string | symbol, fn: () => T): T;
-        clear: (key?: (string | symbol) | undefined) => void;
+        clear: (key?: string | symbol) => void;
     };
-    protected scopeMap: Map<string, Scope<Record<string, any>>>;
+    protected scopeMap: Map<string | symbol, Scope<Record<string, any>>>;
+    /**
+     * A rxjs subject that emits global events occurring within the variable engine.
+     */
     globalEvent$: Subject<GlobalEventActionType>;
     protected onScopeChangeEmitter: Emitter<ScopeChangeAction>;
-    globalVariableTable: VariableTable;
+    /**
+     * A table containing all global variables.
+     */
+    globalVariableTable: IVariableTable;
+    /**
+     * An event that fires whenever a scope is added, updated, or deleted.
+     */
     onScopeChange: _flowgram_ai_utils.Event<ScopeChangeAction>;
     private readonly containerProvider;
+    /**
+     * The Inversify container instance.
+     */
     get container(): interfaces.Container;
-    constructor(chain: ScopeChain, // 作用域依赖关系偏序集
+    constructor(
+    /**
+     * The scope chain, which manages the dependency relationships between scopes.
+     */
+    chain: ScopeChain, 
+    /**
+     * The registry for all AST node types.
+     */
     astRegisters: ASTRegisters);
+    /**
+     * Disposes of all resources used by the variable engine.
+     */
     dispose(): void;
-    getScopeById(scopeId: string): Scope | undefined;
-    removeScopeById(scopeId: string): void;
-    createScope(id: string, meta?: Record<string, any>): Scope;
+    /**
+     * Retrieves a scope by its unique identifier.
+     * @param scopeId The ID of the scope to retrieve.
+     * @returns The scope if found, otherwise undefined.
+     */
+    getScopeById(scopeId: string | symbol): Scope | undefined;
+    /**
+     * Removes a scope by its unique identifier and disposes of it.
+     * @param scopeId The ID of the scope to remove.
+     */
+    removeScopeById(scopeId: string | symbol): void;
+    /**
+     * Creates a new scope or retrieves an existing one if the ID and type match.
+     * @param id The unique identifier for the scope.
+     * @param meta Optional metadata for the scope, defined by the user.
+     * @param options Options for creating the scope.
+     * @param options.ScopeConstructor The constructor to use for creating the scope. Defaults to `Scope`.
+     * @returns The created or existing scope.
+     */
+    createScope(id: string | symbol, meta?: Record<string, any>, options?: {
+        ScopeConstructor?: IScopeConstructor;
+    }): Scope;
+    /**
+     * Retrieves all scopes currently managed by the engine.
+     * @param options Options for retrieving the scopes.
+     * @param options.sort Whether to sort the scopes based on their dependency chain.
+     * @returns An array of all scopes.
+     */
     getAllScopes({ sort, }?: {
         sort?: boolean;
     }): Scope[];
+    /**
+     * Fires a global event to be broadcast to all listeners.
+     * @param event The global event to fire.
+     */
     fireGlobalEvent(event: GlobalEventActionType): void;
+    /**
+     * Subscribes to a specific type of global event.
+     * @param type The type of the event to listen for.
+     * @param observer A function to be called when the event is observed.
+     * @returns A disposable object to unsubscribe from the event.
+     */
     onGlobalEvent<ActionType extends GlobalEventActionType = GlobalEventActionType>(type: ActionType['type'], observer: (action: ActionType) => void): Disposable;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface ScopeContextProps {
     scope: Scope;
 }
-declare const ScopeProvider: react.Provider<ScopeContextProps>;
-declare const useScopeContext: () => ScopeContextProps | null;
-declare const useCurrentScope: () => Scope<Record<string, any>>;
+/**
+ * ScopeProvider provides the scope to its children via context.
+ */
+declare const ScopeProvider: (props: React.PropsWithChildren<{
+    /**
+     * scope used in the context
+     */
+    scope?: Scope;
+    /**
+     * @deprecated use scope prop instead, this is kept for backward compatibility
+     */
+    value?: ScopeContextProps;
+}>) => React.JSX.Element;
+/**
+ * useCurrentScope returns the scope provided by ScopeProvider.
+ * @returns
+ */
+declare const useCurrentScope: <Strict extends boolean = false>(params?: {
+    /**
+     * whether to throw error when no scope in ScopeProvider is found
+     */
+    strict: Strict;
+}) => Strict extends true ? Scope : Scope | undefined;
 
 /**
- * 获取作用域的可访问变量
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
  */
-declare function useScopeAvailable(): ScopeAvailableData;
 
 /**
+ * Get the available variables in the current scope.
  * 获取作用域的可访问变量
+ *
+ * @returns the available variables in the current scope
+ */
+declare function useScopeAvailable(params?: {
+    autoRefresh?: boolean;
+}): ScopeAvailableData;
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Get available variable list in the current scope.
+ *
+ * - If no scope, return global variable list.
+ * - The hook is reactive to variable list or any variables change.
  */
 declare function useAvailableVariables(): VariableDeclaration[];
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Get output variable list in the current scope.
+ *
+ * - The hook is reactive to variable list or any variables change.
+ */
+declare function useOutputVariables(): VariableDeclaration[];
+
 interface RenameInfo {
     before: BaseVariableField;
     after: BaseVariableField;
 }
+/**
+ * This service is responsible for detecting when a variable field's key is renamed.
+ * It listens for changes in variable declaration lists and object properties, and
+ * determines if a change constitutes a rename operation.
+ */
 declare class VariableFieldKeyRenameService {
     variableEngine: VariableEngine;
     toDispose: DisposableCollection;
     renameEmitter: Emitter<RenameInfo>;
+    /**
+     * Emits events for fields that are disposed of during a list change, but not renamed.
+     * This helps distinguish between a field that was truly removed and one that was renamed.
+     */
     disposeInListEmitter: Emitter<BaseVariableField<any>>;
+    /**
+     * An event that fires when a variable field key is successfully renamed.
+     */
     onRename: _flowgram_ai_utils.Event<RenameInfo>;
+    /**
+     * An event that fires when a field is removed from a list (and not part of a rename).
+     */
     onDisposeInList: _flowgram_ai_utils.Event<BaseVariableField<any>>;
+    /**
+     * Handles changes in a list of fields to detect rename operations.
+     * @param ast The AST node where the change occurred.
+     * @param prev The list of fields before the change.
+     * @param next The list of fields after the change.
+     */
     handleFieldListChange(ast?: ASTNode, prev?: BaseVariableField[], next?: BaseVariableField[]): void;
+    /**
+     * Notifies listeners about fields that were removed from a list.
+     * @param prev The list of fields before the change.
+     * @param next The list of fields after the change.
+     */
     notifyFieldsDispose(prev?: BaseVariableField[], next?: BaseVariableField[]): void;
     init(): void;
     dispose(): void;
 }
 
-export { ASTFactory, ASTKind, 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, type GetKindJSON, type GetKindJSONOrKind, type GlobalEventActionType, type IVariableTable, IntegerType, KeyPathExpression, type KeyPathExpressionJSON$1 as KeyPathExpressionJSON, LegacyKeyPathExpression, 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, WrapArrayExpression, type WrapArrayExpressionJSON, injectToAST, isMatchAST, postConstructAST, useAvailableVariables, useCurrentScope, useOutputVariables, useScopeAvailable };