@flowgram-vue/variable-core 0.2.0

package/src/scope/scope-chain.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { inject, injectable } from 'inversify';
+import { DisposableCollection, type Event } from '@flowgram-vue/utils';
+
+import { VariableEngineProvider } from '../providers';
+import { type Scope } from './scope';
+
+/**
+ * Manages the dependency relationships between scopes.
+ * This is an abstract class, and specific implementations determine how the scope order is managed.
+ */
+@injectable()
+export abstract class ScopeChain {
+  readonly toDispose: DisposableCollection = new DisposableCollection();
+
+  @inject(VariableEngineProvider) variableEngineProvider: VariableEngineProvider;
+
+  get variableEngine() {
+    return this.variableEngineProvider();
+  }
+
+  constructor() {}
+
+  /**
+   * Refreshes the dependency and coverage relationships for all scopes.
+   */
+  refreshAllChange(): void {
+    this.variableEngine.getAllScopes().forEach((_scope) => {
+      _scope.refreshCovers();
+      _scope.refreshDeps();
+    });
+  }
+
+  /**
+   * Gets the dependency scopes for a given scope.
+   * @param scope The scope to get dependencies for.
+   * @returns An array of dependency scopes.
+   */
+  abstract getDeps(scope: Scope): Scope[];
+
+  /**
+   * Gets the covering scopes for a given scope.
+   * @param scope The scope to get covers for.
+   * @returns An array of covering scopes.
+   */
+  abstract getCovers(scope: Scope): Scope[];
+
+  /**
+   * Sorts all scopes based on their dependency relationships.
+   * @returns A sorted array of all scopes.
+   */
+  abstract sortAll(): Scope[];
+
+  dispose(): void {
+    this.toDispose.dispose();
+  }
+
+  get disposed(): boolean {
+    return this.toDispose.disposed;
+  }
+
+  get onDispose(): Event<void> {
+    return this.toDispose.onDispose;
+  }
+}

package/src/scope/scope.ts

