@flowgram.ai/variable-layout 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/index.d.ts

@@ -1,25 +1,73 @@
-import { Scope, VariableEngine, ASTNodeJSON, ASTNode, ScopeChain } from '@flowgram.ai/variable-core';
+import { Scope, VariableEngine, ASTNodeJSON, ASTNode, BaseVariableField, ScopeChain } from '@flowgram.ai/variable-core';
 import { FlowNodeEntity, FlowDocument, FlowVirtualTree } from '@flowgram.ai/document';
 import { EntityData, EntityManager } from '@flowgram.ai/core';
+import { interfaces } from 'inversify';
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Enum for flow node scope types.
+ */
 declare enum FlowNodeScopeTypeEnum {
+    /**
+     * Public scope.
+     */
     public = "public",
+    /**
+     * Private scope.
+     */
     private = "private"
 }
+/**
+ * Metadata for a flow node scope.
+ */
 interface FlowNodeScopeMeta {
+    /**
+     * The flow node entity associated with the scope.
+     */
     node?: FlowNodeEntity;
+    /**
+     * The type of the scope.
+     */
     type?: FlowNodeScopeTypeEnum;
 }
+/**
+ * Represents a virtual node in the scope chain.
+ */
 interface ScopeVirtualNode {
+    /**
+     * The ID of the virtual node.
+     */
     id: string;
+    /**
+     * The type of the flow node.
+     */
     flowNodeType: 'virtualNode';
 }
+/**
+ * Represents a node in the scope chain, which can be either a flow node entity or a virtual node.
+ */
 type ScopeChainNode = FlowNodeEntity | ScopeVirtualNode;
