@flowgram-vue/variable-core 0.2.0

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

@@ -0,0 +1,157 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { distinctUntilChanged } from 'rxjs';
+import { shallowEqual } from 'fast-equals';
+
+import { checkRefCycle } from '../utils/expression';
+import { ASTNodeJSON, ASTKind, CreateASTParams } from '../types';
+import { BaseType } from '../type';
+import { type BaseVariableField } from '../declaration';
+import { subsToDisposable } from '../../utils/toDisposable';
+import { BaseExpression } from './base-expression';
+
+/**
+ * ASTNodeJSON representation of `KeyPathExpression`
+ */
+export interface KeyPathExpressionJSON {
+  /**
+   * The key path of the variable.
+   */
+  keyPath: string[];
+}
+
+/**
+ * Represents a key path expression, which is used to reference a variable by its key path.
+ *
+ * This is the V2 of `KeyPathExpression`, with the following improvements:
+ * - `returnType` is copied to a new instance to avoid reference issues.
+ * - Circular reference detection is introduced.
+ */
+export class KeyPathExpression<
+  CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON
+> extends BaseExpression<CustomPathJSON> {
+  static kind: string = ASTKind.KeyPathExpression;
+
+  protected _keyPath: string[] = [];
+
+  protected _rawPathJson: CustomPathJSON;
+
+  /**
+   * The key path of the variable.
+   */
+  get keyPath(): string[] {
+    return this._keyPath;
+  }
+
+  /**
+   * Get the variable fields referenced by the expression.
+   * @returns An array of referenced variable fields.
+   */
+  getRefFields(): BaseVariableField[] {
+    const ref = this.scope.available.getByKeyPath(this._keyPath);
+
+    // When refreshing references, check for circular references. If a circular reference exists, do not reference the variable.
+    if (checkRefCycle(this, [ref])) {
+      // Prompt that a circular reference exists.
+      console.warn(
+        '[CustomKeyPathExpression] checkRefCycle: Reference Cycle Existed',
+        this.parentFields.map((_field) => _field.key).reverse()
+      );
+      return [];
+    }
+
+    return ref ? [ref] : [];
+  }
+
+  /**
+   * The return type of the expression.
+   *
+   * A new `returnType` node is generated directly, instead of reusing the existing one, to ensure that different key paths do not point to the same field.
+   */
+  _returnType: BaseType;
+
+  /**
+   * The return type of the expression.
+   */
+  get returnType() {
+    return this._returnType;
+  }
+
+  /**
+   * 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.
+   */
+  protected parseToKeyPath(json: CustomPathJSON): string[] {
+    // The default JSON is in KeyPathExpressionJSON format.
+    return (json as unknown as KeyPathExpressionJSON).keyPath;
+  }
+
+  /**
+   * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+   * @param json The `KeyPathExpressionJSON` to deserialize.
+   */
+  fromJSON(json: CustomPathJSON): void {
+    const keyPath = this.parseToKeyPath(json);
+
+    if (!shallowEqual(keyPath, this._keyPath)) {
+      this._keyPath = keyPath;
+      this._rawPathJson = json;
+
+      // After the keyPath is updated, the referenced variables need to be refreshed.
+      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: BaseVariableField | undefined): ASTNodeJSON | undefined {
+    return _ref?.type?.toJSON();
+  }
+
+  constructor(params: CreateASTParams, opts: any) {
+    super(params, opts);
+
+    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();
+        }
+      }),
+      subsToDisposable(
+        this.refs$
+          .pipe(
+            distinctUntilChanged(
+              (prev, next) => prev === next,
+              (_refs) => _refs?.[0]?.type?.hash
+            )
+          )
+          .subscribe((_type) => {
+            const [ref] = this._refs;
+            this.updateChildNodeByKey('_returnType', this.getReturnTypeJSONByRef(ref));
+          })
+      ),
+    ]);
+  }
+
+  /**
+   * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+   * @returns The JSON representation of `KeyPathExpression`.
+   */
+  toJSON() {
+    return this._rawPathJson;
+  }
+}

