@flowgram.ai/variable-core 0.1.0-alpha.10

package/dist/index.d.mts

@@ -0,0 +1,1279 @@
+import { ContainerModule, interfaces } from 'inversify';
+import * as _flowgram_ai_utils from '@flowgram.ai/utils';
+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';
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+declare const VariableContainerModule: ContainerModule;
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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;
+    /**
+     * @deprecated use onListOrAnyVarChange instead
+     */
+    get onDataChange(): _flowgram_ai_utils.Event<void>;
+    /**
+     * listen to variable list change
+     */
+    get onVariableListChange(): (observer: (variables: VariableDeclaration<any>[]) => void) => _flowgram_ai_utils.Disposable;
+    /**
+     * listen to any variable update in list
+     */
+    get onAnyVariableChange(): (observer: (changedVariable: VariableDeclaration<any>) => void) => _flowgram_ai_utils.Disposable;
+    /**
+     * listen to variable list change + any variable update in list
+     */
+    get onListOrAnyVarChange(): (observer: () => 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>;
+    /**
+     * listen to any variable update in list
+     * @param observer
+     * @returns
+     */
+    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    /**
+     * listen to variable list change
+     * @param observer
+     * @returns
+     */
+    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>[]>;
+    /**
+     * listen to variable list change + any variable drilldown change
+     */
+    onListOrAnyVarChange: _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[]): BaseVariableField | undefined;
+    /**
+     * Track Variable Change (Includes type update and children update) By KeyPath
+     * @returns
+     */
+    trackByKeyPath(keyPath: string[] | undefined, cb: (variable?: BaseVariableField | undefined) => void, opts?: {
+        triggerOnInit?: boolean;
+    }): Disposable;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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;
+    /**
+     * Sets a variable in the Scope with the default key 'outputs'.
+     *
+     * @param json - The JSON value to store.
+     * @returns The updated AST node.
+     */
+    setVar(json: ASTNodeJSON): ASTNode;
+    /**
+     * Sets a variable in the Scope by key.
+     *
+     * @param key - The key of the variable to set.
+     * @param json - The JSON value to store.
+     * @returns The updated AST node.
+     */
+    setVar(key: string, json: ASTNodeJSON): ASTNode;
+    /**
+     * Retrieves a variable from the Scope by key.
+     *
+     * @param key - The key of the variable to retrieve. Defaults to 'outputs'.
+     * @returns The value of the variable, or undefined if not found.
+     */
+    getVar(key?: string): ASTNode<any, any> | undefined;
+    /**
+     * Clears a variable from the Scope by key.
+     *
+     * @param key - The key of the variable to clear. Defaults to 'outputs'.
+     * @returns The updated AST node.
+     */
+    clearVar(key?: string): void;
+}
+
+/**
+ * 作用域依赖关系管理数据结构
+ * - ScopeOrder 可能存在多种实现方式，因此采取抽象类的方式，具体的实现由子类实现
+ */
+declare abstract class ScopeChain {
+    readonly toDispose: DisposableCollection;
+    variableEngineProvider: VariableEngineProvider;
+    get variableEngine(): VariableEngine;
+    constructor();
+    /**
+     * 所有作用域依赖关系刷新
+     */
+    refreshAllChange(): void;
+    abstract getDeps(scope: Scope): Scope[];
+    abstract getCovers(scope: Scope): Scope[];
+    abstract sortAll(): Scope[];
+    dispose(): void;
+    get disposed(): boolean;
+    get onDispose(): Event<void>;
+}
+
+interface ASTNodeRegistry<JSON extends ASTNodeJSON = any, InjectOpts = any> {
+    kind: string;
+    new (params: CreateASTParams, injectOpts: InjectOpts): ASTNode<JSON>;
+}
+declare abstract class ASTNode<JSON extends ASTNodeJSON = any, InjectOpts = any> implements Disposable {
+    /**
+     * @deprecated
+     * 获取 ASTNode 注入的 opts
+     *
+     * 请使用 @injectToAst(XXXService) declare xxxService: XXXService 实现外部依赖注入
+     */
+    readonly opts?: InjectOpts;
+    /**
+     * 节点的唯一标识符，节点不指定则默认由 nanoid 生成，不可更改
+     * - 如需要生成新 key，则销毁当前节点并生成新的节点
+     */
+    readonly key: Identifier;
+    /**
+     * 节点类型
+     */
+    static readonly kind: ASTKindType;
+    /**
+     * 节点 Flags，记录一些 Flag 信息
+     */
+    readonly flags: number;
+    /**
+     * 节点所处的作用域
+     */
+    readonly scope: Scope;
+    /**
+     * 父节点
+     */
+    readonly parent: ASTNode | undefined;
+    /**
+     * 节点的版本号，每 fireChange 一次 version + 1
+     */
+    protected _version: number;
+    /**
+     * 更新锁
+     */
+    changeLocked: boolean;
+    /**
+     * Batch Update 相关参数
+     */
+    private _batch;
+    /**
+     * AST 节点变化事件，基于 Rxjs 实现
+     * - 使用了 BehaviorSubject, 在订阅时会自动触发一次事件，事件为当前值
+     */
+    readonly value$: BehaviorSubject<ASTNode>;
+    /**
+     * 子节点
+     */
+    protected _children: Set<ASTNode<any, any>>;
+    /**
+     * 删除节点处理事件列表
+     */
+    readonly toDispose: DisposableCollection;
+    /**
+     * 销毁时触发的回调
+     */
+    onDispose: _flowgram_ai_utils.Event<void>;
+    /**
+     * 构造函数
+     * @param createParams 创建 ASTNode 的必要参数
+     * @param injectOptions 依赖注入各种模块
+     */
+    constructor({ key, parent, scope }: CreateASTParams, opts?: InjectOpts);
+    /**
+     * AST 节点的类型
+     */
+    get kind(): string;
+    /**
+     * 解析 AST JSON 数据
+     * @param json AST JSON 数据
+     */
+    abstract fromJSON(json: JSON): void;
+    /**
+     * 获取当前节点所有子节点
+     */
+    get children(): ASTNode[];
+    /**
+     * 转化为 ASTNodeJSON
+     * @returns
+     */
+    toJSON(): ASTNodeJSON;
+    /**
+     * 创建子节点
+     * @param json 子节点的 AST JSON
+     * @returns
+     */
+    protected createChildNode<ChildNode extends ASTNode = ASTNode>(json: ASTNodeJSON): ChildNode;
+    /**
+     * 更新子节点，快速实现子节点更新消费逻辑
+     * @param keyInThis 当前对象上的指定 key
+     */
+    protected updateChildNodeByKey(keyInThis: keyof this, nextJSON?: ASTNodeJSON): void;
+    /**
+     * 批处理更新，批处理函数内所有的 fireChange 都合并成一个
+     * @param updater 批处理函数
+     * @returns
+     */
+    protected withBatchUpdate<ParamTypes extends any[], ReturnType>(updater: (...args: ParamTypes) => ReturnType): (...args: ParamTypes) => ReturnType;
+    /**
+     * 触发当前节点更新
+     */
+    fireChange(): void;
+    /**
+     * 节点的版本值
+     * - 通过 NodeA === NodeB && versionA === versionB 可以比较两者是否相等
+     */
+    get version(): number;
+    /**
+     * 节点唯一 hash 值
+     */
+    get hash(): string;
+    /**
+     * 监听 AST 节点的变化
+     * @param observer 监听回调
+     * @param selector 监听指定数据
+     * @returns
+     */
+    subscribe<Data = this>(observer: ObserverOrNext<Data>, { selector, debounceAnimation, triggerOnInit }?: SubscribeConfig<this, Data>): Disposable;
+    dispatchGlobalEvent<ActionType extends GlobalEventActionType = GlobalEventActionType>(event: Omit<ActionType, 'ast'>): void;
+    /**
+     * 销毁
+     */
+    dispose(): void;
+    get disposed(): boolean;
+    /**
+     * 节点扩展信息
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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",
+    WrapArrayExpression = "WrapArrayExpression",
+    /**
+     * 通用 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;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+declare enum ASTNodeFlags {
+    None = 0,
+    /**
+     * 变量字段
+     */
+    VariableField = 1,
+    /**
+     * 表达式
+     */
+    Expression = 4,
+    /**
+     * 变量类型
+     */
+    BasicType = 8,
+    DrilldownType = 16,
+    EnumerateType = 32,
+    UnionType = 64,
+    VariableType = 120
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * 通用数据 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;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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][];
+}
+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;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+declare abstract class BaseType<JSON extends ASTNodeJSON = any, InjectOpts = any> extends ASTNode<JSON, InjectOpts> {
+    flags: number;
+    /**
+     * 类型是否一致
+     * @param targetTypeJSON
+     */
+    isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
+    /**
+     * 可下钻类型需实现
+     * @param keyPath
+     */
+    getByKeyPath(keyPath?: string[]): BaseVariableField | undefined;
+    /**
+     * Get AST JSON for current base type
+     * @returns
+     */
+    toJSON(): ASTNodeJSON;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+declare class StringType extends BaseType {
+    flags: ASTNodeFlags;
+    static kind: string;
+    fromJSON(): void;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+declare class IntegerType extends BaseType {
+    flags: ASTNodeFlags;
+    static kind: string;
+    fromJSON(): void;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+declare class BooleanType extends BaseType {
+    static kind: string;
+    fromJSON(): void;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+declare class NumberType extends BaseType {
+    static kind: string;
+    fromJSON(): void;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+interface ArrayJSON {
+    items?: ASTNodeJSONOrKind;
+}
+declare class ArrayType extends BaseType<ArrayJSON> {
+    flags: ASTNodeFlags;
+    static kind: string;
+    items: BaseType;
+    fromJSON({ items }: ArrayJSON): void;
+    get canDrilldownItems(): boolean;
+    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
+    /**
+     * Array 强比较
+     * @param targetTypeJSON
+     * @returns
+     */
+    protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
+    toJSON(): ASTNodeJSON;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+interface MapJSON {
+    keyType?: ASTNodeJSONOrKind;
+    valueType?: ASTNodeJSONOrKind;
+}
+declare class MapType extends BaseType<MapJSON> {
+    static kind: string;
+    keyType: BaseType;
+    valueType: BaseType;
+    fromJSON({ keyType, valueType }: MapJSON): void;
+    isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
+    /**
+     * Map 强比较
+     * @param targetTypeJSON
+     * @returns
+     */
+    protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
+    toJSON(): ASTNodeJSON;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+type PropertyJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
+    key: string;
+};
+declare class Property<VariableMeta = any> extends BaseVariableField<VariableMeta> {
+    static kind: string;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+interface ObjectJSON<VariableMeta = any> {
+    /**
+     *  Object 的 properties 一定是 Property 类型，因此业务可以不用填 kind
+     */
+    properties?: PropertyJSON<VariableMeta>[];
+}
+type ObjectPropertiesChangeAction = GlobalEventActionType<'ObjectPropertiesChange', {
+    prev: Property[];
+    next: Property[];
+}, ObjectType>;
+declare class ObjectType extends BaseType<ObjectJSON> {
+    flags: ASTNodeFlags;
+    static kind: string;
+    propertyTable: Map<string, Property>;
+    properties: Property[];
+    fromJSON({ properties }: ObjectJSON): void;
+    toJSON(): ASTNodeJSON;
+    /**
+     * 根据 KeyPath 找到对应的变量
+     * @param keyPath 变量路径
+     * @returns
+     */
+    getByKeyPath(keyPath: string[]): Property | undefined;
+    isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
+    /**
+     * Object 类型强比较
+     * @param targetTypeJSON
+     * @returns
+     */
+    protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+interface UnionJSON {
+    types?: ASTNodeJSONOrKind[];
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+interface CustomTypeJSON {
+    typeName: string;
+}
+declare class CustomType extends BaseType<CustomTypeJSON> {
+    static kind: string;
+    protected _typeName: string;
+    get typeName(): string;
+    fromJSON(json: CustomTypeJSON): void;
+    isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
+}
+
+/**
+ * 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> {
+    flags: ASTNodeFlags;
+    /**
+     * 获取全局变量表，方便表达式获取引用变量
+     */
+    get globalVariableTable(): IVariableTable;
+    /**
+     * 父变量字段，通过由近而远的方式进行排序
+     */
+    get parentFields(): BaseVariableField[];
+    /**
+     * 获取表达式引用的变量字段
+     * - 通常是 变量 VariableDeclaration，或者 属性 Property 节点
+     */
+    abstract getRefFields(): ExpressionRefs;
+    /**
+     * 表达式返回的数据类型
+     */
+    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);
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+interface WrapArrayExpressionJSON {
+    wrapFor: ASTNodeJSON;
+}
+/**
+ * 遍历表达式，对列表进行遍历，获取遍历后的变量类型
+ */
+declare class WrapArrayExpression extends BaseExpression<WrapArrayExpressionJSON> {
+    static kind: string;
+    protected _wrapFor: BaseExpression | undefined;
+    protected _returnType: BaseType | undefined;
+    get wrapFor(): BaseExpression<any, any> | undefined;
+    get returnType(): BaseType | undefined;
+    refreshReturnType(): void;
+    getRefFields(): [];
+    fromJSON({ wrapFor: expression }: WrapArrayExpressionJSON): void;
+    toJSON(): ASTNodeJSON;
+    protected init(): void;
+}
+
+/**
+ * 声明类 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 keyPath(): string[];
+    get meta(): VariableMeta;
+    get type(): BaseType;
+    get initializer(): BaseExpression | undefined;
+    get hash(): string;
+    /**
+     * 解析 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;
+    };
+}
+
+/**
+ * 声明类 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;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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 {
+    /**
+     * 类型相关
+     * @returns
+     */
+    const createString: () => {
+        kind: ASTKind;
+    };
+    const createNumber: () => {
+        kind: ASTKind;
+    };
+    const createBoolean: () => {
+        kind: ASTKind;
+    };
+    const createInteger: () => {
+        kind: ASTKind;
+    };
+    const createObject: (json: ObjectJSON) => {
+        properties?: PropertyJSON<any>[] | undefined;
+        kind: ASTKind;
+    };
+    const createArray: (json: ArrayJSON) => {
+        items?: ASTNodeJSONOrKind | undefined;
+        kind: ASTKind;
+    };
+    const createMap: (json: MapJSON) => {
+        keyType?: ASTNodeJSONOrKind | undefined;
+        valueType?: ASTNodeJSONOrKind | undefined;
+        kind: ASTKind;
+    };
+    const createUnion: (json: UnionJSON) => {
+        types?: ASTNodeJSONOrKind[] | undefined;
+        kind: ASTKind;
+    };
+    const createCustomType: (json: CustomTypeJSON) => {
+        typeName: string;
+        kind: ASTKind;
+    };
+    /**
+     * 声明相关
+     */
+    const createVariableDeclaration: <VariableMeta = any>(json: VariableDeclarationJSON<VariableMeta>) => {
+        key?: string | undefined;
+        type?: ASTNodeJSONOrKind | undefined;
+        initializer?: ASTNodeJSON | undefined;
+        meta?: VariableMeta | undefined;
+        order?: number | undefined;
+        kind: ASTKind;
+    };
+    const createProperty: <VariableMeta = any>(json: PropertyJSON<VariableMeta>) => {
+        key: string;
+        type?: ASTNodeJSONOrKind | undefined;
+        initializer?: ASTNodeJSON | undefined;
+        meta?: VariableMeta | undefined;
+        kind: ASTKind;
+    };
+    const createVariableDeclarationList: (json: VariableDeclarationListJSON) => {
+        declarations?: VariableDeclarationJSON<any>[] | undefined;
+        startOrder?: number | undefined;
+        kind: ASTKind;
+    };
+    /**
+     * 表达式相关
+     */
+    const createEnumerateExpression: (json: EnumerateExpressionJSON) => {
+        enumerateFor: ASTNodeJSON;
+        kind: ASTKind;
+    };
+    const createKeyPathExpression: (json: KeyPathExpressionJSON$1) => {
+        keyPath: string[];
+        kind: ASTKind;
+    };
+    const createWrapArrayExpression: (json: WrapArrayExpressionJSON) => {
+        wrapFor: ASTNodeJSON;
+        kind: ASTKind;
+    };
+    /**
+     * 通过 AST Class 创建
+     */
+    const create: <JSON_1 extends ASTNodeJSON>(targetType: {
+        new (...args: any[]): ASTNode<JSON_1, any>;
+        kind: string;
+    }, json: JSON_1) => {
+        kind: string;
+    } & JSON_1;
+}
+
+declare namespace ASTMatch {
+    /**
+     * 类型相关
+     * @returns
+     */
+    const isString: (node?: ASTNode) => node is StringType;
+    const isNumber: (node?: ASTNode) => node is NumberType;
+    const isBoolean: (node?: ASTNode) => node is BooleanType;
+    const isInteger: (node?: ASTNode) => node is IntegerType;
+    const isObject: (node?: ASTNode) => node is ObjectType;
+    const isArray: (node?: ASTNode) => node is ArrayType;
+    const isMap: (node?: ASTNode) => node is MapType;
+    const isCustomType: (node?: ASTNode) => node is CustomType;
+    /**
+     * 声明相关
+     */
+    const isVariableDeclaration: <VariableMeta = any>(node?: ASTNode) => node is VariableDeclaration<VariableMeta>;
+    const isProperty: <VariableMeta = any>(node?: ASTNode) => node is Property<VariableMeta>;
+    const isVariableDeclarationList: (node?: ASTNode) => node is VariableDeclarationList;
+    /**
+     * 表达式相关
+     */
+    const isEnumerateExpression: (node?: ASTNode) => node is EnumerateExpression;
+    const isKeyPathExpression: (node?: ASTNode) => node is KeyPathExpression<KeyPathExpressionJSON$1>;
+    /**
+     * Check AST Match by ASTClass
+     */
+    function is<TargetASTNode extends ASTNode>(node?: ASTNode, targetType?: {
+        kind: string;
+        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;
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+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;
+    onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
+    onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    onListOrAnyVarChange(observer: () => void): Disposable;
+}
+
+declare class VariableEngine implements Disposable {
+    readonly chain: ScopeChain;
+    readonly astRegisters: ASTRegisters;
+    protected toDispose: DisposableCollection;
+    protected memo: {
+        <T>(key: string | symbol, fn: () => T): T;
+        clear: (key?: (string | symbol) | undefined) => void;
+    };
+    protected scopeMap: Map<string | symbol, Scope<Record<string, any>>>;
+    globalEvent$: Subject<GlobalEventActionType>;
+    protected onScopeChangeEmitter: Emitter<ScopeChangeAction>;
+    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 | 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[];
+    fireGlobalEvent(event: GlobalEventActionType): void;
+    onGlobalEvent<ActionType extends GlobalEventActionType = GlobalEventActionType>(type: ActionType['type'], observer: (action: ActionType) => void): Disposable;
+}
+
+interface ScopeContextProps {
+    scope: Scope;
+}
+declare const ScopeProvider: react.Provider<ScopeContextProps>;
+declare const useScopeContext: () => ScopeContextProps | null;
+declare const useCurrentScope: () => Scope<Record<string, any>>;
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * 获取作用域的可访问变量
+ */
+declare function useScopeAvailable(): ScopeAvailableData;
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * 获取作用域的可访问变量
+ */
+declare function useAvailableVariables(): VariableDeclaration[];
+
+interface RenameInfo {
+    before: BaseVariableField;
+    after: BaseVariableField;
+}
+declare class VariableFieldKeyRenameService {
+    variableEngine: VariableEngine;
+    toDispose: DisposableCollection;
+    renameEmitter: Emitter<RenameInfo>;
+    disposeInListEmitter: Emitter<BaseVariableField<any>>;
+    onRename: _flowgram_ai_utils.Event<RenameInfo>;
+    onDisposeInList: _flowgram_ai_utils.Event<BaseVariableField<any>>;
+    handleFieldListChange(ast?: ASTNode, prev?: BaseVariableField[], next?: BaseVariableField[]): void;
+    notifyFieldsDispose(prev?: BaseVariableField[], next?: BaseVariableField[]): void;
+    init(): void;
+    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, 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, WrapArrayExpression, type WrapArrayExpressionJSON, injectToAST, isMatchAST, postConstructAST, useAvailableVariables, useCurrentScope, useScopeAvailable, useScopeContext };