filter-downstream-nodes.ts

Overview

This file provides utility functions to traverse and filter downstream nodes in a directed graph structure, specifically within the context of a flow or pipeline system represented by nodes and edges. The main focus is on identifying downstream nodes connected via specific types of edges, such as agent operators or tools, by filtering edges based on source handles.

These utilities are essential for determining the propagation of effects, dependencies, or operations downstream from a given set of nodes, enabling workflows and logic to be executed or analyzed in a structured manner.

Functions

filterAllDownstreamNodeIds(edges, nodeIds, predicate)

Description

Recursively retrieves all downstream node IDs starting from the specified nodeIds, considering only edges that satisfy the given predicate. It performs a depth-first traversal of the graph edges, filtering edges based on a user-provided condition.

Parameters

• edges: Edge[]
  An array of edges representing connections between nodes. Each Edge object typically has source, target, and sourceHandle properties.

• nodeIds: string[]
  An array of node IDs from which to start searching downstream.

• predicate: (edge: Edge) => boolean
  A callback function to filter edges. Only edges for which this function returns true are traversed.

Returns

• string[]
  An array of unique downstream node IDs reachable from the input nodeIds through edges satisfying the predicate.

Usage Example

const downstreamNodes = filterAllDownstreamNodeIds(
  edges,
  ['node1', 'node2'],
  (edge) => edge.sourceHandle === 'someHandleId'
);

filterAllDownstreamAgentAndToolNodeIds(edges, nodeIds)

Description

Finds all downstream nodes that are either agent operators or tool operators starting from the given node IDs. This function uses a predicate that matches edges with sourceHandle equal to either AgentBottom or Tool.

Parameters

• edges: Edge[]
  Array of edges representing the graph.

• nodeIds: string[]
  Starting node IDs.

Returns

• string[]
  Array of downstream node IDs connected via edges with sourceHandle as AgentBottom or Tool.

Usage Example

const downstreamAgentsAndTools = filterAllDownstreamAgentAndToolNodeIds(
  edges,
  ['agentNode1']
);

filterAllDownstreamAgentNodeIds(edges, nodeIds)

Description

Retrieves all downstream agent operator nodes starting from the given node IDs. It filters edges with sourceHandle equal to AgentBottom only.

Parameters

• edges: Edge[]
  Array of edges.

• nodeIds: string[]
  Starting node IDs.

Returns

• string[]
  Downstream agent node IDs reachable from the input.

Usage Example

const downstreamAgents = filterAllDownstreamAgentNodeIds(edges, ['agentNode1']);

filterDownstreamAgentNodeIds(edges, nodeId)

Description

Gets the direct child agent nodes of the specified single node by filtering edges where the source is the node and the sourceHandle is AgentBottom. Unlike the recursive functions above, this only returns immediate downstream nodes.

Parameters

• edges: Edge[]
  Array of edges.

• nodeId?: string
  The ID of the node whose direct downstream agent nodes are to be found. Optional; if undefined, returns an empty list.

Returns

• string[]
  Array of direct downstream agent node IDs.

Usage Example

const directChildren = filterDownstreamAgentNodeIds(edges, 'agentNode1');

Implementation Details and Algorithms

• Recursive Depth-First Traversal:
  The filterAllDownstreamNodeIds function uses a recursive approach to traverse the graph downstream. For each node ID, it finds all edges originating from it that satisfy the predicate, collects their target nodes, and recursively continues from those targets.

• Duplicate Avoidance:
  To avoid duplicates, downstream node IDs are added to the accumulator array only if they are not already present (pre.every((y) => y !== x)).

• Predicate Filtering:
  The predicate function parameter allows flexible filtering of edges based on criteria like sourceHandle, enabling reuse for different types of downstream node filtering like agents or tools.

Interaction with Other Parts of the System

• Edges and Nodes:
  This file depends on the Edge type imported from @xyflow/react, indicating it is part of a larger flow or graph visualization/manipulation system.

• Constants:
  It uses NodeHandleId constants (imported from ../constant) to identify types of connections, such as AgentBottom and Tool. These constants likely represent specific handles or ports on nodes.

• Use Case:
  These utilities are likely used in modules that need to analyze or operate on the flow graph, such as determining which nodes downstream are affected by changes, executing downstream operations, or visualizing flows.

Mermaid Diagram - Function Flowchart

flowchart TD
    A[filterAllDownstreamNodeIds] -->|calls recursively| A
    B[filterAllDownstreamAgentAndToolNodeIds] -->|calls| A
    C[filterAllDownstreamAgentNodeIds] -->|calls| A
    D[filterDownstreamAgentNodeIds]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:1.5px
    style C fill:#bbf,stroke:#333,stroke-width:1.5px
    style D fill:#afa,stroke:#333,stroke-width:1.5px

    B --> A
    C --> A

Diagram Explanation:

• filterAllDownstreamNodeIds is the core recursive function.

• filterAllDownstreamAgentAndToolNodeIds and filterAllDownstreamAgentNodeIds are specialized wrappers that invoke the core function with different predicates.

• filterDownstreamAgentNodeIds is a simpler, non-recursive function that directly filters edges for immediate downstream agent nodes.

Summary

This file offers a set of utility functions to traverse downstream nodes in a graph, filtering based on edge properties to isolate agent and tool nodes in particular. By combining recursion, predicate filtering, and duplicate checks, it efficiently extracts relevant downstream node IDs for use in graph processing, visualization, or execution workflows within the larger application.