use-build-options.ts

Overview

The use-build-options.ts file defines a custom React hook useBuildSubNodeOutputOptions that constructs and returns a structured list of output options for sub-nodes of a given node within a graph data structure. This hook is primarily used in the context of a node-based graph system, where each node can have children (sub-nodes) with outputs that need to be dynamically fetched and formatted for UI components such as dropdowns or selectors.

The functionality centers around filtering sub-nodes based on a parent node ID, excluding certain node types (specifically those labeled as IterationStart), and generating output options based on their form outputs. It leverages memoization for performance optimization and integrates with a centralized graph state store.

Detailed Explanation

Imports

• isEmpty from lodash: Utility to check if an object or array is empty.

• useMemo from react: React hook to memoize expensive computations.

• Operator from ../../constant: Enum or constants including operator labels, e.g., IterationStart.

• buildOutputOptions from ../../hooks/use-get-begin-query: Helper function to format output options from node form outputs.

• useGraphStore from ../../store: State management hook to access the graph's nodes.

Function: useBuildSubNodeOutputOptions

export function useBuildSubNodeOutputOptions(nodeId?: string): Array<{
  label: string;
  value: string;
  title: string;
  options: ReturnType<typeof buildOutputOptions>;
}>

Purpose

This React hook returns a list of output option objects representing the outputs of all valid sub-nodes of the node identified by nodeId.

Parameters

• nodeId (optional string): The identifier of the parent node whose sub-nodes' output options are to be built. If nodeId is undefined or falsy, the hook returns an empty array.

Returns

An array of objects, where each object represents a sub-node's output options structured as:

• label (string): The display name of the sub-node.

• value (string): The unique ID of the sub-node.

• title (string): The tooltip or descriptive title for the sub-node, same as label.

• options (array): The output options generated by buildOutputOptions based on the sub-node's form outputs.

Behavior & Implementation Details

• Uses useGraphStore to access the current nodes in the graph state.

• Uses useMemo to avoid recomputing the output options unless nodeId or nodes change.

• Filters nodes to:

  • Only include nodes whose parentId matches the provided nodeId.

  • Exclude nodes with the label Operator.IterationStart to skip iteration start nodes.

  • Include nodes only if they have non-empty outputs defined in their data.form.

• Maps the filtered nodes to the desired output options structure.

• Calls buildOutputOptions to format the outputs of each sub-node.

Usage Example

import { useBuildSubNodeOutputOptions } from './use-build-options';

function SubNodeOutputSelector({ parentNodeId }) {
  const outputOptions = useBuildSubNodeOutputOptions(parentNodeId);

  return (
    <select>
      {outputOptions.map((optionGroup) => (
        <optgroup label={optionGroup.label} key={optionGroup.value}>
          {optionGroup.options.map((opt) => (
            <option value={opt.value} key={opt.value} title={opt.title}>
              {opt.label}
            </option>
          ))}
        </optgroup>
      ))}
    </select>
  );
}

Important Implementation Details

• Exclusion of IterationStart Nodes: The hook explicitly filters out nodes labeled with Operator.IterationStart. This suggests that iteration start nodes are not considered valid output providers for this purpose, likely due to their special role in the graph.

• Use of useMemo: Ensures that the expensive filtering and mapping operations only run when dependencies change, improving performance especially in large graphs.

• Dependence on Centralized Store: The hook depends on useGraphStore, indicating it is tightly coupled with a global application state representing the graph nodes.

• Output Formatting Delegated: Formatting of individual node outputs is delegated to buildOutputOptions, promoting modularity and separation of concerns.

Interaction with Other System Components

• useGraphStore: This hook interacts with a global or centralized store managing the graph state, retrieving the current list of nodes.

• buildOutputOptions: Relies on this utility function to convert raw output definitions from node forms into UI-friendly option objects.

• Operator Constants: Uses operator constants to filter nodes by type.

• The resulting output options are typically used in UI components that need to present selectable outputs from sub-nodes, such as dropdown selectors or forms.

Mermaid Diagram

flowchart TD
    A[useBuildSubNodeOutputOptions(nodeId)] --> |calls| B[useGraphStore(state => state.nodes)]
    A --> |filters| C[Filter nodes where parentId = nodeId]
    C --> D[Exclude nodes with label === Operator.IterationStart]
    D --> E[Filter nodes with non-empty outputs]
    E --> F[Map nodes to output option objects]
    F --> G[Call buildOutputOptions on each node's outputs]
    G --> H[Return array of output option groups]

Summary

The use-build-options.ts file provides a specialized React hook that builds a structured set of output options from sub-nodes of a given node in a graph. It efficiently filters and processes nodes, excluding certain node types, and formats their outputs for UI consumption. It is a critical utility for components that allow users to select or interact with outputs of node subtrees in the graph, leveraging a centralized state store and modular helper functions.