package/src/ast/expression/legacy-keypath-expression.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { shallowEqual } from 'fast-equals';
+
+import { ASTNodeJSON, ASTKind, CreateASTParams } from '../types';
+import { BaseType } from '../type';
+import { ASTNodeFlags } from '../flags';
+import { type BaseVariableField } from '../declaration';
+import { BaseExpression } from './base-expression';
+
+/**
+ * ASTNodeJSON representation of `KeyPathExpression`
+ */
+export interface KeyPathExpressionJSON {
+  /**
+   * The key path of the variable.
+   */
+  keyPath: string[];
+}
+
+/**
+ * @deprecated Use `KeyPathExpression` instead.
+ * Represents a key path expression, which is used to reference a variable by its key path.
+ */
+export class LegacyKeyPathExpression<
+  CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON
+> extends BaseExpression<CustomPathJSON> {
+  static kind: string = ASTKind.KeyPathExpression;
+
+  protected _keyPath: string[] = [];
+
+  protected _rawPathJson: CustomPathJSON;
+
+  /**
+   * The key path of the variable.
+   */
+  get keyPath(): string[] {
+    return this._keyPath;
+  }
+
+  /**
+   * Get the variable fields referenced by the expression.
+   * @returns An array of referenced variable fields.
+   */
+  getRefFields(): BaseVariableField[] {
+    const ref = this.scope.available.getByKeyPath(this._keyPath);
+    return ref ? [ref] : [];
+  }
+
+  /**
+   * The return type of the expression.
+   */
+  get returnType(): BaseType | undefined {
+    const [refNode] = this._refs || [];
+
+    // Get the type of the referenced variable.
+    if (refNode && refNode.flags & ASTNodeFlags.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.
+   */
+  protected parseToKeyPath(json: CustomPathJSON): string[] {
+    // The default JSON is in KeyPathExpressionJSON format.
+    return (json as unknown as KeyPathExpressionJSON).keyPath;
+  }
+
+  /**
+   * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+   * @param json The `KeyPathExpressionJSON` to deserialize.
+   */
+  fromJSON(json: CustomPathJSON): void {
+    const keyPath = this.parseToKeyPath(json);
+
+    if (!shallowEqual(keyPath, this._keyPath)) {
+      this._keyPath = keyPath;
+      this._rawPathJson = json;
+
+      // After the keyPath is updated, the referenced variables need to be refreshed.
+      this.refreshRefs();
+    }
+  }
+
+  constructor(params: CreateASTParams, opts: any) {
+    super(params, opts);
+
+    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();
+        }
+      }),
+    ]);
+  }
+
+  /**
+   * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+   * @returns The JSON representation of `KeyPathExpression`.
+   */
+  toJSON() {
+    return this._rawPathJson;
+  }
+}

