@flowgram-vue/variable-core 0.2.0

package/src/ast/common/map-node.ts

@@ -0,0 +1,89 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { updateChildNodeHelper } from '../utils/helpers';
+import { ASTKind, ASTNodeJSON } from '../types';
+import { ASTNode } from '../ast-node';
+
+/**
+ * ASTNodeJSON representation of `MapNode`
+ */
+export interface MapNodeJSON {
+  /**
+   * The map of nodes.
+   */
+  map: [string, ASTNodeJSON][];
+}
+
+/**
+ * Represents a map of nodes.
+ */
+export class MapNode extends ASTNode<MapNodeJSON> {
+  static kind: string = ASTKind.MapNode;
+
+  protected map: Map<string, ASTNode> = new Map<string, ASTNode>();
+
+  /**
+   * Deserializes the `MapNodeJSON` to the `MapNode`.
+   * @param json The `MapNodeJSON` to deserialize.
+   */
+  fromJSON({ map }: MapNodeJSON): void {
+    const removedKeys = new Set(this.map.keys());
+
+    for (const [key, item] of map || []) {
+      removedKeys.delete(key);
+      this.set(key, item);
+    }
+
+    for (const removeKey of Array.from(removedKeys)) {
+      this.remove(removeKey);
+    }
+  }
+
+  /**
+   * Serialize the `MapNode` to `MapNodeJSON`.
+   * @returns The JSON representation of `MapNode`.
+   */
+  toJSON() {
+    return {
+      kind: ASTKind.MapNode,
+      map: Array.from(this.map.entries()),
+    };
+  }
+
+  /**
+   * 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<Node extends ASTNode = ASTNode>(key: string, nextJSON: ASTNodeJSON): Node {
+    return this.withBatchUpdate(updateChildNodeHelper).call(this, {
+      getChildNode: () => this.get(key),
+      removeChildNode: () => this.map.delete(key),
+      updateChildNode: (nextNode) => this.map.set(key, nextNode),
+      nextJSON,
+    }) as Node;
+  }
+
+  /**
+   * Remove a node from the map.
+   * @param key The key of the node.
+   */
+  remove(key: string) {
+    this.get(key)?.dispose();
+    this.map.delete(key);
+    this.fireChange();
+  }
+
+  /**
+   * Get a node from the map.
+   * @param key The key of the node.
+   * @returns The node instance if found, otherwise `undefined`.
+   */
+  get<Node extends ASTNode = ASTNode>(key: string): Node | undefined {
+    return this.map.get(key) as Node | undefined;
+  }
+}

package/src/ast/declaration/base-variable-field.ts

