@flowgram-vue/variable-core 0.2.0

package/src/ast/match.ts

@@ -0,0 +1,146 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind } from './types';
+import {
+  type StringType,
+  type NumberType,
+  type BooleanType,
+  type IntegerType,
+  type ObjectType,
+  type ArrayType,
+  type MapType,
+  type CustomType,
+} from './type';
+import { ASTNodeFlags } from './flags';
+import {
+  type WrapArrayExpression,
+  type EnumerateExpression,
+  type KeyPathExpression,
+} from './expression';
+import {
+  type BaseVariableField,
+  type Property,
+  type VariableDeclaration,
+  type VariableDeclarationList,
+} from './declaration';
+import { type ASTNode } from './ast-node';
+
+/**
+ * Variable-core ASTNode matchers.
+ *
+ * - Typescript code inside if statement will be type guarded.
+ */
+export namespace ASTMatch {
+  /**
+   * # Type-related matchers.
+   */
+
+  /**
+   * Check if the node is a `StringType`.
+   */
+  export const isString = (node?: ASTNode): node is StringType => node?.kind === ASTKind.String;
+
+  /**
+   * Check if the node is a `NumberType`.
+   */
+  export const isNumber = (node?: ASTNode): node is NumberType => node?.kind === ASTKind.Number;
+
+  /**
+   * Check if the node is a `BooleanType`.
+   */
+  export const isBoolean = (node?: ASTNode): node is BooleanType => node?.kind === ASTKind.Boolean;
+
+  /**
+   * Check if the node is a `IntegerType`.
+   */
+  export const isInteger = (node?: ASTNode): node is IntegerType => node?.kind === ASTKind.Integer;
+
+  /**
+   * Check if the node is a `ObjectType`.
+   */
+  export const isObject = (node?: ASTNode): node is ObjectType => node?.kind === ASTKind.Object;
+
+  /**
+   * Check if the node is a `ArrayType`.
+   */
+  export const isArray = (node?: ASTNode): node is ArrayType => node?.kind === ASTKind.Array;
+
+  /**
+   * Check if the node is a `MapType`.
+   */
+  export const isMap = (node?: ASTNode): node is MapType => node?.kind === ASTKind.Map;
+
+  /**
+   * Check if the node is a `CustomType`.
+   */
+  export const isCustomType = (node?: ASTNode): node is CustomType =>
+    node?.kind === ASTKind.CustomType;
+
+  /**
+   * # Declaration-related matchers.
+   */
+
+  /**
+   * Check if the node is a `VariableDeclaration`.
+   */
+  export const isVariableDeclaration = <VariableMeta = any>(
+    node?: ASTNode
+  ): node is VariableDeclaration<VariableMeta> => node?.kind === ASTKind.VariableDeclaration;
+
+  /**
+   * Check if the node is a `Property`.
+   */
+  export const isProperty = <VariableMeta = any>(node?: ASTNode): node is Property<VariableMeta> =>
+    node?.kind === ASTKind.Property;
+
+  /**
+   * Check if the node is a `BaseVariableField`.
+   */
+  export const isBaseVariableField = (node?: ASTNode): node is BaseVariableField =>
+    !!(node?.flags || 0 & ASTNodeFlags.VariableField);
+
+  /**
+   * Check if the node is a `VariableDeclarationList`.
+   */
+  export const isVariableDeclarationList = (node?: ASTNode): node is VariableDeclarationList =>
+    node?.kind === ASTKind.VariableDeclarationList;
+
+  /**
+   * # Expression-related matchers.
+   */
+
+  /**
+   * Check if the node is a `EnumerateExpression`.
+   */
+  export const isEnumerateExpression = (node?: ASTNode): node is EnumerateExpression =>
+    node?.kind === ASTKind.EnumerateExpression;
+
+  /**
+   * Check if the node is a `WrapArrayExpression`.
+   */
+  export const isWrapArrayExpression = (node?: ASTNode): node is WrapArrayExpression =>
+    node?.kind === ASTKind.WrapArrayExpression;
+
+  /**
+   * Check if the node is a `KeyPathExpression`.
+   */
+  export const isKeyPathExpression = (node?: ASTNode): node is KeyPathExpression =>
+    node?.kind === ASTKind.KeyPathExpression;
+
+  /**
+   * Check ASTNode Match by ASTClass
+   *
+   * @param node ASTNode to be checked.
+   * @param targetType Target ASTNode class.
+   * @returns Whether the node is of the target type.
+   */
+  export function is<TargetASTNode extends ASTNode>(
+    node?: ASTNode,
+    targetType?: { kind: string; new (...args: any[]): TargetASTNode }
+  ): node is TargetASTNode {
+    return node?.kind === targetType?.kind;
+  }
+}

package/src/ast/type/array.ts

