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

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var __decorateClass = (decorators, target, key, kind) => {
   var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
@@ -27,10 +37,11 @@ var __decorateClass = (decorators, target, key, kind) => {
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   ASTFactory: () => ASTFactory,
   ASTKind: () => ASTKind,
+  ASTMatch: () => ASTMatch,
   ASTNode: () => ASTNode,
   ASTNodeFlags: () => ASTNodeFlags,
   ASTRegisters: () => ASTRegisters,
@@ -39,12 +50,12 @@ __export(src_exports, {
   BaseType: () => BaseType,
   BaseVariableField: () => BaseVariableField,
   BooleanType: () => BooleanType,
+  CustomType: () => CustomType,
   DataNode: () => DataNode,
   EnumerateExpression: () => EnumerateExpression,
-  ExpressionList: () => ExpressionList,
   IntegerType: () => IntegerType,
   KeyPathExpression: () => KeyPathExpression,
-  KeyPathExpressionV2: () => KeyPathExpressionV2,
+  LegacyKeyPathExpression: () => LegacyKeyPathExpression,
   ListNode: () => ListNode,
   MapNode: () => MapNode,
   MapType: () => MapType,
@@ -62,25 +73,25 @@ __export(src_exports, {
   VariableEngine: () => VariableEngine,
   VariableEngineProvider: () => VariableEngineProvider,
   VariableFieldKeyRenameService: () => VariableFieldKeyRenameService,
-  VariableTable: () => VariableTable,
+  WrapArrayExpression: () => WrapArrayExpression,
   injectToAST: () => injectToAST,
   isMatchAST: () => isMatchAST,
   postConstructAST: () => postConstructAST,
   useAvailableVariables: () => useAvailableVariables,
   useCurrentScope: () => useCurrentScope,
-  useScopeAvailable: () => useScopeAvailable,
-  useScopeContext: () => useScopeContext
+  useOutputVariables: () => useOutputVariables,
+  useScopeAvailable: () => useScopeAvailable
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/variable-container-module.ts
-var import_inversify7 = require("inversify");
+var import_inversify8 = require("inversify");
 
 // src/variable-engine.ts
-var import_rxjs6 = require("rxjs");
-var import_inversify5 = require("inversify");
-var import_utils10 = require("@flowgram.ai/utils");
-var import_utils11 = require("@flowgram.ai/utils");
+var import_rxjs7 = require("rxjs");
+var import_inversify6 = require("inversify");
+var import_utils8 = require("@flowgram.ai/utils");
+var import_utils9 = require("@flowgram.ai/utils");
 
 // src/utils/toDisposable.tsx
 var import_utils = require("@flowgram.ai/utils");
@@ -110,9 +121,170 @@ var createMemo = () => {
   return memo;
 };
 
+// src/scope/variable-table.ts
+var import_rxjs = require("rxjs");
+var import_utils2 = require("@flowgram.ai/utils");
+var VariableTable = class {
+  constructor(parentTable) {
+    this.parentTable = parentTable;
+    this.table = /* @__PURE__ */ new Map();
+    this.toDispose = new import_utils2.DisposableCollection();
+    /**
+     * @deprecated
+     */
+    this.onDataChangeEmitter = new import_utils2.Emitter();
+    this.variables$ = new import_rxjs.Subject();
+    /**
+     * An observable that listens for value changes on any variable within the table.
+     */
+    this.anyVariableChange$ = this.variables$.pipe(
+      (0, import_rxjs.switchMap)(
+        (_variables) => (0, import_rxjs.merge)(
+          ..._variables.map(
+            (_v) => _v.value$.pipe(
+              // Skip the initial value of the BehaviorSubject
+              (0, import_rxjs.skip)(1)
+            )
+          )
+        )
+      ),
+      (0, import_rxjs.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 import_utils2.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
 var import_inversify = require("inversify");
-var import_utils2 = require("@flowgram.ai/utils");
+var import_utils3 = require("@flowgram.ai/utils");
 
 // src/providers.ts
 var VariableEngineProvider = Symbol("DynamicVariableEngine");
@@ -121,13 +293,13 @@ var ContainerProvider = Symbol("ContainerProvider");
 // src/scope/scope-chain.ts
 var ScopeChain = class {
   constructor() {
-    this.toDispose = new import_utils2.DisposableCollection();
+    this.toDispose = new import_utils3.DisposableCollection();
   }
   get variableEngine() {
     return this.variableEngineProvider();
   }
   /**
-   * 所有作用域依赖关系刷新
+   * Refreshes the dependency and coverage relationships for all scopes.
    */
   refreshAllChange() {
     this.variableEngine.getAllScopes().forEach((_scope) => {
@@ -153,7 +325,7 @@ ScopeChain = __decorateClass([
 ], ScopeChain);
 
 // src/scope/scope.ts
-var import_utils9 = require("@flowgram.ai/utils");
+var import_utils7 = require("@flowgram.ai/utils");
 
 // src/ast/types.ts
 var ASTKind = /* @__PURE__ */ ((ASTKind2) => {
@@ -166,12 +338,13 @@ var ASTKind = /* @__PURE__ */ ((ASTKind2) => {
   ASTKind2["Map"] = "Map";
   ASTKind2["Union"] = "Union";
   ASTKind2["Any"] = "Any";
+  ASTKind2["CustomType"] = "CustomType";
   ASTKind2["Property"] = "Property";
   ASTKind2["VariableDeclaration"] = "VariableDeclaration";
   ASTKind2["VariableDeclarationList"] = "VariableDeclarationList";
   ASTKind2["KeyPathExpression"] = "KeyPathExpression";
   ASTKind2["EnumerateExpression"] = "EnumerateExpression";
-  ASTKind2["ExpressionList"] = "ExpressionList";
+  ASTKind2["WrapArrayExpression"] = "WrapArrayExpression";
   ASTKind2["ListNode"] = "ListNode";
   ASTKind2["DataNode"] = "DataNode";
   ASTKind2["MapNode"] = "MapNode";
@@ -179,8 +352,8 @@ var ASTKind = /* @__PURE__ */ ((ASTKind2) => {
 })(ASTKind || {});
 
 // src/ast/ast-registers.ts
-var import_lodash3 = require("lodash");
-var import_inversify2 = require("inversify");
+var import_lodash_es4 = require("lodash-es");
+var import_inversify3 = require("inversify");
 
 // src/ast/utils/inversify.ts
 var injectToAST = (serviceIdentifier) => function(target, propertyKey) {
@@ -210,6 +383,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,
@@ -245,73 +455,64 @@ 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
-var import_rxjs = require("rxjs");
+var import_rxjs2 = require("rxjs");
 var import_nanoid = require("nanoid");
+var import_lodash_es = require("lodash-es");
 var import_fast_equals = require("fast-equals");
-var import_utils3 = require("@flowgram.ai/utils");
+var import_utils4 = require("@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 import_rxjs.BehaviorSubject(this);
+    this.value$ = new import_rxjs2.BehaviorSubject(this);
     /**
-     * 子节点
+     * Child ASTNodes.
      */
     this._children = /* @__PURE__ */ new Set();
     /**
-     * 删除节点处理事件列表
+     * List of disposal handlers for the ASTNode.
      */
-    this.toDispose = new import_utils3.DisposableCollection(
-      import_utils3.Disposable.create(() => {
+    this.toDispose = new import_utils4.DisposableCollection(
+      import_utils4.Disposable.create(() => {
         this.parent?.fireChange();
         this.children.forEach((child) => child.dispose());
       })
     );
     /**
-     * 销毁时触发的回调
+     * Callback triggered upon disposal.
      */
     this.onDispose = this.toDispose.onDispose;
     this.scope = scope;
@@ -319,10 +520,19 @@ var ASTNode = class _ASTNode {
     this.opts = opts;
     this.key = key || (0, import_nanoid.nanoid)();
     this.fromJSON = this.withBatchUpdate(this.fromJSON.bind(this));
-    this.dispatchGlobalEvent({ type: "NewAST" });
+    const rawToJSON = this.toJSON?.bind(this);
+    this.toJSON = () => (0, import_lodash_es.omitBy)(
+      {
+        // always include kind
+        kind: this.kind,
+        ...rawToJSON?.() || {}
+      },
+      // remove undefined fields
+      import_lodash_es.isNil
+    );
   }
   /**
-   * AST 节点的类型
+   * The type of the ASTNode.
    */
   get kind() {
     if (!this.constructor.kind) {
@@ -331,24 +541,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) {
@@ -359,15 +559,15 @@ var ASTNode = class _ASTNode {
     });
     this._children.add(child);
     child.toDispose.push(
-      import_utils3.Disposable.create(() => {
+      import_utils4.Disposable.create(() => {
         this._children.delete(child);
       })
     );
     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, {
@@ -378,8 +578,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) {
@@ -399,7 +599,7 @@ var ASTNode = class _ASTNode {
     };
   }
   /**
-   * 触发当前节点更新
+   * Triggers an update for the current node.
    */
   fireChange() {
     if (this.changeLocked || this.disposed) {
@@ -415,29 +615,31 @@ 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 } = {}) {
     return subsToDisposable(
       this.value$.pipe(
-        (0, import_rxjs.map)(() => selector ? selector(this) : this),
-        (0, import_rxjs.distinctUntilChanged)(
+        (0, import_rxjs2.map)(() => selector ? selector(this) : this),
+        (0, import_rxjs2.distinctUntilChanged)(
           (a, b) => (0, import_fast_equals.shallowEqual)(a, b),
           (value) => {
             if (value instanceof _ASTNode) {
@@ -446,13 +648,17 @@ var ASTNode = class _ASTNode {
             return value;
           }
         ),
-        // 默认跳过 BehaviorSubject 第一次触发
-        triggerOnInit ? (0, import_rxjs.tap)(() => null) : (0, import_rxjs.skip)(1),
-        // 每个 animationFrame 内所有更新合并成一个
-        debounceAnimation ? (0, import_rxjs.debounceTime)(0, import_rxjs.animationFrameScheduler) : (0, import_rxjs.tap)(() => null)
+        // By default, skip the first trigger of BehaviorSubject.
+        triggerOnInit ? (0, import_rxjs2.tap)(() => null) : (0, import_rxjs2.skip)(1),
+        // All updates within each animationFrame are merged into one.
+        debounceAnimation ? (0, import_rxjs2.debounceTime)(0, import_rxjs2.animationFrameScheduler) : (0, import_rxjs2.tap)(() => null)
       ).subscribe(observer)
     );
   }
+  /**
+   * Dispatches a global event for the current ASTNode.
+   * @param event The global event.
+   */
   dispatchGlobalEvent(event) {
     this.scope.event.dispatch({
       ...event,
@@ -460,7 +666,7 @@ var ASTNode = class _ASTNode {
     });
   }
   /**
-   * 销毁
+   * Disposes the ASTNode.
    */
   dispose() {
     if (this.toDispose.disposed) {
@@ -483,8 +689,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);
@@ -496,17 +703,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
@@ -515,13 +720,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) {
@@ -529,19 +745,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) {
@@ -549,6 +770,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 */,
@@ -564,7 +789,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 */;
@@ -575,61 +824,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 */,
@@ -638,17 +910,23 @@ var MapType = class extends BaseType {
     };
   }
 };
-// public flags: ASTNodeFlags = ASTNodeFlags.DrilldownType | ASTNodeFlags.EnumerateType;
 MapType.kind = "Map" /* Map */;
 
 // src/ast/type/object.ts
-var import_lodash = require("lodash");
+var import_lodash_es2 = require("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 || []];
@@ -682,16 +960,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;
@@ -704,25 +985,30 @@ 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 || [];
     const sourcePropertyKeys = Array.from(this.propertyTable.keys());
     const targetPropertyKeys = targetProperties.map((_target) => _target.key);
-    const isKeyStrongEqual = !(0, import_lodash.xor)(sourcePropertyKeys, targetPropertyKeys).length;
+    const isKeyStrongEqual = !(0, import_lodash_es2.xor)(sourcePropertyKeys, targetPropertyKeys).length;
     return isKeyStrongEqual && targetProperties.every((targetProperty) => {
       const sourceProperty = this.propertyTable.get(targetProperty.key);
       return sourceProperty && sourceProperty.key === targetProperty.key && sourceProperty.type?.isTypeEqual(targetProperty?.type);
@@ -731,8 +1017,48 @@ var ObjectType = class extends BaseType {
 };
 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 */) {
+      return (targetTypeJSON?.types || [])?.some(
+        (_subType) => this.isTypeEqual(_subType)
+      );
+    }
+    return targetTypeJSON?.kind === this.kind && targetTypeJSON?.typeName === this.typeName;
+  }
+  toJSON() {
+    return {
+      typeName: this.typeName
+    };
+  }
+};
+CustomType.kind = "CustomType" /* CustomType */;
+
 // src/ast/expression/base-expression.ts
-var import_rxjs2 = require("rxjs");
+var import_rxjs3 = require("rxjs");
 var import_fast_equals2 = require("fast-equals");
 
 // src/ast/utils/variable-field.ts
@@ -754,25 +1080,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 import_rxjs2.Subject();
+    this.refreshRefs$ = new import_rxjs3.Subject();
     /**
-     * 监听引用变量变化
-     * 监听 [a.b.c] -> [a.b]
+     * An observable that emits the referenced variable fields when they change.
      */
     this.refs$ = this.refreshRefs$.pipe(
-      (0, import_rxjs2.map)(() => this.getRefFields()),
-      (0, import_rxjs2.distinctUntilChanged)(import_fast_equals2.shallowEqual),
-      (0, import_rxjs2.switchMap)(
-        (refs) => !refs?.length ? (0, import_rxjs2.of)([]) : (0, import_rxjs2.combineLatest)(
+      (0, import_rxjs3.map)(() => this.getRefFields()),
+      (0, import_rxjs3.distinctUntilChanged)(import_fast_equals2.shallowEqual),
+      (0, import_rxjs3.switchMap)(
+        (refs) => !refs?.length ? (0, import_rxjs3.of)([]) : (0, import_rxjs3.combineLatest)(
           refs.map(
-            (ref) => ref ? ref.value$ : (0, import_rxjs2.of)(void 0)
+            (ref) => ref ? ref.value$ : (0, import_rxjs3.of)(void 0)
           )
         )
       ),
-      (0, import_rxjs2.share)()
+      (0, import_rxjs3.share)()
     );
     this.toDispose.push(
       subsToDisposable(
@@ -784,114 +1109,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
-var import_fast_equals3 = require("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 (!(0, import_fast_equals3.shallowEqual)(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 */) {
@@ -899,12 +1152,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 */,
@@ -914,16 +1179,17 @@ var EnumerateExpression = class extends BaseExpression {
 };
 EnumerateExpression.kind = "EnumerateExpression" /* EnumerateExpression */;
 
-// src/ast/expression/keypath-expression-v2.ts
-var import_fast_equals4 = require("fast-equals");
+// src/ast/expression/keypath-expression.ts
+var import_rxjs4 = require("rxjs");
+var import_fast_equals3 = require("fast-equals");
 
 // src/ast/utils/expression.ts
-var import_lodash2 = require("lodash");
+var import_lodash_es3 = require("lodash-es");
 function getAllRefs(ast) {
   return getAllChildren(ast).filter((_child) => _child.flags & 4 /* Expression */).map((_child) => _child.refs).flat().filter(Boolean);
 }
 function checkRefCycle(curr, refNodes) {
-  if ((0, import_lodash2.intersection)(curr.scope.coverScopes, refNodes.map((_ref) => _ref?.scope).filter(Boolean)).length === 0) {
+  if ((0, import_lodash_es3.intersection)(curr.scope.coverScopes, refNodes.map((_ref) => _ref?.scope).filter(Boolean)).length === 0) {
     return false;
   }
   const visited = /* @__PURE__ */ new Set();
@@ -935,39 +1201,48 @@ function checkRefCycle(curr, refNodes) {
       queue.push(ref);
     }
   }
-  return (0, import_lodash2.intersection)(Array.from(visited), getParentFields(curr)).length > 0;
+  return (0, import_lodash_es3.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(
+          (0, import_rxjs4.distinctUntilChanged)(
+            (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])) {
@@ -979,39 +1254,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 (!(0, import_fast_equals4.shallowEqual)(keyPath, this._keyPath)) {
+    if (!(0, import_fast_equals3.shallowEqual)(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
+var import_fast_equals4 = require("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 (!(0, import_fast_equals4.shallowEqual)(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
-var import_utils4 = require("@flowgram.ai/utils");
+WrapArrayExpression.kind = "WrapArrayExpression" /* WrapArrayExpression */;
+__decorateClass([
+  postConstructAST()
+], WrapArrayExpression.prototype, "init", 1);
 
 // src/ast/declaration/base-variable-field.ts
 var import_fast_equals5 = require("fast-equals");
@@ -1022,35 +1447,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 (!(0, import_fast_equals5.shallowEqual)(nextMeta, this._meta)) {
       this._meta = nextMeta;
@@ -1058,7 +1521,8 @@ var BaseVariableField = class extends ASTNode {
     }
   }
   /**
-   * 根据 keyPath 去找下钻的变量字段
+   * Get the variable field by keyPath, similar to js code:
+   * `v.a.b`
    * @param keyPath
    * @returns
    */
@@ -1069,7 +1533,7 @@ var BaseVariableField = class extends ASTNode {
     return void 0;
   }
   /**
-   * 监听类型变化
+   * Subscribe to type change of the variable field
    * @param observer
    * @returns
    */
@@ -1077,12 +1541,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(),
@@ -1096,34 +1559,42 @@ var VariableDeclaration = class extends BaseVariableField {
   constructor(params) {
     super(params);
     this._order = 0;
-    this.scope.output.addVariableToTable(this);
-    this.toDispose.push(
-      import_utils4.Disposable.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 */;
@@ -1132,8 +1603,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 || []];
@@ -1173,10 +1654,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())
     };
   }
 };
@@ -1190,9 +1675,16 @@ Property.kind = "Property" /* Property */;
 // src/ast/common/data-node.ts
 var import_fast_equals6 = require("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 (!(0, import_fast_equals6.shallowEqual)(restData, this._data)) {
@@ -1200,12 +1692,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 (!(0, import_fast_equals6.shallowEqual)(nextData, this._data)) {
       this._data = {
@@ -1220,9 +1720,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();
@@ -1239,6 +1746,10 @@ var ListNode = class extends ASTNode {
       return prevItem;
     });
   }
+  /**
+   * Serialize the `ListNode` to `ListNodeJSON`.
+   * @returns The JSON representation of `ListNode`.
+   */
   toJSON() {
     return {
       kind: "ListNode" /* ListNode */,
@@ -1254,6 +1765,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 || []) {
@@ -1264,6 +1779,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 */,
@@ -1271,9 +1790,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, {
@@ -1284,8 +1804,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();
@@ -1293,9 +1813,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);
@@ -1306,9 +1826,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);
@@ -1318,18 +1841,19 @@ var ASTRegisters = class {
     this.registerAST(ObjectType);
     this.registerAST(ArrayType);
     this.registerAST(MapType);
+    this.registerAST(CustomType);
     this.registerAST(Property);
     this.registerAST(VariableDeclaration);
     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 }) {
@@ -1347,8 +1871,9 @@ var ASTRegisters = class {
       injector?.() || {}
     );
     node.changeLocked = true;
-    node.fromJSON((0, import_lodash3.omit)(json, ["key", "kind"]));
+    node.fromJSON((0, import_lodash_es4.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]?.();
@@ -1356,7 +1881,7 @@ var ASTRegisters = class {
     return node;
   }
   /**
-   * 根据 AST 节点类型获取节点 Registry
+   * Gets the node Registry by AST node type.
    * @param kind
    * @returns
    */
@@ -1364,9 +1889,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);
@@ -1376,13 +1900,16 @@ var ASTRegisters = class {
   }
 };
 ASTRegisters = __decorateClass([
-  (0, import_inversify2.injectable)()
+  (0, import_inversify3.injectable)()
 ], ASTRegisters);
 
 // 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 */ });
@@ -1402,6 +1929,10 @@ var ASTFactory;
     kind: "Union" /* Union */,
     ...json
   });
+  ASTFactory2.createCustomType = (json) => ({
+    kind: "CustomType" /* CustomType */,
+    ...json
+  });
   ASTFactory2.createVariableDeclaration = (json) => ({
     kind: "VariableDeclaration" /* VariableDeclaration */,
     ...json
@@ -1422,115 +1953,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
-var import_rxjs3 = require("rxjs");
-var import_utils5 = require("@flowgram.ai/utils");
-var import_utils6 = require("@flowgram.ai/utils");
-var VariableTable = class {
-  constructor(parentTable) {
-    this.parentTable = parentTable;
-    this.table = /* @__PURE__ */ new Map();
-    this.onDataChangeEmitter = new import_utils5.Emitter();
-    this.variables$ = new import_rxjs3.Subject();
-    // 监听变量列表中的单个变量变化
-    this.anyVariableChange$ = this.variables$.pipe(
-      (0, import_rxjs3.switchMap)(
-        (_variables) => (0, import_rxjs3.merge)(
-          ..._variables.map(
-            (_v) => _v.value$.pipe(
-              // 跳过 BehaviorSubject 第一个
-              (0, import_rxjs3.skip)(1)
-            )
-          )
-        )
-      ),
-      (0, import_rxjs3.share)()
-    );
-    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 import_utils6.DisposableCollection();
-    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) {
@@ -1539,7 +1968,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();
@@ -1548,23 +1977,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(
@@ -1573,7 +2045,7 @@ var ScopeOutputData = class {
     );
   }
   /**
-   * 输出的变量 keys
+   * The keys of the output variables.
    */
   get variableKeys() {
     return this.memo("variableKeys", () => this.variableTable.variableKeys);
@@ -1585,83 +2057,119 @@ 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());
   }
 };
 
 // src/scope/datas/scope-available-data.ts
-var import_rxjs4 = require("rxjs");
-var import_lodash4 = require("lodash");
+var import_rxjs5 = require("rxjs");
+var import_lodash_es5 = require("lodash-es");
 var import_fast_equals7 = require("fast-equals");
-var import_utils7 = require("@flowgram.ai/utils");
-var import_utils8 = require("@flowgram.ai/utils");
+var import_utils5 = require("@flowgram.ai/utils");
+var import_utils6 = require("@flowgram.ai/utils");
 var ScopeAvailableData = class {
   constructor(scope) {
     this.scope = scope;
     this.memo = createMemo();
-    this.refresh$ = new import_rxjs4.Subject();
+    this._version = 0;
+    this.refresh$ = new import_rxjs5.Subject();
     this._variables = [];
     /**
-     * 监听
+     * An observable that emits when the list of available variables changes.
      */
     this.variables$ = this.refresh$.pipe(
-      // 输出变量是否 version 发生变化
-      (0, import_rxjs4.map)(() => (0, import_lodash4.flatten)(this.depScopes.map((scope) => scope.output.variables || []))),
-      // 变量列表浅比较
-      (0, import_rxjs4.distinctUntilChanged)(import_fast_equals7.shallowEqual),
-      (0, import_rxjs4.share)()
+      // Map to the flattened list of variables from all dependency scopes.
+      (0, import_rxjs5.map)(() => (0, import_lodash_es5.flatten)(this.depScopes.map((scope) => scope.output.variables || []))),
+      // Use shallow equality to check if the variable list has changed.
+      (0, import_rxjs5.distinctUntilChanged)(import_fast_equals7.shallowEqual),
+      (0, import_rxjs5.share)()
     );
-    // 监听变量列表中的单个变量变化
+    /**
+     * An observable that emits when any variable in the available list changes its value.
+     */
     this.anyVariableChange$ = this.variables$.pipe(
-      (0, import_rxjs4.switchMap)(
-        (_variables) => (0, import_rxjs4.merge)(
+      (0, import_rxjs5.switchMap)(
+        (_variables) => (0, import_rxjs5.merge)(
           ..._variables.map(
             (_v) => _v.value$.pipe(
-              // 跳过 BehaviorSubject 第一个
-              (0, import_rxjs4.skip)(1)
+              // Skip the initial value of the BehaviorSubject.
+              (0, import_rxjs5.skip)(1)
             )
           )
         )
       ),
-      (0, import_rxjs4.share)()
+      (0, import_rxjs5.share)()
     );
-    this.onDataChangeEmitter = new import_utils8.Emitter();
     /**
-     * 监听变量列表变化 + 任意子变量变化
+     * @deprecated
+     */
+    this.onDataChangeEmitter = new import_utils6.Emitter();
+    this.onListOrAnyVarChangeEmitter = new import_utils6.Emitter();
+    /**
+     * @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);
       }),
-      import_utils7.Disposable.create(() => {
+      import_utils5.Disposable.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;
@@ -1669,43 +2177,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])) {
@@ -1713,32 +2221,78 @@ 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(
+      (0, import_rxjs5.merge)(this.anyVariableChange$, this.variables$).pipe(
+        triggerOnInit ? (0, import_rxjs5.startWith)() : (0, import_rxjs5.tap)(() => null),
+        (0, import_rxjs5.map)(() => {
+          const v = this.getByKeyPath(keyPath);
+          return selector ? selector(v) : v;
+        }),
+        (0, import_rxjs5.distinctUntilChanged)(
+          (a, b) => (0, import_fast_equals7.shallowEqual)(a, b),
+          (value) => {
+            if (value instanceof ASTNode) {
+              return value.hash;
+            }
+            return value;
+          }
+        ),
+        // Debounce updates to a single emission per animation frame.
+        debounceAnimation ? (0, import_rxjs5.debounceTime)(0, import_rxjs5.animationFrameScheduler) : (0, import_rxjs5.tap)(() => null)
+      ).subscribe(cb)
+    );
+  }
 };
 
 // src/scope/datas/scope-event-data.ts
-var import_rxjs5 = require("rxjs");
+var import_rxjs6 = require("rxjs");
 var ScopeEventData = class {
   constructor(scope) {
     this.scope = scope;
-    this.event$ = new import_rxjs5.Subject();
+    this.event$ = new import_rxjs6.Subject();
     scope.toDispose.pushAll([
       this.subscribe((_action) => {
         scope.variableEngine.fireGlobalEvent(_action);
       })
     ]);
   }
+  /**
+   * 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((0, import_rxjs5.filter)((_action) => _action.type === type)).subscribe(observer)
+      this.event$.pipe((0, import_rxjs6.filter)((_action) => _action.type === type)).subscribe(observer)
     );
   }
 };
@@ -1747,10 +2301,10 @@ var ScopeEventData = class {
 var Scope = class {
   constructor(options) {
     /**
-     * 数据缓存
+     * A memoization utility for caching computed values.
      */
     this.memo = createMemo();
-    this.toDispose = new import_utils9.DisposableCollection();
+    this.toDispose = new import_utils7.DisposableCollection();
     this.onDispose = this.toDispose.onDispose;
     this.id = options.id;
     this.meta = options.meta || {};
@@ -1759,7 +2313,7 @@ var Scope = class {
     this.ast = this.variableEngine.astRegisters.createAST(
       {
         kind: "MapNode" /* MapNode */,
-        key: this.id
+        key: String(this.id)
       },
       {
         scope: this
@@ -1768,25 +2322,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();
@@ -1796,6 +2366,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
@@ -1803,47 +2399,74 @@ var VariableEngine = class {
   constructor(chain, astRegisters) {
     this.chain = chain;
     this.astRegisters = astRegisters;
-    this.toDispose = new import_utils10.DisposableCollection();
+    this.toDispose = new import_utils8.DisposableCollection();
     this.memo = createMemo();
     this.scopeMap = /* @__PURE__ */ new Map();
-    this.globalEvent$ = new import_rxjs6.Subject();
-    this.onScopeChangeEmitter = new import_utils11.Emitter();
+    /**
+     * A rxjs subject that emits global events occurring within the variable engine.
+     */
+    this.globalEvent$ = new import_rxjs7.Subject();
+    this.onScopeChangeEmitter = new import_utils9.Emitter();
+    /**
+     * 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,
-      import_utils10.Disposable.create(() => {
+      import_utils8.Disposable.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 });
         })
@@ -1855,7 +2478,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
   } = {}) {
@@ -1868,9 +2496,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) => {
@@ -1882,30 +2520,45 @@ var VariableEngine = class {
   }
 };
 __decorateClass([
-  (0, import_inversify5.inject)(ContainerProvider)
+  (0, import_inversify6.inject)(ContainerProvider)
 ], VariableEngine.prototype, "containerProvider", 2);
 __decorateClass([
-  (0, import_inversify5.preDestroy)()
+  (0, import_inversify6.preDestroy)()
 ], VariableEngine.prototype, "dispose", 1);
 VariableEngine = __decorateClass([
-  (0, import_inversify5.injectable)(),
-  __decorateParam(0, (0, import_inversify5.inject)(ScopeChain)),
-  __decorateParam(1, (0, import_inversify5.inject)(ASTRegisters))
+  (0, import_inversify6.injectable)(),
+  __decorateParam(0, (0, import_inversify6.inject)(ScopeChain)),
+  __decorateParam(1, (0, import_inversify6.inject)(ASTRegisters))
 ], VariableEngine);
 
 // src/services/variable-field-key-rename-service.ts
-var import_lodash5 = require("lodash");
-var import_inversify6 = require("inversify");
-var import_utils12 = require("@flowgram.ai/utils");
+var import_lodash_es6 = require("lodash-es");
+var import_inversify7 = require("inversify");
+var import_utils10 = require("@flowgram.ai/utils");
 var VariableFieldKeyRenameService = class {
   constructor() {
-    this.toDispose = new import_utils12.DisposableCollection();
-    this.renameEmitter = new import_utils12.Emitter();
-    // 没有被 rename 的字段通过 disposeInList 透出，让业务区分变量是 rename 删除的，还是真正从列表中删除的
-    this.disposeInListEmitter = new import_utils12.Emitter();
+    this.toDispose = new import_utils10.DisposableCollection();
+    this.renameEmitter = new import_utils10.Emitter();
+    /**
+     * 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 import_utils10.Emitter();
+    /**
+     * 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);
@@ -1936,8 +2589,13 @@ 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 = (0, import_lodash5.difference)(prev || [], next || []);
+    const removedFields = (0, import_lodash_es6.difference)(prev || [], next || []);
     removedFields.forEach((_field) => this.disposeInListEmitter.fire(_field));
   }
   init() {
@@ -1961,20 +2619,20 @@ var VariableFieldKeyRenameService = class {
   }
 };
 __decorateClass([
-  (0, import_inversify6.inject)(VariableEngine)
+  (0, import_inversify7.inject)(VariableEngine)
 ], VariableFieldKeyRenameService.prototype, "variableEngine", 2);
 __decorateClass([
-  (0, import_inversify6.postConstruct)()
+  (0, import_inversify7.postConstruct)()
 ], VariableFieldKeyRenameService.prototype, "init", 1);
 __decorateClass([
-  (0, import_inversify6.preDestroy)()
+  (0, import_inversify7.preDestroy)()
 ], VariableFieldKeyRenameService.prototype, "dispose", 1);
 VariableFieldKeyRenameService = __decorateClass([
-  (0, import_inversify6.injectable)()
+  (0, import_inversify7.injectable)()
 ], VariableFieldKeyRenameService);
 
 // src/variable-container-module.ts
-var VariableContainerModule = new import_inversify7.ContainerModule((bind) => {
+var VariableContainerModule = new import_inversify8.ContainerModule((bind) => {
   bind(VariableEngine).toSelf().inSingletonScope();
   bind(ASTRegisters).toSelf().inSingletonScope();
   bind(VariableFieldKeyRenameService).toSelf().inSingletonScope();
@@ -1983,28 +2641,48 @@ var VariableContainerModule = new import_inversify7.ContainerModule((bind) => {
 });
 
 // src/react/context.tsx
-var import_react = require("react");
+var import_react = __toESM(require("react"));
 var ScopeContext = (0, import_react.createContext)(null);
-var ScopeProvider = ScopeContext.Provider;
-var useScopeContext = () => (0, import_react.useContext)(ScopeContext);
-var useCurrentScope = () => (0, import_react.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__ */ import_react.default.createElement(ScopeContext.Provider, { value: { scope: scopeToUse } }, children);
+};
+var useCurrentScope = (params) => {
+  const { strict = false } = params || {};
+  const context = (0, import_react.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
 var import_react2 = require("react");
 var import_core = require("@flowgram.ai/core");
-function useScopeAvailable() {
-  const scope = useCurrentScope();
+function useScopeAvailable(params) {
+  const { autoRefresh = true } = params || {};
+  const scope = useCurrentScope({ strict: true });
   const refresh = (0, import_core.useRefresh)();
   (0, import_react2.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
 var import_react3 = require("react");
 var import_core2 = require("@flowgram.ai/core");
 function useAvailableVariables() {
@@ -2013,7 +2691,7 @@ function useAvailableVariables() {
   const refresh = (0, import_core2.useRefresh)();
   (0, import_react3.useEffect)(() => {
     if (!scope) {
-      const disposable2 = variableEngine.globalVariableTable.onAnyChange(() => {
+      const disposable2 = variableEngine.globalVariableTable.onListOrAnyVarChange(() => {
         refresh();
       });
       return () => disposable2.dispose();
@@ -2025,10 +2703,31 @@ function useAvailableVariables() {
   }, []);
   return scope ? scope.available.variables : variableEngine.globalVariableTable.variables;
 }
+
+// src/react/hooks/use-output-variables.ts
+var import_react4 = require("react");
+var import_core3 = require("@flowgram.ai/core");
+function useOutputVariables() {
+  const scope = useCurrentScope();
+  const refresh = (0, import_core3.useRefresh)();
+  (0, import_react4.useEffect)(() => {
+    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 || [];
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ASTFactory,
   ASTKind,
+  ASTMatch,
   ASTNode,
   ASTNodeFlags,
   ASTRegisters,
@@ -2037,12 +2736,12 @@ function useAvailableVariables() {
   BaseType,
   BaseVariableField,
   BooleanType,
+  CustomType,
   DataNode,
   EnumerateExpression,
-  ExpressionList,
   IntegerType,
   KeyPathExpression,
-  KeyPathExpressionV2,
+  LegacyKeyPathExpression,
   ListNode,
   MapNode,
   MapType,
@@ -2060,13 +2759,13 @@ function useAvailableVariables() {
   VariableEngine,
   VariableEngineProvider,
   VariableFieldKeyRenameService,
-  VariableTable,
+  WrapArrayExpression,
   injectToAST,
   isMatchAST,
   postConstructAST,
   useAvailableVariables,
   useCurrentScope,
-  useScopeAvailable,
-  useScopeContext
+  useOutputVariables,
+  useScopeAvailable
 });
 //# sourceMappingURL=index.js.map