@flowgram-vue/variable-core 0.2.0

package/src/composables/scope-provider.ts

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import {
+  computed,
+  defineComponent,
+  inject,
+  provide,
+  unref,
+  type ComputedRef,
+  type InjectionKey,
+  type PropType,
+} from 'vue';
+
+import { Scope } from '../scope';
+
+interface ScopeContextProps {
+  scope: Scope;
+}
+
+export const ScopeKey: InjectionKey<Scope | ComputedRef<Scope>> = Symbol('Scope');
+
+/**
+ * ScopeProvider provides the scope to its children via provide/inject.
+ */
+export const ScopeProvider = defineComponent({
+  name: 'ScopeProvider',
+  props: {
+    /**
+     * scope used in the context
+     */
+    scope: {
+      type: Object as PropType<Scope>,
+    },
+    /**
+     * @deprecated use scope prop instead, this is kept for backward compatibility
+     */
+    value: {
+      type: Object as PropType<ScopeContextProps>,
+    },
+  },
+  setup(props, { slots }) {
+    const scopeToUse = computed(() => props.scope || props.value?.scope);
+
+    if (!scopeToUse.value) {
+      throw new Error('[ScopeProvider] scope is required');
+    }
+
+    provide(ScopeKey, scopeToUse as ComputedRef<Scope>);
+
+    return () => slots.default?.();
+  },
+});
+
+/**
+ * useCurrentScope returns the scope provided by ScopeProvider.
+ */
+export const useCurrentScope = <Strict extends boolean = false>(params?: {
+  /**
+   * whether to throw error when no scope in ScopeProvider is found
+   */
+  strict: Strict;
+}): Strict extends true ? Scope : Scope | undefined => {
+  const { strict = false } = params || {};
+
+  const context = inject(ScopeKey, undefined);
+
+  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 unref(context) as Strict extends true ? Scope : Scope | undefined;
+};

package/src/composables/use-available-variables.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { computed, onScopeDispose, shallowRef, type ComputedRef } from 'vue';
+
+import { useService } from '@flowgram-vue/core';
+
+import { VariableDeclaration } from '../ast';
+import { VariableEngine } from '../variable-engine';
+import { useCurrentScope } from './scope-provider';
+
+/**
+ * Get available variable list in the current scope.
+ *
+ * - If no scope, return global variable list.
+ * - The composable is reactive to variable list or any variables change.
+ */
+export function useAvailableVariables(): ComputedRef<VariableDeclaration[]> {
+  const scope = useCurrentScope();
+  const variableEngine: VariableEngine = useService(VariableEngine);
+  const tick = shallowRef(0);
+
+  const disposable = !scope
+    ? variableEngine.globalVariableTable.onListOrAnyVarChange(() => {
+        tick.value += 1;
+      })
+    : scope.available.onDataChange(() => {
+        tick.value += 1;
+      });
+
+  onScopeDispose(() => disposable.dispose());
+
+  return computed(() => {
+    tick.value;
+    return scope ? scope.available.variables : variableEngine.globalVariableTable.variables;
+  });
+}

package/src/composables/use-output-variables.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { computed, onScopeDispose, shallowRef, type ComputedRef } from 'vue';
+
+import { VariableDeclaration } from '../ast';
+import { useCurrentScope } from './scope-provider';
+
+/**
+ * Get output variable list in the current scope.
+ *
+ * - The composable is reactive to variable list or any variables change.
+ */
+export function useOutputVariables(): ComputedRef<VariableDeclaration[]> {
+  const scope = useCurrentScope();
+  const tick = shallowRef(0);
+
+  if (!scope) {
+    throw new Error(
+      '[useOutputVariables]: No scope found, useOutputVariables must be used in <ScopeProvider>'
+    );
+  }
+
+  const disposable = scope.output.onListOrAnyVarChange(() => {
+    tick.value += 1;
+  });
+
+  onScopeDispose(() => disposable.dispose());
+
+  return computed(() => {
+    tick.value;
+    return scope.output.variables;
+  });
+}

