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

package/dist/esm/index.js

@@ -16,7 +16,7 @@ import { ContainerModule } from "inversify";
 // src/variable-engine.ts
 import { Subject as Subject5 } from "rxjs";
 import { inject as inject2, injectable as injectable3, preDestroy } from "inversify";
-import { Disposable as Disposable6, DisposableCollection as DisposableCollection5 } from "@flowgram.ai/utils";
+import { Disposable as Disposable4, DisposableCollection as DisposableCollection5 } from "@flowgram.ai/utils";
 import { Emitter as Emitter3 } from "@flowgram.ai/utils";
 
 // src/utils/toDisposable.tsx
@@ -47,9 +47,170 @@ var createMemo = () => {
   return memo;
 };
 
+// src/scope/variable-table.ts
+import { Subject, merge, share, skip, switchMap } from "rxjs";
+import { DisposableCollection, Emitter } from "@flowgram.ai/utils";
+var VariableTable = class {
+  constructor(parentTable) {
+    this.parentTable = parentTable;
+    this.table = /* @__PURE__ */ new Map();
+    this.toDispose = new DisposableCollection();
+    /**
+     * @deprecated
+     */
+    this.onDataChangeEmitter = new Emitter();
+    this.variables$ = new Subject();
+    /**
+     * An observable that listens for value changes on any variable within the table.
+     */
+    this.anyVariableChange$ = this.variables$.pipe(
+      switchMap(
+        (_variables) => merge(
+          ..._variables.map(
+            (_v) => _v.value$.pipe(
+              // Skip the initial value of the BehaviorSubject
+              skip(1)
+            )
+          )
+        )
+      ),
+      share()
+    );
+    /**
+     * @deprecated Use onListOrAnyVarChange instead.
+     */
+    this.onDataChange = this.onDataChangeEmitter.event;
+    this._version = 0;
+    this.toDispose.pushAll([
+      this.onDataChangeEmitter,
+      // Activate the share() operator
+      this.onAnyVariableChange(() => {
+        this.bumpVersion();
+      })
+    ]);
+  }
+  /**
+   * Subscribes to updates on any variable in the list.
+   * @param observer A function to be called when any variable's value changes.
+   * @returns A disposable object to unsubscribe from the updates.
+   */
+  onAnyVariableChange(observer) {
+    return subsToDisposable(this.anyVariableChange$.subscribe(observer));
+  }
+  /**
+   * Subscribes to changes in the variable list (additions or removals).
+   * @param observer A function to be called when the list of variables changes.
+   * @returns A disposable object to unsubscribe from the updates.
+   */
+  onVariableListChange(observer) {
+    return subsToDisposable(this.variables$.subscribe(observer));
+  }
+  /**
+   * Subscribes to both variable list changes and updates to any variable in the list.
+   * @param observer A function to be called when either the list or a variable in it changes.
+   * @returns A disposable collection to unsubscribe from both events.
+   */
+  onListOrAnyVarChange(observer) {
+    const disposables = new DisposableCollection();
+    disposables.pushAll([this.onVariableListChange(observer), this.onAnyVariableChange(observer)]);
+    return disposables;
+  }
+  /**
+   * Fires change events to notify listeners that the data has been updated.
+   */
+  fireChange() {
+    this.bumpVersion();
+    this.onDataChangeEmitter.fire();
+    this.variables$.next(this.variables);
+    this.parentTable?.fireChange();
+  }
+  /**
+   * The current version of the variable table, incremented on each change.
+   */
+  get version() {
+    return this._version;
+  }
+  /**
+   * Increments the version number, resetting to 0 if it reaches MAX_SAFE_INTEGER.
+   */
+  bumpVersion() {
+    this._version = this._version + 1;
+    if (this._version === Number.MAX_SAFE_INTEGER) {
+      this._version = 0;
+    }
+  }
+  /**
+   * An array of all variables in the table.
+   */
+  get variables() {
+    return Array.from(this.table.values());
+  }
+  /**
+   * An array of all variable keys in the table.
+   */
+  get variableKeys() {
+    return Array.from(this.table.keys());
+  }
+  /**
+   * Retrieves a variable or a nested property field by its key path.
+   * @param keyPath An array of keys representing the path to the desired field.
+   * @returns The found variable or property field, or undefined if not found.
+   */
+  getByKeyPath(keyPath) {
+    const [variableKey, ...propertyKeys] = keyPath || [];
+    if (!variableKey) {
+      return;
+    }
+    const variable = this.getVariableByKey(variableKey);
+    return propertyKeys.length ? variable?.getByKeyPath(propertyKeys) : variable;
+  }
+  /**
+   * Retrieves a variable by its key.
+   * @param key The key of the variable to retrieve.
+   * @returns The variable declaration if found, otherwise undefined.
+   */
+  getVariableByKey(key) {
+    return this.table.get(key);
+  }
+  /**
+   * Adds a variable to the table.
+   * If a parent table exists, the variable is also added to the parent.
+   * @param variable The variable declaration to add.
+   */
+  addVariableToTable(variable) {
+    this.table.set(variable.key, variable);
+    if (this.parentTable) {
+      this.parentTable.addVariableToTable(variable);
+    }
+  }
+  /**
+   * Removes a variable from the table.
+   * If a parent table exists, the variable is also removed from the parent.
+   * @param key The key of the variable to remove.
+   */
+  removeVariableFromTable(key) {
+    this.table.delete(key);
+    if (this.parentTable) {
+      this.parentTable.removeVariableFromTable(key);
+    }
+  }
+  /**
+   * Disposes of all resources used by the variable table.
+   */
+  dispose() {
+    this.variableKeys.forEach(
+      (_key) => this.parentTable?.removeVariableFromTable(_key)
+    );
+    this.parentTable?.fireChange();
+    this.variables$.complete();
+    this.variables$.unsubscribe();
+    this.toDispose.dispose();
+  }
+};
+
 // src/scope/scope-chain.ts
 import { inject, injectable } from "inversify";
-import { DisposableCollection } from "@flowgram.ai/utils";
+import { DisposableCollection as DisposableCollection2 } from "@flowgram.ai/utils";
 
 // src/providers.ts
 var VariableEngineProvider = Symbol("DynamicVariableEngine");