-type FlowNodeScope = Scope<FlowNodeScopeMeta>;
+/**
+ * Represents a scope associated with a flow node.
+ */
+interface FlowNodeScope extends Scope<FlowNodeScopeMeta> {
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
 
 interface Options {
     variableEngine: VariableEngine;
 }
+/**
+ * Manages variable data for a flow node, including public and private scopes.
+ */
 declare class FlowNodeVariableData extends EntityData {
     readonly opts: Options;
     static type: string;
@@ -30,7 +78,13 @@ declare class FlowNodeVariableData extends EntityData {
      */
     protected _private?: FlowNodeScope;
     protected _public: FlowNodeScope;
+    /**
+     * The private scope of the node.
+     */
     get private(): FlowNodeScope | undefined;
+    /**
+     * The public scope of the node.
+     */
     get public(): FlowNodeScope;
     /**
      * Sets a variable in the public AST (Abstract Syntax Tree) with the given key and JSON value.
@@ -53,7 +107,7 @@ declare class FlowNodeVariableData extends EntityData {
      * @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;
+    getVar(key?: string): ASTNode<any> | undefined;
     /**
      * Clears a variable from the public AST (Abstract Syntax Tree) by key.
      *
@@ -82,7 +136,7 @@ declare class FlowNodeVariableData extends EntityData {
      * @param key - The key of the variable to retrieve. Defaults to 'outputs'.
      * @returns The value of the variable, or undefined if not found.
      */
-    getPrivateVar(key?: string): ASTNode<any, any> | undefined;
+    getPrivateVar(key?: string): ASTNode<any> | undefined;
     /**
      * Clears a variable from the private AST (Abstract Syntax Tree) by key.
      *
@@ -90,90 +144,312 @@ declare class FlowNodeVariableData extends EntityData {
      * @returns The updated AST node.
      */
     clearPrivateVar(key?: string): void | undefined;
+    /**
+     * An array containing all scopes (public and private) of the node.
+     */
     get allScopes(): FlowNodeScope[];
     getDefaultData(): {};
     constructor(entity: FlowNodeEntity, opts: Options);
+    /**
+     * Initializes and returns the private scope for the node.
+     * If the private scope already exists, it returns the existing one.
+     * @returns The private scope of the node.
+     */
     initPrivate(): FlowNodeScope;
+    /**
+     * Find a variable field by key path in the public scope by scope chain.
+     * @param keyPath - The key path of the variable field.
+     * @returns The variable field, or undefined if not found.
+     */
+    getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    /**
+     * Find a variable field by key path in the private scope by scope chain.
+     * @param keyPath - The key path of the variable field.
+     * @returns The variable field, or undefined if not found.
+     */
+    getByKeyPathInPrivate(keyPath: string[]): BaseVariableField | undefined;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Context for scope transformers.
+ */
 interface TransformerContext {
+    /**
+     * The current scope
+     */
     scope: FlowNodeScope;
+    /**
+     * The flow document.
+     */
     document: FlowDocument;
+    /**
+     * The variable engine.
+     */
     variableEngine: VariableEngine;
 }
-interface VariableLayoutConfig {
+/**
+ * A function that transforms an array of scopes.
+ * @param scopes The array of scopes to transform.
+ * @param ctx The transformer context.
+ * @returns The transformed array of scopes.
+ */
+type IScopeTransformer = (scopes: Scope[], ctx: TransformerContext) => Scope[];
+/**
+ * A service for transforming scope chains.
+ */
+declare class ScopeChainTransformService {
+    protected configs?: VariableChainConfig | undefined;
+    protected transformerMap: Map<string, {
+        transformDeps: IScopeTransformer;
+        transformCovers: IScopeTransformer;
+    }>;
+    document: FlowDocument;
+    variableEngine: VariableEngine;
+    constructor(configs?: VariableChainConfig | undefined);
+    /**
+     * check if transformer registered
+     * @param transformerId used to identify transformer, prevent duplicated
+     * @returns
+     */
+    hasTransformer(transformerId: string): boolean;
+    /**
+     * register new transform function
+     * @param transformerId used to identify transformer, prevent duplicated transformer
+     * @param transformer The transformer to register.
+     */
+    registerTransformer(transformerId: string, transformer: {
+        transformDeps: IScopeTransformer;
+        transformCovers: IScopeTransformer;
+    }): void;
+    /**
+     * Transforms the dependency scopes.
+     * @param scopes The array of scopes to transform.
+     * @param param1 The context for the transformation.
+     * @returns The transformed array of scopes.
+     */
+    transformDeps(scopes: Scope[], { scope }: {
+        scope: Scope;
+    }): Scope[];
     /**
-     * 开始节点的节点 Id
+     * Transforms the cover scopes.
+     * @param scopes The array of scopes to transform.
+     * @param param1 The context for the transformation.
+     * @returns The transformed array of scopes.
      */
-    startNodeId?: string;
+    transformCovers(scopes: Scope[], { scope }: {
+        scope: Scope;
+    }): Scope[];
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Configuration for the variable chain.
+ */
+interface VariableChainConfig {
     /**
-     * 节点的子节点输出变量，不能被后续节点所访问，用于固定布局场景
+     * The output variables of a node's children cannot be accessed by subsequent nodes.
+     *
      * @param node
      * @returns
      */
     isNodeChildrenPrivate?: (node: ScopeChainNode) => boolean;
     /**
-     * 用于自由画布场景，部分场景通过连线或者其他交互形式来表达节点之间的父子关系，需要可配置化
+     * For fixed layout scenarios: there are a large number of useless nodes between parent and child (such as inlineBlocks, etc., which need to be configured to be skipped)
+     * For free canvas scenarios: in some scenarios, the parent-child relationship between nodes is expressed through connections or other interactive forms, which needs to be configurable
      */
-    getFreeChildren?: (node: FlowNodeEntity) => FlowNodeEntity[];
-    getFreeParent?: (node: FlowNodeEntity) => FlowNodeEntity | undefined;
+    getNodeChildren?: (node: FlowNodeEntity) => FlowNodeEntity[];
+    getNodeParent?: (node: FlowNodeEntity) => FlowNodeEntity | undefined;
     /**
-     * 对依赖作用域进行微调
+     * Fine-tune the dependency scope.
      */
-    transformDeps?: (scopes: Scope[], ctx: TransformerContext) => Scope[];
+    transformDeps?: IScopeTransformer;
     /**
-     * 对依赖作用域进行微调
+     * Fine-tune the cover scope.
      */
-    transformCovers?: (scopes: Scope[], ctx: TransformerContext) => Scope[];
+    transformCovers?: IScopeTransformer;
 }
-declare const VariableLayoutConfig: unique symbol;
+declare const VariableChainConfig: unique symbol;
 
 /**
- * 自由布局作用域链实现
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Scope chain implementation for free layout.
  */
 declare class FreeLayoutScopeChain extends ScopeChain {
     entityManager: EntityManager;
     protected flowDocument: FlowDocument;
-    protected configs?: VariableLayoutConfig;
+    protected configs?: VariableChainConfig;
+    protected transformService: ScopeChainTransformService;
+    /**
+     * The virtual tree of the flow document.
+     */
     get tree(): FlowVirtualTree<FlowNodeEntity>;
     onInit(): void;
-    protected getAllInputLayerNodes(curr: FlowNodeEntity): FlowNodeEntity[];
+    /**
+     * Gets all input layer nodes for a given node in the same layer, sorted by distance.
+     * @param node The node to get input layer nodes for.
+     * @returns An array of input layer nodes.
+     */
+    protected getAllInputLayerNodes(node: FlowNodeEntity): FlowNodeEntity[];
+    /**
+     * Gets all output layer nodes for a given node in the same layer.
+     * @param curr The node to get output layer nodes for.
+     * @returns An array of output layer nodes.
+     */
     protected getAllOutputLayerNodes(curr: FlowNodeEntity): FlowNodeEntity[];
+    /**
+     * Gets the dependency scopes for a given scope.
+     * @param scope The scope to get dependencies for.
+     * @returns An array of dependency scopes.
+     */
     getDeps(scope: FlowNodeScope): FlowNodeScope[];
+    /**
+     * Gets the covering scopes for a given scope.
+     * @param scope The scope to get covering scopes for.
+     * @returns An array of covering scopes.
+     */
     getCovers(scope: FlowNodeScope): FlowNodeScope[];
-    protected transformCovers(covers: Scope[], { scope }: {
-        scope: Scope;
-    }): Scope[];
-    protected transformDeps(deps: Scope[], { scope }: {
-        scope: Scope;
-    }): Scope[];
-    getChildren(node: FlowNodeEntity): FlowNodeEntity[];
-    getParent(node: FlowNodeEntity): FlowNodeEntity | undefined;
+    /**
+     * Gets the children of a node.
+     * @param node The node to get children for.
+     * @returns An array of child nodes.
+     */
+    getNodeChildren(node: FlowNodeEntity): FlowNodeEntity[];
+    /**
+     * Get All children of nodes
+     * @param node
+     * @returns
+     */
+    getAllPublicChildScopes(node: FlowNodeEntity): Scope[];
+    /**
+     * Gets the parent of a node.
+     * @param node The node to get the parent for.
+     * @returns The parent node or `undefined` if not found.
+     */
+    getNodeParent(node: FlowNodeEntity): FlowNodeEntity | undefined;
+    /**
+     * Checks if the children of a node are private and cannot be accessed by subsequent nodes.
+     * @param node The node to check.
+     * @returns `true` if the children are private, `false` otherwise.
+     */
+    protected isNodeChildrenPrivate(node?: FlowNodeEntity): boolean;
+    /**
+     * Sorts all scopes in the scope chain.
+     * @returns An empty array, as this method is not implemented.
+     */
     sortAll(): Scope[];
 }
 
 /**
- * 基于 FlowVirtualTree 的 ScopeOrder 实现
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Scope chain implementation based on `FlowVirtualTree`.
  */
 declare class FixedLayoutScopeChain extends ScopeChain {
     protected flowDocument: FlowDocument;
-    protected configs?: VariableLayoutConfig | undefined;
+    protected configs?: VariableChainConfig | undefined;
     tree: FlowVirtualTree<ScopeChainNode> | undefined;
-    constructor(flowDocument: FlowDocument, configs?: VariableLayoutConfig | undefined);
+    protected transformService: ScopeChainTransformService;
+    constructor(flowDocument: FlowDocument, configs?: VariableChainConfig | undefined);
+    /**
+     * Binds the scope chain to a `FlowVirtualTree`.
+     * @param tree The `FlowVirtualTree` to bind to.
+     */
     bindTree(tree: FlowVirtualTree<ScopeChainNode>): void;
+    /**
+     * Gets the dependency scopes for a given scope.
+     * @param scope The scope to get dependencies for.
+     * @returns An array of dependency scopes.
+     */
     getDeps(scope: FlowNodeScope): FlowNodeScope[];
+    /**
+     * Gets the covering scopes for a given scope.
+     * @param scope The scope to get covering scopes for.
+     * @returns An array of covering scopes.
+     */
     getCovers(scope: FlowNodeScope): FlowNodeScope[];
-    protected transformCovers(covers: Scope[], { scope }: {
-        scope: Scope;
-    }): Scope[];
-    protected transformDeps(deps: Scope[], { scope }: {
-        scope: Scope;
-    }): Scope[];
+    /**
+     * Sorts all scopes in the scope chain.
+     * @returns A sorted array of all scopes.
+     */
     sortAll(): Scope[];
+    /**
+     * Gets the `FlowNodeVariableData` for a given `ScopeChainNode`.
+     * @param node The `ScopeChainNode` to get data for.
+     * @returns The `FlowNodeVariableData` or `undefined` if not found.
+     */
     private getVariableData;
+    /**
+     * Checks if the children of a node are private.
+     * @param node The node to check.
+     * @returns `true` if the children are private, `false` otherwise.
+     */
     private isNodeChildrenPrivate;
+    /**
+     * Checks if a node has children.
+     * @param node The node to check.
+     * @returns `true` if the node has children, `false` otherwise.
+     */
     private hasChildren;
+    /**
+     * Gets all sorted child scopes of a node.
+     * @param node The node to get child scopes for.
+     * @param options Options for getting child scopes.
+     * @returns An array of sorted child scopes.
+     */
     private getAllSortedChildScope;
 }
 
-export { FixedLayoutScopeChain, type FlowNodeScope, type FlowNodeScopeMeta, FlowNodeScopeTypeEnum as FlowNodeScopeType, FlowNodeVariableData, FreeLayoutScopeChain, VariableLayoutConfig };
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Global Scope stores all variables that are not scoped to any node.
+ *
+ * - Variables in Global Scope can be accessed by any node.
+ * - Any other scope's variables can not be accessed by Global Scope.
+ */
+declare class GlobalScope extends Scope {
+    static readonly ID: unique symbol;
+    /**
+     * Check if the scope is Global Scope.
+     * @param scope
+     * @returns
+     */
+    static is(scope: Scope): boolean;
+}
+declare const bindGlobalScope: (bind: interfaces.Bind) => void;
+
+/**
+ * Use `node.scope` instead.
+ * @deprecated
+ * @param node The flow node entity.
+ * @returns The public scope of the node.
+ */
+declare function getNodeScope(node: FlowNodeEntity): FlowNodeScope;
+/**
+ * Use `node.privateScope` instead.
+ * @deprecated
+ * @param node The flow node entity.
+ * @returns The private scope of the node.
+ */
+declare function getNodePrivateScope(node: FlowNodeEntity): FlowNodeScope;
+
+export { FixedLayoutScopeChain, type FlowNodeScope, type FlowNodeScopeMeta, FlowNodeScopeTypeEnum as FlowNodeScopeType, FlowNodeVariableData, FreeLayoutScopeChain, GlobalScope, ScopeChainTransformService, VariableChainConfig, bindGlobalScope, getNodePrivateScope, getNodeScope };