@flowgram-vue/variable-core 0.2.0

package/src/ast/type/object.ts

@@ -0,0 +1,185 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { xor } from 'lodash-es';
+
+import { parseTypeJsonOrKind } from '../utils/helpers';
+import { ASTNodeJSON, ASTKind, ASTNodeJSONOrKind, type GlobalEventActionType } from '../types';
+import { ASTNodeFlags } from '../flags';
+import { Property, type PropertyJSON } from '../declaration/property';
+import { BaseType } from './base-type';
+
+/**
+ * ASTNodeJSON representation of `ObjectType`
+ */
+export interface ObjectJSON<VariableMeta = any> {
+  /**
+   * The properties of the object.
+   *
+   * The `properties` of an Object must be of type `Property`, so the business can omit the `kind` field.
+   */
+  properties?: PropertyJSON<VariableMeta>[];
+}
+
+/**
+ * Action type for object properties change.
+ */
+export type ObjectPropertiesChangeAction = GlobalEventActionType<
+  'ObjectPropertiesChange',
+  {
+    prev: Property[];
+    next: Property[];
+  },
+  ObjectType
+>;
+
+/**
+ * Represents an object type.
+ */
+export class ObjectType extends BaseType<ObjectJSON> {
+  public flags: ASTNodeFlags = ASTNodeFlags.DrilldownType;
+
+  static kind: string = ASTKind.Object;
+
+  /**
+   * A map of property keys to `Property` instances.
+   */
+  propertyTable: Map<string, Property> = new Map();
+
+  /**
+   * An array of `Property` instances.
+   */
+  properties: Property[];
+
+  /**
+   * Deserializes the `ObjectJSON` to the `ObjectType`.
+   * @param json The `ObjectJSON` to deserialize.
+   */
+  fromJSON({ properties }: ObjectJSON): void {
+    const removedKeys = new Set(this.propertyTable.keys());
+    const prev = [...(this.properties || [])];
+
+    // Iterate over the new properties.
+    this.properties = (properties || []).map((property: PropertyJSON) => {
+      const existProperty = this.propertyTable.get(property.key);
+      removedKeys.delete(property.key);
+
+      if (existProperty) {
+        existProperty.fromJSON(property as PropertyJSON);
+
+        return existProperty;
+      } else {
+        const newProperty = this.createChildNode({
+          ...property,
+          kind: ASTKind.Property,
+        }) as Property;
+
+        this.fireChange();
+
+        this.propertyTable.set(property.key, newProperty);
+        // TODO: When a child node is actively destroyed, delete the information in the table.
+
+        return newProperty;
+      }
+    });
+
+    // Delete properties that no longer exist.
+    removedKeys.forEach((key) => {
+      const property = this.propertyTable.get(key);
+      property?.dispose();
+      this.propertyTable.delete(key);
+      this.fireChange();
+    });
+
+    this.dispatchGlobalEvent<ObjectPropertiesChangeAction>({
+      type: 'ObjectPropertiesChange',
+      payload: {
+        prev,
+        next: [...this.properties],
+      },
+    });
+  }
+
+  /**
+   * Serialize the `ObjectType` to `ObjectJSON`.
+   * @returns The JSON representation of `ObjectType`.
+   */
+  toJSON() {
+    return {
+      properties: this.properties.map((_property) => _property.toJSON()),
+    };
+  }
+
+  /**
+   * 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[]): Property | undefined {
+    const [curr, ...restKeyPath] = keyPath;
+
+    const property = this.propertyTable.get(curr);
+
+    // Found the end of the path.
+    if (!restKeyPath.length) {
+      return property;
+    }
+
+    // Otherwise, continue searching downwards.
+    if (property?.type && property?.type?.flags & ASTNodeFlags.DrilldownType) {
+      return property.type.getByKeyPath(restKeyPath) as Property | undefined;
+    }
+
+    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))
+    );
+  }
+
+  /**
+   * Object type strong comparison.
+   * @param targetTypeJSON The type to compare with.
+   * @returns `true` if the types are equal, `false` otherwise.
+   */
+  protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean {
+    const targetProperties = (targetTypeJSON as ObjectJSON).properties || [];
+
+    const sourcePropertyKeys = Array.from(this.propertyTable.keys());
+    const targetPropertyKeys = targetProperties.map((_target) => _target.key);
+
+    const isKeyStrongEqual = !xor(sourcePropertyKeys, targetPropertyKeys).length;
+
+    return (
+      isKeyStrongEqual &&
+      targetProperties.every((targetProperty) => {
+        const sourceProperty = this.propertyTable.get(targetProperty.key);
+
+        return (
+          sourceProperty &&
+          sourceProperty.key === targetProperty.key &&
+          sourceProperty.type?.isTypeEqual(targetProperty?.type)
+        );
+      })
+    );
+  }
+}

