@flowgram.ai/variable-core 0.5.5 → 0.5.7

package/dist/esm/index.js

@@ -60,13 +60,15 @@ var VariableTable = class {
      */
     this.onDataChangeEmitter = new Emitter();
     this.variables$ = new Subject();
-    // 监听变量列表中的单个变量变化
+    /**
+     * An observable that listens for value changes on any variable within the table.
+     */
     this.anyVariableChange$ = this.variables$.pipe(
       switchMap(
         (_variables) => merge(
           ..._variables.map(
             (_v) => _v.value$.pipe(
-              // 跳过 BehaviorSubject 第一个
+              // Skip the initial value of the BehaviorSubject
               skip(1)
             )
           )
@@ -75,68 +77,84 @@ var VariableTable = class {
       share()
     );
     /**
-     * @deprecated use onListOrAnyVarChange instead
+     * @deprecated Use onListOrAnyVarChange instead.
      */
     this.onDataChange = this.onDataChangeEmitter.event;
     this._version = 0;
     this.toDispose.pushAll([
       this.onDataChangeEmitter,
-      // active share()
+      // Activate the share() operator
       this.onAnyVariableChange(() => {
         this.bumpVersion();
       })
     ]);
   }
   /**
-   * listen to any variable update in list
-   * @param observer
-   * @returns
+   * 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));
   }
   /**
-   * listen to variable list change
-   * @param observer
-   * @returns
+   * 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));
   }
   /**
-   * listen to variable list change + any variable update in list
-   * @param observer
+   * Subscribes to both variable list changes and updates to any variable in the list.
+   * @param observer A function to be called when either the list or a variable in it changes.
+   * @returns A disposable collection to unsubscribe from both events.
    */
   onListOrAnyVarChange(observer) {
     const disposables = new DisposableCollection();
     disposables.pushAll([this.onVariableListChange(observer), this.onAnyVariableChange(observer)]);
     return disposables;
   }
+  /**
+   * Fires change events to notify listeners that the data has been updated.
+   */
   fireChange() {
     this.bumpVersion();
     this.onDataChangeEmitter.fire();
     this.variables$.next(this.variables);
     this.parentTable?.fireChange();
   }
+  /**
+   * The current version of the variable table, incremented on each change.
+   */
   get version() {
     return this._version;
   }
+  /**
+   * Increments the version number, resetting to 0 if it reaches MAX_SAFE_INTEGER.
+   */
   bumpVersion() {
     this._version = this._version + 1;
     if (this._version === Number.MAX_SAFE_INTEGER) {
       this._version = 0;
     }
   }
+  /**
+   * An array of all variables in the table.
+   */
   get variables() {
     return Array.from(this.table.values());
   }
+  /**
+   * An array of all variable keys in the table.
+   */
   get variableKeys() {
     return Array.from(this.table.keys());
   }
   /**
-   * 根据 keyPath 找到对应的变量，或 Property 节点
-   * @param keyPath
-   * @returns
+   * 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 || [];
@@ -147,16 +165,17 @@ var VariableTable = class {
     return propertyKeys.length ? variable?.getByKeyPath(propertyKeys) : variable;
   }
   /**
-   * 根据 key 值找到相应的变量
-   * @param key
-   * @returns
+   * 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);
   }
   /**
-   * 往 variableTable 添加输出变量
-   * @param variable
+   * 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);
@@ -165,8 +184,9 @@ var VariableTable = class {
     }
   }
   /**
-   * 从 variableTable 中移除变量
-   * @param key
+   * 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);
@@ -174,6 +194,9 @@ var VariableTable = class {
       this.parentTable.removeVariableFromTable(key);
     }
   }
+  /**
+   * Disposes of all resources used by the variable table.
+   */
   dispose() {
     this.variableKeys.forEach(
       (_key) => this.parentTable?.removeVariableFromTable(_key)
@@ -202,7 +225,7 @@ var ScopeChain = class {
     return this.variableEngineProvider();
   }
   /**
-   * 所有作用域依赖关系刷新
+   * Refreshes the dependency and coverage relationships for all scopes.
    */
   refreshAllChange() {
     this.variableEngine.getAllScopes().forEach((_scope) => {
@@ -286,6 +309,19 @@ 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) => {
@@ -299,8 +335,10 @@ var ASTMatch;
   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;
@@ -346,19 +384,6 @@ function isMatchAST(node, targetType) {
   return ASTMatch.is(node, targetType);
 }
 
-// src/ast/flags.ts
-var ASTNodeFlags = /* @__PURE__ */ ((ASTNodeFlags2) => {
-  ASTNodeFlags2[ASTNodeFlags2["None"] = 0] = "None";
-  ASTNodeFlags2[ASTNodeFlags2["VariableField"] = 1] = "VariableField";
-  ASTNodeFlags2[ASTNodeFlags2["Expression"] = 4] = "Expression";
-  ASTNodeFlags2[ASTNodeFlags2["BasicType"] = 8] = "BasicType";
-  ASTNodeFlags2[ASTNodeFlags2["DrilldownType"] = 16] = "DrilldownType";
-  ASTNodeFlags2[ASTNodeFlags2["EnumerateType"] = 32] = "EnumerateType";
-  ASTNodeFlags2[ASTNodeFlags2["UnionType"] = 64] = "UnionType";
-  ASTNodeFlags2[ASTNodeFlags2["VariableType"] = 120] = "VariableType";
-  return ASTNodeFlags2;
-})(ASTNodeFlags || {});
-
 // src/ast/ast-node.ts
 import {
   BehaviorSubject,
@@ -374,41 +399,44 @@ import { shallowEqual } from "fast-equals";
 import { Disposable as Disposable2, DisposableCollection as DisposableCollection3 } from "@flowgram.ai/utils";
 var ASTNode = class _ASTNode {
   /**
-   * 构造函数
-   * @param createParams 创建 ASTNode 的必要参数
-   * @param injectOptions 依赖注入各种模块
+   * Constructor.
+   * @param createParams Necessary parameters for creating an ASTNode.
+   * @param injectOptions Dependency injection for various modules.
    */
   constructor({ key, parent, scope }, opts) {
     /**
-     * 节点 Flags，记录一些 Flag 信息
+     * Node flags, used to record some flag information.
      */
     this.flags = 0 /* None */;
     /**
-     * 节点的版本号，每 fireChange 一次 version + 1
+     * The version number of the ASTNode, which increments by 1 each time `fireChange` is called.
      */
     this._version = 0;
     /**
-     * 更新锁
+     * Update lock.
+     * - When set to `true`, `fireChange` will not trigger any events.
+     * - This is useful when multiple updates are needed, and you want to avoid multiple triggers.
      */
     this.changeLocked = false;
     /**
-     * Batch Update 相关参数
+     * Parameters related to batch updates.
      */
     this._batch = {
       batching: false,
       hasChangesInBatch: false
     };
     /**
-     * AST 节点变化事件，基于 Rxjs 实现
-     * - 使用了 BehaviorSubject, 在订阅时会自动触发一次事件，事件为当前值
+     * AST node change Observable events, implemented based on RxJS.
+     * - Emits the current ASTNode value upon subscription.
+     * - Emits a new value whenever `fireChange` is called.
      */
     this.value$ = new BehaviorSubject(this);
     /**
-     * 子节点
+     * Child ASTNodes.
      */
     this._children = /* @__PURE__ */ new Set();
     /**
-     * 删除节点处理事件列表
+     * List of disposal handlers for the ASTNode.
      */
     this.toDispose = new DisposableCollection3(
       Disposable2.create(() => {
@@ -417,7 +445,7 @@ var ASTNode = class _ASTNode {
       })
     );
     /**
-     * 销毁时触发的回调
+     * Callback triggered upon disposal.
      */
     this.onDispose = this.toDispose.onDispose;
     this.scope = scope;
@@ -427,7 +455,7 @@ var ASTNode = class _ASTNode {
     this.fromJSON = this.withBatchUpdate(this.fromJSON.bind(this));
   }
   /**
-   * AST 节点的类型
+   * The type of the ASTNode.
    */
   get kind() {
     if (!this.constructor.kind) {
@@ -436,13 +464,13 @@ var ASTNode = class _ASTNode {
     return this.constructor.kind;
   }
   /**
-   * 获取当前节点所有子节点
+   * Gets all child ASTNodes of the current ASTNode.
    */
   get children() {
     return Array.from(this._children);
   }
   /**
-   * 转化为 ASTNodeJSON
+   * Serializes the current ASTNode to ASTNodeJSON.
    * @returns
    */
   toJSON() {
@@ -452,8 +480,8 @@ var ASTNode = class _ASTNode {
     };
   }
   /**
-   * 创建子节点
-   * @param json 子节点的 AST JSON
+   * Creates a child ASTNode.
+   * @param json The AST JSON of the child ASTNode.
    * @returns
    */
   createChildNode(json) {
@@ -471,8 +499,8 @@ var ASTNode = class _ASTNode {
     return child;
   }
   /**
-   * 更新子节点，快速实现子节点更新消费逻辑
-   * @param keyInThis 当前对象上的指定 key
+   * Updates a child ASTNode, quickly implementing the consumption logic for child ASTNode updates.
+   * @param keyInThis The specified key on the current object.
    */
   updateChildNodeByKey(keyInThis, nextJSON) {
     this.withBatchUpdate(updateChildNodeHelper).call(this, {
@@ -483,8 +511,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) {
@@ -504,7 +532,7 @@ var ASTNode = class _ASTNode {
     };
   }
   /**
-   * 触发当前节点更新
+   * Triggers an update for the current node.
    */
   fireChange() {
     if (this.changeLocked || this.disposed) {
@@ -520,22 +548,24 @@ var ASTNode = class _ASTNode {
     this.parent?.fireChange();
   }
   /**
-   * 节点的版本值
-   * - 通过 NodeA === NodeB && versionA === versionB 可以比较两者是否相等
+   * The version value of the ASTNode.
+   * - You can used to check whether ASTNode are updated.
    */
   get version() {
     return this._version;
   }
   /**
-   * 节点唯一 hash 值
+   * The unique hash value of the ASTNode.
+   * - It will update when the ASTNode is updated.
+   * - You can used to check two ASTNode are equal.
    */
   get hash() {
     return `${this._version}${this.kind}${this.key}`;
   }
   /**
-   * 监听 AST 节点的变化
-   * @param observer 监听回调
-   * @param selector 监听指定数据
+   * Listens for changes to the ASTNode.
+   * @param observer The listener callback.
+   * @param selector Listens for specified data.
    * @returns
    */
   subscribe(observer, { selector, debounceAnimation, triggerOnInit } = {}) {
@@ -551,13 +581,17 @@ var ASTNode = class _ASTNode {
             return value;
           }
         ),
-        // 默认跳过 BehaviorSubject 第一次触发
+        // By default, skip the first trigger of BehaviorSubject.
         triggerOnInit ? tap(() => null) : skip2(1),
-        // 每个 animationFrame 内所有更新合并成一个
+        // All updates within each animationFrame are merged into one.
         debounceAnimation ? debounceTime(0, animationFrameScheduler) : tap(() => null)
       ).subscribe(observer)
     );
   }
+  /**
+   * Dispatches a global event for the current ASTNode.
+   * @param event The global event.
+   */
   dispatchGlobalEvent(event) {
     this.scope.event.dispatch({
       ...event,
@@ -565,7 +599,7 @@ var ASTNode = class _ASTNode {
     });
   }
   /**
-   * 销毁
+   * Disposes the ASTNode.
    */
   dispose() {
     if (this.toDispose.disposed) {
@@ -588,8 +622,9 @@ var BaseType = class extends ASTNode {
     this.flags = 8 /* BasicType */;
   }
   /**
-   * 类型是否一致
-   * @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);
@@ -601,15 +636,18 @@ 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}`);
   }
   /**
-   * Get AST JSON for current base type
-   * @returns
+   * Serialize the node to a JSON object.
+   * @returns The JSON representation of the node.
    */
   toJSON() {
     return {
@@ -624,13 +662,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) {
@@ -638,19 +687,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) {
@@ -658,6 +712,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 */,
@@ -674,11 +732,16 @@ var StringType = class extends BaseType {
     this.flags = 8 /* BasicType */;
   }
   /**
-   * https://json-schema.org/understanding-json-schema/reference/type#format
+   * 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;
@@ -694,6 +757,10 @@ var IntegerType = class extends BaseType {
     super(...arguments);
     this.flags = 8 /* BasicType */;
   }
+  /**
+   * Deserializes the `IntegerJSON` to the `IntegerType`.
+   * @param json The `IntegerJSON` to deserialize.
+   */
   fromJSON() {
   }
 };
@@ -701,6 +768,10 @@ 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() {
   }
 };
@@ -708,6 +779,10 @@ 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() {
   }
 };
@@ -715,40 +790,42 @@ 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 */,
@@ -757,7 +834,6 @@ var MapType = class extends BaseType {
     };
   }
 };
-// public flags: ASTNodeFlags = ASTNodeFlags.DrilldownType | ASTNodeFlags.EnumerateType;
 MapType.kind = "Map" /* Map */;
 
 // src/ast/type/object.ts
@@ -766,8 +842,15 @@ 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 || []];
@@ -801,6 +884,10 @@ var ObjectType = class extends BaseType {
       }
     });
   }
+  /**
+   * Serialize the `ObjectType` to `ObjectJSON`.
+   * @returns The JSON representation of `ObjectType`.
+   */
   toJSON() {
     return {
       kind: "Object" /* Object */,
@@ -808,9 +895,9 @@ var ObjectType = class extends BaseType {
     };
   }
   /**
-   * 根据 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;
@@ -823,19 +910,24 @@ var ObjectType = class extends BaseType {
     }
     return void 0;
   }
+  /**
+   * Check if the current type is equal to the target type.
+   * @param targetTypeJSONOrKind The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
+   */
   isTypeEqual(targetTypeJSONOrKind) {
     const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
     const isSuperEqual = super.isTypeEqual(targetTypeJSONOrKind);
     if (targetTypeJSON?.weak || targetTypeJSON?.kind === "Union" /* Union */) {
       return isSuperEqual;
     }
-    return targetTypeJSON && isSuperEqual && // 弱比较，只需要比较 Kind 即可
+    return targetTypeJSON && isSuperEqual && // Weak comparison, only need to compare the Kind.
     (targetTypeJSON?.weak || this.customStrongEqual(targetTypeJSON));
   }
   /**
-   * Object 类型强比较
-   * @param targetTypeJSON
-   * @returns
+   * Object type strong comparison.
+   * @param targetTypeJSON The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
    */
   customStrongEqual(targetTypeJSON) {
     const targetProperties = targetTypeJSON.properties || [];
@@ -852,15 +944,27 @@ ObjectType.kind = "Object" /* Object */;
 
 // src/ast/type/custom-type.ts
 var CustomType = class extends BaseType {
+  /**
+   * The name of the custom type.
+   */
   get typeName() {
     return this._typeName;
   }
+  /**
+   * Deserializes the `CustomTypeJSON` to the `CustomType`.
+   * @param json The `CustomTypeJSON` to deserialize.
+   */
   fromJSON(json) {
     if (this._typeName !== json.typeName) {
       this._typeName = json.typeName;
       this.fireChange();
     }
   }
+  /**
+   * Check if the current type is equal to the target type.
+   * @param targetTypeJSONOrKind The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
+   */
   isTypeEqual(targetTypeJSONOrKind) {
     const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
     if (targetTypeJSON?.kind === "Union" /* Union */) {
@@ -904,13 +1008,12 @@ var BaseExpression = class extends ASTNode {
     super(params, opts);
     this.flags = 4 /* Expression */;
     /**
-     * 引用变量
+     * The variable fields referenced by the expression.
      */
     this._refs = [];
     this.refreshRefs$ = new Subject2();
     /**
-     * 监听引用变量变化
-     * 监听 [a.b.c] -> [a.b]
+     * An observable that emits the referenced variable fields when they change.
      */
     this.refs$ = this.refreshRefs$.pipe(
       map2(() => this.getRefFields()),
@@ -934,91 +1037,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/keypath-expression.ts
-import { shallowEqual as shallowEqual3 } from "fast-equals";
-var KeyPathExpression = class extends BaseExpression {
-  constructor(params, opts) {
-    super(params, opts);
-    this._keyPath = [];
-    this.toDispose.pushAll([
-      // 可以用变量列表变化时候 (有新增或者删除时)
-      this.scope.available.onVariableListChange(() => {
-        this.refreshRefs();
-      }),
-      // this._keyPath 指向的可引用变量发生变化时，刷新引用数据
-      this.scope.available.onAnyVariableChange((_v) => {
-        if (_v.key === this._keyPath[0]) {
-          this.refreshRefs();
-        }
-      })
-    ]);
-  }
-  get keyPath() {
-    return this._keyPath;
-  }
-  getRefFields() {
-    const ref = this.scope.available.getByKeyPath(this._keyPath);
-    return ref ? [ref] : [];
-  }
-  get returnType() {
-    const [refNode] = this._refs || [];
-    if (refNode && refNode.flags & 1 /* VariableField */) {
-      return refNode.type;
-    }
-    return;
-  }
-  /**
-   * 业务重改该方法可快速定制自己的 Path 表达式
-   * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-   * @param json 业务定义的 Path 表达式
-   * @returns
-   */
-  parseToKeyPath(json) {
-    return json.keyPath;
-  }
-  fromJSON(json) {
-    const keyPath = this.parseToKeyPath(json);
-    if (!shallowEqual3(keyPath, this._keyPath)) {
-      this._keyPath = keyPath;
-      this.refreshRefs();
-    }
-  }
-  toJSON() {
-    return {
-      kind: "KeyPathExpression" /* KeyPathExpression */,
-      keyPath: this._keyPath
-    };
-  }
-};
-KeyPathExpression.kind = "KeyPathExpression" /* KeyPathExpression */;
-
 // src/ast/expression/enumerate-expression.ts
 var EnumerateExpression = class extends BaseExpression {
+  /**
+   * The expression to be enumerated.
+   */
   get enumerateFor() {
     return this._enumerateFor;
   }
+  /**
+   * The return type of the expression.
+   */
   get returnType() {
     const childReturnType = this.enumerateFor?.returnType;
     if (childReturnType?.kind === "Array" /* Array */) {
@@ -1026,12 +1080,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 */,
@@ -1041,8 +1107,8 @@ var EnumerateExpression = class extends BaseExpression {
 };
 EnumerateExpression.kind = "EnumerateExpression" /* EnumerateExpression */;
 
-// src/ast/expression/keypath-expression-v2.ts
-import { shallowEqual as shallowEqual4 } from "fast-equals";
+// src/ast/expression/keypath-expression.ts
+import { shallowEqual as shallowEqual3 } from "fast-equals";
 
 // src/ast/utils/expression.ts
 import { intersection } from "lodash-es";
@@ -1065,17 +1131,17 @@ function checkRefCycle(curr, refNodes) {
   return intersection(Array.from(visited), getParentFields(curr)).length > 0;
 }
 
-// src/ast/expression/keypath-expression-v2.ts
-var KeyPathExpressionV2 = class extends BaseExpression {
+// src/ast/expression/keypath-expression.ts
+var KeyPathExpression = class extends BaseExpression {
   constructor(params, opts) {
     super(params, opts);
     this._keyPath = [];
     this.toDispose.pushAll([
-      // 可以用变量列表变化时候 (有新增或者删除时)
+      // Can be used when the variable list changes (when there are additions or deletions).
       this.scope.available.onVariableListChange(() => {
         this.refreshRefs();
       }),
-      // this._keyPath 指向的可引用变量发生变化时，刷新引用数据
+      // When the referable variable pointed to by this._keyPath changes, refresh the reference data.
       this.scope.available.onAnyVariableChange((_v) => {
         if (_v.key === this._keyPath[0]) {
           this.refreshRefs();
@@ -1092,9 +1158,16 @@ var KeyPathExpressionV2 = class extends BaseExpression {
       )
     ]);
   }
+  /**
+   * 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])) {
@@ -1106,28 +1179,122 @@ var KeyPathExpressionV2 = class extends BaseExpression {
     }
     return ref ? [ref] : [];
   }
+  /**
+   * The return type of the expression.
+   */
   get returnType() {
     return this._returnType;
   }
   /**
-   * 业务重改该方法可快速定制自己的 Path 表达式
-   * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-   * @param json 业务定义的 Path 表达式
-   * @returns
+   * Parse the business-defined path expression into a key path.
+   *
+   * Businesses can quickly customize their own path expressions by modifying this method.
+   * @param json The path expression defined by the business.
+   * @returns The key path.
    */
   parseToKeyPath(json) {
     return json.keyPath;
   }
+  /**
+   * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+   * @param json The `KeyPathExpressionJSON` to deserialize.
+   */
   fromJSON(json) {
     const keyPath = this.parseToKeyPath(json);
-    if (!shallowEqual4(keyPath, this._keyPath)) {
+    if (!shallowEqual3(keyPath, this._keyPath)) {
       this._keyPath = keyPath;
       this.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 {
+      kind: "KeyPathExpression" /* KeyPathExpression */,
+      keyPath: this._keyPath
+    };
+  }
+};
+KeyPathExpression.kind = "KeyPathExpression" /* KeyPathExpression */;
+
+// src/ast/expression/legacy-keypath-expression.ts
+import { shallowEqual as shallowEqual4 } from "fast-equals";
+var LegacyKeyPathExpression = class extends BaseExpression {
+  constructor(params, opts) {
+    super(params, opts);
+    this._keyPath = [];
+    this.toDispose.pushAll([
+      // Can be used when the variable list changes (when there are additions or deletions).
+      this.scope.available.onVariableListChange(() => {
+        this.refreshRefs();
+      }),
+      // When the referable variable pointed to by this._keyPath changes, refresh the reference data.
+      this.scope.available.onAnyVariableChange((_v) => {
+        if (_v.key === this._keyPath[0]) {
+          this.refreshRefs();
+        }
+      })
+    ]);
+  }
+  /**
+   * The key path of the variable.
+   */
+  get keyPath() {
+    return this._keyPath;
+  }
+  /**
+   * Get the variable fields referenced by the expression.
+   * @returns An array of referenced variable fields.
+   */
+  getRefFields() {
+    const ref = this.scope.available.getByKeyPath(this._keyPath);
+    return ref ? [ref] : [];
+  }
+  /**
+   * The return type of the expression.
+   */
+  get returnType() {
+    const [refNode] = this._refs || [];
+    if (refNode && refNode.flags & 1 /* VariableField */) {
+      return refNode.type;
+    }
+    return;
+  }
+  /**
+   * Parse the business-defined path expression into a key path.
+   *
+   * Businesses can quickly customize their own path expressions by modifying this method.
+   * @param json The path expression defined by the business.
+   * @returns The key path.
+   */
+  parseToKeyPath(json) {
+    return json.keyPath;
+  }
+  /**
+   * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+   * @param json The `KeyPathExpressionJSON` to deserialize.
+   */
+  fromJSON(json) {
+    const keyPath = this.parseToKeyPath(json);
+    if (!shallowEqual4(keyPath, this._keyPath)) {
+      this._keyPath = keyPath;
+      this.refreshRefs();
+    }
+  }
+  /**
+   * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+   * @returns The JSON representation of `KeyPathExpression`.
+   */
   toJSON() {
     return {
       kind: "KeyPathExpression" /* KeyPathExpression */,
@@ -1135,16 +1302,25 @@ var KeyPathExpressionV2 = class extends BaseExpression {
     };
   }
 };
-KeyPathExpressionV2.kind = "KeyPathExpression" /* KeyPathExpression */;
+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", {
@@ -1152,12 +1328,24 @@ var WrapArrayExpression = class extends BaseExpression {
       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: "WrapArrayExpression" /* WrapArrayExpression */,
@@ -1188,41 +1376,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;
   }
+  /**
+   * The global unique hash of the field, and will be changed when the field is updated.
+   */
   get hash() {
     return `[${this._version}]${this.keyPath.join(".")}`;
   }
   /**
-   * 解析 VariableDeclarationJSON 从而生成变量声明节点
+   * Deserialize the `BaseVariableFieldJSON` to the `BaseVariableField`.
+   * @param json ASTJSON representation of `BaseVariableField`
    */
   fromJSON({ type, initializer, meta }) {
     this.updateType(type);
     this.updateInitializer(initializer);
     this.updateMeta(meta);
   }
+  /**
+   * Update the type of the variable field
+   * @param type type ASTJSON representation of Type
+   */
   updateType(type) {
     const nextTypeJson = typeof type === "string" ? { kind: type } : type;
     this.updateChildNodeByKey("_type", nextTypeJson);
   }
+  /**
+   * Update the initializer of the variable field
+   * @param nextInitializer initializer ASTJSON representation of Expression
+   */
   updateInitializer(nextInitializer) {
     this.updateChildNodeByKey("_initializer", nextInitializer);
   }
+  /**
+   * Update the meta data of the variable field
+   * @param nextMeta meta data of the variable field
+   */
   updateMeta(nextMeta) {
     if (!shallowEqual5(nextMeta, this._meta)) {
       this._meta = nextMeta;
@@ -1230,7 +1450,8 @@ var BaseVariableField = class extends ASTNode {
     }
   }
   /**
-   * 根据 keyPath 去找下钻的变量字段
+   * Get the variable field by keyPath, similar to js code:
+   * `v.a.b`
    * @param keyPath
    * @returns
    */
@@ -1241,7 +1462,7 @@ var BaseVariableField = class extends ASTNode {
     return void 0;
   }
   /**
-   * 监听类型变化
+   * Subscribe to type change of the variable field
    * @param observer
    * @returns
    */
@@ -1249,8 +1470,8 @@ 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 {
@@ -1269,16 +1490,23 @@ var VariableDeclaration = class extends BaseVariableField {
     super(params);
     this._order = 0;
   }
+  /**
+   * 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;
@@ -1288,10 +1516,6 @@ var VariableDeclaration = class extends BaseVariableField {
       this.fireChange();
     }
   }
-  // 监听类型变化
-  onTypeChange(observer) {
-    return this.subscribe(observer, { selector: (curr) => curr.type });
-  }
 };
 VariableDeclaration.kind = "VariableDeclaration" /* VariableDeclaration */;
 
@@ -1299,8 +1523,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 || []];
@@ -1340,10 +1574,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())
     };
   }
 };
@@ -1357,9 +1595,16 @@ Property.kind = "Property" /* Property */;
 // src/ast/common/data-node.ts
 import { shallowEqual as shallowEqual6 } from "fast-equals";
 var DataNode = class extends ASTNode {
+  /**
+   * The data of the node.
+   */
   get data() {
     return this._data;
   }
+  /**
+   * Deserializes the `DataNodeJSON` to the `DataNode`.
+   * @param json The `DataNodeJSON` to deserialize.
+   */
   fromJSON(json) {
     const { kind, ...restData } = json;
     if (!shallowEqual6(restData, this._data)) {
@@ -1367,12 +1612,20 @@ var DataNode = class extends ASTNode {
       this.fireChange();
     }
   }
+  /**
+   * Serialize the `DataNode` to `DataNodeJSON`.
+   * @returns The JSON representation of `DataNode`.
+   */
   toJSON() {
     return {
       kind: "DataNode" /* DataNode */,
       ...this._data
     };
   }
+  /**
+   * Partially update the data of the node.
+   * @param nextData The data to be updated.
+   */
   partialUpdate(nextData) {
     if (!shallowEqual6(nextData, this._data)) {
       this._data = {
@@ -1387,9 +1640,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();
@@ -1406,6 +1666,10 @@ var ListNode = class extends ASTNode {
       return prevItem;
     });
   }
+  /**
+   * Serialize the `ListNode` to `ListNodeJSON`.
+   * @returns The JSON representation of `ListNode`.
+   */
   toJSON() {
     return {
       kind: "ListNode" /* ListNode */,
@@ -1421,6 +1685,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 || []) {
@@ -1431,6 +1699,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 */,
@@ -1438,9 +1710,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, {
@@ -1451,8 +1724,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();
@@ -1460,9 +1733,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);
@@ -1473,7 +1746,7 @@ MapNode.kind = "MapNode" /* MapNode */;
 // src/ast/ast-registers.ts
 var ASTRegisters = class {
   /**
-   * 核心 AST 节点注册
+   * Core AST node registration.
    */
   constructor() {
     this.injectors = /* @__PURE__ */ new Map();
@@ -1489,15 +1762,15 @@ var ASTRegisters = class {
     this.registerAST(Property);
     this.registerAST(VariableDeclaration);
     this.registerAST(VariableDeclarationList);
-    this.registerAST(KeyPathExpressionV2);
+    this.registerAST(KeyPathExpression);
     this.registerAST(EnumerateExpression);
     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 }) {
@@ -1525,7 +1798,7 @@ var ASTRegisters = class {
     return node;
   }
   /**
-   * 根据 AST 节点类型获取节点 Registry
+   * Gets the node Registry by AST node type.
    * @param kind
    * @returns
    */
@@ -1533,7 +1806,7 @@ var ASTRegisters = class {
     return this.astMap.get(kind);
   }
   /**
-   * 注册 AST 节点
+   * Registers an AST node.
    * @param ASTNode
    * @param injector
    */
@@ -1613,7 +1886,7 @@ var ScopeOutputData = class {
     this._hasChanges = false;
     this.variableTable = new VariableTable(scope.variableEngine.globalVariableTable);
     this.scope.toDispose.pushAll([
-      // When root AST node is updated, check if there are any changes during this AST change
+      // When the root AST node is updated, check if there are any changes.
       this.scope.ast.subscribe(() => {
         if (this._hasChanges) {
           this.memo.clear();
@@ -1638,12 +1911,21 @@ var ScopeOutputData = class {
       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;
   }
@@ -1654,25 +1936,25 @@ var ScopeOutputData = class {
     return this.variableTable.onDataChange.bind(this.variableTable);
   }
   /**
-   * listen to variable list change
+   * An event that fires when the list of output variables changes.
    */
   get onVariableListChange() {
     return this.variableTable.onVariableListChange.bind(this.variableTable);
   }
   /**
-   * listen to any variable update in list
+   * An event that fires when any output variable's value changes.
    */
   get onAnyVariableChange() {
     return this.variableTable.onAnyVariableChange.bind(this.variableTable);
   }
   /**
-   * listen to variable list change + any variable update in list
+   * 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);
   }
   /**
-   * Scope Output Variable Declarations
+   * The output variable declarations of the scope, sorted by order.
    */
   get variables() {
     return this.memo(
@@ -1681,7 +1963,7 @@ var ScopeOutputData = class {
     );
   }
   /**
-   * Output Variable Keys
+   * The keys of the output variables.
    */
   get variableKeys() {
     return this.memo("variableKeys", () => this.variableTable.variableKeys);
@@ -1697,11 +1979,16 @@ var ScopeOutputData = class {
     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());
@@ -1734,22 +2021,24 @@ var ScopeAvailableData = class {
     this.refresh$ = new Subject3();
     this._variables = [];
     /**
-     * 监听
+     * An observable that emits when the list of available variables changes.
      */
     this.variables$ = this.refresh$.pipe(
-      // 输出变量是否 version 发生变化
+      // Map to the flattened list of variables from all dependency scopes.
       map3(() => flatten(this.depScopes.map((scope) => scope.output.variables || []))),
-      // 变量列表浅比较
+      // Use shallow equality to check if the variable list has changed.
       distinctUntilChanged3(shallowEqual7),
       share3()
     );
-    // 监听变量列表中的单个变量变化
+    /**
+     * An observable that emits when any variable in the available list changes its value.
+     */
     this.anyVariableChange$ = this.variables$.pipe(
       switchMap3(
         (_variables) => merge2(
           ..._variables.map(
             (_v) => _v.value$.pipe(
-              // 跳过 BehaviorSubject 第一个
+              // Skip the initial value of the BehaviorSubject.
               skip3(1)
             )
           )
@@ -1767,7 +2056,7 @@ var ScopeAvailableData = class {
      */
     this.onDataChange = this.onDataChangeEmitter.event;
     /**
-     * listen to variable list change + any variable drilldown change
+     * 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([
@@ -1789,9 +2078,15 @@ var ScopeAvailableData = class {
       })
     ]);
   }
+  /**
+   * 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;
   }
@@ -1801,7 +2096,10 @@ var ScopeAvailableData = class {
       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;
@@ -1809,43 +2107,43 @@ var ScopeAvailableData = class {
     this.refresh$.next();
   }
   /**
-   * listen to any variable update in list
-   * @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));
   }
   /**
-   * listen to variable list change
-   * @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])) {
@@ -1854,8 +2152,12 @@ var ScopeAvailableData = class {
     return this.globalVariableTable.getByKeyPath(keyPath);
   }
   /**
-   * Track Variable Change (Includes type update and children update) By KeyPath
-   * @returns
+   * 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 || {};
@@ -1875,7 +2177,7 @@ var ScopeAvailableData = class {
             return value;
           }
         ),
-        // 每个 animationFrame 内所有更新合并成一个
+        // Debounce updates to a single emission per animation frame.
         debounceAnimation ? debounceTime2(0, animationFrameScheduler2) : tap2(() => null)
       ).subscribe(cb)
     );
@@ -1894,15 +2196,30 @@ var ScopeEventData = class {
       })
     ]);
   }
+  /**
+   * Dispatches a global event.
+   * @param action The event action to dispatch.
+   */
   dispatch(action) {
     if (this.scope.disposed) {
       return;
     }
     this.event$.next(action);
   }
+  /**
+   * Subscribes to all global events.
+   * @param observer The observer function to call with the event action.
+   * @returns A disposable to unsubscribe from the events.
+   */
   subscribe(observer) {
     return subsToDisposable(this.event$.subscribe(observer));
   }
+  /**
+   * Subscribes to a specific type of global event.
+   * @param type The type of the event to subscribe to.
+   * @param observer The observer function to call with the event action.
+   * @returns A disposable to unsubscribe from the event.
+   */
   on(type, observer) {
     return subsToDisposable(
       this.event$.pipe(filter((_action) => _action.type === type)).subscribe(observer)
@@ -1914,7 +2231,7 @@ var ScopeEventData = class {
 var Scope = class {
   constructor(options) {
     /**
-     * 数据缓存
+     * A memoization utility for caching computed values.
      */
     this.memo = createMemo();
     this.toDispose = new DisposableCollection4();
@@ -1935,25 +2252,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();
@@ -1973,19 +2306,18 @@ var Scope = class {
     throw new Error("Invalid arguments");
   }
   /**
-   * Retrieves a variable from the Scope by key.
+   * Retrieves a variable from the scope by its key.
    *
-   * @param key - The key of the variable to retrieve. Defaults to 'outputs'.
-   * @returns The value of the variable, or undefined if not found.
+   * @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 key.
+   * Clears a variable from the scope by its key.
    *
-   * @param key - The key of the variable to clear. Defaults to 'outputs'.
-   * @returns The updated AST node.
+   * @param key The key of the variable to clear. Defaults to 'outputs'.
    */
   clearVar(key = "outputs") {
     return this.ast.remove(key);
@@ -2000,9 +2332,18 @@ var VariableEngine = class {
     this.toDispose = new DisposableCollection5();
     this.memo = createMemo();
     this.scopeMap = /* @__PURE__ */ new Map();
+    /**
+     * A rxjs subject that emits global events occurring within the variable engine.
+     */
     this.globalEvent$ = new Subject5();
     this.onScopeChangeEmitter = new Emitter3();
+    /**
+     * A table containing all global variables.
+     */
     this.globalVariableTable = new VariableTable();
+    /**
+     * An event that fires whenever a scope is added, updated, or deleted.
+     */
     this.onScopeChange = this.onScopeChangeEmitter.event;
     this.toDispose.pushAll([
       chain,
@@ -2012,26 +2353,37 @@ var VariableEngine = class {
       })
     ]);
   }
+  /**
+   * 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();
   }
   /**
-   * Get Scope, if Scope exists and type is same, will use it directly
-   * @param id scope id
-   * @param meta scope meta, defined by user
-   * @param ScopeConstructor scope constructor, default is Scope. you can extends Scope to create your own scope
-   * @returns
+   * 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;
@@ -2044,7 +2396,7 @@ var VariableEngine = class {
         scope.ast.subscribe(() => {
           this.onScopeChangeEmitter.fire({ type: "update", scope });
         }),
-        // 可用变量发生变化
+        // Fires when available variables change
         scope.available.onDataChange(() => {
           this.onScopeChangeEmitter.fire({ type: "available", scope });
         })
@@ -2056,7 +2408,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
   } = {}) {
@@ -2069,9 +2426,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) => {
@@ -2102,11 +2469,26 @@ var VariableFieldKeyRenameService = class {
   constructor() {
     this.toDispose = new DisposableCollection6();
     this.renameEmitter = new Emitter4();
-    // 没有被 rename 的字段通过 disposeInList 透出，让业务区分变量是 rename 删除的，还是真正从列表中删除的
+    /**
+     * Emits events for fields that are disposed of during a list change, but not renamed.
+     * This helps distinguish between a field that was truly removed and one that was renamed.
+     */
     this.disposeInListEmitter = new Emitter4();
+    /**
+     * An event that fires when a variable field key is successfully renamed.
+     */
     this.onRename = this.renameEmitter.event;
+    /**
+     * An event that fires when a field is removed from a list (and not part of a rename).
+     */
     this.onDisposeInList = this.disposeInListEmitter.event;
   }
+  /**
+   * Handles changes in a list of fields to detect rename operations.
+   * @param ast The AST node where the change occurred.
+   * @param prev The list of fields before the change.
+   * @param next The list of fields after the change.
+   */
   handleFieldListChange(ast, prev, next) {
     if (!ast || !prev?.length || !next?.length) {
       this.notifyFieldsDispose(prev, next);
@@ -2137,6 +2519,11 @@ var VariableFieldKeyRenameService = class {
     }
     this.renameEmitter.fire(renameNodeInfo);
   }
+  /**
+   * Notifies listeners about fields that were removed from a list.
+   * @param prev The list of fields before the change.
+   * @param next The list of fields after the change.
+   */
   notifyFieldsDispose(prev, next) {
     const removedFields = difference(prev || [], next || []);
     removedFields.forEach((_field) => this.disposeInListEmitter.fire(_field));
@@ -2184,28 +2571,48 @@ var VariableContainerModule = new ContainerModule((bind) => {
 });
 
 // src/react/context.tsx
-import { createContext, useContext } from "react";
+import React, { createContext, useContext } from "react";
 var ScopeContext = createContext(null);
-var ScopeProvider = ScopeContext.Provider;
-var useScopeContext = () => useContext(ScopeContext);
-var useCurrentScope = () => useContext(ScopeContext)?.scope;
+var ScopeProvider = (props) => {
+  const { scope, value, children } = props;
+  const scopeToUse = scope || value?.scope;
+  if (!scopeToUse) {
+    throw new Error("[ScopeProvider] scope is required");
+  }
+  return /* @__PURE__ */ React.createElement(ScopeContext.Provider, { value: { scope: scopeToUse } }, children);
+};
+var useCurrentScope = (params) => {
+  const { strict = false } = params || {};
+  const context = useContext(ScopeContext);
+  if (!context) {
+    if (strict) {
+      throw new Error("useCurrentScope must be used within a <ScopeProvider scope={scope}>");
+    }
+    console.warn("useCurrentScope should be used within a <ScopeProvider scope={scope}>");
+  }
+  return context?.scope;
+};
 
-// src/react/hooks/useScopeAvailable.ts
+// src/react/hooks/use-scope-available.ts
 import { useEffect } from "react";
 import { useRefresh } from "@flowgram.ai/core";
-function useScopeAvailable() {
-  const scope = useCurrentScope();
+function useScopeAvailable(params) {
+  const { autoRefresh = true } = params || {};
+  const scope = useCurrentScope({ strict: true });
   const refresh = useRefresh();
   useEffect(() => {
-    const disposable = scope.available.onDataChange(() => {
+    if (!autoRefresh) {
+      return () => null;
+    }
+    const disposable = scope.available.onListOrAnyVarChange(() => {
       refresh();
     });
     return () => disposable.dispose();
-  }, []);
+  }, [autoRefresh]);
   return scope.available;
 }
 
-// src/react/hooks/useAvailableVariables.ts
+// src/react/hooks/use-available-variables.ts
 import { useEffect as useEffect2 } from "react";
 import { useRefresh as useRefresh2, useService } from "@flowgram.ai/core";
 function useAvailableVariables() {
@@ -2226,6 +2633,26 @@ function useAvailableVariables() {
   }, []);
   return scope ? scope.available.variables : variableEngine.globalVariableTable.variables;
 }
+
+// src/react/hooks/use-output-variables.ts
+import { useEffect as useEffect3 } from "react";
+import { useRefresh as useRefresh3 } from "@flowgram.ai/core";
+function useOutputVariables() {
+  const scope = useCurrentScope();
+  const refresh = useRefresh3();
+  useEffect3(() => {
+    if (!scope) {
+      throw new Error(
+        "[useOutputVariables]: No scope found, useOutputVariables must be used in <ScopeProvider>"
+      );
+    }
+    const disposable = scope.output.onListOrAnyVarChange(() => {
+      refresh();
+    });
+    return () => disposable.dispose();
+  }, []);
+  return scope?.output.variables || [];
+}
 export {
   ASTFactory,
   ASTKind,
@@ -2243,7 +2670,7 @@ export {
   EnumerateExpression,
   IntegerType,
   KeyPathExpression,
-  KeyPathExpressionV2,
+  LegacyKeyPathExpression,
   ListNode,
   MapNode,
   MapType,
@@ -2267,7 +2694,7 @@ export {
   postConstructAST,
   useAvailableVariables,
   useCurrentScope,
-  useScopeAvailable,
-  useScopeContext
+  useOutputVariables,
+  useScopeAvailable
 };
 //# sourceMappingURL=index.js.map