DependencyGraph

Defined in: packages/engine/src/vm/DependencyGraph.ts:20

Dependency graph for variable and data-source tracking across document lines.

Tracks which lines read/write which variables, and propagates changes through the graph when a variable is modified. Supports:

• Variable dependency tracking (registerLine, getAffectedLines)
• Data-source dependency tracking (registerLineDataSourceDependency)
• Topological ordering of affected lines (getAffectedLinesInOrder)
• Efficient removal of deleted lines (removeLine)

Constructors

Constructor

new DependencyGraph(): DependencyGraph;

Returns

DependencyGraph

Methods

clear()

clear(): void;

Defined in: packages/engine/src/vm/DependencyGraph.ts:332

Clear all dependency graph state. Called on document switch or engine reset.

Returns

void

---

getAffectedLines()

getAffectedLines(changedVariable): Set<number>;

Defined in: packages/engine/src/vm/DependencyGraph.ts:105

Find all lines affected by a changed variable via BFS through the consumer graph.

When a variable is modified (e.g., :x = 5 changes to :x = 10), this returns all lines that transitively depend on it, lines that read x, lines that read variables written by those lines, and so on.

Parameters

Parameter	Type	Description
changedVariable	string	The variable name that changed

Returns

Set<number>

Set of line numbers that need re-evaluation

---

getAffectedLinesByDataSource()

getAffectedLinesByDataSource(dataSourceId, queryKey): Set<number>;

Defined in: packages/engine/src/vm/DependencyGraph.ts:226

Find all lines affected by a data source update.

When an async data source resolves (e.g., currency rate fetch completes), this returns all lines that depend on that specific data query.

Parameters

Parameter	Type	Description
dataSourceId	string	The data source identifier
queryKey	string[]	The query key that was updated

Returns

Set<number>

Set of line numbers that need re-evaluation

---

getAffectedLinesInOrder()

getAffectedLinesInOrder(startVariable): number[];

Defined in: packages/engine/src/vm/DependencyGraph.ts:136

Phase 1.4 DAG-walk optimization: return affected lines in dependency-safe topological order. Uses Kahn’s algorithm (BFS-based) to ensure every line is evaluated AFTER all lines it depends on have been processed.

This is more correct than ascending line-number sort, which fails when variable definitions and their consumers are not in document order.

Parameters

Parameter	Type
startVariable	string

Returns

number[]

Line numbers in topological order (producers before consumers).

---

getConsumers()

getConsumers(variable): Set<number>;

Defined in: packages/engine/src/vm/DependencyGraph.ts:272

Get all line numbers that consume (read) a given variable.

Parameters

Parameter	Type	Description
variable	string	The variable name

Returns

Set<number>

Set of line numbers that read this variable, or empty set if none

---

getDependencies()

getDependencies(lineNumber): Set<string>;

Defined in: packages/engine/src/vm/DependencyGraph.ts:282

Get all variables that a line depends on (reads).

Parameters

Parameter	Type	Description
lineNumber	number	The line number to query

Returns

Set<string>

Set of variable names this line reads, or empty set if none

---

getSnapshot()

getSnapshot(): DagSnapshot;

Defined in: packages/engine/src/vm/DependencyGraph.ts:302

Get a serializable snapshot of the entire dependency graph for diagnostics.

Returns plain objects (not Maps/Sets) so consumers don’t need to reach into private fields. Used by playground diagnostic tabs for DAG visualization.

Returns

DagSnapshot

---

getWrites()

getWrites(lineNumber): Set<string>;

Defined in: packages/engine/src/vm/DependencyGraph.ts:292

Get all variables that a line writes (assigns to).

Parameters

Parameter	Type	Description
lineNumber	number	The line number to query

Returns

Set<string>

Set of variable names this line writes, or empty set if none

---

registerLine()

registerLine(
   lineNumber,
   reads,
   writes): void;

Defined in: packages/engine/src/vm/DependencyGraph.ts:42

Register a line’s variable reads and writes in the dependency graph.

If re-registering the same line (e.g., after editing), old consumer references are cleaned up first. Write-variables are removed from the consumer set so that redefinition breaks the old dependency chain.

Parameters

Parameter	Type	Description
lineNumber	number	1-based line number in the document
reads	string[]	Variable names this line reads
writes	string[]	Variable names this line writes (assigns to)

Returns

void

---

registerLineDataSourceDependency()

registerLineDataSourceDependency(
   lineNumber,
   dataSourceId,
   queryKey): void;

Defined in: packages/engine/src/vm/DependencyGraph.ts:80

Register a line’s dependency on an external data source (e.g., currency rate, OSRS GE price).

When the data source updates, getAffectedLinesByDataSource returns all lines that depend on this data, enabling targeted re-evaluation.

Parameters

Parameter	Type	Description
lineNumber	number	1-based line number in the document
dataSourceId	string	Unique identifier for the data source (e.g., “currency”, “osrs-ge”)
queryKey	string[]	Query key array identifying the specific data (e.g., [“USD”, “EUR”])

Returns

void

---

removeLine()

removeLine(lineNumber): void;

Defined in: packages/engine/src/vm/DependencyGraph.ts:240

Remove a line from the dependency graph (e.g., when a line is deleted from the document).

Cleans up all consumer references, write registrations, and data source dependencies for the removed line. O(k) where k is the number of variables the line reads.

Parameters

Parameter	Type	Description
lineNumber	number	The line number being removed

Returns

void