Class StateManager

Manages the GraphState partitions (input, scratch, artifacts, memory, diagnostics) for a single graph run.

All methods return a new GraphState object; the original is never mutated.

Example

const manager = new StateManager({ 'scratch.messages': 'concat' });
let state = manager.initialize({ prompt: 'Hello' });
state = manager.updateScratch(state, { messages: ['first'] });
state = manager.updateScratch(state, { messages: ['second'] });
// state.scratch.messages === ['first', 'second']

Constructors

constructor

Methods

initialize updateScratch updateArtifacts recordNodeVisit mergeParallelBranches

Constructors

constructor

Methods

initialize

  • initialize(input): GraphState<unknown, unknown, unknown>

  • Create a clean initial GraphState from the caller-supplied input value.

    The input partition is frozen with Object.freeze() so that no node can accidentally mutate it. All other partitions start empty.

    Parameters

    • input: unknown

      Arbitrary value provided by the graph caller; becomes state.input.

    Returns GraphState<unknown, unknown, unknown>

    A fully initialised GraphState ready for the first node execution.

updateScratch

  • updateScratch(state, patch): GraphState<unknown, unknown, unknown>

  • Apply a patch to the scratch partition, honoring any registered reducers.

    For each key in patch:

    • If a reducer is registered at scratch.<key> and the key already exists in the current scratch, the reducer is called to merge the existing and incoming values.
    • Otherwise the incoming value simply overwrites (last-write-wins semantics).

    Parameters

    • state: GraphState<unknown, unknown, unknown>

      Current graph state (not mutated).

    • patch: Record<string, unknown>

      Partial scratch update emitted by a completed node.

    Returns GraphState<unknown, unknown, unknown>

    New GraphState with the merged scratch partition.

updateArtifacts

  • updateArtifacts(state, patch): GraphState<unknown, unknown, unknown>

  • Apply a patch to the artifacts partition using last-write-wins semantics.

    Artifact fields are intended for caller-facing outputs and are not subject to reducer logic in this method. If you need reducer-aware artifact merging, use mergeParallelBranches() instead.

    Parameters

    • state: GraphState<unknown, unknown, unknown>

      Current graph state (not mutated).

    • patch: Record<string, unknown>

      Partial artifacts update emitted by a completed node.

    Returns GraphState<unknown, unknown, unknown>

    New GraphState with the updated artifacts partition.

recordNodeVisit

  • recordNodeVisit(state, nodeId): GraphState<unknown, unknown, unknown>

  • Record that execution has entered nodeId.

    Updates currentNodeId, appends to visitedNodes, and increments iteration.

    Parameters

    • state: GraphState<unknown, unknown, unknown>

      Current graph state (not mutated).

    • nodeId: string

      Id of the node that is about to execute.

    Returns GraphState<unknown, unknown, unknown>

    New GraphState reflecting the visit.

mergeParallelBranches

  • mergeParallelBranches(baseState, branchStates): GraphState<unknown, unknown, unknown>

  • Merge the scratch partitions of one or more parallel branch states back into a single GraphState.

    The algorithm walks every key present in any branch's scratch object and applies the registered reducer for that key (if any) against the accumulator. When no reducer is registered, the last branch's value wins.

    The artifacts, memory, diagnostics, visitedNodes, and iteration fields of baseState are preserved unchanged — the caller is responsible for merging those separately if needed.

    Parameters

    • baseState: GraphState<unknown, unknown, unknown>

      State prior to the parallel fan-out (provides the baseline scratch).

    • branchStates: GraphState<unknown, unknown, unknown>[]

      States produced by each parallel branch.

    Returns GraphState<unknown, unknown, unknown>

    New GraphState with the merged scratch partition.

Settings

Member Visibility

Theme

On This Page

constructorinitializeupdateScratchupdateArtifactsrecordNodeVisitmergeParallelBranches