@flowgram.ai/variable-layout 0.5.5 → 0.5.7

package/dist/index.d.mts

@@ -8,19 +8,52 @@ import { interfaces } from 'inversify';
  * 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;
+/**
+ * Represents a scope associated with a flow node.
+ */
 interface FlowNodeScope extends Scope<FlowNodeScopeMeta> {
 }
 
@@ -32,6 +65,9 @@ interface FlowNodeScope extends Scope<FlowNodeScopeMeta> {
 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;
@@ -42,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.
@@ -102,9 +144,17 @@ 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.
@@ -125,12 +175,33 @@ declare class FlowNodeVariableData extends EntityData {
  * 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;
 }
+/**
+ * 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, {
@@ -149,15 +220,27 @@ declare class ScopeChainTransformService {
     /**
      * register new transform function
      * @param transformerId used to identify transformer, prevent duplicated transformer
-     * @param 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[];
+    /**
+     * 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.
+     */
     transformCovers(scopes: Scope[], { scope }: {
         scope: Scope;
     }): Scope[];
@@ -168,6 +251,9 @@ declare class ScopeChainTransformService {
  * 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.
@@ -183,11 +269,11 @@ interface VariableChainConfig {
     getNodeChildren?: (node: FlowNodeEntity) => FlowNodeEntity[];
     getNodeParent?: (node: FlowNodeEntity) => FlowNodeEntity | undefined;
     /**
-     * Fine-tune the dependency scope
+     * Fine-tune the dependency scope.
      */
     transformDeps?: IScopeTransformer;
     /**
-     * 对依赖作用域进行微调
+     * Fine-tune the cover scope.
      */
     transformCovers?: IScopeTransformer;
 }
@@ -199,19 +285,47 @@ declare const VariableChainConfig: unique symbol;
  */
 
 /**
- * 自由布局作用域链实现
+ * Scope chain implementation for free layout.
  */
 declare class FreeLayoutScopeChain extends ScopeChain {
     entityManager: EntityManager;
     protected flowDocument: FlowDocument;
     protected configs?: VariableChainConfig;
     protected transformService: ScopeChainTransformService;
+    /**
+     * The virtual tree of the flow document.
+     */
     get tree(): FlowVirtualTree<FlowNodeEntity>;
     onInit(): void;
+    /**
+     * 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[];
+    /**
+     * 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
@@ -219,8 +333,22 @@ declare class FreeLayoutScopeChain extends ScopeChain {
      * @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[];
 }
 
@@ -230,7 +358,7 @@ declare class FreeLayoutScopeChain extends ScopeChain {
  */
 
 /**
- * 基于 FlowVirtualTree 的 ScopeOrder 实现
+ * Scope chain implementation based on `FlowVirtualTree`.
  */
 declare class FixedLayoutScopeChain extends ScopeChain {
     protected flowDocument: FlowDocument;
@@ -238,13 +366,52 @@ declare class FixedLayoutScopeChain extends ScopeChain {
     tree: FlowVirtualTree<ScopeChainNode> | 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[];
+    /**
+     * 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;
 }
 
@@ -253,22 +420,35 @@ declare class FixedLayoutScopeChain extends ScopeChain {
  * 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
+ * Use `node.scope` instead.
  * @deprecated
- * @param node
+ * @param node The flow node entity.
+ * @returns The public scope of the node.
  */
 declare function getNodeScope(node: FlowNodeEntity): FlowNodeScope;
 /**
- * Use `node.privateScope` instead
+ * Use `node.privateScope` instead.
  * @deprecated
- * @param node
+ * @param node The flow node entity.
+ * @returns The private scope of the node.
  */
 declare function getNodePrivateScope(node: FlowNodeEntity): FlowNodeScope;
 

package/dist/index.d.ts

@@ -8,19 +8,52 @@ import { interfaces } from 'inversify';
  * 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;
+/**
+ * Represents a scope associated with a flow node.
+ */
 interface FlowNodeScope extends Scope<FlowNodeScopeMeta> {
 }
 
@@ -32,6 +65,9 @@ interface FlowNodeScope extends Scope<FlowNodeScopeMeta> {
 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;
@@ -42,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.
@@ -102,9 +144,17 @@ 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.
@@ -125,12 +175,33 @@ declare class FlowNodeVariableData extends EntityData {
  * 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;
 }
+/**
+ * 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, {
@@ -149,15 +220,27 @@ declare class ScopeChainTransformService {
     /**
      * register new transform function
      * @param transformerId used to identify transformer, prevent duplicated transformer
-     * @param 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[];
+    /**
+     * 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.
+     */
     transformCovers(scopes: Scope[], { scope }: {
         scope: Scope;
     }): Scope[];
@@ -168,6 +251,9 @@ declare class ScopeChainTransformService {
  * 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.
@@ -183,11 +269,11 @@ interface VariableChainConfig {
     getNodeChildren?: (node: FlowNodeEntity) => FlowNodeEntity[];
     getNodeParent?: (node: FlowNodeEntity) => FlowNodeEntity | undefined;
     /**
-     * Fine-tune the dependency scope
+     * Fine-tune the dependency scope.
      */
     transformDeps?: IScopeTransformer;
     /**
-     * 对依赖作用域进行微调
+     * Fine-tune the cover scope.
      */
     transformCovers?: IScopeTransformer;
 }
@@ -199,19 +285,47 @@ declare const VariableChainConfig: unique symbol;
  */
 
 /**
- * 自由布局作用域链实现
+ * Scope chain implementation for free layout.
  */
 declare class FreeLayoutScopeChain extends ScopeChain {
     entityManager: EntityManager;
     protected flowDocument: FlowDocument;
     protected configs?: VariableChainConfig;
     protected transformService: ScopeChainTransformService;
+    /**
+     * The virtual tree of the flow document.
+     */
     get tree(): FlowVirtualTree<FlowNodeEntity>;
     onInit(): void;
+    /**
+     * 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[];
+    /**
+     * 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
@@ -219,8 +333,22 @@ declare class FreeLayoutScopeChain extends ScopeChain {
      * @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[];
 }
 
@@ -230,7 +358,7 @@ declare class FreeLayoutScopeChain extends ScopeChain {
  */
 
 /**
- * 基于 FlowVirtualTree 的 ScopeOrder 实现
+ * Scope chain implementation based on `FlowVirtualTree`.
  */
 declare class FixedLayoutScopeChain extends ScopeChain {
     protected flowDocument: FlowDocument;
@@ -238,13 +366,52 @@ declare class FixedLayoutScopeChain extends ScopeChain {
     tree: FlowVirtualTree<ScopeChainNode> | 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[];
+    /**
+     * 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;
 }
 
@@ -253,22 +420,35 @@ declare class FixedLayoutScopeChain extends ScopeChain {
  * 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
+ * Use `node.scope` instead.
  * @deprecated
- * @param node
+ * @param node The flow node entity.
+ * @returns The public scope of the node.
  */
 declare function getNodeScope(node: FlowNodeEntity): FlowNodeScope;
 /**
- * Use `node.privateScope` instead
+ * Use `node.privateScope` instead.
  * @deprecated
- * @param node
+ * @param node The flow node entity.
+ * @returns The private scope of the node.
  */
 declare function getNodePrivateScope(node: FlowNodeEntity): FlowNodeScope;