utils.ts

Overview

The utils.ts file is a utility module designed to support the construction, manipulation, and management of graph nodes and edges within a flow-based application, likely involving a Directed Acyclic Graph (DAG) or workflow system. The utilities in this file mainly handle the conversion between DSL (Domain-Specific Language) components and graph representations, manage node and edge relationships, clean and prepare operator parameters, and assist in UI-related operations such as positioning and naming nodes.

This file is heavily oriented towards operators and nodes in a flow graph, particularly for a system involving RAG (Retrieval-Augmented Generation) flows, categorization, and iteration operators. It integrates with React flow components (@xyflow/react), uses Ant Design forms (antd), and leverages several utility libraries such as Lodash and UUID for common tasks.

Detailed Explanations

Imports and Dependencies

Functions

1. buildEdges

const buildEdges = (
  operatorIds: string[],
  currentId: string,
  allEdges: Edge[],
  isUpstream = false,
  componentName: string,
  nodeParams: Record<string, unknown>,
)

buildEdges(['node1', 'node2'], 'currentNode', edgesArray, false, 'Categorize', nodeParams);

2. buildNodesAndEdgesFromDSLComponents

export const buildNodesAndEdgesFromDSLComponents = (data: DSLComponents) => { ... }

const { nodes, edges } = buildNodesAndEdgesFromDSLComponents(dslComponents);

3. buildComponentDownstreamOrUpstream

const buildComponentDownstreamOrUpstream = (
  edges: Edge[],
  nodeId: string,
  isBuildDownstream = true,
) => { ... }

4. removeUselessDataInTheOperator (curried function)

const removeUselessDataInTheOperator = curry(
  (operatorName: string, params: Record<string, unknown>) => { ... }
);

5. buildOperatorParams

const buildOperatorParams = (operatorName: string) =>
  pipe(removeUselessDataInTheOperator(operatorName));

6. buildDslComponentsByGraph

export const buildDslComponentsByGraph = (
  nodes: RAGFlowNodeType[],
  edges: Edge[],
  oldDslComponents: DSLComponents,
): DSLComponents => { ... }

7. receiveMessageError

export const receiveMessageError = (res: any) => boolean;

8. replaceIdWithText

export const replaceIdWithText = (
  obj: Record<string, unknown> | unknown[] | unknown,
  getNameById: (id?: string) => string | undefined,
) => { ... }

9. isEdgeEqual

export const isEdgeEqual = (previous: Edge, current: Edge) => boolean;

10. buildNewPositionMap

export const buildNewPositionMap = (
  currentKeys: string[],
  previousPositionMap: Record<string, IPosition>,
) => { ... }

11. isKeysEqual

export const isKeysEqual = (currentKeys: string[], previousKeys: string[]) => boolean;

12. getOperatorIndex

export const getOperatorIndex = (handleTitle: string) => string | undefined;

13. getOtherFieldValues

export const getOtherFieldValues = (
  form: FormInstance,
  formListName: string = 'items',
  field: FormListFieldData,
  latestField: string,
) => string[];

14. generateSwitchHandleText

export const generateSwitchHandleText = (idx: number) => string;

15. getNodeDragHandle

export const getNodeDragHandle = (nodeType?: string) => string | undefined;

16. generateNodeNamesWithIncreasingIndex

export const generateNodeNamesWithIncreasingIndex = (
  name: string,
  nodes: RAGFlowNodeType[],
) => string;

17. duplicateNodeForm

export const duplicateNodeForm = (nodeData?: RAGFlowNodeType['data']) => RAGFlowNodeType['data'];

18. getDrawerWidth

export const getDrawerWidth = () => string | number;

19. needsSingleStepDebugging

export const needsSingleStepDebugging = (label: string) => boolean;

20. getRelativePositionToIterationNode

export function getRelativePositionToIterationNode(
  nodes: RAGFlowNodeType[],
  position?: XYPosition,
)

21. generateDuplicateNode

export const generateDuplicateNode = (
  position?: XYPosition,
  label?: string,
)

22. buildCategorizeListFromObject

export const buildCategorizeListFromObject = (
  categorizeItem: ICategorizeItemResult,
) => ICategorizeItem[];

Important Implementation Details and Algorithms

Interaction with Other Parts of the System

Usage Examples

import { buildNodesAndEdgesFromDSLComponents, buildDslComponentsByGraph } from './utils';

// Convert DSL components to graph
const { nodes, edges } = buildNodesAndEdgesFromDSLComponents(dslComponents);

// Update DSL from graph interactions
const updatedDSL = buildDslComponentsByGraph(nodes, edges, dslComponents);

// Generate a unique node name
const newName = generateNodeNamesWithIncreasingIndex('generate', nodes);

// Duplicate a node form
const duplicatedForm = duplicateNodeForm(nodes[0]?.data);

Mermaid Flowchart Diagram

flowchart TD
    A[buildNodesAndEdgesFromDSLComponents] --> B[buildEdges]
    B --> C[Edge Creation & Deduplication]
    A --> D[Node Creation]

    E[buildDslComponentsByGraph] --> F[buildComponentDownstreamOrUpstream]
    F --> G[Edge Filtering for Upstream/Downstream]
    E --> H[buildOperatorParams]
    H --> I[removeUselessDataInTheOperator]

    J[replaceIdWithText] --> K[Recursive ID Replacement]

    L[generateNodeNamesWithIncreasingIndex] --> M[Parse existing names]
    L --> N[Find next index]

    O[buildNewPositionMap] --> P[Calculate intersectionKeys]
    O --> Q[Assign new positions from anchor points]

    R[duplicateNodeForm] --> S[Clear downstream references for specific operators]

    T[getRelativePositionToIterationNode] --> U[Check bounding box]

    V[generateDuplicateNode] --> W[Generate new node with offset position]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#bbf,stroke:#333,stroke-width:2px
    style J fill:#fbf,stroke:#333,stroke-width:2px

Summary

The utils.ts file provides foundational utility functions to build and maintain a graph-based workflow system, including:

These utilities are essential to enable graph construction, editing, and serialization, supporting the broader system’s flow-based execution and visualization capabilities.