package/src/ast/expression/wrap-array-expression.ts

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { postConstructAST } from '../utils/inversify';
+import { ASTKind, ASTNodeJSON } from '../types';
+import { BaseType } from '../type';
+import { BaseExpression } from './base-expression';
+
+/**
+ * ASTNodeJSON representation of `WrapArrayExpression`
+ */
+export interface WrapArrayExpressionJSON {
+  /**
+   * The expression to be wrapped.
+   */
+  wrapFor: ASTNodeJSON;
+}
+
+/**
+ * Represents a wrap expression, which wraps an expression with an array.
+ */
+export class WrapArrayExpression extends BaseExpression<WrapArrayExpressionJSON> {
+  static kind: string = ASTKind.WrapArrayExpression;
+
+  protected _wrapFor: BaseExpression | undefined;
+
+  protected _returnType: BaseType | undefined;
+
+  /**
+   * The expression to be wrapped.
+   */
+  get wrapFor() {
+    return this._wrapFor;
+  }
+
+  /**
+   * The return type of the expression.
+   */
+  get returnType(): BaseType | undefined {
+    return this._returnType;
+  }
+
+  /**
+   * Refresh the return type of the expression.
+   */
+  refreshReturnType() {
+    // The return value of the wrapped expression.
+    const childReturnTypeJSON = this.wrapFor?.returnType?.toJSON();
+
+    this.updateChildNodeByKey('_returnType', {
+      kind: ASTKind.Array,
+      items: childReturnTypeJSON,
+    });
+  }
+
+  /**
+   * Get the variable fields referenced by the expression.
+   * @returns An empty array, as this expression does not reference any variables.
+   */
+  getRefFields(): [] {
+    return [];
+  }
+
+  /**
+   * Deserializes the `WrapArrayExpressionJSON` to the `WrapArrayExpression`.
+   * @param json The `WrapArrayExpressionJSON` to deserialize.
+   */
+  fromJSON({ wrapFor: expression }: WrapArrayExpressionJSON): void {
+    this.updateChildNodeByKey('_wrapFor', expression);
+  }
+
+  /**
+   * Serialize the `WrapArrayExpression` to `WrapArrayExpressionJSON`.
+   * @returns The JSON representation of `WrapArrayExpression`.
+   */
+  toJSON() {
+    return {
+      kind: ASTKind.WrapArrayExpression,
+      wrapFor: this.wrapFor?.toJSON(),
+    };
+  }
+
+  @postConstructAST()
+  protected init() {
+    this.refreshReturnType = this.refreshReturnType.bind(this);
+
+    this.toDispose.push(
+      this.subscribe(this.refreshReturnType, {
+        selector: (curr) => curr.wrapFor?.returnType,
+        triggerOnInit: true,
+      })
+    );
+  }
+}

package/src/ast/factory.ts

