use-build-options.ts

Overview

The use-build-options.ts file defines a React custom hook, useBuildSubNodeOutputOptions, which is responsible for generating a structured list of output options from a graph store's nodes. Specifically, it processes the child nodes (sub-nodes) of a given node and extracts their outputs, formatting them into an options array suitable for UI components such as dropdowns or selectors.

This hook optimizes performance by memoizing the computed options, recalculating only when the nodeId or the graph nodes change. It excludes nodes marked as iteration start operators and nodes lacking output data, ensuring only relevant sub-node outputs are presented.

Detailed Explanation

`useBuildSubNodeOutputOptions(nodeId?: string): Array<SubNodeOutputOption>`

A React hook that returns an array of output options derived from the sub-nodes of the node identified by nodeId.

Parameters

Parameter	Type	Description
`nodeId`	`string` (optional)	The unique identifier of the parent node whose sub-nodes are to be processed. If absent, the hook returns an empty array.

Returns

An array of objects, each representing a sub-node's output options:

type SubNodeOutputOption = {
  label: string;       // The display name of the sub-node
  value: string;       // The unique identifier of the sub-node
  title: string;       // Tooltip or title text, typically the sub-node's name
  options: Array<any>; // An array of output options built from the sub-node's form outputs
};

Usage Example

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

function OutputSelector({ nodeId }: { nodeId: string }) {
  const outputOptions = useBuildSubNodeOutputOptions(nodeId);

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

Implementation Details

State Source: The hook utilizes useGraphStore (likely a Zustand or similar state management store) to access the current graph nodes.
Filtering Logic:
- It filters nodes that have a parentId matching the input nodeId.
- Excludes nodes where data.label equals the constant Operator.IterationStart, likely representing loop entry points that do not have meaningful outputs for this context.
- Excludes nodes with empty or undefined data.form.outputs.
Output Options Construction:
- For each qualifying node, it creates an object containing:
  - label and title set to the node's human-readable name (data.name).
  - value set to the node's unique id.
  - options constructed by invoking buildOutputOptions with the node's output definitions and id.
Performance Optimization:
- Uses React's useMemo to memoize the computed array, avoiding unnecessary recomputations unless nodeId or nodes change.

Interaction with Other Parts of the System

useGraphStore: This hook accesses the global graph state, which contains all nodes and their metadata.
Operator.IterationStart: This constant is imported from a central constants file and is used to filter out iteration start nodes.
buildOutputOptions: A utility function (imported from use-get-begin-query hook) that processes the raw outputs of a node's form into a structured format appropriate for UI consumption.
Consumer Components: UI components that need to present selectable outputs from sub-nodes—like dropdowns or complex selectors—will use this hook to get the data structure they require.

Summary

This file provides a specialized, memoized hook that centralizes the logic to extract and format output options from sub-nodes in a graph structure, enabling other components to easily consume and display these options. It enforces filtering rules to ensure only relevant sub-nodes with meaningful outputs are included, thereby simplifying UI logic and improving maintainability.

Mermaid Diagram

flowchart TD
    A[useBuildSubNodeOutputOptions(nodeId?)] --> B{Check nodeId exists}
    B -- No --> C[Return []]
    B -- Yes --> D[Retrieve nodes from useGraphStore]
    D --> E[Filter nodes where]
    E -->|parentId === nodeId| F[Exclude nodes with label === IterationStart]
    F --> G[Exclude nodes with empty form.outputs]
    G --> H[Map filtered nodes to output options]
    H --> I[Return array of { label, value, title, options }]
    I --> J[buildOutputOptions(outputs, nodeId) called for options]

Appendix - Imports Summary

Import	Source	Role
isEmpty	`lodash`	Utility to check if outputs object/array is empty
`useMemo`	`react`	Memoization hook to optimize performance
`Operator`	../../constant	Contains constants like `IterationStart` for filtering nodes
`buildOutputOptions`	../../hooks/use-get-begin-query	Function to build formatted output options from raw outputs
`useGraphStore`	../../store	State hook to access graph nodes

End of Documentation for use-build-options.ts