@@ -0,0 +1,200 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { DisposableCollection } from '@flowgram-vue/utils';
+
+import { type VariableEngine } from '../variable-engine';
+import { createMemo } from '../utils/memo';
+import { ASTKind, type ASTNode, type ASTNodeJSON, MapNode } from '../ast';
+import { ScopeAvailableData, ScopeEventData, ScopeOutputData } from './datas';
+
+/**
+ * Interface for the Scope constructor.
+ */
+export interface IScopeConstructor {
+  new (options: {
+    id: string | symbol;
+    variableEngine: VariableEngine;
+    meta?: Record<string, any>;
+  }): Scope;
+}
+
+/**
+ * Represents a variable scope, which manages its own set of variables and their lifecycle.
+ * - `scope.output` represents the variables declared within this scope.
+ * - `scope.available` represents all variables accessible from this scope, including those from parent scopes.
+ */
+export class Scope<ScopeMeta extends Record<string, any> = Record<string, any>> {
+  /**
+   * A unique identifier for the scope.
+   */
+  readonly id: string | symbol;
+
+  /**
+   * The variable engine instance this scope belongs to.
+   */
+  readonly variableEngine: VariableEngine;
+
+  /**
+   * Metadata associated with the scope, which can be extended by higher-level business logic.
+   */
+  readonly meta: ScopeMeta;
+
+  /**
+   * The root AST node for this scope, which is a MapNode.
+   * It stores various data related to the scope, such as `outputs`.
+   */
+  readonly ast: MapNode;
+
+  /**
+   * Manages the available variables for this scope.
+   */
+  readonly available: ScopeAvailableData;
+
+  /**
+   * Manages the output variables for this scope.
+   */
+  readonly output: ScopeOutputData;
+
+  /**
+   * Manages event dispatching and handling for this scope.
+   */
+  readonly event: ScopeEventData;
+
+  /**
+   * A memoization utility for caching computed values.
+   */
+  protected memo = createMemo();
+
+  public toDispose: DisposableCollection = new DisposableCollection();
+
+  constructor(options: { id: string | symbol; variableEngine: VariableEngine; meta?: ScopeMeta }) {
+    this.id = options.id;
+    this.meta = options.meta || ({} as any);
+    this.variableEngine = options.variableEngine;
+
+    this.event = new ScopeEventData(this);
+
+    this.ast = this.variableEngine.astRegisters.createAST(
+      {
+        kind: ASTKind.MapNode,
+        key: String(this.id),
+      },
+      {
+        scope: this,
+      }
+    ) as MapNode;
+
+    this.output = new ScopeOutputData(this);
+    this.available = new ScopeAvailableData(this);
+  }
+
+  /**
+   * Refreshes the covering scopes.
+   */
+  refreshCovers(): void {
+    this.memo.clear('covers');
+  }
+
+  /**
+   * Refreshes the dependency scopes and the available variables.
+   */
+  refreshDeps(): void {
+    this.memo.clear('deps');
+    this.available.refresh();
+  }
+
+  /**
+   * Gets the scopes that this scope depends on.
+   */
+  get depScopes(): Scope[] {
+    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(): Scope[] {
+    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(): void {
+    this.ast.dispose();
+    this.toDispose.dispose();
+
+    // When a scope is disposed, update its dependent and covering scopes.
+    this.coverScopes.forEach((_scope) => _scope.refreshDeps());
+    this.depScopes.forEach((_scope) => _scope.refreshCovers());
+  }
+
+  onDispose = this.toDispose.onDispose;
+
+  get disposed(): boolean {
+    return this.toDispose.disposed;
+  }
+
+  /**
+   * Sets a variable in the scope with the default key 'outputs'.
+   *
+   * @param json The JSON representation of the AST node to set.
+   * @returns The created or updated AST node.
+   */
+  public setVar<Node extends ASTNode = ASTNode>(json: ASTNodeJSON): Node;
+
+  /**
+   * Sets a variable in the scope with a specified key.
+   *
+   * @param key The key of the variable to set.
+   * @param json The JSON representation of the AST node to set.
+   * @returns The created or updated AST node.
+   */
+  public setVar<Node extends ASTNode = ASTNode>(key: string, json: ASTNodeJSON): Node;
+
+  public setVar<Node extends ASTNode = ASTNode>(
+    arg1: string | ASTNodeJSON,
+    arg2?: ASTNodeJSON
+  ): Node {
+    if (typeof arg1 === 'string' && arg2 !== undefined) {
+      return this.ast.set(arg1, arg2);
+    }
+
+    if (typeof arg1 === 'object' && arg2 === undefined) {
+      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.
+   */
+  public getVar<Node extends ASTNode = ASTNode>(key: string = 'outputs') {
+    return this.ast.get<Node>(key);
+  }
+
+  /**
+   * Clears a variable from the scope by its key.
+   *
+   * @param key The key of the variable to clear. Defaults to 'outputs'.
+   */
+  public clearVar(key: string = 'outputs') {
+    return this.ast.remove(key);
+  }
+}

package/src/scope/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Event, Disposable } from '@flowgram-vue/utils';
+
+import { BaseVariableField, VariableDeclaration } from '../ast';
+import { type Scope } from './scope';
+
+/**
+ * Parameters for getting all scopes.
+ */
+export interface GetAllScopeParams {
+  /**
+   * Whether to sort the scopes.
+   */
+  sort?: boolean;
+}
+
+/**
+ * Action type for scope changes.
+ */
+export interface ScopeChangeAction {
+  type: 'add' | 'delete' | 'update' | 'available';
+  scope: Scope;
+}
+
+/**
+ * Interface for a variable table.
+ */
+export interface IVariableTable extends Disposable {
+  /**
+   * The parent variable table.
+   */
+  parentTable?: IVariableTable;
+
+  /**
+   * @deprecated Use `onVariableListChange` or `onAnyVariableChange` instead.
+   */
+  onDataChange: Event<void>;
+
+  /**
+   * The current version of the variable table.
+   */
+  version: number;
+
+  /**
+   * The list of variables in the table.
+   */
+  variables: VariableDeclaration[];
+
+  /**
+   * The keys of the variables in the table.
+   */
+  variableKeys: string[];
+
+  /**
+   * Fires a change event.
+   */
+  fireChange(): void;
+
+  /**
+   * Gets a variable or property by its key path.
+   * @param keyPath The key path to the variable or property.
+   * @returns The found `BaseVariableField` or `undefined`.
+   */
+  getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+
+  /**
+   * Gets a variable by its key.
+   * @param key The key of the variable.
+   * @returns The found `VariableDeclaration` or `undefined`.
+   */
+  getVariableByKey(key: string): VariableDeclaration | undefined;
+
+  /**
+   * Disposes the variable table.
+   */
+  dispose(): void;
+
+  /**
+   * Subscribes to changes in the variable list.
+   * @param observer The observer function.
+   * @returns A disposable to unsubscribe.
+   */
+  onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
+
+  /**
+   * Subscribes to changes in any variable's value.
+   * @param observer The observer function.
+   * @returns A disposable to unsubscribe.
+   */
+  onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+
+  /**
+   * Subscribes to both variable list changes and any variable's value changes.
+   * @param observer The observer function.
+   * @returns A disposable to unsubscribe.
+   */
+  onListOrAnyVarChange(observer: () => void): Disposable;
+}

package/src/scope/variable-table.ts

@@ -0,0 +1,203 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Observable, Subject, merge, share, skip, switchMap } from 'rxjs';
+import { DisposableCollection, Emitter } from '@flowgram-vue/utils';
+
+import { subsToDisposable } from '../utils/toDisposable';
+import { BaseVariableField } from '../ast/declaration/base-variable-field';
+import { VariableDeclaration } from '../ast';
+import { IVariableTable } from './types';
+
+/**
+ * A class that stores and manages variables in a table-like structure.
+ * It provides methods for adding, removing, and retrieving variables, as well as
+ * observables for listening to changes in the variable list and individual variables.
+ */
+export class VariableTable implements IVariableTable {
+  protected table: Map<string, VariableDeclaration> = new Map();
+
+  toDispose = new DisposableCollection();
+
+  /**
+   * @deprecated
+   */
+  protected onDataChangeEmitter = new Emitter<void>();
+
+  protected variables$: Subject<VariableDeclaration[]> = new Subject<VariableDeclaration[]>();
+
+  /**
+   * An observable that listens for value changes on any variable within the table.
+   */
+  protected anyVariableChange$: Observable<VariableDeclaration> = this.variables$.pipe(
+    switchMap((_variables) =>
+      merge(
+        ..._variables.map((_v) =>
+          _v.value$.pipe<any>(
+            // Skip the initial value of the BehaviorSubject
+            skip(1)
+          )
+        )
+      )
+    ),
+    share()
+  );
+
+  /**
+   * 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: (changedVariable: VariableDeclaration) => void) {
+    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: (variables: VariableDeclaration[]) => void) {
+    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: () => void) {
+    const disposables = new DisposableCollection();
+    disposables.pushAll([this.onVariableListChange(observer), this.onAnyVariableChange(observer)]);
+    return disposables;
+  }
+
+  /**
+   * @deprecated Use onListOrAnyVarChange instead.
+   */
+  public onDataChange = this.onDataChangeEmitter.event;
+
+  protected _version: number = 0;
+
+  /**
+   * 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(): number {
+    return this._version;
+  }
+
+  /**
+   * Increments the version number, resetting to 0 if it reaches MAX_SAFE_INTEGER.
+   */
+  protected bumpVersion() {
+    this._version = this._version + 1;
+    if (this._version === Number.MAX_SAFE_INTEGER) {
+      this._version = 0;
+    }
+  }
+
+  constructor(
+    /**
+     * An optional parent table. If provided, this table will contain all variables
+     * from the current table.
+     */
+    public parentTable?: IVariableTable
+  ) {
+    this.toDispose.pushAll([
+      this.onDataChangeEmitter,
+      // Activate the share() operator
+      this.onAnyVariableChange(() => {
+        this.bumpVersion();
+      }),
+    ]);
+  }
+
+  /**
+   * An array of all variables in the table.
+   */
+  get variables(): VariableDeclaration[] {
+    return Array.from(this.table.values());
+  }
+
+  /**
+   * An array of all variable keys in the table.
+   */
+  get variableKeys(): string[] {
+    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: string[]): BaseVariableField | undefined {
+    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: string) {
+    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: VariableDeclaration) {
+    this.table.set(variable.key, variable);
+    if (this.parentTable) {
+      (this.parentTable as VariableTable).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: string) {
+    this.table.delete(key);
+    if (this.parentTable) {
+      (this.parentTable as VariableTable).removeVariableFromTable(key);
+    }
+  }
+
+  /**
+   * Disposes of all resources used by the variable table.
+   */
+  dispose(): void {
+    this.variableKeys.forEach((_key) =>
+      (this.parentTable as VariableTable)?.removeVariableFromTable(_key)
+    );
+    this.parentTable?.fireChange();
+    this.variables$.complete();
+    this.variables$.unsubscribe();
+    this.toDispose.dispose();
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { VariableFieldKeyRenameService } from './variable-field-key-rename-service';

package/src/services/variable-field-key-rename-service.ts

@@ -0,0 +1,131 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { difference } from 'lodash-es';
+import { inject, injectable, postConstruct, preDestroy } from 'inversify';
+import { DisposableCollection, Emitter } from '@flowgram-vue/utils';
+
+import { VariableEngine } from '../variable-engine';
+import {
+  ASTNode,
+  BaseVariableField,
+  ObjectPropertiesChangeAction,
+  VariableDeclarationListChangeAction,
+} from '../ast';
+
+interface RenameInfo {
+  before: BaseVariableField;
+  after: BaseVariableField;
+}
+
+/**
+ * This service is responsible for detecting when a variable field's key is renamed.
+ * It listens for changes in variable declaration lists and object properties, and
+ * determines if a change constitutes a rename operation.
+ */
+@injectable()
+export class VariableFieldKeyRenameService {
+  @inject(VariableEngine) variableEngine: VariableEngine;
+
+  toDispose = new DisposableCollection();
+
+  renameEmitter = new Emitter<RenameInfo>();
+
+  /**
+   * 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.
+   */
+  disposeInListEmitter = new Emitter<BaseVariableField>();
+
+  /**
+   * An event that fires when a variable field key is successfully renamed.
+   */
+  onRename = this.renameEmitter.event;
+
+  /**
+   * An event that fires when a field is removed from a list (and not part of a rename).
+   */
+  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?: ASTNode, prev?: BaseVariableField[], next?: BaseVariableField[]) {
+    // 1. Check if a rename is possible.
+    if (!ast || !prev?.length || !next?.length) {
+      this.notifyFieldsDispose(prev, next);
+      return;
+    }
+
+    // 2. The lengths of the lists must be the same for a rename.
+    if (prev.length !== next.length) {
+      this.notifyFieldsDispose(prev, next);
+      return;
+    }
+
+    let renameNodeInfo: RenameInfo | null = null;
+    let existFieldChanged = false;
+
+    for (const [index, prevField] of prev.entries()) {
+      const nextField = next[index];
+
+      if (prevField.key !== nextField.key) {
+        // Only one rename is allowed at a time.
+        if (existFieldChanged) {
+          this.notifyFieldsDispose(prev, next);
+          return;
+        }
+        existFieldChanged = true;
+
+        if (prevField.type?.kind === nextField.type?.kind) {
+          renameNodeInfo = { before: prevField, after: nextField };
+        }
+      }
+    }
+
+    if (!renameNodeInfo) {
+      this.notifyFieldsDispose(prev, next);
+      return;
+    }
+
+    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?: BaseVariableField[], next?: BaseVariableField[]) {
+    const removedFields = difference(prev || [], next || []);
+    removedFields.forEach((_field) => this.disposeInListEmitter.fire(_field));
+  }
+
+  @postConstruct()
+  init() {
+    this.toDispose.pushAll([
+      this.variableEngine.onGlobalEvent<VariableDeclarationListChangeAction>(
+        'VariableListChange',
+        (_action) => {
+          this.handleFieldListChange(_action.ast, _action.payload?.prev, _action.payload?.next);
+        }
+      ),
+      this.variableEngine.onGlobalEvent<ObjectPropertiesChangeAction>(
+        'ObjectPropertiesChange',
+        (_action) => {
+          this.handleFieldListChange(_action.ast, _action.payload?.prev, _action.payload?.next);
+        }
+      ),
+    ]);
+  }
+
+  @preDestroy()
+  dispose() {
+    this.toDispose.dispose();
+  }
+}