@flowgram.ai/variable-core 0.2.15 → 0.2.17

package/dist/index.d.mts

@@ -5,8 +5,18 @@ import { Subject, Observable, BehaviorSubject, Observer as Observer$1 } from 'rx
 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;
 
@@ -22,8 +32,22 @@ declare class ScopeOutputData {
     };
     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);
     /**
@@ -62,22 +86,30 @@ declare class ScopeAvailableData {
     protected variables$: Observable<VariableDeclaration[]>;
     protected anyVariableChange$: Observable<VariableDeclaration>;
     /**
-     * 监听任意变量变化
-     * @param observer 监听器，变量变化时会吐出值
+     * 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);
     /**
      * 获取可消费变量
@@ -96,9 +128,21 @@ declare class ScopeAvailableData {
      * @param keyPath
      * @returns
      */
-    getByKeyPath(keyPath?: string[]): VariableDeclaration | Property | undefined;
+    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;
@@ -166,6 +210,27 @@ declare class Scope<ScopeMeta extends Record<string, any> = Record<string, any>>
     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;
+    /**
+     * 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;
 }
 
 /**
@@ -225,7 +290,7 @@ declare abstract class ASTNode<JSON extends ASTNodeJSON = any, InjectOpts = any>
     /**
      * 节点的版本号，每 fireChange 一次 version + 1
      */
-    private _version;
+    protected _version: number;
     /**
      * 更新锁
      */
@@ -324,6 +389,11 @@ declare abstract class ASTNode<JSON extends ASTNodeJSON = any, InjectOpts = any>
     [key: string]: unknown;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 type ASTKindType = string;
 type Identifier = string;
 interface ASTNodeJSON {
@@ -394,6 +464,11 @@ interface GlobalEventActionType<Type = string, Payload = any, AST extends ASTNod
     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>;
@@ -422,6 +497,10 @@ declare class ASTRegisters {
     registerAST(ASTNode: ASTNodeRegistry, injector?: DataInjector): void;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
 declare enum ASTNodeFlags {
     None = 0,
     /**
@@ -442,6 +521,11 @@ declare enum ASTNodeFlags {
     VariableType = 120
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 /**
  * 通用数据 AST 节点，无子节点
  */
@@ -456,6 +540,11 @@ declare class DataNode<Data = any> extends ASTNode {
     partialUpdate(nextData: Data): void;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface ListNodeJSON {
     list: ASTNodeJSON[];
 }
@@ -467,6 +556,11 @@ declare class ListNode extends ASTNode<ListNodeJSON> {
     toJSON(): ASTNodeJSON;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface MapNodeJSON {
     map: [string, ASTNodeJSON][];
 }
@@ -494,6 +588,11 @@ declare class MapNode extends ASTNode<MapNodeJSON> {
     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;
     /**
@@ -513,28 +612,53 @@ declare abstract class BaseType<JSON extends ASTNodeJSON = any, InjectOpts = any
     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;
 }
@@ -555,6 +679,11 @@ declare class ArrayType extends BaseType<ArrayJSON> {
     toJSON(): ASTNodeJSON;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface MapJSON {
     keyType?: ASTNodeJSONOrKind;
     valueType?: ASTNodeJSONOrKind;
@@ -574,6 +703,11 @@ declare class MapType extends BaseType<MapJSON> {
     toJSON(): ASTNodeJSON;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 type PropertyJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
     key: string;
 };
@@ -581,6 +715,11 @@ declare class Property<VariableMeta = any> extends BaseVariableField<VariableMet
     static kind: string;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface ObjectJSON<VariableMeta = any> {
     /**
      *  Object 的 properties 一定是 Property 类型，因此业务可以不用填 kind
@@ -613,10 +752,20 @@ declare class ObjectType extends BaseType<ObjectJSON> {
     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;
 }
@@ -628,6 +777,11 @@ declare class CustomType extends BaseType<CustomTypeJSON> {
     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;
@@ -666,6 +820,11 @@ declare abstract class BaseExpression<JSON extends ASTNodeJSON = any, InjectOpts
     constructor(params: CreateASTParams, opts?: InjectOpts);
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface KeyPathExpressionJSON$1 {
     keyPath: string[];
 }
@@ -687,6 +846,11 @@ declare class KeyPathExpression<CustomPathJSON extends ASTNodeJSON = KeyPathExpr
     toJSON(): ASTNodeJSON;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface EnumerateExpressionJSON {
     enumerateFor: ASTNodeJSON;
 }
@@ -703,6 +867,11 @@ declare class EnumerateExpression extends BaseExpression<EnumerateExpressionJSON
     toJSON(): ASTNodeJSON;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface KeyPathExpressionJSON {
     keyPath: string[];
 }
@@ -732,6 +901,11 @@ declare class KeyPathExpressionV2<CustomPathJSON extends ASTNodeJSON = KeyPathEx
     toJSON(): ASTNodeJSON;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface WrapArrayExpressionJSON {
     wrapFor: ASTNodeJSON;
 }
@@ -769,9 +943,11 @@ declare abstract class BaseVariableField<VariableMeta = any> extends ASTNode<Bas
      * 父变量字段，通过由近而远的方式进行排序
      */
     get parentFields(): BaseVariableField[];
+    get keyPath(): string[];
     get meta(): VariableMeta;
     get type(): BaseType;
     get initializer(): BaseExpression | undefined;
+    get hash(): string;
     /**
      * 解析 VariableDeclarationJSON 从而生成变量声明节点
      */
@@ -819,6 +995,11 @@ declare class VariableDeclaration<VariableMeta = any> extends BaseVariableField<
     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
@@ -958,9 +1139,19 @@ declare namespace ASTMatch {
     }): 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
@@ -972,6 +1163,11 @@ declare function isMatchAST<TargetASTNode extends ASTNode>(node?: ASTNode, targe
     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;
@@ -986,8 +1182,9 @@ interface IVariableTable extends Disposable {
     getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
     getVariableByKey(key: string): VariableDeclaration | undefined;
     dispose(): void;
+    onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
     onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
-    onAnyChange(observer: () => void): Disposable;
+    onListOrAnyVarChange(observer: () => void): Disposable;
 }
 
 declare class VariableEngine implements Disposable {
@@ -1034,11 +1231,21 @@ 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
+ */
+
 /**
  * 获取作用域的可访问变量
  */