@@ -0,0 +1,184 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { shallowEqual } from 'fast-equals';
+
+import { getParentFields } from '../utils/variable-field';
+import { ASTNodeJSON, ASTNodeJSONOrKind, Identifier } from '../types';
+import { type BaseType } from '../type';
+import { ASTNodeFlags } from '../flags';
+import { type BaseExpression } from '../expression';
+import { ASTNode } from '../ast-node';
+
+/**
+ * ASTNodeJSON representation of `BaseVariableField`
+ */
+export interface BaseVariableFieldJSON<VariableMeta = any> extends ASTNodeJSON {
+  /**
+   * key of the variable field
+   * - For `VariableDeclaration`, the key should be global unique.
+   * - For `Property`, the key is the property name.
+   */
+  key: Identifier;
+  /**
+   * type of the variable field, similar to js code:
+   * `const v: string`
+   */
+  type?: ASTNodeJSONOrKind;
+  /**
+   * initializer of the variable field, similar to js code:
+   * `const v = 'hello'`
+   *
+   * with initializer, the type of field will be inferred from the initializer.
+   */
+  initializer?: ASTNodeJSON;
+  /**
+   * meta data of the variable field, you cans store information like `title`, `icon`, etc.
+   */
+  meta?: VariableMeta;
+}
+
+/**
+ * Variable Field abstract class, which is the base class for `VariableDeclaration` and `Property`
+ *
+ * - `VariableDeclaration` is used to declare a variable in a block scope.
+ * - `Property` is used to declare a property in an object.
+ */
+export abstract class BaseVariableField<VariableMeta = any> extends ASTNode<
+  BaseVariableFieldJSON<VariableMeta>
+> {
+  public flags: ASTNodeFlags = ASTNodeFlags.VariableField;
+
+  protected _type?: BaseType;
+
+  protected _meta: VariableMeta = {} as any;
+
+  protected _initializer?: BaseExpression;
+
+  /**
+   * Parent variable fields, sorted from closest to farthest
+   */
+  get parentFields(): BaseVariableField[] {
+    return getParentFields(this);
+  }
+
+  /**
+   * KeyPath of the variable field, sorted from farthest to closest
+   */
+  get keyPath(): string[] {
+    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(): VariableMeta {
+    return this._meta;
+  }
+
+  /**
+   * Type of the variable field, similar to js code:
+   * `const v: string`
+   */
+  get type(): BaseType {
+    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(): BaseExpression | undefined {
+    return this._initializer;
+  }
+
+  /**
+   * The global unique hash of the field, and will be changed when the field is updated.
+   */
+  get hash(): string {
+    return `[${this._version}]${this.keyPath.join('.')}`;
+  }
+
+  /**
+   * Deserialize the `BaseVariableFieldJSON` to the `BaseVariableField`.
+   * @param json ASTJSON representation of `BaseVariableField`
+   */
+  fromJSON({ type, initializer, meta }: Omit<BaseVariableFieldJSON<VariableMeta>, 'key'>): void {
+    // 类型变化
+    this.updateType(type);
+
+    // 表达式更新
+    this.updateInitializer(initializer);
+
+    // Extra 更新
+    this.updateMeta(meta!);
+  }
+
+  /**
+   * Update the type of the variable field
+   * @param type type ASTJSON representation of Type
+   */
+  updateType(type: BaseVariableFieldJSON['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?: BaseVariableFieldJSON['initializer']) {
+    this.updateChildNodeByKey('_initializer', nextInitializer);
+  }
+
+  /**
+   * Update the meta data of the variable field
+   * @param nextMeta meta data of the variable field
+   */
+  updateMeta(nextMeta: VariableMeta) {
+    if (!shallowEqual(nextMeta, this._meta)) {
+      this._meta = nextMeta;
+      this.fireChange();
+    }
+  }
+
+  /**
+   * Get the variable field by keyPath, similar to js code:
+   * `v.a.b`
+   * @param keyPath
+   * @returns
+   */
+  getByKeyPath(keyPath: string[]): BaseVariableField | undefined {
+    if (this.type?.flags & ASTNodeFlags.DrilldownType) {
+      return this.type.getByKeyPath(keyPath) as BaseVariableField | undefined;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Subscribe to type change of the variable field
+   * @param observer
+   * @returns
+   */
+  onTypeChange(observer: (type: ASTNode | undefined) => void) {
+    return this.subscribe(observer, { selector: (curr) => curr.type });
+  }
+
+  /**
+   * Serialize the variable field to JSON
+   * @returns ASTNodeJSON representation of `BaseVariableField`
+   */
+  toJSON(): BaseVariableFieldJSON<VariableMeta> {
+    return {
+      key: this.key,
+      type: this.type?.toJSON(),
+      initializer: this.initializer?.toJSON(),
+      meta: this._meta,
+    };
+  }
+}

package/src/ast/declaration/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { VariableDeclaration, type VariableDeclarationJSON } from './variable-declaration';
+export {
+  VariableDeclarationList,
+  type VariableDeclarationListJSON,
+  type VariableDeclarationListChangeAction,
+} from './variable-declaration-list';
+export { type PropertyJSON, Property } from './property';
+export { BaseVariableField } from './base-variable-field';

package/src/ast/declaration/property.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind } from '../types';
+import { BaseVariableField, BaseVariableFieldJSON } from './base-variable-field';
+
+/**
+ * ASTNodeJSON representation of the `Property`.
+ */
+export type PropertyJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta>;
+
+/**
+ * `Property` is a variable field that represents a property of a `ObjectType`.
+ */
+export class Property<VariableMeta = any> extends BaseVariableField<VariableMeta> {
+  static kind: string = ASTKind.Property;
+}

package/src/ast/declaration/variable-declaration-list.ts

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind } from '../types';
+import { GlobalEventActionType } from '../types';
+import { ASTNode } from '../ast-node';
+import { type VariableDeclarationJSON, VariableDeclaration } from './variable-declaration';
+
+export interface VariableDeclarationListJSON<VariableMeta = any> {
+  /**
+   * `declarations` must be of type `VariableDeclaration`, so the business can omit the `kind` field.
+   */
+  declarations?: VariableDeclarationJSON<VariableMeta>[];
+  /**
+   * The starting order number for variables.
+   */
+  startOrder?: number;
+}
+
+export type VariableDeclarationListChangeAction = GlobalEventActionType<
+  'VariableListChange',
+  {
+    prev: VariableDeclaration[];
+    next: VariableDeclaration[];
+  },
+  VariableDeclarationList
+>;
+
+export class VariableDeclarationList extends ASTNode<VariableDeclarationListJSON> {
+  static kind: string = ASTKind.VariableDeclarationList;
+
+  /**
+   * Map of variable declarations, keyed by variable name.
+   */
+  declarationTable: Map<string, VariableDeclaration> = new Map();
+
+  /**
+   * Variable declarations, sorted by `order`.
+   */
+  declarations: VariableDeclaration[];
+
+  /**
+   * 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 }: VariableDeclarationListJSON): void {
+    const removedKeys = new Set(this.declarationTable.keys());
+    const prev = [...(this.declarations || [])];
+
+    // Iterate over the new properties.
+    this.declarations = (declarations || []).map(
+      (declaration: VariableDeclarationJSON, idx: number) => {
+        const order = (startOrder || 0) + idx;
+
+        // If the key is not set, reuse the previous key.
+        const declarationKey = declaration.key || this.declarations?.[idx]?.key;
+        const existDeclaration = this.declarationTable.get(declarationKey);
+        if (declarationKey) {
+          removedKeys.delete(declarationKey);
+        }
+
+        if (existDeclaration) {
+          existDeclaration.fromJSON({ order, ...declaration });
+
+          return existDeclaration;
+        } else {
+          const newDeclaration = this.createChildNode({
+            order,
+            ...declaration,
+            kind: ASTKind.VariableDeclaration,
+          }) as VariableDeclaration;
+          this.fireChange();
+
+          this.declarationTable.set(newDeclaration.key, newDeclaration);
+
+          return newDeclaration;
+        }
+      }
+    );
+
+    // Delete variables that no longer exist.
+    removedKeys.forEach((key) => {
+      const declaration = this.declarationTable.get(key);
+      declaration?.dispose();
+      this.declarationTable.delete(key);
+    });
+
+    this.dispatchGlobalEvent<VariableDeclarationListChangeAction>({
+      type: 'VariableListChange',
+      payload: {
+        prev,
+        next: [...this.declarations],
+      },
+    });
+  }
+
+  /**
+   * Serialize the `VariableDeclarationList` to the `VariableDeclarationListJSON`.
+   * @returns ASTJSON representation of `VariableDeclarationList`
+   */
+  toJSON() {
+    return {
+      kind: ASTKind.VariableDeclarationList,
+      declarations: this.declarations.map((_declaration) => _declaration.toJSON()),
+    };
+  }
+}

package/src/ast/declaration/variable-declaration.ts

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind, GlobalEventActionType, type CreateASTParams } from '../types';
+import { BaseVariableField, BaseVariableFieldJSON } from './base-variable-field';
+
+/**
+ * ASTNodeJSON representation of the `VariableDeclaration`.
+ */
+export type VariableDeclarationJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
+  /**
+   * Variable sorting order, which is used to sort variables in `scope.outputs.variables`
+   */
+  order?: number;
+};
+
+/**
+ * Action type for re-sorting variable declarations.
+ */
+export type ReSortVariableDeclarationsAction = GlobalEventActionType<'ReSortVariableDeclarations'>;
+
+/**
+ * `VariableDeclaration` is a variable field that represents a variable declaration.
+ */
+export class VariableDeclaration<VariableMeta = any> extends BaseVariableField<VariableMeta> {
+  static kind: string = ASTKind.VariableDeclaration;
+
+  protected _order: number = 0;
+
+  /**
+   * Variable sorting order, which is used to sort variables in `scope.outputs.variables`
+   */
+  get order(): number {
+    return this._order;
+  }
+
+  constructor(params: CreateASTParams) {
+    super(params);
+  }
+
+  /**
+   * Deserialize the `VariableDeclarationJSON` to the `VariableDeclaration`.
+   */
+  fromJSON({ order, ...rest }: Omit<VariableDeclarationJSON<VariableMeta>, 'key'>): void {
+    // Update order.
+    this.updateOrder(order);
+
+    // Update other information.
+    super.fromJSON(rest as BaseVariableFieldJSON<VariableMeta>);
+  }
+
+  /**
+   * Update the sorting order of the variable declaration.
+   * @param order Variable sorting order. Default is 0.
+   */
+  updateOrder(order: number = 0): void {
+    if (order !== this._order) {
+      this._order = order;
+      this.dispatchGlobalEvent<ReSortVariableDeclarationsAction>({
+        type: 'ReSortVariableDeclarations',
+      });
+      this.fireChange();
+    }
+  }
+
+  /**
+   * Serialize the `VariableDeclaration` to `VariableDeclarationJSON`.
+   * @returns The JSON representation of `VariableDeclaration`.
+   */
+  toJSON(): VariableDeclarationJSON<VariableMeta> {
+    return {
+      ...super.toJSON(),
+      order: this.order,
+    };
+  }
+}

package/src/ast/expression/base-expression.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import {
+  type Observable,
+  distinctUntilChanged,
+  map,
+  switchMap,
+  combineLatest,
+  of,
+  Subject,
+  share,
+} from 'rxjs';
+import { shallowEqual } from 'fast-equals';
+
+import { getParentFields } from '../utils/variable-field';
+import { ASTNodeJSON, type CreateASTParams } from '../types';
+import { type BaseType } from '../type';
+import { ASTNodeFlags } from '../flags';
+import { type BaseVariableField } from '../declaration';
+import { ASTNode } from '../ast-node';
+import { subsToDisposable } from '../../utils/toDisposable';
+import { IVariableTable } from '../../scope/types';
+
+type ExpressionRefs = (BaseVariableField | undefined)[];
+
+/**
+ * Base class for all expressions.
+ *
+ * All other expressions should extend this class.
+ */
+export abstract class BaseExpression<JSON extends ASTNodeJSON = any> extends ASTNode<JSON> {
+  public flags: ASTNodeFlags = ASTNodeFlags.Expression;
+
+  /**
+   * Get the global variable table, which is used to access referenced variables.
+   */
+  get globalVariableTable(): IVariableTable {
+    return this.scope.variableEngine.globalVariableTable;
+  }
+
+  /**
+   * Parent variable fields, sorted from closest to farthest.
+   */
+  get parentFields(): BaseVariableField[] {
+    return getParentFields(this);
+  }
+
+  /**
+   * Get the variable fields referenced by the expression.
+   *
+   * This method should be implemented by subclasses.
+   * @returns An array of referenced variable fields.
+   */
+  abstract getRefFields(): ExpressionRefs;
+
+  /**
+   * The return type of the expression.
+   */
+  abstract returnType: BaseType | undefined;
+
+  /**
+   * The variable fields referenced by the expression.
+   */
+  protected _refs: ExpressionRefs = [];
+
+  /**
+   * The variable fields referenced by the expression.
+   */
+  get refs(): ExpressionRefs {
+    return this._refs;
+  }
+
+  protected refreshRefs$: Subject<void> = new Subject();
+
+  /**
+   * Refresh the variable references.
+   */
+  refreshRefs() {
+    this.refreshRefs$.next();
+  }
+
+  /**
+   * An observable that emits the referenced variable fields when they change.
+   */
+  refs$: Observable<ExpressionRefs> = this.refreshRefs$.pipe(
+    map(() => this.getRefFields()),
+    distinctUntilChanged<ExpressionRefs>(shallowEqual),
+    switchMap((refs) =>
+      !refs?.length
+        ? of([])
+        : combineLatest(
+            refs.map((ref) =>
+              ref
+                ? (ref.value$ as unknown as Observable<BaseVariableField | undefined>)
+                : of(undefined)
+            )
+          )
+    ),
+    share()
+  );
+
+  constructor(params: CreateASTParams, opts?: any) {
+    super(params, opts);
+
+    this.toDispose.push(
+      subsToDisposable(
+        this.refs$.subscribe((_refs: ExpressionRefs) => {
+          this._refs = _refs;
+          this.fireChange();
+        })
+      )
+    );
+  }
+}

package/src/ast/expression/enumerate-expression.ts

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind, ASTNodeJSON } from '../types';
+import { ArrayType } from '../type/array';
+import { BaseType } from '../type';
+import { BaseExpression } from './base-expression';
+
+/**
+ * ASTNodeJSON representation of `EnumerateExpression`
+ */
+export interface EnumerateExpressionJSON {
+  /**
+   * The expression to be enumerated.
+   */
+  enumerateFor: ASTNodeJSON;
+}
+
+/**
+ * Represents an enumeration expression, which iterates over a list and returns the type of the enumerated variable.
+ */
+export class EnumerateExpression extends BaseExpression<EnumerateExpressionJSON> {
+  static kind: string = ASTKind.EnumerateExpression;
+
+  protected _enumerateFor: BaseExpression | undefined;
+
+  /**
+   * The expression to be enumerated.
+   */
+  get enumerateFor() {
+    return this._enumerateFor;
+  }
+
+  /**
+   * The return type of the expression.
+   */
+  get returnType(): BaseType | undefined {
+    // The return value of the enumerated expression.
+    const childReturnType = this.enumerateFor?.returnType;
+
+    if (childReturnType?.kind === ASTKind.Array) {
+      // Get the item type of the array.
+      return (childReturnType as ArrayType).items;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * 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 }: EnumerateExpressionJSON): void {
+    this.updateChildNodeByKey('_enumerateFor', expression);
+  }
+
+  /**
+   * Serialize the `EnumerateExpression` to `EnumerateExpressionJSON`.
+   * @returns The JSON representation of `EnumerateExpression`.
+   */
+  toJSON() {
+    return {
+      kind: ASTKind.EnumerateExpression,
+      enumerateFor: this.enumerateFor?.toJSON(),
+    };
+  }
+}

package/src/ast/expression/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { BaseExpression } from './base-expression';
+export { EnumerateExpression, type EnumerateExpressionJSON } from './enumerate-expression';
+export { KeyPathExpression, type KeyPathExpressionJSON } from './keypath-expression';
+export { LegacyKeyPathExpression } from './legacy-keypath-expression';
+export { WrapArrayExpression, type WrapArrayExpressionJSON } from './wrap-array-expression';