package/src/ast/type/string.ts

@@ -0,0 +1,55 @@
+/**
+ * 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';
+
+/**
+ * ASTNodeJSON representation of the `StringType`.
+ */
+export interface StringJSON {
+  /**
+   * see https://json-schema.org/understanding-json-schema/reference/type#format
+   */
+  format?: string;
+}
+
+export class StringType extends BaseType<StringJSON> {
+  public flags: ASTNodeFlags = ASTNodeFlags.BasicType;
+
+  static kind: string = ASTKind.String;
+
+  protected _format?: string;
+
+  /**
+   * see https://json-schema.org/understanding-json-schema/reference/string#format
+   */
+  get format() {
+    return this._format;
+  }
+
+  /**
+   * Deserialize the `StringJSON` to the `StringType`.
+   *
+   * @param json StringJSON representation of the `StringType`.
+   */
+  fromJSON(json?: StringJSON): void {
+    if (json?.format !== this._format) {
+      this._format = json?.format;
+      this.fireChange();
+    }
+  }
+
+  /**
+   * Serialize the `StringType` to `StringJSON`.
+   * @returns The JSON representation of `StringType`.
+   */
+  toJSON() {
+    return {
+      format: this._format,
+    };
+  }
+}

package/src/ast/type/union.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTNodeJSONOrKind } from '../types';
+
+/**
+ * ASTNodeJSON representation of `UnionType`, which union multiple `BaseType`.
+ */
+export interface UnionJSON {
+  types?: ASTNodeJSONOrKind[];
+}

package/src/ast/types.ts

@@ -0,0 +1,188 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { type Observer } from 'rxjs';
+
+import { type Scope } from '../scope';
+import { type ASTNode } from './ast-node';
+
+export type ASTKindType = string;
+export type Identifier = string;
+
+/**
+ * ASTNodeJSON is the JSON representation of an ASTNode.
+ */
+export interface ASTNodeJSON {
+  /**
+   * Kind is the type of the AST node.
+   */
+  kind?: ASTKindType;
+
+  /**
+   * Key is the unique identifier of the node.
+   * If not provided, the node will generate a default key value.
+   */
+  key?: Identifier;
+  [key: string]: any;
+}
+
+/**
+ * Core AST node types.
+ */
+export enum ASTKind {
+  /**
+   * # Type-related.
+   * - A set of type AST nodes based on JSON types is implemented internally by default.
+   */
+
+  /**
+   * String type.
+   */
+  String = 'String',
+  /**
+   * Number type.
+   */
+  Number = 'Number',
+  /**
+   * Integer type.
+   */
+  Integer = 'Integer',
+  /**
+   * Boolean type.
+   */
+  Boolean = 'Boolean',
+  /**
+   * Object type.
+   */
+  Object = 'Object',
+  /**
+   * Array type.
+   */
+  Array = 'Array',
+  /**
+   * Map type.
+   */
+  Map = 'Map',
+  /**
+   * Union type.
+   * Commonly used for type checking, generally not exposed to the business.
+   */
+  Union = 'Union',
+  /**
+   * Any type.
+   * Commonly used for business logic.
+   */
+  Any = 'Any',
+  /**
+   * Custom type.
+   * For business-defined types.
+   */
+  CustomType = 'CustomType',
+
+  /**
+   * # Declaration-related.
+   */
+
+  /**
+   * Field definition for Object drill-down.
+   */
+  Property = 'Property',
+  /**
+   * Variable declaration.
+   */
+  VariableDeclaration = 'VariableDeclaration',
+  /**
+   * Variable declaration list.
+   */
+  VariableDeclarationList = 'VariableDeclarationList',
+
+  /**
+   * # Expression-related.
+   */
+
+  /**
+   * Access fields on variables through the path system.
+   */
+  KeyPathExpression = 'KeyPathExpression',
+  /**
+   * Iterate over specified data.
+   */
+  EnumerateExpression = 'EnumerateExpression',
+  /**
+   * Wrap with Array Type.
+   */
+  WrapArrayExpression = 'WrapArrayExpression',
+
+  /**
+   * # General-purpose AST nodes.
+   */
+
+  /**
+   * General-purpose List<ASTNode> storage node.
+   */
+  ListNode = 'ListNode',
+  /**
+   * General-purpose data storage node.
+   */
+  DataNode = 'DataNode',
+  /**
+   * General-purpose Map<string, ASTNode> storage node.
+   */
+  MapNode = 'MapNode',
+}
+
+export interface CreateASTParams {
+  scope: Scope;
+  key?: Identifier;
+  parent?: ASTNode;
+}
+
+export type ASTNodeJSONOrKind = string | ASTNodeJSON;
+
+export type ObserverOrNext<T> = Partial<Observer<T>> | ((value: T) => void);
+
+export interface SubscribeConfig<This, Data> {
+  // Merge all changes within one animationFrame into a single one.
+  debounceAnimation?: boolean;
+  // Respond with a value by default upon subscription.
+  triggerOnInit?: boolean;
+  selector?: (curr: This) => Data;
+}
+
+/**
+ * TypeUtils to get the JSON representation of an AST node with a specific kind.
+ */
+export type GetKindJSON<KindType extends string, JSON extends ASTNodeJSON> = {
+  kind: KindType;
+  key?: Identifier;
+} & JSON;
+
+/**
+ * TypeUtils to get the JSON representation of an AST node with a specific kind or just the kind string.
+ */
+export type GetKindJSONOrKind<KindType extends string, JSON extends ASTNodeJSON> =
+  | ({
+      kind: KindType;
+      key?: Identifier;
+    } & JSON)
+  | KindType;
+
+/**
+ * Global event action type.
+ * - Global event might be dispatched from `ASTNode` or `Scope`.
+ */
+export interface GlobalEventActionType<
+  Type = string,
+  Payload = any,
+  AST extends ASTNode = ASTNode
+> {
+  type: Type;
+  payload?: Payload;
+  ast?: AST;
+}
+
+export type NewASTAction = GlobalEventActionType<'NewAST'>;
+export type UpdateASTAction = GlobalEventActionType<'UpdateAST'>;
+export type DisposeASTAction = GlobalEventActionType<'DisposeAST'>;