package/src/composables/use-scope-available.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { computed, onScopeDispose, shallowRef, type ComputedRef } from 'vue';
+
+import { ScopeAvailableData } from '../scope/datas';
+import { useCurrentScope } from './scope-provider';
+
+/**
+ * Get the available variables in the current scope.
+ * 获取作用域的可访问变量
+ */
+export function useScopeAvailable(params?: { autoRefresh?: boolean }): ComputedRef<ScopeAvailableData> {
+  const { autoRefresh = true } = params || {};
+
+  const scope = useCurrentScope({ strict: true });
+  const tick = shallowRef(0);
+
+  if (autoRefresh) {
+    const disposable = scope.available.onListOrAnyVarChange(() => {
+      tick.value += 1;
+    });
+    onScopeDispose(() => disposable.dispose());
+  }
+
+  return computed(() => {
+    tick.value;
+    return scope.available;
+  });
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { VariableContainerModule } from './variable-container-module';
+export { VariableEngine } from './variable-engine';
+export { VariableEngineProvider } from './providers';
+
+export * from './composables';
+export * from './scope';
+export * from './ast';
+export * from './services';
+export { type Observer } from 'rxjs';

package/src/providers.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { interfaces } from 'inversify';
+
+import { type VariableEngine } from './variable-engine';
+
+/**
+ * A provider for dynamically obtaining the `VariableEngine` instance.
+ * This is used to prevent circular dependencies when injecting `VariableEngine`.
+ */
+export const VariableEngineProvider = Symbol('DynamicVariableEngine');
+export type VariableEngineProvider = () => VariableEngine;
+
+/**
+ * A provider for obtaining the Inversify container instance.
+ * This allows other parts of the application, like AST nodes, to access the container for dependency injection.
+ */
+export const ContainerProvider = Symbol('ContainerProvider');
+export type ContainerProvider = () => interfaces.Container;

package/src/scope/datas/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { ScopeOutputData } from './scope-output-data';
+export { ScopeAvailableData } from './scope-available-data';
+export { ScopeEventData } from './scope-event-data';

package/src/scope/datas/scope-available-data.ts

@@ -0,0 +1,234 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import {
+  Observable,
+  Subject,
+  animationFrameScheduler,
+  debounceTime,
+  distinctUntilChanged,
+  map,
+  merge,
+  share,
+  skip,
+  startWith,
+  switchMap,
+  tap,
+} from 'rxjs';
+import { flatten } from 'lodash-es';
+import { shallowEqual } from 'fast-equals';
+import { Disposable } from '@flowgram-vue/utils';
+import { Emitter } from '@flowgram-vue/utils';
+
+import { IVariableTable } from '../types';
+import { type Scope } from '../scope';
+import { subsToDisposable } from '../../utils/toDisposable';
+import { createMemo } from '../../utils/memo';
+import { SubscribeConfig } from '../../ast/types';
+import { ASTNode, BaseVariableField, VariableDeclaration } from '../../ast';
+
+/**
+ * Manages the available variables within a scope.
+ */
+export class ScopeAvailableData {
+  protected memo = createMemo();
+
+  /**
+   * The global variable table from the variable engine.
+   */
+  get globalVariableTable(): IVariableTable {
+    return this.scope.variableEngine.globalVariableTable;
+  }
+
+  protected _version: number = 0;
+
+  protected refresh$: Subject<void> = new Subject();
+
+  protected _variables: VariableDeclaration[] = [];
+
+  /**
+   * The current version of the available data, which increments on each change.
+   */
+  get version() {
+    return this._version;
+  }
+
+  protected 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(): void {
+    // Do not trigger refresh for a disposed scope.
+    if (this.scope.disposed) {
+      return;
+    }
+    this.refresh$.next();
+  }
+
+  /**
+   * An observable that emits when the list of available variables changes.
+   */
+  protected variables$: Observable<VariableDeclaration[]> = this.refresh$.pipe(
+    // Map to the flattened list of variables from all dependency scopes.
+    map(() => flatten(this.depScopes.map((scope) => scope.output.variables || []))),
+    // Use shallow equality to check if the variable list has changed.
+    distinctUntilChanged<VariableDeclaration[]>(shallowEqual),
+    share()
+  );
+
+  /**
+   * An observable that emits when any variable in the available list changes its value.
+   */
+  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 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: (changedVariable: VariableDeclaration) => void) {
+    return subsToDisposable(this.anyVariableChange$.subscribe(observer));
+  }
+
+  /**
+   * 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: (variables: VariableDeclaration[]) => void) {
+    return subsToDisposable(this.variables$.subscribe(observer));
+  }
+
+  /**
+   * @deprecated
+   */
+  protected onDataChangeEmitter = new Emitter<VariableDeclaration[]>();
+
+  protected onListOrAnyVarChangeEmitter = new Emitter<VariableDeclaration[]>();
+
+  /**
+   * @deprecated use available.onListOrAnyVarChange instead
+   */
+  public onDataChange = this.onDataChangeEmitter.event;
+
+  /**
+   * An event that fires when the variable list changes or any variable's value is updated.
+   */
+  public onListOrAnyVarChange = this.onListOrAnyVarChangeEmitter.event;
+
+  constructor(public readonly scope: Scope) {
+    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);
+      }),
+      Disposable.create(() => {
+        this.refresh$.complete();
+        this.refresh$.unsubscribe();
+      }),
+    ]);
+  }
+
+  /**
+   * Gets the list of available variables.
+   */
+  get variables(): VariableDeclaration[] {
+    return this._variables;
+  }
+
+  /**
+   * Gets the keys of the available variables.
+   */
+  get variableKeys(): string[] {
+    return this.memo('availableKeys', () => this._variables.map((_v) => _v.key));
+  }
+
+  /**
+   * Gets the dependency scopes.
+   */
+  get depScopes(): Scope[] {
+    return this.scope.depScopes;
+  }
+
+  /**
+   * 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: string[] = []): BaseVariableField | undefined {
+    // Check if the variable is accessible in the current scope.
+    if (!this.variableKeys.includes(keyPath[0])) {
+      return;
+    }
+    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<Data = BaseVariableField | undefined>(
+    keyPath: string[] = [],
+    cb: (variable?: Data) => void,
+    opts?: SubscribeConfig<BaseVariableField | undefined, Data>
+  ): Disposable {
+    const { triggerOnInit = true, debounceAnimation, selector } = opts || {};
+
+    return subsToDisposable(
+      merge(this.anyVariableChange$, this.variables$)
+        .pipe(
+          triggerOnInit ? startWith() : tap(() => null),
+          map(() => {
+            const v = this.getByKeyPath(keyPath);
+            return selector ? selector(v) : (v as any);
+          }),
+          distinctUntilChanged(
+            (a, b) => shallowEqual(a, b),
+            (value) => {
+              if (value instanceof ASTNode) {
+                // If the value is an ASTNode, compare its hash for changes.
+                return value.hash;
+              }
+              return value;
+            }
+          ),
+          // Debounce updates to a single emission per animation frame.
+          debounceAnimation ? debounceTime(0, animationFrameScheduler) : tap(() => null)
+        )
+        .subscribe(cb)
+    );
+  }
+}

package/src/scope/datas/scope-event-data.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Subject, filter } from 'rxjs';
+import { Disposable } from '@flowgram-vue/utils';
+
+import { type Scope } from '../scope';
+import { subsToDisposable } from '../../utils/toDisposable';
+import { type GlobalEventActionType } from '../../ast';
+
+type Observer<ActionType extends GlobalEventActionType = GlobalEventActionType> = (
+  action: ActionType
+) => void;
+
+/**
+ * Manages global events within a scope.
+ */
+export class ScopeEventData {
+  event$: Subject<GlobalEventActionType> = new Subject<GlobalEventActionType>();
+
+  /**
+   * Dispatches a global event.
+   * @param action The event action to dispatch.
+   */
+  dispatch<ActionType extends GlobalEventActionType = GlobalEventActionType>(action: ActionType) {
+    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<ActionType extends GlobalEventActionType = GlobalEventActionType>(
+    observer: Observer<ActionType>
+  ): Disposable {
+    return subsToDisposable(this.event$.subscribe(observer as 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<ActionType extends GlobalEventActionType = GlobalEventActionType>(
+    type: ActionType['type'],
+    observer: Observer<ActionType>
+  ): Disposable {
+    return subsToDisposable(
+      this.event$.pipe(filter((_action) => _action.type === type)).subscribe(observer as Observer)
+    );
+  }
+
+  constructor(public readonly scope: Scope) {
+    scope.toDispose.pushAll([
+      this.subscribe((_action) => {
+        scope.variableEngine.fireGlobalEvent(_action);
+      }),
+    ]);
+  }
+}

package/src/scope/datas/scope-output-data.ts

@@ -0,0 +1,151 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { VariableTable } from '../variable-table';
+import { IVariableTable } from '../types';
+import { type Scope } from '../scope';
+import { type VariableEngine } from '../../variable-engine';
+import { createMemo } from '../../utils/memo';
+import { NewASTAction } from '../../ast/types';
+import { DisposeASTAction } from '../../ast/types';
+import { ReSortVariableDeclarationsAction } from '../../ast/declaration/variable-declaration';
+import { ASTKind, type VariableDeclaration } from '../../ast';
+
+/**
+ * Manages the output variables of a scope.
+ */
+export class ScopeOutputData {
+  protected variableTable: IVariableTable;
+
+  protected memo = createMemo();
+
+  /**
+   * The variable engine instance.
+   */
+  get variableEngine(): VariableEngine {
+    return this.scope.variableEngine;
+  }
+
+  /**
+   * The global variable table from the variable engine.
+   */
+  get globalVariableTable(): IVariableTable {
+    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);
+  }
+
+  protected _hasChanges = false;
+
+  constructor(public readonly scope: Scope) {
+    // Setup scope variable table based on globalVariableTable
+    this.variableTable = new VariableTable(scope.variableEngine.globalVariableTable);
+
+    this.scope.toDispose.pushAll([
+      // When the root AST node is updated, check if there are any changes.
+      this.scope.ast.subscribe(() => {
+        if (this._hasChanges) {
+          this.memo.clear();
+          this.notifyCoversChange();
+          this.variableTable.fireChange();
+          this._hasChanges = false;
+        }
+      }),
+      this.scope.event.on<DisposeASTAction>('DisposeAST', (_action) => {
+        if (_action.ast?.kind === ASTKind.VariableDeclaration) {
+          this.removeVariableFromTable(_action.ast.key);
+        }
+      }),
+      this.scope.event.on<NewASTAction>('NewAST', (_action) => {
+        if (_action.ast?.kind === ASTKind.VariableDeclaration) {
+          this.addVariableToTable(_action.ast as VariableDeclaration);
+        }
+      }),
+      this.scope.event.on<ReSortVariableDeclarationsAction>('ReSortVariableDeclarations', () => {
+        this._hasChanges = true;
+      }),
+      this.variableTable,
+    ]);
+  }
+
+  /**
+   * The output variable declarations of the scope, sorted by order.
+   */
+  get variables(): VariableDeclaration[] {
+    return this.memo('variables', () =>
+      this.variableTable.variables.sort((a, b) => a.order - b.order)
+    );
+  }
+
+  /**
+   * The keys of the output variables.
+   */
+  get variableKeys(): string[] {
+    return this.memo('variableKeys', () => this.variableTable.variableKeys);
+  }
+
+  protected addVariableToTable(variable: VariableDeclaration) {
+    if (variable.scope !== this.scope) {
+      throw Error('VariableDeclaration must be a ast node in scope');
+    }
+
+    (this.variableTable as VariableTable).addVariableToTable(variable);
+    this._hasChanges = true;
+  }
+
+  protected removeVariableFromTable(key: string) {
+    (this.variableTable as 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: string) {
+    return this.variableTable.getVariableByKey(key);
+  }
+
+  /**
+   * Notifies the covering scopes that the available variables have changed.
+   */
+  notifyCoversChange(): void {
+    this.scope.coverScopes.forEach((scope) => scope.available.refresh());
+  }
+}

package/src/scope/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { ScopeChain } from './scope-chain';
+export { Scope } from './scope';
+export { ScopeOutputData } from './datas';
+export { type IVariableTable } from './types';