@@ -0,0 +1,163 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind, ASTNodeJSON } from './types';
+import { StringJSON } from './type/string';
+import { MapJSON } from './type/map';
+import { ArrayJSON } from './type/array';
+import { CustomTypeJSON, ObjectJSON, UnionJSON } from './type';
+import {
+  EnumerateExpressionJSON,
+  KeyPathExpressionJSON,
+  WrapArrayExpressionJSON,
+} from './expression';
+import { PropertyJSON, VariableDeclarationJSON, VariableDeclarationListJSON } from './declaration';
+import { ASTNode } from './ast-node';
+
+/**
+ * Variable-core ASTNode factories.
+ */
+export namespace ASTFactory {
+  /**
+   * Type-related factories.
+   */
+
+  /**
+   * Creates a `String` type node.
+   */
+  export const createString = (json?: StringJSON) => ({
+    kind: ASTKind.String,
+    ...(json || {}),
+  });
+
+  /**
+   * Creates a `Number` type node.
+   */
+  export const createNumber = () => ({ kind: ASTKind.Number });
+
+  /**
+   * Creates a `Boolean` type node.
+   */
+  export const createBoolean = () => ({ kind: ASTKind.Boolean });
+
+  /**
+   * Creates an `Integer` type node.
+   */
+  export const createInteger = () => ({ kind: ASTKind.Integer });
+
+  /**
+   * Creates an `Object` type node.
+   */
+  export const createObject = (json: ObjectJSON) => ({
+    kind: ASTKind.Object,
+    ...json,
+  });
+
+  /**
+   * Creates an `Array` type node.
+   */
+  export const createArray = (json: ArrayJSON) => ({
+    kind: ASTKind.Array,
+    ...json,
+  });
+
+  /**
+   * Creates a `Map` type node.
+   */
+  export const createMap = (json: MapJSON) => ({
+    kind: ASTKind.Map,
+    ...json,
+  });
+
+  /**
+   * Creates a `Union` type node.
+   */
+  export const createUnion = (json: UnionJSON) => ({
+    kind: ASTKind.Union,
+    ...json,
+  });
+
+  /**
+   * Creates a `CustomType` node.
+   */
+  export const createCustomType = (json: CustomTypeJSON) => ({
+    kind: ASTKind.CustomType,
+    ...json,
+  });
+
+  /**
+   * Declaration-related factories.
+   */
+
+  /**
+   * Creates a `VariableDeclaration` node.
+   */
+  export const createVariableDeclaration = <VariableMeta = any>(
+    json: VariableDeclarationJSON<VariableMeta>
+  ) => ({
+    kind: ASTKind.VariableDeclaration,
+    ...json,
+  });
+
+  /**
+   * Creates a `Property` node.
+   */
+  export const createProperty = <VariableMeta = any>(json: PropertyJSON<VariableMeta>) => ({
+    kind: ASTKind.Property,
+    ...json,
+  });
+
+  /**
+   * Creates a `VariableDeclarationList` node.
+   */
+  export const createVariableDeclarationList = (json: VariableDeclarationListJSON) => ({
+    kind: ASTKind.VariableDeclarationList,
+    ...json,
+  });
+
+  /**
+   * Expression-related factories.
+   */
+
+  /**
+   * Creates an `EnumerateExpression` node.
+   */
+  export const createEnumerateExpression = (json: EnumerateExpressionJSON) => ({
+    kind: ASTKind.EnumerateExpression,
+    ...json,
+  });
+
+  /**
+   * Creates a `KeyPathExpression` node.
+   */
+  export const createKeyPathExpression = (json: KeyPathExpressionJSON) => ({
+    kind: ASTKind.KeyPathExpression,
+    ...json,
+  });
+
+  /**
+   * Creates a `WrapArrayExpression` node.
+   */
+  export const createWrapArrayExpression = (json: WrapArrayExpressionJSON) => ({
+    kind: ASTKind.WrapArrayExpression,
+    ...json,
+  });
+
+  /**
+   * Create by AST Class.
+   */
+
+  /**
+   * Creates Type-Safe ASTNodeJSON object based on the provided AST class.
+   *
+   * @param targetType Target ASTNode class.
+   * @param json The JSON data for the node.
+   * @returns The ASTNode JSON object.
+   */
+  export const create = <JSON extends ASTNodeJSON>(
+    targetType: { kind: string; new (...args: any[]): ASTNode<JSON> },
+    json: JSON
+  ) => ({ kind: targetType.kind, ...json });
+}

package/src/ast/flags.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNode flags. Stored in the `flags` property of the `ASTNode`.
+ */
+export enum ASTNodeFlags {
+  /**
+   * None.
+   */
+  None = 0,
+
+  /**
+   * Variable Field.
+   */
+  VariableField = 1 << 0,
+
+  /**
+   * Expression.
+   */
+  Expression = 1 << 2,
+
+  /**
+   * # Variable Type Flags
+   */
+
+  /**
+   *  Basic type.
+   */
+  BasicType = 1 << 3,
+  /**
+   * Drillable variable type.
+   */
+  DrilldownType = 1 << 4,
+  /**
+   * Enumerable variable type.
+   */
+  EnumerateType = 1 << 5,
+  /**
+   * Composite type, currently not in use.
+   */
+  UnionType = 1 << 6,
+
+  /**
+   * Variable type.
+   */
+  VariableType = BasicType | DrilldownType | EnumerateType | UnionType,
+}

package/src/ast/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export {
+  type ASTNodeJSON,
+  ASTKind,
+  type GetKindJSON,
+  type GetKindJSONOrKind,
+  type CreateASTParams,
+  type GlobalEventActionType,
+} from './types';
+export { ASTRegisters } from './ast-registers';
+export { ASTNode, type ASTNodeRegistry } from './ast-node';
+export { ASTNodeFlags } from './flags';
+
+export * from './common';
+export * from './declaration';
+export * from './type';
+export * from './expression';
+
+export { ASTFactory } from './factory';
+export { ASTMatch } from './match';
+export { injectToAST, postConstructAST } from './utils/inversify';
+export { isMatchAST } from './utils/helpers';