package/src/ast/utils/expression.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { intersection } from 'lodash-es';
+
+import { ASTNodeFlags } from '../flags';
+import { type BaseExpression } from '../expression';
+import { type BaseVariableField } from '../declaration';
+import { type ASTNode } from '../ast-node';
+import { getParentFields } from './variable-field';
+import { getAllChildren } from './helpers';
+
+/**
+ * Get all variables referenced by child ASTs.
+ * @param ast The ASTNode to traverse.
+ * @returns All variables referenced by child ASTs.
+ */
+export function getAllRefs(ast: ASTNode): BaseVariableField[] {
+  return getAllChildren(ast)
+    .filter((_child) => _child.flags & ASTNodeFlags.Expression)
+    .map((_child) => (_child as BaseExpression).refs)
+    .flat()
+    .filter(Boolean) as BaseVariableField[];
+}
+
+/**
+ * Checks for circular references.
+ * @param curr The current expression.
+ * @param refNode The referenced variable node.
+ * @returns Whether a circular reference exists.
+ */
+export function checkRefCycle(
+  curr: BaseExpression,
+  refNodes: (BaseVariableField | undefined)[]
+): boolean {
+  // If there are no circular references in the scope, then it is impossible to have a circular reference.
+  if (
+    intersection(curr.scope.coverScopes, refNodes.map((_ref) => _ref?.scope).filter(Boolean))
+      .length === 0
+  ) {
+    return false;
+  }
+
+  // BFS traversal.
+  const visited = new Set<BaseVariableField>();
+  const queue = [...refNodes];
+
+  while (queue.length) {
+    const currNode = queue.shift()!;
+    visited.add(currNode);
+
+    for (const ref of getAllRefs(currNode).filter((_ref) => !visited.has(_ref))) {
+      queue.push(ref);
+    }
+  }
+
+  // If the referenced variables include the parent variable of the expression, then there is a circular reference.
+  return intersection(Array.from(visited), getParentFields(curr)).length > 0;
+}