@@ -0,0 +1,109 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { parseTypeJsonOrKind } from '../utils/helpers';
+import { ASTKind, ASTNodeJSON, ASTNodeJSONOrKind } from '../types';
+import { ASTNodeFlags } from '../flags';
+import { type BaseVariableField } from '../declaration';
+import { BaseType } from './base-type';
+
+/**
+ * ASTNodeJSON representation of `ArrayType`
+ */
+export interface ArrayJSON {
+  /**
+   * The type of the items in the array.
+   */
+  items?: ASTNodeJSONOrKind;
+}
+
+/**
+ * Represents an array type.
+ */
+export class ArrayType extends BaseType<ArrayJSON> {
+  public flags: ASTNodeFlags = ASTNodeFlags.DrilldownType | ASTNodeFlags.EnumerateType;
+
+  static kind: string = ASTKind.Array;
+
+  /**
+   * The type of the items in the array.
+   */
+  items: BaseType;
+
+  /**
+   * Deserializes the `ArrayJSON` to the `ArrayType`.
+   * @param json The `ArrayJSON` to deserialize.
+   */
+  fromJSON({ items }: ArrayJSON): void {
+    this.updateChildNodeByKey('items', parseTypeJsonOrKind(items));
+  }
+
+  /**
+   * Whether the items type can be drilled down.
+   */
+  get canDrilldownItems(): boolean {
+    return !!(this.items?.flags & ASTNodeFlags.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: string[]): BaseVariableField | undefined {
+    const [curr, ...rest] = keyPath || [];
+
+    if (curr === '0' && this.canDrilldownItems) {
+      // The first item of the array.
+      return this.items.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.
+   */
+  public isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean {
+    const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
+    const isSuperEqual = super.isTypeEqual(targetTypeJSONOrKind);
+
+    if (targetTypeJSON?.weak || targetTypeJSON?.kind === ASTKind.Union) {
+      return isSuperEqual;
+    }
+
+    return (
+      targetTypeJSON &&
+      isSuperEqual &&
+      // Weak comparison, only need to compare the Kind.
+      (targetTypeJSON?.weak || this.customStrongEqual(targetTypeJSON))
+    );
+  }
+
+  /**
+   * Array strong comparison.
+   * @param targetTypeJSON The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
+   */
+  protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean {
+    if (!this.items) {
+      return !(targetTypeJSON as ArrayJSON)?.items;
+    }
+    return this.items?.isTypeEqual((targetTypeJSON as ArrayJSON).items);
+  }
+
+  /**
+   * Serialize the `ArrayType` to `ArrayJSON`
+   * @returns The JSON representation of `ArrayType`.
+   */
+  toJSON() {
+    return {
+      kind: ASTKind.Array,
+      items: this.items?.toJSON(),
+    };
+  }
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { parseTypeJsonOrKind } from '../utils/helpers';
+import { ASTKind, ASTNodeJSON, ASTNodeJSONOrKind } from '../types';
+import { ASTNodeFlags } from '../flags';
+import { BaseVariableField } from '../declaration';
+import { ASTNode } from '../ast-node';
+import { UnionJSON } from './union';
+
+/**
+ * Base class for all types.
+ *
+ * All other types should extend this class.
+ */
+export abstract class BaseType<JSON extends ASTNodeJSON = any> extends ASTNode<JSON> {
+  public flags: number = ASTNodeFlags.BasicType;
+
+  /**
+   * 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.
+   */
+  public isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean {
+    const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
+
+    // If it is a Union type, it is sufficient for one of the subtypes to be equal.
+    if (targetTypeJSON?.kind === ASTKind.Union) {
+      return ((targetTypeJSON as UnionJSON)?.types || [])?.some((_subType) =>
+        this.isTypeEqual(_subType)
+      );
+    }
+
+    return this.kind === targetTypeJSON?.kind;
+  }
+
+  /**
+   * 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: string[] = []): BaseVariableField | undefined {
+    throw new Error(`Get By Key Path is not implemented for Type: ${this.kind}`);
+  }
+}

package/src/ast/type/boolean.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind } from '../types';
+import { BaseType } from './base-type';
+
+/**
+ * Represents a boolean type.
+ */
+export class BooleanType extends BaseType {
+  static kind: string = ASTKind.Boolean;
+
+  /**
+   * Deserializes the `BooleanJSON` to the `BooleanType`.
+   * @param json The `BooleanJSON` to deserialize.
+   */
+  fromJSON(): void {
+    // noop
+  }
+
+  toJSON() {
+    return {};
+  }
+}

package/src/ast/type/custom-type.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { parseTypeJsonOrKind } from '../utils/helpers';
+import { ASTKind, ASTNodeJSONOrKind } from '../types';
+import { type UnionJSON } from './union';
+import { BaseType } from './base-type';
+
+/**
+ * ASTNodeJSON representation of `CustomType`
+ */
+export interface CustomTypeJSON {
+  /**
+   * The name of the custom type.
+   */
+  typeName: string;
+}
+
+/**
+ * Represents a custom type.
+ */
+export class CustomType extends BaseType<CustomTypeJSON> {
+  static kind: string = ASTKind.CustomType;
+
+  protected _typeName: string;
+
+  /**
+   * The name of the custom type.
+   */
+  get typeName(): string {
+    return this._typeName;
+  }
+
+  /**
+   * Deserializes the `CustomTypeJSON` to the `CustomType`.
+   * @param json The `CustomTypeJSON` to deserialize.
+   */
+  fromJSON(json: CustomTypeJSON): void {
+    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.
+   */
+  public isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean {
+    const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
+
+    // If it is a Union type, it is sufficient for one of the subtypes to be equal.
+    if (targetTypeJSON?.kind === ASTKind.Union) {
+      return ((targetTypeJSON as UnionJSON)?.types || [])?.some((_subType) =>
+        this.isTypeEqual(_subType)
+      );
+    }
+
+    return targetTypeJSON?.kind === this.kind && targetTypeJSON?.typeName === this.typeName;
+  }
+
+  toJSON() {
+    return {
+      typeName: this.typeName,
+    };
+  }
+}

package/src/ast/type/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { StringType } from './string';
+export { IntegerType } from './integer';
+export { BooleanType } from './boolean';
+export { NumberType } from './number';
+export { ArrayType } from './array';
+export { MapType } from './map';
+export {
+  type ObjectJSON as ObjectJSON,
+  ObjectType,
+  type ObjectPropertiesChangeAction,
+} from './object';
+export { BaseType } from './base-type';
+export { type UnionJSON } from './union';
+export { CustomType, type CustomTypeJSON } from './custom-type';

package/src/ast/type/integer.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind } from '../types';
+import { ASTNodeFlags } from '../flags';
+import { BaseType } from './base-type';
+
+/**
+ * Represents an integer type.
+ */
+export class IntegerType extends BaseType {
+  public flags: ASTNodeFlags = ASTNodeFlags.BasicType;
+
+  static kind: string = ASTKind.Integer;
+
+  /**
+   * Deserializes the `IntegerJSON` to the `IntegerType`.
+   * @param json The `IntegerJSON` to deserialize.
+   */
+  fromJSON(): void {
+    // noop
+  }
+
+  toJSON() {
+    return {};
+  }
+}

package/src/ast/type/map.ts

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { parseTypeJsonOrKind } from '../utils/helpers';
+import { ASTKind, ASTNodeJSON, ASTNodeJSONOrKind } from '../types';
+import { BaseType } from './base-type';
+
+/**
+ * ASTNodeJSON representation of `MapType`
+ */
+export interface MapJSON {
+  /**
+   * The type of the keys in the map.
+   */
+  keyType?: ASTNodeJSONOrKind;
+  /**
+   * The type of the values in the map.
+   */
+  valueType?: ASTNodeJSONOrKind;
+}
+
+/**
+ * Represents a map type.
+ */
+export class MapType extends BaseType<MapJSON> {
+  static kind: string = ASTKind.Map;
+
+  /**
+   * The type of the keys in the map.
+   */
+  keyType: BaseType;
+
+  /**
+   * The type of the values in the map.
+   */
+  valueType: BaseType;
+
+  /**
+   * Deserializes the `MapJSON` to the `MapType`.
+   * @param json The `MapJSON` to deserialize.
+   */
+  fromJSON({ keyType = ASTKind.String, valueType }: MapJSON): void {
+    // Key defaults to String.
+    this.updateChildNodeByKey('keyType', parseTypeJsonOrKind(keyType));
+    this.updateChildNodeByKey('valueType', parseTypeJsonOrKind(valueType));
+  }
+
+  /**
+   * 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.
+   */
+  public isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean {
+    const targetTypeJSON = parseTypeJsonOrKind(targetTypeJSONOrKind);
+    const isSuperEqual = super.isTypeEqual(targetTypeJSONOrKind);
+
+    if (targetTypeJSON?.weak || targetTypeJSON?.kind === ASTKind.Union) {
+      return isSuperEqual;
+    }
+
+    return (
+      targetTypeJSON &&
+      isSuperEqual &&
+      // Weak comparison, only need to compare the Kind.
+      (targetTypeJSON?.weak || this.customStrongEqual(targetTypeJSON))
+    );
+  }
+
+  /**
+   * Map strong comparison.
+   * @param targetTypeJSON The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
+   */
+  protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean {
+    const { keyType = ASTKind.String, valueType } = targetTypeJSON as MapJSON;
+
+    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: ASTKind.Map,
+      keyType: this.keyType?.toJSON(),
+      valueType: this.valueType?.toJSON(),
+    };
+  }
+}

package/src/ast/type/number.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTKind } from '../types';
+import { BaseType } from './base-type';
+
+/**
+ * Represents a number type.
+ */
+export class NumberType extends BaseType {
+  static kind: string = ASTKind.Number;
+
+  /**
+   * Deserializes the `NumberJSON` to the `NumberType`.
+   * @param json The `NumberJSON` to deserialize.
+   */
+  fromJSON(): void {
+    // noop
+  }
+
+  toJSON() {
+    return {};
+  }
+}