#Concepts

#Reading Path

• Skim the terminology navigator below to confirm the term you need is covered.
• Study the “Core Concepts” diagram to link variables, scopes, and AST into one picture.
• Jump to the sections you need based on the problem at hand—no need to read in order.

#Core Concepts

You can connect the variable engine’s core concepts through the diagram below:

To keep things tangible, hold on to one real-world case:

A “Batch” node reads the array output from an upstream HTTP node → iterates to produce item → and continues using item inside its child nodes.

Every concept mentioned in that workflow appears below, so feel free to cross-reference as you read.

#Variable

Variables are containers defined during design time and evaluated during runtime. See Variable Introduction for a deeper primer.

#Scope 🌟

A scope is a container that bundles variable information and keeps track of relationships with other scopes. In short, a scope decides “who can access which variables.”

Its boundaries vary by business scenario; the three most common cases are:

Scene	Example
Nodes in a process can be defined as scopes
The global variable sidebar can also be defined as a scope
Components (including variables) in UI editing can be defined as scopes

#AST 🌟

Scopes store variable information through an AST. Treat it as a tree where each node describes a declaration, type, or expression.

#ASTNode

ASTNode is the basic information unit used in the variable engine to store variable information. It can model various pieces of information:

• Declarations: such as VariableDeclaration, used to declare new variables.
• Types: such as StringType, used to represent the String type.
• Expressions: such as KeyPathExpression, used to reference variables.

#ASTNodeJSON

ASTNodeJSON is the pure JSON serialization of an ASTNode. We usually construct it on the design side and let the variable engine instantiate it later.

Its most important field is kind, which indicates the type of the ASTNode:

/**
 * Equivalent to the JavaScript code:
 * `var var_index: string`
 */
{
  kind: 'VariableDeclaration',
  key: 'var_index',
  type: { kind: 'StringType' },
}

When using the variable engine, we describe variable information with ASTNodeJSON. The engine then instantiates it into an ASTNode and stores it in the scope.

/**
 * Instantiate ASTNodeJSON into an ASTNode and add it to the scope using the scope.setVar method
 */
const variableDeclaration: VariableDeclaration = scope.setVar({
  kind: 'VariableDeclaration',
  key: 'var_index',
  type: { kind: 'StringType' },
});

/**
 * After ASTNodeJSON is instantiated into an ASTNode, you can listen for changes reactively
 */
variableDeclaration.onTypeChange((newType) => {
  console.log('Variable type changed', newType);
})

import { ASTFactory } from '@flowgram/editor';

/**
 * Type-safely create a VariableDeclaration ASTNodeJSON
 *
 * Equivalent to:
 * {
 *   kind: 'VariableDeclaration',
 *   key: 'var_index',
 *   type: { kind: 'StringType' },
 * }
 */
ASTFactory.createVariableDeclaration({
  key: 'var_index',
  type: { kind: 'StringType' },
});

#Declaration 🌟

Declaration = Identifier (Key) + Definition. In design mode, a declaration is an ASTNode that stores an identifier plus variable information—the smallest unit that can be referenced.

• Identifier (Key): The index used to access a declaration.
• Definition: The information carried by the declaration. For a variable, the definition = type + right-hand value.

/**
 * Identifier: some_var
 * Variable Definition: type is number, initial value is 10
 */
const some_var: number = 10;

/**
 * Identifier: add
 * Function Definition: parameters are two number variables a, b, and the return value is a number variable
 */
function add(a: number, b: number): number {
  return a + b;
}

/**
 * Identifier: Point
 * Struct Definition: fields are x, y, both of type number
 */
interface Point {
  x: number;
  y: number;
}

The variable engine currently only provides variable field declaration (BaseVariableField), and extends it to two types of declarations: variable declaration (VariableDeclaration) and property declaration (Property).