@@ -58,13 +219,13 @@ var ContainerProvider = Symbol("ContainerProvider");
 // src/scope/scope-chain.ts
 var ScopeChain = class {
   constructor() {
-    this.toDispose = new DisposableCollection();
+    this.toDispose = new DisposableCollection2();
   }
   get variableEngine() {
     return this.variableEngineProvider();
   }
   /**
-   * 所有作用域依赖关系刷新
+   * Refreshes the dependency and coverage relationships for all scopes.
    */
   refreshAllChange() {
     this.variableEngine.getAllScopes().forEach((_scope) => {
@@ -109,7 +270,7 @@ var ASTKind = /* @__PURE__ */ ((ASTKind2) => {
   ASTKind2["VariableDeclarationList"] = "VariableDeclarationList";
   ASTKind2["KeyPathExpression"] = "KeyPathExpression";
   ASTKind2["EnumerateExpression"] = "EnumerateExpression";
-  ASTKind2["ExpressionList"] = "ExpressionList";
+  ASTKind2["WrapArrayExpression"] = "WrapArrayExpression";
   ASTKind2["ListNode"] = "ListNode";
   ASTKind2["DataNode"] = "DataNode";
   ASTKind2["MapNode"] = "MapNode";
@@ -117,7 +278,7 @@ var ASTKind = /* @__PURE__ */ ((ASTKind2) => {
 })(ASTKind || {});
 
 // src/ast/ast-registers.ts
-import { omit } from "lodash";
+import { omit } from "lodash-es";
 import { injectable as injectable2 } from "inversify";
 
 // src/ast/utils/inversify.ts
@@ -148,6 +309,43 @@ var postConstructAST = () => (target, propertyKey) => {
   }
 };
 
+// src/ast/flags.ts
+var ASTNodeFlags = /* @__PURE__ */ ((ASTNodeFlags2) => {
+  ASTNodeFlags2[ASTNodeFlags2["None"] = 0] = "None";
+  ASTNodeFlags2[ASTNodeFlags2["VariableField"] = 1] = "VariableField";
+  ASTNodeFlags2[ASTNodeFlags2["Expression"] = 4] = "Expression";
+  ASTNodeFlags2[ASTNodeFlags2["BasicType"] = 8] = "BasicType";
+  ASTNodeFlags2[ASTNodeFlags2["DrilldownType"] = 16] = "DrilldownType";
+  ASTNodeFlags2[ASTNodeFlags2["EnumerateType"] = 32] = "EnumerateType";
+  ASTNodeFlags2[ASTNodeFlags2["UnionType"] = 64] = "UnionType";
+  ASTNodeFlags2[ASTNodeFlags2["VariableType"] = 120] = "VariableType";
+  return ASTNodeFlags2;
+})(ASTNodeFlags || {});
+
+// src/ast/match.ts
+var ASTMatch;
+((ASTMatch2) => {
+  ASTMatch2.isString = (node) => node?.kind === "String" /* String */;
+  ASTMatch2.isNumber = (node) => node?.kind === "Number" /* Number */;
+  ASTMatch2.isBoolean = (node) => node?.kind === "Boolean" /* Boolean */;
+  ASTMatch2.isInteger = (node) => node?.kind === "Integer" /* Integer */;
+  ASTMatch2.isObject = (node) => node?.kind === "Object" /* Object */;
+  ASTMatch2.isArray = (node) => node?.kind === "Array" /* Array */;
+  ASTMatch2.isMap = (node) => node?.kind === "Map" /* Map */;
+  ASTMatch2.isCustomType = (node) => node?.kind === "CustomType" /* CustomType */;
+  ASTMatch2.isVariableDeclaration = (node) => node?.kind === "VariableDeclaration" /* VariableDeclaration */;
+  ASTMatch2.isProperty = (node) => node?.kind === "Property" /* Property */;
+  ASTMatch2.isBaseVariableField = (node) => !!(node?.flags || 0 & 1 /* VariableField */);
+  ASTMatch2.isVariableDeclarationList = (node) => node?.kind === "VariableDeclarationList" /* VariableDeclarationList */;
+  ASTMatch2.isEnumerateExpression = (node) => node?.kind === "EnumerateExpression" /* EnumerateExpression */;
+  ASTMatch2.isWrapArrayExpression = (node) => node?.kind === "WrapArrayExpression" /* WrapArrayExpression */;
+  ASTMatch2.isKeyPathExpression = (node) => node?.kind === "KeyPathExpression" /* KeyPathExpression */;
+  function is(node, targetType) {
+    return node?.kind === targetType?.kind;
+  }
+  ASTMatch2.is = is;
+})(ASTMatch || (ASTMatch = {}));
+
 // src/ast/utils/helpers.ts
 function updateChildNodeHelper({
   getChildNode,
@@ -183,22 +381,9 @@ function getAllChildren(ast) {
   return [...ast.children, ...ast.children.map((_child) => getAllChildren(_child)).flat()];
 }
 function isMatchAST(node, targetType) {
-  return node?.kind === targetType?.kind;
+  return ASTMatch.is(node, targetType);
 }
 
-// src/ast/flags.ts
-var ASTNodeFlags = /* @__PURE__ */ ((ASTNodeFlags2) => {
-  ASTNodeFlags2[ASTNodeFlags2["None"] = 0] = "None";
-  ASTNodeFlags2[ASTNodeFlags2["VariableField"] = 1] = "VariableField";
-  ASTNodeFlags2[ASTNodeFlags2["Expression"] = 4] = "Expression";
-  ASTNodeFlags2[ASTNodeFlags2["BasicType"] = 8] = "BasicType";
-  ASTNodeFlags2[ASTNodeFlags2["DrilldownType"] = 16] = "DrilldownType";
-  ASTNodeFlags2[ASTNodeFlags2["EnumerateType"] = 32] = "EnumerateType";
-  ASTNodeFlags2[ASTNodeFlags2["UnionType"] = 64] = "UnionType";
-  ASTNodeFlags2[ASTNodeFlags2["VariableType"] = 120] = "VariableType";
-  return ASTNodeFlags2;
-})(ASTNodeFlags || {});
-
 // src/ast/ast-node.ts
 import {
   BehaviorSubject,
@@ -206,58 +391,62 @@ import {
   debounceTime,
   distinctUntilChanged,
   map,
-  skip,
+  skip as skip2,
   tap
 } from "rxjs";
 import { nanoid } from "nanoid";
+import { isNil, omitBy } from "lodash-es";
 import { shallowEqual } from "fast-equals";
-import { Disposable as Disposable2, DisposableCollection as DisposableCollection2 } from "@flowgram.ai/utils";
+import { Disposable as Disposable2, DisposableCollection as DisposableCollection3 } from "@flowgram.ai/utils";
 var ASTNode = class _ASTNode {
   /**
-   * 构造函数
-   * @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 }, opts) {
     /**
-     * 节点 Flags，记录一些 Flag 信息
+     * Node flags, used to record some flag information.
      */
     this.flags = 0 /* None */;
     /**
-     * 节点的版本号，每 fireChange 一次 version + 1
+     * The version number of the ASTNode, which increments by 1 each time `fireChange` is called.
      */
     this._version = 0;
     /**
-     * 更新锁
+     * 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.
      */
     this.changeLocked = false;
     /**
-     * Batch Update 相关参数
+     * Parameters related to batch updates.
      */
     this._batch = {
       batching: false,
       hasChangesInBatch: false
     };
     /**
-     * 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.
      */
     this.value$ = new BehaviorSubject(this);
     /**
-     * 子节点
+     * Child ASTNodes.
      */
     this._children = /* @__PURE__ */ new Set();
     /**
-     * 删除节点处理事件列表
+     * List of disposal handlers for the ASTNode.
      */
-    this.toDispose = new DisposableCollection2(
+    this.toDispose = new DisposableCollection3(
       Disposable2.create(() => {
         this.parent?.fireChange();
         this.children.forEach((child) => child.dispose());
       })
     );
     /**
-     * 销毁时触发的回调
+     * Callback triggered upon disposal.
      */
     this.onDispose = this.toDispose.onDispose;
     this.scope = scope;
@@ -265,10 +454,19 @@ var ASTNode = class _ASTNode {
     this.opts = opts;
     this.key = key || nanoid();
     this.fromJSON = this.withBatchUpdate(this.fromJSON.bind(this));
-    this.dispatchGlobalEvent({ type: "NewAST" });
+    const rawToJSON = this.toJSON?.bind(this);
+    this.toJSON = () => omitBy(
+      {
+        // always include kind
+        kind: this.kind,
+        ...rawToJSON?.() || {}
+      },
+      // remove undefined fields
+      isNil
+    );
   }
   /**
-   * AST 节点的类型
+   * The type of the ASTNode.
    */
   get kind() {
     if (!this.constructor.kind) {
@@ -277,24 +475,14 @@ var ASTNode = class _ASTNode {
     return this.constructor.kind;
   }
   /**
-   * 获取当前节点所有子节点
+   * Gets all child ASTNodes of the current ASTNode.
    */
   get children() {
     return Array.from(this._children);
   }
   /**
-   * 转化为 ASTNodeJSON
-   * @returns
-   */
-  toJSON() {
-    console.warn("[VariableEngine] Please Implement toJSON method for " + this.kind);
-    return {
-      kind: this.kind
-    };
-  }
-  /**
-   * 创建子节点
-   * @param json 子节点的 AST JSON
+   * Creates a child ASTNode.
+   * @param json The AST JSON of the child ASTNode.
    * @returns
    */
   createChildNode(json) {
@@ -312,8 +500,8 @@ var ASTNode = class _ASTNode {
     return child;
   }
   /**
-   * 更新子节点，快速实现子节点更新消费逻辑
-   * @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.
    */
   updateChildNodeByKey(keyInThis, nextJSON) {
     this.withBatchUpdate(updateChildNodeHelper).call(this, {
@@ -324,8 +512,8 @@ var ASTNode = class _ASTNode {
     });
   }
   /**
-   * 批处理更新，批处理函数内所有的 fireChange 都合并成一个
-   * @param updater 批处理函数
+   * Batch updates the ASTNode, merging all `fireChange` calls within the batch function into one.
+   * @param updater The batch function.
    * @returns
    */
   withBatchUpdate(updater) {
@@ -345,7 +533,7 @@ var ASTNode = class _ASTNode {
     };
   }
   /**
-   * 触发当前节点更新
+   * Triggers an update for the current node.
    */
   fireChange() {
     if (this.changeLocked || this.disposed) {
@@ -361,22 +549,24 @@ var ASTNode = class _ASTNode {
     this.parent?.fireChange();
   }
   /**
-   * 节点的版本值
-   * - 通过 NodeA === NodeB && versionA === versionB 可以比较两者是否相等
+   * The version value of the ASTNode.
+   * - You can used to check whether ASTNode are updated.
    */
   get version() {
     return this._version;
   }
   /**
-   * 节点唯一 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() {
     return `${this._version}${this.kind}${this.key}`;
   }
   /**
-   * 监听 AST 节点的变化
-   * @param observer 监听回调
-   * @param selector 监听指定数据
+   * Listens for changes to the ASTNode.
+   * @param observer The listener callback.
+   * @param selector Listens for specified data.
    * @returns
    */
   subscribe(observer, { selector, debounceAnimation, triggerOnInit } = {}) {
@@ -392,13 +582,17 @@ var ASTNode = class _ASTNode {
             return value;
           }
         ),
-        // 默认跳过 BehaviorSubject 第一次触发
-        triggerOnInit ? tap(() => null) : skip(1),
-        // 每个 animationFrame 内所有更新合并成一个
+        // By default, skip the first trigger of BehaviorSubject.
+        triggerOnInit ? tap(() => null) : skip2(1),
+        // All updates within each animationFrame are merged into one.
         debounceAnimation ? debounceTime(0, animationFrameScheduler) : tap(() => null)
       ).subscribe(observer)
     );
   }
+  /**
+   * Dispatches a global event for the current ASTNode.
+   * @param event The global event.
+   */
   dispatchGlobalEvent(event) {
     this.scope.event.dispatch({
       ...event,
@@ -406,7 +600,7 @@ var ASTNode = class _ASTNode {
     });
   }
   /**
-   * 销毁
+   * Disposes the ASTNode.
    */
   dispose() {
     if (this.toDispose.disposed) {
@@ -429,8 +623,9 @@ var BaseType = class extends ASTNode {
     this.flags = 8 /* BasicType */;
   }
   /**
-   * 类型是否一致，节点有额外信息判断，请参考 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) {
     const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
@@ -442,17 +637,15 @@ var BaseType = class extends ASTNode {
     return this.kind === targetTypeJSON?.kind;
   }
   /**
-   * 可下钻类型需实现
-   * @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 = []) {
     throw new Error(`Get By Key Path is not implemented for Type: ${this.kind}`);
   }
-  toJSON() {
-    return {
-      kind: this.kind
-    };
-  }
 };
 
 // src/ast/type/array.ts
@@ -461,13 +654,24 @@ var ArrayType = class extends BaseType {
     super(...arguments);
     this.flags = 16 /* DrilldownType */ | 32 /* EnumerateType */;
   }
+  /**
+   * Deserializes the `ArrayJSON` to the `ArrayType`.
+   * @param json The `ArrayJSON` to deserialize.
+   */
   fromJSON({ items }) {
     this.updateChildNodeByKey("items", parseTypeJsonOrKind(items));
   }
-  // items 类型是否可下钻
+  /**
+   * Whether the items type can be drilled down.
+   */
   get canDrilldownItems() {
     return !!(this.items?.flags & 16 /* DrilldownType */);
   }
+  /**
+   * 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) {
     const [curr, ...rest] = keyPath || [];
     if (curr === "0" && this.canDrilldownItems) {
@@ -475,19 +679,24 @@ var ArrayType = class extends BaseType {
     }
     return void 0;
   }
+  /**
+   * 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) {
     const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
     const isSuperEqual = super.isTypeEqual(targetTypeJSONOrKind);
     if (targetTypeJSON?.weak || targetTypeJSON?.kind === "Union" /* Union */) {
       return isSuperEqual;
     }
-    return targetTypeJSON && isSuperEqual && // 弱比较，只需要比较 Kind 即可
+    return targetTypeJSON && isSuperEqual && // Weak comparison, only need to compare the Kind.
     (targetTypeJSON?.weak || this.customStrongEqual(targetTypeJSON));
   }
   /**
-   * Array 强比较
-   * @param targetTypeJSON
-   * @returns
+   * Array strong comparison.
+   * @param targetTypeJSON The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
    */
   customStrongEqual(targetTypeJSON) {
     if (!this.items) {
@@ -495,6 +704,10 @@ var ArrayType = class extends BaseType {
     }
     return this.items?.isTypeEqual(targetTypeJSON.items);
   }
+  /**
+   * Serialize the `ArrayType` to `ArrayJSON`
+   * @returns The JSON representation of `ArrayType`.
+   */
   toJSON() {
     return {
       kind: "Array" /* Array */,
@@ -510,7 +723,31 @@ var StringType = class extends BaseType {
     super(...arguments);
     this.flags = 8 /* BasicType */;
   }
-  fromJSON() {
+  /**
+   * see https://json-schema.org/understanding-json-schema/reference/string#format
+   */
+  get format() {
+    return this._format;
+  }
+  /**
+   * Deserialize the `StringJSON` to the `StringType`.
+   *
+   * @param json StringJSON representation of the `StringType`.
+   */
+  fromJSON(json) {
+    if (json?.format !== this._format) {
+      this._format = json?.format;
+      this.fireChange();
+    }
+  }
+  /**
+   * Serialize the `StringType` to `StringJSON`.
+   * @returns The JSON representation of `StringType`.
+   */
+  toJSON() {
+    return {
+      format: this._format
+    };
   }
 };
 StringType.kind = "String" /* String */;
@@ -521,61 +758,84 @@ var IntegerType = class extends BaseType {
     super(...arguments);
     this.flags = 8 /* BasicType */;
   }
+  /**
+   * Deserializes the `IntegerJSON` to the `IntegerType`.
+   * @param json The `IntegerJSON` to deserialize.
+   */
   fromJSON() {
   }
+  toJSON() {
+    return {};
+  }
 };
 IntegerType.kind = "Integer" /* Integer */;
 
 // src/ast/type/boolean.ts
 var BooleanType = class extends BaseType {
+  /**
+   * Deserializes the `BooleanJSON` to the `BooleanType`.
+   * @param json The `BooleanJSON` to deserialize.
+   */
   fromJSON() {
   }
+  toJSON() {
+    return {};
+  }
 };
 BooleanType.kind = "Boolean" /* Boolean */;
 
 // src/ast/type/number.ts
 var NumberType = class extends BaseType {
+  /**
+   * Deserializes the `NumberJSON` to the `NumberType`.
+   * @param json The `NumberJSON` to deserialize.
+   */
   fromJSON() {
   }
+  toJSON() {
+    return {};
+  }
 };
 NumberType.kind = "Number" /* Number */;
 
 // src/ast/type/map.ts
 var MapType = class extends BaseType {
+  /**
+   * Deserializes the `MapJSON` to the `MapType`.
+   * @param json The `MapJSON` to deserialize.
+   */
   fromJSON({ keyType = "String" /* String */, valueType }) {
     this.updateChildNodeByKey("keyType", parseTypeJsonOrKind(keyType));
     this.updateChildNodeByKey("valueType", parseTypeJsonOrKind(valueType));
   }
-  // Value 类型是否可下钻，后续实现
-  // get canDrilldownValue(): boolean {
-  //   return !!(this.valueType.flags & ASTNodeFlags.DrilldownType);
-  // }
-  // getByKeyPath(keyPath: string[]): BaseVariableField | undefined {
-  //   const [curr, ...rest] = keyPath || [];
-  //   if (curr === '*' && this.canDrilldownValue) {
-  //     return this.valueType.getByKeyPath(rest);
-  //   }
-  //   return 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) {
     const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
     const isSuperEqual = super.isTypeEqual(targetTypeJSONOrKind);
     if (targetTypeJSON?.weak || targetTypeJSON?.kind === "Union" /* Union */) {
       return isSuperEqual;
     }
-    return targetTypeJSON && isSuperEqual && // 弱比较，只需要比较 Kind 即可
+    return targetTypeJSON && isSuperEqual && // Weak comparison, only need to compare the Kind.
     (targetTypeJSON?.weak || this.customStrongEqual(targetTypeJSON));
   }
   /**
-   * Map 强比较
-   * @param targetTypeJSON
-   * @returns
+   * Map strong comparison.
+   * @param targetTypeJSON The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
    */
   customStrongEqual(targetTypeJSON) {
     const { keyType = "String" /* String */, valueType } = targetTypeJSON;
     const isValueTypeEqual = !valueType && !this.valueType || this.valueType?.isTypeEqual(valueType);
     return isValueTypeEqual && this.keyType?.isTypeEqual(keyType);
   }
+  /**
+   * Serialize the node to a JSON object.
+   * @returns The JSON representation of the node.
+   */
   toJSON() {
     return {
       kind: "Map" /* Map */,
@@ -584,17 +844,23 @@ var MapType = class extends BaseType {
     };
   }
 };
-// public flags: ASTNodeFlags = ASTNodeFlags.DrilldownType | ASTNodeFlags.EnumerateType;
 MapType.kind = "Map" /* Map */;
 
 // src/ast/type/object.ts
-import { xor } from "lodash";
+import { xor } from "lodash-es";
 var ObjectType = class extends BaseType {
   constructor() {
     super(...arguments);
     this.flags = 16 /* DrilldownType */;
+    /**
+     * A map of property keys to `Property` instances.
+     */
     this.propertyTable = /* @__PURE__ */ new Map();
   }
+  /**
+   * Deserializes the `ObjectJSON` to the `ObjectType`.
+   * @param json The `ObjectJSON` to deserialize.
+   */
   fromJSON({ properties }) {
     const removedKeys = new Set(this.propertyTable.keys());
     const prev = [...this.properties || []];
@@ -628,16 +894,19 @@ var ObjectType = class extends BaseType {
       }
     });
   }
+  /**
+   * Serialize the `ObjectType` to `ObjectJSON`.
+   * @returns The JSON representation of `ObjectType`.
+   */
   toJSON() {
     return {
-      kind: "Object" /* Object */,
       properties: this.properties.map((_property) => _property.toJSON())
     };
   }
   /**
-   * 根据 KeyPath 找到对应的变量
-   * @param keyPath 变量路径
-   * @returns
+   * 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) {
     const [curr, ...restKeyPath] = keyPath;
@@ -650,19 +919,24 @@ var ObjectType = class extends BaseType {
     }
     return void 0;
   }
+  /**
+   * 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) {
     const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
     const isSuperEqual = super.isTypeEqual(targetTypeJSONOrKind);
     if (targetTypeJSON?.weak || targetTypeJSON?.kind === "Union" /* Union */) {
       return isSuperEqual;
     }
-    return targetTypeJSON && isSuperEqual && // 弱比较，只需要比较 Kind 即可
+    return targetTypeJSON && isSuperEqual && // Weak comparison, only need to compare the Kind.
     (targetTypeJSON?.weak || this.customStrongEqual(targetTypeJSON));
   }
   /**
-   * Object 类型强比较
-   * @param targetTypeJSON
-   * @returns
+   * Object type strong comparison.
+   * @param targetTypeJSON The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
    */
   customStrongEqual(targetTypeJSON) {
     const targetProperties = targetTypeJSON.properties || [];
@@ -679,15 +953,27 @@ ObjectType.kind = "Object" /* Object */;
 
 // src/ast/type/custom-type.ts
 var CustomType = class extends BaseType {
+  /**
+   * The name of the custom type.
+   */
   get typeName() {
     return this._typeName;
   }
+  /**
+   * Deserializes the `CustomTypeJSON` to the `CustomType`.
+   * @param json The `CustomTypeJSON` to deserialize.
+   */
   fromJSON(json) {
     if (this._typeName !== json.typeName) {
       this._typeName = json.typeName;
       this.fireChange();
     }
   }
+  /**
+   * 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) {
     const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
     if (targetTypeJSON?.kind === "Union" /* Union */) {
@@ -697,6 +983,11 @@ var CustomType = class extends BaseType {
     }
     return targetTypeJSON?.kind === this.kind && targetTypeJSON?.typeName === this.typeName;
   }
+  toJSON() {
+    return {
+      typeName: this.typeName
+    };
+  }
 };
 CustomType.kind = "CustomType" /* CustomType */;
 
@@ -704,11 +995,11 @@ CustomType.kind = "CustomType" /* CustomType */;
 import {
   distinctUntilChanged as distinctUntilChanged2,
   map as map2,
-  switchMap,
+  switchMap as switchMap2,
   combineLatest,
   of,
-  Subject,
-  share
+  Subject as Subject2,
+  share as share2
 } from "rxjs";
 import { shallowEqual as shallowEqual2 } from "fast-equals";
 
@@ -731,25 +1022,24 @@ var BaseExpression = class extends ASTNode {
     super(params, opts);
     this.flags = 4 /* Expression */;
     /**
-     * 引用变量
+     * The variable fields referenced by the expression.
      */
     this._refs = [];
-    this.refreshRefs$ = new Subject();
+    this.refreshRefs$ = new Subject2();
     /**
-     * 监听引用变量变化
-     * 监听 [a.b.c] -> [a.b]
+     * An observable that emits the referenced variable fields when they change.
      */
     this.refs$ = this.refreshRefs$.pipe(
       map2(() => this.getRefFields()),
       distinctUntilChanged2(shallowEqual2),
-      switchMap(
+      switchMap2(
         (refs) => !refs?.length ? of([]) : combineLatest(
           refs.map(
             (ref) => ref ? ref.value$ : of(void 0)
           )
         )
       ),
-      share()
+      share2()
     );
     this.toDispose.push(
       subsToDisposable(
@@ -761,114 +1051,42 @@ var BaseExpression = class extends ASTNode {
     );
   }
   /**
-   * 获取全局变量表，方便表达式获取引用变量
+   * Get the global variable table, which is used to access referenced variables.
    */
   get globalVariableTable() {
     return this.scope.variableEngine.globalVariableTable;
   }
   /**
-   * 父变量字段，通过由近而远的方式进行排序
+   * Parent variable fields, sorted from closest to farthest.
    */
   get parentFields() {
     return getParentFields(this);
   }
+  /**
+   * The variable fields referenced by the expression.
+   */
   get refs() {
     return this._refs;
   }
   /**
-   * 刷新变量引用
+   * Refresh the variable references.
    */
   refreshRefs() {
     this.refreshRefs$.next();
   }
 };
 
-// src/ast/expression/expression-list.ts
-var ExpressionList = class extends ASTNode {
-  fromJSON({ expressions }) {
-    this.expressions = expressions.map((_expression, idx) => {
-      const prevExpression = this.expressions[idx];
-      if (prevExpression.kind !== _expression.kind) {
-        prevExpression.dispose();
-        this.fireChange();
-        return this.createChildNode(_expression);
-      }
-      prevExpression.fromJSON(_expression);
-      return prevExpression;
-    });
-  }
-  toJSON() {
-    return {
-      kind: "ExpressionList" /* ExpressionList */,
-      properties: this.expressions.map((_expression) => _expression.toJSON())
-    };
-  }
-};
-ExpressionList.kind = "ExpressionList" /* ExpressionList */;
-
-// src/ast/expression/keypath-expression.ts
-import { shallowEqual as shallowEqual3 } from "fast-equals";
-var KeyPathExpression = class extends BaseExpression {
-  constructor(params, opts) {
-    super(params, opts);
-    this._keyPath = [];
-    this.toDispose.pushAll([
-      // 可以用变量列表变化时候 (有新增或者删除时)
-      this.scope.available.onVariableListChange(() => {
-        this.refreshRefs();
-      }),
-      // this._keyPath 指向的可引用变量发生变化时，刷新引用数据
-      this.scope.available.onAnyVariableChange((_v) => {
-        if (_v.key === this._keyPath[0]) {
-          this.refreshRefs();
-        }
-      })
-    ]);
-  }
-  get keyPath() {
-    return this._keyPath;
-  }
-  getRefFields() {
-    const ref = this.scope.available.getByKeyPath(this._keyPath);
-    return ref ? [ref] : [];
-  }
-  get returnType() {
-    const [refNode] = this._refs || [];
-    if (refNode && refNode.flags & 1 /* VariableField */) {
-      return refNode.type;
-    }
-    return;
-  }
-  /**
-   * 业务重改该方法可快速定制自己的 Path 表达式
-   * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-   * @param json 业务定义的 Path 表达式
-   * @returns
-   */
-  parseToKeyPath(json) {
-    return json.keyPath;
-  }
-  fromJSON(json) {
-    const keyPath = this.parseToKeyPath(json);
-    if (!shallowEqual3(keyPath, this._keyPath)) {
-      this._keyPath = keyPath;
-      this.refreshRefs();
-    }
-  }
-  toJSON() {
-    return {
-      kind: "KeyPathExpression" /* KeyPathExpression */,
-      keyPath: this._keyPath
-    };
-  }
-};
-KeyPathExpression.kind = "KeyPathExpression" /* KeyPathExpression */;
-
 // src/ast/expression/enumerate-expression.ts
 var EnumerateExpression = class extends BaseExpression {
+  /**
+   * The expression to be enumerated.
+   */
   get enumerateFor() {
     return this._enumerateFor;
   }
+  /**
+   * The return type of the expression.
+   */
   get returnType() {
     const childReturnType = this.enumerateFor?.returnType;
     if (childReturnType?.kind === "Array" /* Array */) {
@@ -876,12 +1094,24 @@ var EnumerateExpression = class extends BaseExpression {
     }
     return void 0;
   }
+  /**
+   * Get the variable fields referenced by the expression.
+   * @returns An empty array, as this expression does not reference any variables.
+   */
   getRefFields() {
     return [];
   }
+  /**
+   * Deserializes the `EnumerateExpressionJSON` to the `EnumerateExpression`.
+   * @param json The `EnumerateExpressionJSON` to deserialize.
+   */
   fromJSON({ enumerateFor: expression }) {
     this.updateChildNodeByKey("_enumerateFor", expression);
   }
+  /**
+   * Serialize the `EnumerateExpression` to `EnumerateExpressionJSON`.
+   * @returns The JSON representation of `EnumerateExpression`.
+   */
   toJSON() {
     return {
       kind: "EnumerateExpression" /* EnumerateExpression */,
@@ -891,11 +1121,12 @@ var EnumerateExpression = class extends BaseExpression {
 };
 EnumerateExpression.kind = "EnumerateExpression" /* EnumerateExpression */;
 
-// src/ast/expression/keypath-expression-v2.ts
-import { shallowEqual as shallowEqual4 } from "fast-equals";
+// src/ast/expression/keypath-expression.ts
+import { distinctUntilChanged as distinctUntilChanged3 } from "rxjs";
+import { shallowEqual as shallowEqual3 } from "fast-equals";
 
 // src/ast/utils/expression.ts
-import { intersection } from "lodash";
+import { intersection } from "lodash-es";
 function getAllRefs(ast) {
   return getAllChildren(ast).filter((_child) => _child.flags & 4 /* Expression */).map((_child) => _child.refs).flat().filter(Boolean);
 }
@@ -915,36 +1146,45 @@ function checkRefCycle(curr, refNodes) {
   return intersection(Array.from(visited), getParentFields(curr)).length > 0;
 }
 
-// src/ast/expression/keypath-expression-v2.ts
-var KeyPathExpressionV2 = class extends BaseExpression {
+// src/ast/expression/keypath-expression.ts
+var KeyPathExpression = class extends BaseExpression {
   constructor(params, opts) {
     super(params, opts);
     this._keyPath = [];
     this.toDispose.pushAll([
-      // 可以用变量列表变化时候 (有新增或者删除时)
+      // Can be used when the variable list changes (when there are additions or deletions).
       this.scope.available.onVariableListChange(() => {
         this.refreshRefs();
       }),
-      // this._keyPath 指向的可引用变量发生变化时，刷新引用数据
+      // When the referable variable pointed to by this._keyPath changes, refresh the reference data.
       this.scope.available.onAnyVariableChange((_v) => {
         if (_v.key === this._keyPath[0]) {
           this.refreshRefs();
         }
       }),
       subsToDisposable(
-        this.refs$.subscribe((_type) => {
+        this.refs$.pipe(
+          distinctUntilChanged3(
+            (prev, next) => prev === next,
+            (_refs) => _refs?.[0]?.type?.hash
+          )
+        ).subscribe((_type) => {
           const [ref] = this._refs;
-          if (this.prevRefTypeHash !== ref?.type?.hash) {
-            this.prevRefTypeHash = ref?.type?.hash;
-            this.updateChildNodeByKey("_returnType", this.getReturnTypeJSONByRef(ref));
-          }
+          this.updateChildNodeByKey("_returnType", this.getReturnTypeJSONByRef(ref));
         })
       )
     ]);
   }
+  /**
+   * The key path of the variable.
+   */
   get keyPath() {
     return this._keyPath;
   }
+  /**
+   * Get the variable fields referenced by the expression.
+   * @returns An array of referenced variable fields.
+   */
   getRefFields() {
     const ref = this.scope.available.getByKeyPath(this._keyPath);
     if (checkRefCycle(this, [ref])) {
@@ -956,39 +1196,189 @@ var KeyPathExpressionV2 = class extends BaseExpression {
     }
     return ref ? [ref] : [];
   }
+  /**
+   * The return type of the expression.
+   */
   get returnType() {
     return this._returnType;
   }
   /**
-   * 业务重改该方法可快速定制自己的 Path 表达式
-   * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-   * @param json 业务定义的 Path 表达式
-   * @returns
+   * 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.
    */
   parseToKeyPath(json) {
     return json.keyPath;
   }
+  /**
+   * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+   * @param json The `KeyPathExpressionJSON` to deserialize.
+   */
   fromJSON(json) {
     const keyPath = this.parseToKeyPath(json);
-    if (!shallowEqual4(keyPath, this._keyPath)) {
+    if (!shallowEqual3(keyPath, this._keyPath)) {
       this._keyPath = keyPath;
+      this._rawPathJson = json;
       this.refreshRefs();
     }
   }
+  /**
+   * Get the return type JSON by reference.
+   * @param _ref The referenced variable field.
+   * @returns The JSON representation of the return type.
+   */
   getReturnTypeJSONByRef(_ref) {
     return _ref?.type?.toJSON();
   }
+  /**
+   * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+   * @returns The JSON representation of `KeyPathExpression`.
+   */
+  toJSON() {
+    return this._rawPathJson;
+  }
+};
+KeyPathExpression.kind = "KeyPathExpression" /* KeyPathExpression */;
+
+// src/ast/expression/legacy-keypath-expression.ts
+import { shallowEqual as shallowEqual4 } from "fast-equals";
+var LegacyKeyPathExpression = class extends BaseExpression {
+  constructor(params, opts) {
+    super(params, opts);
+    this._keyPath = [];
+    this.toDispose.pushAll([
+      // Can be used when the variable list changes (when there are additions or deletions).
+      this.scope.available.onVariableListChange(() => {
+        this.refreshRefs();
+      }),
+      // When the referable variable pointed to by this._keyPath changes, refresh the reference data.
+      this.scope.available.onAnyVariableChange((_v) => {
+        if (_v.key === this._keyPath[0]) {
+          this.refreshRefs();
+        }
+      })
+    ]);
+  }
+  /**
+   * The key path of the variable.
+   */
+  get keyPath() {
+    return this._keyPath;
+  }
+  /**
+   * Get the variable fields referenced by the expression.
+   * @returns An array of referenced variable fields.
+   */
+  getRefFields() {
+    const ref = this.scope.available.getByKeyPath(this._keyPath);
+    return ref ? [ref] : [];
+  }
+  /**
+   * The return type of the expression.
+   */
+  get returnType() {
+    const [refNode] = this._refs || [];
+    if (refNode && refNode.flags & 1 /* VariableField */) {
+      return refNode.type;
+    }
+    return;
+  }
+  /**
+   * 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.
+   */
+  parseToKeyPath(json) {
+    return json.keyPath;
+  }
+  /**
+   * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+   * @param json The `KeyPathExpressionJSON` to deserialize.
+   */
+  fromJSON(json) {
+    const keyPath = this.parseToKeyPath(json);
+    if (!shallowEqual4(keyPath, this._keyPath)) {
+      this._keyPath = keyPath;
+      this._rawPathJson = json;
+      this.refreshRefs();
+    }
+  }
+  /**
+   * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+   * @returns The JSON representation of `KeyPathExpression`.
+   */
+  toJSON() {
+    return this._rawPathJson;
+  }
+};
+LegacyKeyPathExpression.kind = "KeyPathExpression" /* KeyPathExpression */;
+
+// src/ast/expression/wrap-array-expression.ts
+var WrapArrayExpression = class extends BaseExpression {
+  /**
+   * The expression to be wrapped.
+   */
+  get wrapFor() {
+    return this._wrapFor;
+  }
+  /**
+   * The return type of the expression.
+   */
+  get returnType() {
+    return this._returnType;
+  }
+  /**
+   * Refresh the return type of the expression.
+   */
+  refreshReturnType() {
+    const childReturnTypeJSON = this.wrapFor?.returnType?.toJSON();
+    this.updateChildNodeByKey("_returnType", {
+      kind: "Array" /* Array */,
+      items: childReturnTypeJSON
+    });
+  }
+  /**
+   * Get the variable fields referenced by the expression.
+   * @returns An empty array, as this expression does not reference any variables.
+   */
+  getRefFields() {
+    return [];
+  }
+  /**
+   * Deserializes the `WrapArrayExpressionJSON` to the `WrapArrayExpression`.
+   * @param json The `WrapArrayExpressionJSON` to deserialize.
+   */
+  fromJSON({ wrapFor: expression }) {
+    this.updateChildNodeByKey("_wrapFor", expression);
+  }
+  /**
+   * Serialize the `WrapArrayExpression` to `WrapArrayExpressionJSON`.
+   * @returns The JSON representation of `WrapArrayExpression`.
+   */
   toJSON() {
     return {
-      kind: "KeyPathExpression" /* KeyPathExpression */,
-      keyPath: this._keyPath
+      kind: "WrapArrayExpression" /* WrapArrayExpression */,
+      wrapFor: this.wrapFor?.toJSON()
     };
   }
+  init() {
+    this.refreshReturnType = this.refreshReturnType.bind(this);
+    this.toDispose.push(
+      this.subscribe(this.refreshReturnType, {
+        selector: (curr) => curr.wrapFor?.returnType,
+        triggerOnInit: true
+      })
+    );
+  }
 };
-KeyPathExpressionV2.kind = "KeyPathExpression" /* KeyPathExpression */;
-
-// src/ast/declaration/variable-declaration.ts
-import { Disposable as Disposable3 } from "@flowgram.ai/utils";
+WrapArrayExpression.kind = "WrapArrayExpression" /* WrapArrayExpression */;
+__decorateClass([
+  postConstructAST()
+], WrapArrayExpression.prototype, "init", 1);
 
 // src/ast/declaration/base-variable-field.ts
 import { shallowEqual as shallowEqual5 } from "fast-equals";
@@ -999,35 +1389,73 @@ var BaseVariableField = class extends ASTNode {
     this._meta = {};
   }
   /**
-   * 父变量字段，通过由近而远的方式进行排序
+   * Parent variable fields, sorted from closest to farthest
    */
   get parentFields() {
     return getParentFields(this);
   }
+  /**
+   * KeyPath of the variable field, sorted from farthest to closest
+   */
+  get keyPath() {
+    return [...this.parentFields.reverse().map((_field) => _field.key), this.key];
+  }
+  /**
+   * Metadata of the variable field, you cans store information like `title`, `icon`, etc.
+   */
   get meta() {
     return this._meta;
   }
+  /**
+   * Type of the variable field, similar to js code:
+   * `const v: string`
+   */
   get type() {
     return this._initializer?.returnType || this._type;
   }
+  /**
+   * Initializer of the variable field, similar to js code:
+   * `const v = 'hello'`
+   *
+   * with initializer, the type of field will be inferred from the initializer.
+   */
   get initializer() {
     return this._initializer;
   }
   /**
-   * 解析 VariableDeclarationJSON 从而生成变量声明节点
+   * The global unique hash of the field, and will be changed when the field is updated.
+   */
+  get hash() {
+    return `[${this._version}]${this.keyPath.join(".")}`;
+  }
+  /**
+   * Deserialize the `BaseVariableFieldJSON` to the `BaseVariableField`.
+   * @param json ASTJSON representation of `BaseVariableField`
    */
   fromJSON({ type, initializer, meta }) {
     this.updateType(type);
     this.updateInitializer(initializer);
     this.updateMeta(meta);
   }
+  /**
+   * Update the type of the variable field
+   * @param type type ASTJSON representation of Type
+   */
   updateType(type) {
     const nextTypeJson = typeof type === "string" ? { kind: type } : type;
     this.updateChildNodeByKey("_type", nextTypeJson);
   }
+  /**
+   * Update the initializer of the variable field
+   * @param nextInitializer initializer ASTJSON representation of Expression
+   */
   updateInitializer(nextInitializer) {
     this.updateChildNodeByKey("_initializer", nextInitializer);
   }
+  /**
+   * Update the meta data of the variable field
+   * @param nextMeta meta data of the variable field
+   */
   updateMeta(nextMeta) {
     if (!shallowEqual5(nextMeta, this._meta)) {
       this._meta = nextMeta;
@@ -1035,7 +1463,8 @@ var BaseVariableField = class extends ASTNode {
     }
   }
   /**
-   * 根据 keyPath 去找下钻的变量字段
+   * Get the variable field by keyPath, similar to js code:
+   * `v.a.b`
    * @param keyPath
    * @returns
    */
@@ -1046,7 +1475,7 @@ var BaseVariableField = class extends ASTNode {
     return void 0;
   }
   /**
-   * 监听类型变化
+   * Subscribe to type change of the variable field
    * @param observer
    * @returns
    */
@@ -1054,12 +1483,11 @@ var BaseVariableField = class extends ASTNode {
     return this.subscribe(observer, { selector: (curr) => curr.type });
   }
   /**
-   * 转换为 JSON
-   * @returns
+   * Serialize the variable field to JSON
+   * @returns ASTNodeJSON representation of `BaseVariableField`
    */
   toJSON() {
     return {
-      kind: this.kind,
       key: this.key,
       type: this.type?.toJSON(),
       initializer: this.initializer?.toJSON(),
@@ -1073,34 +1501,42 @@ var VariableDeclaration = class extends BaseVariableField {
   constructor(params) {
     super(params);
     this._order = 0;
-    this.scope.output.addVariableToTable(this);
-    this.toDispose.push(
-      Disposable3.create(() => {
-        this.scope.output.setHasChanges();
-        this.scope.output.removeVariableFromTable(this.key);
-      })
-    );
   }
+  /**
+   * Variable sorting order, which is used to sort variables in `scope.outputs.variables`
+   */
   get order() {
     return this._order;
   }
   /**
-   * 解析 VariableDeclarationJSON 从而生成变量声明节点
+   * Deserialize the `VariableDeclarationJSON` to the `VariableDeclaration`.
    */
   fromJSON({ order, ...rest }) {
     this.updateOrder(order);
     super.fromJSON(rest);
   }
+  /**
+   * Update the sorting order of the variable declaration.
+   * @param order Variable sorting order. Default is 0.
+   */
   updateOrder(order = 0) {
     if (order !== this._order) {
       this._order = order;
-      this.scope.output.setHasChanges();
+      this.dispatchGlobalEvent({
+        type: "ReSortVariableDeclarations"
+      });
       this.fireChange();
     }
   }
-  // 监听类型变化
-  onTypeChange(observer) {
-    return this.subscribe(observer, { selector: (curr) => curr.type });
+  /**
+   * Serialize the `VariableDeclaration` to `VariableDeclarationJSON`.
+   * @returns The JSON representation of `VariableDeclaration`.
+   */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      order: this.order
+    };
   }
 };
 VariableDeclaration.kind = "VariableDeclaration" /* VariableDeclaration */;
@@ -1109,8 +1545,18 @@ VariableDeclaration.kind = "VariableDeclaration" /* VariableDeclaration */;
 var VariableDeclarationList = class extends ASTNode {
   constructor() {
     super(...arguments);
+    /**
+     * Map of variable declarations, keyed by variable name.
+     */
     this.declarationTable = /* @__PURE__ */ new Map();
   }
+  /**
+   * 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.
+   */
   fromJSON({ declarations, startOrder }) {
     const removedKeys = new Set(this.declarationTable.keys());
     const prev = [...this.declarations || []];
@@ -1150,10 +1596,14 @@ var VariableDeclarationList = class extends ASTNode {
       }
     });
   }
+  /**
+   * Serialize the `VariableDeclarationList` to the `VariableDeclarationListJSON`.
+   * @returns ASTJSON representation of `VariableDeclarationList`
+   */
   toJSON() {
     return {
       kind: "VariableDeclarationList" /* VariableDeclarationList */,
-      properties: this.declarations.map((_declaration) => _declaration.toJSON())
+      declarations: this.declarations.map((_declaration) => _declaration.toJSON())
     };
   }
 };
@@ -1167,9 +1617,16 @@ Property.kind = "Property" /* Property */;
 // src/ast/common/data-node.ts
 import { shallowEqual as shallowEqual6 } from "fast-equals";
 var DataNode = class extends ASTNode {
+  /**
+   * The data of the node.
+   */
   get data() {
     return this._data;
   }
+  /**
+   * Deserializes the `DataNodeJSON` to the `DataNode`.
+   * @param json The `DataNodeJSON` to deserialize.
+   */
   fromJSON(json) {
     const { kind, ...restData } = json;
     if (!shallowEqual6(restData, this._data)) {
@@ -1177,12 +1634,20 @@ var DataNode = class extends ASTNode {
       this.fireChange();
     }
   }
+  /**
+   * Serialize the `DataNode` to `DataNodeJSON`.
+   * @returns The JSON representation of `DataNode`.
+   */
   toJSON() {
     return {
       kind: "DataNode" /* DataNode */,
       ...this._data
     };
   }
+  /**
+   * Partially update the data of the node.
+   * @param nextData The data to be updated.
+   */
   partialUpdate(nextData) {
     if (!shallowEqual6(nextData, this._data)) {
       this._data = {
@@ -1197,9 +1662,16 @@ DataNode.kind = "DataNode" /* DataNode */;
 
 // src/ast/common/list-node.ts
 var ListNode = class extends ASTNode {
+  /**
+   * The list of nodes.
+   */
   get list() {
     return this._list;
   }
+  /**
+   * Deserializes the `ListNodeJSON` to the `ListNode`.
+   * @param json The `ListNodeJSON` to deserialize.
+   */
   fromJSON({ list }) {
     this._list.slice(list.length).forEach((_item) => {
       _item.dispose();
@@ -1216,6 +1688,10 @@ var ListNode = class extends ASTNode {
       return prevItem;
     });
   }
+  /**
+   * Serialize the `ListNode` to `ListNodeJSON`.
+   * @returns The JSON representation of `ListNode`.
+   */
   toJSON() {
     return {
       kind: "ListNode" /* ListNode */,
@@ -1231,6 +1707,10 @@ var MapNode = class extends ASTNode {
     super(...arguments);
     this.map = /* @__PURE__ */ new Map();
   }
+  /**
+   * Deserializes the `MapNodeJSON` to the `MapNode`.
+   * @param json The `MapNodeJSON` to deserialize.
+   */
   fromJSON({ map: map4 }) {
     const removedKeys = new Set(this.map.keys());
     for (const [key, item] of map4 || []) {
@@ -1241,6 +1721,10 @@ var MapNode = class extends ASTNode {
       this.remove(removeKey);
     }
   }
+  /**
+   * Serialize the `MapNode` to `MapNodeJSON`.
+   * @returns The JSON representation of `MapNode`.
+   */
   toJSON() {
     return {
       kind: "MapNode" /* MapNode */,
@@ -1248,9 +1732,10 @@ var MapNode = class extends ASTNode {
     };
   }
   /**
-   * 往 Map 中设置 ASTNode
-   * @param key ASTNode 的索引，
-   * @param json
+   * 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(key, nextJSON) {
     return this.withBatchUpdate(updateChildNodeHelper).call(this, {
@@ -1261,8 +1746,8 @@ var MapNode = class extends ASTNode {
     });
   }
   /**
-   * 移除指定 ASTNode
-   * @param key
+   * Remove a node from the map.
+   * @param key The key of the node.
    */
   remove(key) {
     this.get(key)?.dispose();
@@ -1270,9 +1755,9 @@ var MapNode = class extends ASTNode {
     this.fireChange();
   }
   /**
-   * 获取 ASTNode
-   * @param key
-   * @returns
+   * Get a node from the map.
+   * @param key The key of the node.
+   * @returns The node instance if found, otherwise `undefined`.
    */
   get(key) {
     return this.map.get(key);
@@ -1283,9 +1768,12 @@ MapNode.kind = "MapNode" /* MapNode */;
 // src/ast/ast-registers.ts
 var ASTRegisters = class {
   /**
-   * 核心 AST 节点注册
+   * Core AST node registration.
    */
   constructor() {
+    /**
+     * @deprecated Please use `@injectToAst(XXXService) declare xxxService: XXXService` to achieve external dependency injection.
+     */
     this.injectors = /* @__PURE__ */ new Map();
     this.astMap = /* @__PURE__ */ new Map();
     this.registerAST(StringType);
@@ -1301,13 +1789,13 @@ var ASTRegisters = class {
     this.registerAST(VariableDeclarationList);
     this.registerAST(KeyPathExpression);
     this.registerAST(EnumerateExpression);
-    this.registerAST(ExpressionList);
+    this.registerAST(WrapArrayExpression);
     this.registerAST(MapNode);
     this.registerAST(DataNode);
   }
   /**
-   * 创建 AST 节点
-   * @param param 创建参数
+   * Creates an AST node.
+   * @param param Creation parameters.
    * @returns
    */
   createAST(json, { parent, scope }) {
@@ -1327,6 +1815,7 @@ var ASTRegisters = class {
     node.changeLocked = true;
     node.fromJSON(omit(json, ["key", "kind"]));
     node.changeLocked = false;
+    node.dispatchGlobalEvent({ type: "NewAST" });
     if (Reflect.hasMetadata(POST_CONSTRUCT_AST_SYMBOL, node)) {
       const postConstructKey = Reflect.getMetadata(POST_CONSTRUCT_AST_SYMBOL, node);
       node[postConstructKey]?.();
@@ -1334,7 +1823,7 @@ var ASTRegisters = class {
     return node;
   }
   /**
-   * 根据 AST 节点类型获取节点 Registry
+   * Gets the node Registry by AST node type.
    * @param kind
    * @returns
    */
@@ -1342,9 +1831,8 @@ var ASTRegisters = class {
     return this.astMap.get(kind);
   }
   /**
-   * 注册 AST 节点
+   * Registers an AST node.
    * @param ASTNode
-   * @param injector
    */
   registerAST(ASTNode2, injector) {
     this.astMap.set(ASTNode2.kind, ASTNode2);
@@ -1360,7 +1848,10 @@ ASTRegisters = __decorateClass([
 // src/ast/factory.ts
 var ASTFactory;
 ((ASTFactory2) => {
-  ASTFactory2.createString = () => ({ kind: "String" /* String */ });
+  ASTFactory2.createString = (json) => ({
+    kind: "String" /* String */,
+    ...json || {}
+  });
   ASTFactory2.createNumber = () => ({ kind: "Number" /* Number */ });
   ASTFactory2.createBoolean = () => ({ kind: "Boolean" /* Boolean */ });
   ASTFactory2.createInteger = () => ({ kind: "Integer" /* Integer */ });
@@ -1404,116 +1895,13 @@ var ASTFactory;
     kind: "KeyPathExpression" /* KeyPathExpression */,
     ...json
   });
+  ASTFactory2.createWrapArrayExpression = (json) => ({
+    kind: "WrapArrayExpression" /* WrapArrayExpression */,
+    ...json
+  });
   ASTFactory2.create = (targetType, json) => ({ kind: targetType.kind, ...json });
 })(ASTFactory || (ASTFactory = {}));
 
-// src/scope/variable-table.ts
-import { Subject as Subject2, merge, share as share2, skip as skip2, switchMap as switchMap2 } from "rxjs";
-import { Emitter } from "@flowgram.ai/utils";
-import { DisposableCollection as DisposableCollection3 } from "@flowgram.ai/utils";
-var VariableTable = class {
-  constructor(parentTable) {
-    this.parentTable = parentTable;
-    this.table = /* @__PURE__ */ new Map();
-    this.onDataChangeEmitter = new Emitter();
-    this.variables$ = new Subject2();
-    // 监听变量列表中的单个变量变化
-    this.anyVariableChange$ = this.variables$.pipe(
-      switchMap2(
-        (_variables) => merge(
-          ..._variables.map(
-            (_v) => _v.value$.pipe(
-              // 跳过 BehaviorSubject 第一个
-              skip2(1)
-            )
-          )
-        )
-      ),
-      share2()
-    );
-    this.onDataChange = this.onDataChangeEmitter.event;
-    this._version = 0;
-  }
-  /**
-   * 监听任意变量变化
-   * @param observer 监听器，变量变化时会吐出值
-   * @returns
-   */
-  onAnyVariableChange(observer) {
-    return subsToDisposable(this.anyVariableChange$.subscribe(observer));
-  }
-  /**
-   * 列表或者任意变量变化
-   * @param observer
-   */
-  onAnyChange(observer) {
-    const disposables = new DisposableCollection3();
-    disposables.pushAll([this.onDataChange(observer), this.onAnyVariableChange(observer)]);
-    return disposables;
-  }
-  fireChange() {
-    this._version++;
-    this.onDataChangeEmitter.fire();
-    this.parentTable?.fireChange();
-  }
-  get version() {
-    return this._version;
-  }
-  get variables() {
-    return Array.from(this.table.values());
-  }
-  get variableKeys() {
-    return Array.from(this.table.keys());
-  }
-  /**
-   * 根据 keyPath 找到对应的变量，或 Property 节点
-   * @param keyPath
-   * @returns
-   */
-  getByKeyPath(keyPath) {
-    const [variableKey, ...propertyKeys] = keyPath || [];
-    if (!variableKey) {
-      return;
-    }
-    const variable = this.getVariableByKey(variableKey);
-    return propertyKeys.length ? variable?.getByKeyPath(propertyKeys) : variable;
-  }
-  /**
-   * 根据 key 值找到相应的变量
-   * @param key
-   * @returns
-   */
-  getVariableByKey(key) {
-    return this.table.get(key);
-  }
-  /**
-   * 往 variableTable 添加输出变量
-   * @param variable
-   */
-  addVariableToTable(variable) {
-    this.table.set(variable.key, variable);
-    if (this.parentTable) {
-      this.parentTable.addVariableToTable(variable);
-    }
-    this.variables$.next(this.variables);
-  }
-  /**
-   * 从 variableTable 中移除变量
-   * @param key
-   */
-  removeVariableFromTable(key) {
-    this.table.delete(key);
-    if (this.parentTable) {
-      this.parentTable.removeVariableFromTable(key);
-    }
-    this.variables$.next(this.variables);
-  }
-  dispose() {
-    this.variableKeys.forEach((_key) => this.parentTable?.removeVariableFromTable(_key));
-    this.onDataChangeEmitter.dispose();
-  }
-};
-
 // src/scope/datas/scope-output-data.ts
 var ScopeOutputData = class {
   constructor(scope) {
@@ -1522,7 +1910,7 @@ var ScopeOutputData = class {
     this._hasChanges = false;
     this.variableTable = new VariableTable(scope.variableEngine.globalVariableTable);
     this.scope.toDispose.pushAll([
-      // AST 根节点更新时，检查在这次 AST 变化期间节点是否有变化
+      // When the root AST node is updated, check if there are any changes.
       this.scope.ast.subscribe(() => {
         if (this._hasChanges) {
           this.memo.clear();
@@ -1531,23 +1919,66 @@ var ScopeOutputData = class {
           this._hasChanges = false;
         }
       }),
+      this.scope.event.on("DisposeAST", (_action) => {
+        if (_action.ast?.kind === "VariableDeclaration" /* VariableDeclaration */) {
+          this.removeVariableFromTable(_action.ast.key);
+        }
+      }),
+      this.scope.event.on("NewAST", (_action) => {
+        if (_action.ast?.kind === "VariableDeclaration" /* VariableDeclaration */) {
+          this.addVariableToTable(_action.ast);
+        }
+      }),
+      this.scope.event.on("ReSortVariableDeclarations", () => {
+        this._hasChanges = true;
+      }),
       this.variableTable
     ]);
   }
+  /**
+   * The variable engine instance.
+   */
   get variableEngine() {
     return this.scope.variableEngine;
   }
+  /**
+   * The global variable table from the variable engine.
+   */
   get globalVariableTable() {
     return this.scope.variableEngine.globalVariableTable;
   }
+  /**
+   * The current version of the output data, which increments on each change.
+   */
+  get version() {
+    return this.variableTable.version;
+  }
+  /**
+   * @deprecated use onListOrAnyVarChange instead
+   */
   get onDataChange() {
     return this.variableTable.onDataChange.bind(this.variableTable);
   }
+  /**
+   * An event that fires when the list of output variables changes.
+   */
+  get onVariableListChange() {
+    return this.variableTable.onVariableListChange.bind(this.variableTable);
+  }
+  /**
+   * An event that fires when any output variable's value changes.
+   */
   get onAnyVariableChange() {
     return this.variableTable.onAnyVariableChange.bind(this.variableTable);
   }
   /**
-   * 作用域输出变量
+   * An event that fires when the output variable list changes or any variable's value is updated.
+   */
+  get onListOrAnyVarChange() {
+    return this.variableTable.onListOrAnyVarChange.bind(this.variableTable);
+  }
+  /**
+   * The output variable declarations of the scope, sorted by order.
    */
   get variables() {
     return this.memo(
@@ -1556,7 +1987,7 @@ var ScopeOutputData = class {
     );
   }
   /**
-   * 输出的变量 keys
+   * The keys of the output variables.
    */
   get variableKeys() {
     return this.memo("variableKeys", () => this.variableTable.variableKeys);
@@ -1568,18 +1999,21 @@ var ScopeOutputData = class {
     this.variableTable.addVariableToTable(variable);
     this._hasChanges = true;
   }
-  // 标记为发生了变化，用于变量排序变化的场景
-  setHasChanges() {
-    this._hasChanges = true;
-  }
   removeVariableFromTable(key) {
     this.variableTable.removeVariableFromTable(key);
     this._hasChanges = true;
   }
+  /**
+   * Retrieves a variable declaration by its key.
+   * @param key The key of the variable.
+   * @returns The `VariableDeclaration` or `undefined` if not found.
+   */
   getVariableByKey(key) {
     return this.variableTable.getVariableByKey(key);
   }
-  // 通知覆盖作用域更新可用变量
+  /**
+   * Notifies the covering scopes that the available variables have changed.
+   */
   notifyCoversChange() {
     this.scope.coverScopes.forEach((scope) => scope.available.refresh());
   }
@@ -1588,40 +2022,47 @@ var ScopeOutputData = class {
 // src/scope/datas/scope-available-data.ts
 import {
   Subject as Subject3,
-  distinctUntilChanged as distinctUntilChanged3,
+  animationFrameScheduler as animationFrameScheduler2,
+  debounceTime as debounceTime2,
+  distinctUntilChanged as distinctUntilChanged4,
   map as map3,
   merge as merge2,
   share as share3,
   skip as skip3,
-  switchMap as switchMap3
+  startWith,
+  switchMap as switchMap3,
+  tap as tap2
 } from "rxjs";
-import { flatten } from "lodash";
+import { flatten } from "lodash-es";
 import { shallowEqual as shallowEqual7 } from "fast-equals";
-import { Disposable as Disposable5 } from "@flowgram.ai/utils";
+import { Disposable as Disposable3 } from "@flowgram.ai/utils";
 import { Emitter as Emitter2 } from "@flowgram.ai/utils";
 var ScopeAvailableData = class {
   constructor(scope) {
     this.scope = scope;
     this.memo = createMemo();
+    this._version = 0;
     this.refresh$ = new Subject3();
     this._variables = [];
     /**
-     * 监听
+     * An observable that emits when the list of available variables changes.
      */
     this.variables$ = this.refresh$.pipe(
-      // 输出变量是否 version 发生变化
+      // Map to the flattened list of variables from all dependency scopes.
       map3(() => flatten(this.depScopes.map((scope) => scope.output.variables || []))),
-      // 变量列表浅比较
-      distinctUntilChanged3(shallowEqual7),
+      // Use shallow equality to check if the variable list has changed.
+      distinctUntilChanged4(shallowEqual7),
       share3()
     );
-    // 监听变量列表中的单个变量变化
+    /**
+     * An observable that emits when any variable in the available list changes its value.
+     */
     this.anyVariableChange$ = this.variables$.pipe(
       switchMap3(
         (_variables) => merge2(
           ..._variables.map(
             (_v) => _v.value$.pipe(
-              // 跳过 BehaviorSubject 第一个
+              // Skip the initial value of the BehaviorSubject.
               skip3(1)
             )
           )
@@ -1629,30 +2070,60 @@ var ScopeAvailableData = class {
       ),
       share3()
     );
+    /**
+     * @deprecated
+     */
     this.onDataChangeEmitter = new Emitter2();
+    this.onListOrAnyVarChangeEmitter = new Emitter2();
     /**
-     * 监听变量列表变化 + 任意子变量变化
+     * @deprecated use available.onListOrAnyVarChange instead
      */
     this.onDataChange = this.onDataChangeEmitter.event;
+    /**
+     * An event that fires when the variable list changes or any variable's value is updated.
+     */
+    this.onListOrAnyVarChange = this.onListOrAnyVarChangeEmitter.event;
     this.scope.toDispose.pushAll([
       this.onVariableListChange((_variables) => {
         this._variables = _variables;
         this.memo.clear();
         this.onDataChangeEmitter.fire(this._variables);
+        this.bumpVersion();
+        this.onListOrAnyVarChangeEmitter.fire(this._variables);
       }),
       this.onAnyVariableChange(() => {
         this.onDataChangeEmitter.fire(this._variables);
+        this.bumpVersion();
+        this.onListOrAnyVarChangeEmitter.fire(this._variables);
       }),
-      Disposable5.create(() => {
+      Disposable3.create(() => {
         this.refresh$.complete();
         this.refresh$.unsubscribe();
       })
     ]);
   }
+  /**
+   * The global variable table from the variable engine.
+   */
   get globalVariableTable() {
     return this.scope.variableEngine.globalVariableTable;
   }
-  // 刷新可访问变量列表
+  /**
+   * The current version of the available data, which increments on each change.
+   */
+  get version() {
+    return this._version;
+  }
+  bumpVersion() {
+    this._version = this._version + 1;
+    if (this._version === Number.MAX_SAFE_INTEGER) {
+      this._version = 0;
+    }
+  }
+  /**
+   * Refreshes the list of available variables.
+   * This should be called when the dependencies of the scope change.
+   */
   refresh() {
     if (this.scope.disposed) {
       return;
@@ -1660,43 +2131,43 @@ var ScopeAvailableData = class {
     this.refresh$.next();
   }
   /**
-   * 监听任意变量变化
-   * @param observer 监听器，变量变化时会吐出值
-   * @returns
+   * 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) {
     return subsToDisposable(this.anyVariableChange$.subscribe(observer));
   }
   /**
-   * 监听变量列表变化
-   * @param observer
-   * @returns
+   * 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) {
     return subsToDisposable(this.variables$.subscribe(observer));
   }
   /**
-   * 获取可消费变量
+   * Gets the list of available variables.
    */
   get variables() {
     return this._variables;
   }
   /**
-   * 获取可访问的变量 keys
+   * Gets the keys of the available variables.
    */
   get variableKeys() {
     return this.memo("availableKeys", () => this._variables.map((_v) => _v.key));
   }
   /**
-   * 返回依赖的作用域
+   * Gets the dependency scopes.
    */
   get depScopes() {
     return this.scope.depScopes;
   }
   /**
-   * 通过 keyPath 找到可用变量
-   * @param keyPath
-   * @returns
+   * 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 = []) {
     if (!this.variableKeys.includes(keyPath[0])) {
@@ -1704,6 +2175,37 @@ var ScopeAvailableData = class {
     }
     return this.globalVariableTable.getByKeyPath(keyPath);
   }
+  /**
+   * 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(keyPath = [], cb, opts) {
+    const { triggerOnInit = true, debounceAnimation, selector } = opts || {};
+    return subsToDisposable(
+      merge2(this.anyVariableChange$, this.variables$).pipe(
+        triggerOnInit ? startWith() : tap2(() => null),
+        map3(() => {
+          const v = this.getByKeyPath(keyPath);
+          return selector ? selector(v) : v;
+        }),
+        distinctUntilChanged4(
+          (a, b) => shallowEqual7(a, b),
+          (value) => {
+            if (value instanceof ASTNode) {
+              return value.hash;
+            }
+            return value;
+          }
+        ),
+        // Debounce updates to a single emission per animation frame.
+        debounceAnimation ? debounceTime2(0, animationFrameScheduler2) : tap2(() => null)
+      ).subscribe(cb)
+    );
+  }
 };
 
 // src/scope/datas/scope-event-data.ts
@@ -1718,15 +2220,30 @@ var ScopeEventData = class {
       })
     ]);
   }
+  /**
+   * Dispatches a global event.
+   * @param action The event action to dispatch.
+   */
   dispatch(action) {
     if (this.scope.disposed) {
       return;
     }
     this.event$.next(action);
   }
+  /**
+   * 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(observer) {
     return subsToDisposable(this.event$.subscribe(observer));
   }
+  /**
+   * 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(type, observer) {
     return subsToDisposable(
       this.event$.pipe(filter((_action) => _action.type === type)).subscribe(observer)
@@ -1738,7 +2255,7 @@ var ScopeEventData = class {
 var Scope = class {
   constructor(options) {
     /**
-     * 数据缓存
+     * A memoization utility for caching computed values.
      */
     this.memo = createMemo();
     this.toDispose = new DisposableCollection4();
@@ -1750,7 +2267,7 @@ var Scope = class {
     this.ast = this.variableEngine.astRegisters.createAST(
       {
         kind: "MapNode" /* MapNode */,
-        key: this.id
+        key: String(this.id)
       },
       {
         scope: this
@@ -1759,25 +2276,41 @@ var Scope = class {
     this.output = new ScopeOutputData(this);
     this.available = new ScopeAvailableData(this);
   }
+  /**
+   * Refreshes the covering scopes.
+   */
   refreshCovers() {
     this.memo.clear("covers");
   }
+  /**
+   * Refreshes the dependency scopes and the available variables.
+   */
   refreshDeps() {
     this.memo.clear("deps");
     this.available.refresh();
   }
+  /**
+   * Gets the scopes that this scope depends on.
+   */
   get depScopes() {
     return this.memo(
       "deps",
       () => this.variableEngine.chain.getDeps(this).filter((_scope) => Boolean(_scope) && !_scope?.disposed)
     );
   }
+  /**
+   * Gets the scopes that are covered by this scope.
+   */
   get coverScopes() {
     return this.memo(
       "covers",
       () => this.variableEngine.chain.getCovers(this).filter((_scope) => Boolean(_scope) && !_scope?.disposed)
     );
   }
+  /**
+   * Disposes of the scope and its resources.
+   * This will also trigger updates in dependent and covering scopes.
+   */
   dispose() {
     this.ast.dispose();
     this.toDispose.dispose();
@@ -1787,6 +2320,32 @@ var Scope = class {
   get disposed() {
     return this.toDispose.disposed;
   }
+  setVar(arg1, arg2) {
+    if (typeof arg1 === "string" && arg2 !== void 0) {
+      return this.ast.set(arg1, arg2);
+    }
+    if (typeof arg1 === "object" && arg2 === void 0) {
+      return this.ast.set("outputs", arg1);
+    }
+    throw new Error("Invalid arguments");
+  }
+  /**
+   * 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(key = "outputs") {
+    return this.ast.get(key);
+  }
+  /**
+   * Clears a variable from the scope by its key.
+   *
+   * @param key The key of the variable to clear. Defaults to 'outputs'.
+   */
+  clearVar(key = "outputs") {
+    return this.ast.remove(key);
+  }
 };
 
 // src/variable-engine.ts
@@ -1797,44 +2356,71 @@ var VariableEngine = class {
     this.toDispose = new DisposableCollection5();
     this.memo = createMemo();
     this.scopeMap = /* @__PURE__ */ new Map();
+    /**
+     * A rxjs subject that emits global events occurring within the variable engine.
+     */
     this.globalEvent$ = new Subject5();
     this.onScopeChangeEmitter = new Emitter3();
+    /**
+     * A table containing all global variables.
+     */
     this.globalVariableTable = new VariableTable();
+    /**
+     * An event that fires whenever a scope is added, updated, or deleted.
+     */
     this.onScopeChange = this.onScopeChangeEmitter.event;
     this.toDispose.pushAll([
       chain,
-      Disposable6.create(() => {
+      Disposable4.create(() => {
         this.getAllScopes().forEach((scope) => scope.dispose());
         this.globalVariableTable.dispose();
       })
     ]);
   }
+  /**
+   * The Inversify container instance.
+   */
   get container() {
     return this.containerProvider();
   }
   dispose() {
     this.toDispose.dispose();
   }
-  // 根据 scopeId 找到作用域
+  /**
+   * 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) {
     return this.scopeMap.get(scopeId);
   }
-  // 移除作用域
+  /**
+   * Removes a scope by its unique identifier and disposes of it.
+   * @param scopeId The ID of the scope to remove.
+   */
   removeScopeById(scopeId) {
     this.getScopeById(scopeId)?.dispose();
   }
-  // 获取 Scope，如果 Scope 存在且类型相同，则会直接使用
-  createScope(id, meta) {
+  /**
+   * 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, meta, options = {}) {
+    const { ScopeConstructor = Scope } = options;
     let scope = this.getScopeById(id);
     if (!scope) {
-      scope = new Scope({ variableEngine: this, meta, id });
+      scope = new ScopeConstructor({ variableEngine: this, meta, id });
       this.scopeMap.set(id, scope);
       this.onScopeChangeEmitter.fire({ type: "add", scope });
       scope.toDispose.pushAll([
         scope.ast.subscribe(() => {
           this.onScopeChangeEmitter.fire({ type: "update", scope });
         }),
-        // 可用变量发生变化
+        // Fires when available variables change
         scope.available.onDataChange(() => {
           this.onScopeChangeEmitter.fire({ type: "available", scope });
         })
@@ -1846,7 +2432,12 @@ var VariableEngine = class {
     }
     return 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
   } = {}) {
@@ -1859,9 +2450,19 @@ var VariableEngine = class {
     }
     return [...allScopes];
   }
+  /**
+   * Fires a global event to be broadcast to all listeners.
+   * @param event The global event to fire.
+   */
   fireGlobalEvent(event) {
     this.globalEvent$.next(event);
   }
+  /**
+   * 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(type, observer) {
     return subsToDisposable(
       this.globalEvent$.subscribe((_action) => {
@@ -1885,18 +2486,33 @@ VariableEngine = __decorateClass([
 ], VariableEngine);
 
 // src/services/variable-field-key-rename-service.ts
-import { difference } from "lodash";
+import { difference } from "lodash-es";
 import { inject as inject3, injectable as injectable4, postConstruct, preDestroy as preDestroy2 } from "inversify";
 import { DisposableCollection as DisposableCollection6, Emitter as Emitter4 } from "@flowgram.ai/utils";
 var VariableFieldKeyRenameService = class {
   constructor() {
     this.toDispose = new DisposableCollection6();
     this.renameEmitter = new Emitter4();
-    // 没有被 rename 的字段通过 disposeInList 透出，让业务区分变量是 rename 删除的，还是真正从列表中删除的
+    /**
+     * 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.
+     */
     this.disposeInListEmitter = new Emitter4();
+    /**
+     * An event that fires when a variable field key is successfully renamed.
+     */
     this.onRename = this.renameEmitter.event;
+    /**
+     * An event that fires when a field is removed from a list (and not part of a rename).
+     */
     this.onDisposeInList = this.disposeInListEmitter.event;
   }
+  /**
+   * 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, prev, next) {
     if (!ast || !prev?.length || !next?.length) {
       this.notifyFieldsDispose(prev, next);
@@ -1927,6 +2543,11 @@ var VariableFieldKeyRenameService = class {
     }
     this.renameEmitter.fire(renameNodeInfo);
   }
+  /**
+   * 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, next) {
     const removedFields = difference(prev || [], next || []);
     removedFields.forEach((_field) => this.disposeInListEmitter.fire(_field));
@@ -1974,28 +2595,48 @@ var VariableContainerModule = new ContainerModule((bind) => {
 });
 
 // src/react/context.tsx
-import { createContext, useContext } from "react";
+import React, { createContext, useContext } from "react";
 var ScopeContext = createContext(null);
-var ScopeProvider = ScopeContext.Provider;
-var useScopeContext = () => useContext(ScopeContext);
-var useCurrentScope = () => useContext(ScopeContext)?.scope;
+var ScopeProvider = (props) => {
+  const { scope, value, children } = props;
+  const scopeToUse = scope || value?.scope;
+  if (!scopeToUse) {
+    throw new Error("[ScopeProvider] scope is required");
+  }
+  return /* @__PURE__ */ React.createElement(ScopeContext.Provider, { value: { scope: scopeToUse } }, children);
+};
+var useCurrentScope = (params) => {
+  const { strict = false } = params || {};
+  const context = useContext(ScopeContext);
+  if (!context) {
+    if (strict) {
+      throw new Error("useCurrentScope must be used within a <ScopeProvider scope={scope}>");
+    }
+    console.warn("useCurrentScope should be used within a <ScopeProvider scope={scope}>");
+  }
+  return context?.scope;
+};
 
-// src/react/hooks/useScopeAvailable.ts
+// src/react/hooks/use-scope-available.ts
 import { useEffect } from "react";
 import { useRefresh } from "@flowgram.ai/core";
-function useScopeAvailable() {
-  const scope = useCurrentScope();
+function useScopeAvailable(params) {
+  const { autoRefresh = true } = params || {};
+  const scope = useCurrentScope({ strict: true });
   const refresh = useRefresh();
   useEffect(() => {
-    const disposable = scope.available.onDataChange(() => {
+    if (!autoRefresh) {
+      return () => null;
+    }
+    const disposable = scope.available.onListOrAnyVarChange(() => {
       refresh();
     });
     return () => disposable.dispose();
-  }, []);
+  }, [autoRefresh]);
   return scope.available;
 }
 
-// src/react/hooks/useAvailableVariables.ts
+// src/react/hooks/use-available-variables.ts
 import { useEffect as useEffect2 } from "react";
 import { useRefresh as useRefresh2, useService } from "@flowgram.ai/core";
 function useAvailableVariables() {
@@ -2004,7 +2645,7 @@ function useAvailableVariables() {
   const refresh = useRefresh2();
   useEffect2(() => {
     if (!scope) {
-      const disposable2 = variableEngine.globalVariableTable.onAnyChange(() => {
+      const disposable2 = variableEngine.globalVariableTable.onListOrAnyVarChange(() => {
         refresh();
       });
       return () => disposable2.dispose();
@@ -2016,9 +2657,30 @@ function useAvailableVariables() {
   }, []);
   return scope ? scope.available.variables : variableEngine.globalVariableTable.variables;
 }
+
+// src/react/hooks/use-output-variables.ts
+import { useEffect as useEffect3 } from "react";
+import { useRefresh as useRefresh3 } from "@flowgram.ai/core";
+function useOutputVariables() {
+  const scope = useCurrentScope();
+  const refresh = useRefresh3();
+  useEffect3(() => {
+    if (!scope) {
+      throw new Error(
+        "[useOutputVariables]: No scope found, useOutputVariables must be used in <ScopeProvider>"
+      );
+    }
+    const disposable = scope.output.onListOrAnyVarChange(() => {
+      refresh();
+    });
+    return () => disposable.dispose();
+  }, []);
+  return scope?.output.variables || [];
+}
 export {
   ASTFactory,
   ASTKind,
+  ASTMatch,
   ASTNode,
   ASTNodeFlags,
   ASTRegisters,
@@ -2030,10 +2692,9 @@ export {
   CustomType,
   DataNode,
   EnumerateExpression,
-  ExpressionList,
   IntegerType,
   KeyPathExpression,
-  KeyPathExpressionV2,
+  LegacyKeyPathExpression,
   ListNode,
   MapNode,
   MapType,
@@ -2051,13 +2712,13 @@ export {
   VariableEngine,
   VariableEngineProvider,
   VariableFieldKeyRenameService,
-  VariableTable,
+  WrapArrayExpression,
   injectToAST,
   isMatchAST,
   postConstructAST,
   useAvailableVariables,
   useCurrentScope,
-  useScopeAvailable,
-  useScopeContext
+  useOutputVariables,
+  useScopeAvailable
 };
 //# sourceMappingURL=index.js.map