package/src/ast/utils/helpers.ts

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTNodeJSON, ASTNodeJSONOrKind } from '../types';
+import { ASTMatch } from '../match';
+import { ASTNode } from '../ast-node';
+
+export function updateChildNodeHelper(
+  this: ASTNode,
+  {
+    getChildNode,
+    updateChildNode,
+    removeChildNode,
+    nextJSON,
+  }: {
+    getChildNode: () => ASTNode | undefined;
+    updateChildNode: (nextNode: ASTNode) => void;
+    removeChildNode: () => void;
+    nextJSON?: ASTNodeJSON;
+  }
+): ASTNode | undefined {
+  const currNode: ASTNode | undefined = getChildNode();
+
+  const isNewKind = currNode?.kind !== nextJSON?.kind;
+  // If `nextJSON` does not pass a key value, the key value remains unchanged by default.
+  const isNewKey = nextJSON?.key && nextJSON?.key !== currNode?.key;
+
+  if (isNewKind || isNewKey) {
+    // The previous node needs to be destroyed.
+    if (currNode) {
+      currNode.dispose();
+      removeChildNode();
+    }
+
+    if (nextJSON) {
+      const newNode = this.createChildNode(nextJSON);
+      updateChildNode(newNode);
+      this.fireChange();
+      return newNode;
+    } else {
+      // Also trigger an update when deleting a child node directly.
+      this.fireChange();
+    }
+  } else if (nextJSON) {
+    currNode?.fromJSON(nextJSON);
+  }
+
+  return currNode;
+}
+
+export function parseTypeJsonOrKind(typeJSONOrKind?: ASTNodeJSONOrKind): ASTNodeJSON | undefined {
+  return typeof typeJSONOrKind === 'string' ? { kind: typeJSONOrKind } : typeJSONOrKind;
+}
+
+// Get all children.
+export function getAllChildren(ast: ASTNode): ASTNode[] {
+  return [...ast.children, ...ast.children.map((_child) => getAllChildren(_child)).flat()];
+}
+
+/**
+ * isMatchAST is same as ASTMatch.is
+ * @param node
+ * @param targetType
+ * @returns
+ */
+export function isMatchAST<TargetASTNode extends ASTNode>(
+  node?: ASTNode,
+  targetType?: { kind: string; new (...args: any[]): TargetASTNode }
+): node is TargetASTNode {
+  return ASTMatch.is(node, targetType);
+}

package/src/ast/utils/inversify.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { interfaces } from 'inversify';
+
+import { type ASTNode } from '../ast-node';
+
+export const injectToAST = (serviceIdentifier: interfaces.ServiceIdentifier) =>
+  function (target: any, propertyKey: string) {
+    if (!serviceIdentifier) {
+      throw new Error(
+        `ServiceIdentifier ${serviceIdentifier} in @lazyInject is Empty, it might be caused by file circular dependency, please check it.`
+      );
+    }
+
+    const descriptor = {
+      get() {
+        const container = (this as ASTNode).scope.variableEngine.container;
+        return container.get(serviceIdentifier);
+      },
+      set() {},
+      configurable: true,
+      enumerable: true,
+    } as any;
+
+    // Object.defineProperty(target, propertyKey, descriptor);
+
+    return descriptor;
+  };
+
+export const POST_CONSTRUCT_AST_SYMBOL = Symbol('post_construct_ast');
+
+export const postConstructAST = () => (target: any, propertyKey: string) => {
+  // Only run once.
+  if (!Reflect.hasMetadata(POST_CONSTRUCT_AST_SYMBOL, target)) {
+    Reflect.defineMetadata(POST_CONSTRUCT_AST_SYMBOL, propertyKey, target);
+  } else {
+    throw Error('Duplication Post Construct AST');
+  }
+};

package/src/ast/utils/observable.ts

@@ -0,0 +1,5 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+

package/src/ast/utils/variable-field.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ASTNodeFlags } from '../flags';
+import { BaseVariableField } from '../declaration';
+import { ASTNode } from '../ast-node';
+
+/**
+ * Parent variable fields, sorted from nearest to farthest.
+ */
+export function getParentFields(ast: ASTNode): BaseVariableField[] {
+  let curr = ast.parent;
+  const res: BaseVariableField[] = [];
+
+  while (curr) {
+    if (curr.flags & ASTNodeFlags.VariableField) {
+      res.push(curr as BaseVariableField);
+    }
+    curr = curr.parent;
+  }
+
+  return res;
+}

package/src/composables/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { ScopeProvider, useCurrentScope, ScopeKey } from './scope-provider';
+export { useScopeAvailable } from './use-scope-available';
+export { useAvailableVariables } from './use-available-variables';
+export { useOutputVariables } from './use-output-variables';