• Variable Field Declaration (BaseVariableField) = Identifier + Variable Field Definition (Type + Metadata + Initial Value)
• Variable Declaration (VariableDeclaration) = Globally Unique Identifier + Variable Definition (Type + Metadata + Initial Value + Order within Scope)
• Property Declaration (Property) = Unique within Object Identifier + Property Definition (Type + Metadata + Initial Value)

#Type 🌟

Types constrain the range of variable values. In design mode, a type is also an ASTNode. Understanding types helps you reason about what a variable can store and what an expression returns.

The variable engine has built-in basic types from JSON:

• StringType: string
• IntegerType: integer
• NumberType: floating-point number
• BooleanType: boolean
• ObjectType: object, which can be drilled down into Property declarations.
• ArrayType: array, which can be drilled down into other types.

It also adds:

• MapType: key-value pairs, where both keys and values can have type definitions.
• CustomType: can be custom extended by the user, such as date, time, file types, etc.

#Expression

An expression takes 0 or more variables as input, processes them in a specific way, and returns a new variable. Design time only records “who it depends on” and the inferred return type—runtime handles the actual value calculation.

In design mode, an expression is an ASTNode. Modeling focuses on:

• Which variable declarations does the expression use?
• How is the expression's return type inferred?

Example: How the Variable Engine Implements Type Inference + Linking

The figure shows a common example: a batch processing node references the output variable of a preceding node, iterates over it, and obtains an item variable. The type of the item variable automatically changes with the type of the output variable of the preceding node.

The ASTNodeJSON for this example can be represented as:

ASTFactory.createVariableDeclaration({
  key: 'item',
  initializer: ASTFactory.createEnumerateExpression({
    enumerateFor: ASTFactory.createKeyPathExpression({
      keyPath: ['start_0', 'arr']
    })
  })
})

The type inference chain is as follows:

#Scope Chain

The scope chain defines which other scopes a scope can read variables from. Think of it as the whitelist for variable access. The variable engine exposes an abstract class, and product teams can implement custom scope chains as needed.

Out of the box, the engine ships with free-layout and fixed-layout scope chain implementations.

#Dependency Scope

Dependency scope = the upstream scopes whose output variables the current scope can access.

You can access a scope's Dependency Scope via scope.depScopes.

#Covering Scope

Covering scope = the downstream scopes that can access the current scope’s output variables.

You can access a scope's Covering Scope via scope.coverScopes.

#Variables in the Canvas

FlowGram defines the following special types of scopes in the canvas:

#Node Scope 🌟

Also known as Node Public Scope, this scope can access the variables of the Node Scope of upstream nodes, and its output variable declarations can also be accessed by the Node Scope of downstream nodes.

The Node Scope can be set and retrieved via node.scope. Its scope chain relationship is shown in the figure below:

#Node Private Scope

The output variables of a Node Private Scope can only be accessed within the current node's Node Scope and its child nodes' Node Scope. This is similar to the concept of private variables in programming languages.

The Node Private Scope can be set and retrieved via node.privateScope. Its scope chain relationship is shown in the figure below:

#Global Scope

Variables in the Global Scope are readable from all node scopes and node private scopes, yet the global scope itself does not depend on any other scope. It’s ideal for configuration, constants, environment context, and other shared data.

For how to set the global scope, see Output Global Variables. Its scope chain relationship is shown in the figure below:

#Overall Architecture

The variable engine follows the Dependency Inversion Principle (DIP) and is split into three layers according to code stability, abstraction level, and proximity to business logic:

#Variable Abstraction Layer

This abstraction layer is the most stable part of the architecture. It defines the core interfaces—ASTNode, Scope, ScopeChain, and more—that upper layers extend.

#Variable Implementation Layer

This layer sits closer to product requirements and evolves more often. The engine provides a set of built-in ASTNode and ScopeChain implementations, and you can register new ones or override defaults via dependency injection when your domain demands it.

#Variable Material Layer

The outermost layer adopts the Facade pattern to boost usability, packaging complex capabilities into “materials” that can be reused directly.

• For the use of variable materials, see: Materials