@flowuent-org/diagramming-core 1.1.4 → 1.1.6

package/packages/diagrams/src/lib/utils/nodeOrderByEdges.ts

@@ -0,0 +1,437 @@
+import { Node, Edge } from '@xyflow/react';
+
+/**
+ * Options for ordering nodes by edges
+ */
+export interface NodeOrderOptions {
+  /** Whether to include orphan nodes (nodes with no connections) at the end */
+  includeOrphanNodes?: boolean;
+  /** Strategy for handling branches: 'breadth-first' or 'depth-first' */
+  traversalStrategy?: 'breadth-first' | 'depth-first';
+}
+
+/**
+ * Result of topological sort with additional metadata
+ */
+export interface NodeOrderResult<T extends Node = Node> {
+  /** Ordered nodes following the arrow direction */
+  orderedNodes: T[];
+  /** Nodes that have no incoming edges (start nodes) */
+  startNodes: T[];
+  /** Nodes that have no outgoing edges (end nodes) */
+  endNodes: T[];
+  /** Nodes with no connections (orphan nodes) */
+  orphanNodes: T[];
+  /** Whether the graph has cycles */
+  hasCycles: boolean;
+  /** Execution levels - nodes grouped by their depth in the flow */
+  levels: T[][];
+}
+
+/**
+ * Orders nodes based on edge connections (arrow direction from source to target).
+ * Uses topological sort to determine the correct execution order.
+ * 
+ * @param nodes - Array of nodes to order
+ * @param edges - Array of edges connecting the nodes
+ * @param options - Optional configuration for ordering
+ * @returns NodeOrderResult with ordered nodes and metadata
+ * 
+ * @example
+ * ```tsx
+ * import { orderNodesByEdges } from '@diagrams/utils/nodeOrderByEdges';
+ * 
+ * const { orderedNodes, startNodes, endNodes } = orderNodesByEdges(nodes, edges);
+ * 
+ * // Execute nodes in order
+ * for (const node of orderedNodes) {
+ *   await executeNode(node);
+ * }
+ * ```
+ */
+export function orderNodesByEdges<T extends Node = Node>(
+  nodes: T[],
+  edges: Edge[],
+  options: NodeOrderOptions = {}
+): NodeOrderResult<T> {
+  const { includeOrphanNodes = true, traversalStrategy = 'breadth-first' } = options;
+
+  // Build adjacency list and in-degree map
+  const adjacencyList = new Map<string, string[]>();
+  const inDegree = new Map<string, number>();
+  const nodeMap = new Map<string, T>();
+
+  // Initialize maps
+  nodes.forEach((node) => {
+    nodeMap.set(node.id, node);
+    adjacencyList.set(node.id, []);
+    inDegree.set(node.id, 0);
+  });
+
+  // Build graph from edges
+  edges.forEach((edge) => {
+    const sourceId = edge.source;
+    const targetId = edge.target;
+
+    // Only process edges where both source and target exist
+    if (nodeMap.has(sourceId) && nodeMap.has(targetId)) {
+      adjacencyList.get(sourceId)!.push(targetId);
+      inDegree.set(targetId, (inDegree.get(targetId) || 0) + 1);
+    }
+  });
+
+  // Find start nodes (no incoming edges)
+  const startNodes: T[] = [];
+  const orphanNodes: T[] = [];
+  
+  nodes.forEach((node) => {
+    const hasIncoming = inDegree.get(node.id)! > 0;
+    const hasOutgoing = (adjacencyList.get(node.id)?.length || 0) > 0;
+
+    if (!hasIncoming && !hasOutgoing) {
+      orphanNodes.push(node);
+    } else if (!hasIncoming) {
+      startNodes.push(node);
+    }
+  });
+
+  // Find end nodes (no outgoing edges)
+  const endNodes: T[] = nodes.filter((node) => {
+    const hasOutgoing = (adjacencyList.get(node.id)?.length || 0) > 0;
+    const hasIncoming = inDegree.get(node.id)! > 0;
+    return !hasOutgoing && hasIncoming;
+  });
+
+  // Perform topological sort (Kahn's algorithm with BFS or DFS)
+  const orderedNodes: T[] = [];
+  const levels: T[][] = [];
+  const visited = new Set<string>();
+
+  if (traversalStrategy === 'breadth-first') {
+    // BFS-based topological sort
+    const queue: string[] = startNodes.map((n) => n.id);
+    const tempInDegree = new Map(inDegree);
+
+    while (queue.length > 0) {
+      const currentLevel: T[] = [];
+      const levelSize = queue.length;
+
+      for (let i = 0; i < levelSize; i++) {
+        const nodeId = queue.shift()!;
+        
+        if (visited.has(nodeId)) continue;
+        visited.add(nodeId);
+
+        const node = nodeMap.get(nodeId);
+        if (node) {
+          orderedNodes.push(node);
+          currentLevel.push(node);
+        }
+
+        // Process neighbors
+        const neighbors = adjacencyList.get(nodeId) || [];
+        neighbors.forEach((neighborId) => {
+          tempInDegree.set(neighborId, (tempInDegree.get(neighborId) || 1) - 1);
+          if (tempInDegree.get(neighborId) === 0 && !visited.has(neighborId)) {
+            queue.push(neighborId);
+          }
+        });
+      }
+
+      if (currentLevel.length > 0) {
+        levels.push(currentLevel);
+      }
+    }
+  } else {
+    // DFS-based topological sort
+    const stack: string[] = [];
+    const tempVisited = new Set<string>();
+
+    const dfs = (nodeId: string) => {
+      if (tempVisited.has(nodeId)) return;
+      tempVisited.add(nodeId);
+
+      const neighbors = adjacencyList.get(nodeId) || [];
+      neighbors.forEach((neighborId) => {
+        if (!tempVisited.has(neighborId)) {
+          dfs(neighborId);
+        }
+      });
+
+      stack.push(nodeId);
+    };
+
+    startNodes.forEach((node) => dfs(node.id));
+
+    // Reverse to get correct order
+    while (stack.length > 0) {
+      const nodeId = stack.pop()!;
+      visited.add(nodeId);
+      const node = nodeMap.get(nodeId);
+      if (node) {
+        orderedNodes.push(node);
+      }
+    }
+
+    // Build levels for DFS (approximate - based on longest path from start)
+    const levelMap = new Map<string, number>();
+    orderedNodes.forEach((node, index) => {
+      const neighbors = adjacencyList.get(node.id) || [];
+      let maxParentLevel = -1;
+
+      edges.forEach((edge) => {
+        if (edge.target === node.id && levelMap.has(edge.source)) {
+          maxParentLevel = Math.max(maxParentLevel, levelMap.get(edge.source)!);
+        }
+      });
+
+      levelMap.set(node.id, maxParentLevel + 1);
+    });
+
+    // Group by levels
+    const levelGroups = new Map<number, T[]>();
+    orderedNodes.forEach((node) => {
+      const level = levelMap.get(node.id) || 0;
+      if (!levelGroups.has(level)) {
+        levelGroups.set(level, []);
+      }
+      levelGroups.get(level)!.push(node);
+    });
+
+    // Convert to array
+    const sortedLevels = Array.from(levelGroups.keys()).sort((a, b) => a - b);
+    sortedLevels.forEach((level) => {
+      levels.push(levelGroups.get(level)!);
+    });
+  }
+
+  // Check for cycles (nodes not visited = cycle exists)
+  const hasCycles = visited.size < (nodes.length - orphanNodes.length);
+
+  // Add orphan nodes at the end if requested
+  if (includeOrphanNodes) {
+    orderedNodes.push(...orphanNodes);
+  }
+
+  return {
+    orderedNodes,
+    startNodes,
+    endNodes,
+    orphanNodes,
+    hasCycles,
+    levels,
+  };
+}
+
+/**
+ * Gets the next nodes that follow a given node based on edge connections
+ * 
+ * @param nodeId - ID of the current node
+ * @param edges - Array of edges
+ * @param nodes - Array of nodes
+ * @returns Array of next nodes (targets of edges from this node)
+ */
+export function getNextNodes<T extends Node = Node>(
+  nodeId: string,
+  edges: Edge[],
+  nodes: T[]
+): T[] {
+  const outgoingEdges = edges.filter((edge) => edge.source === nodeId);
+  const nextNodeIds = outgoingEdges.map((edge) => edge.target);
+  return nodes.filter((node) => nextNodeIds.includes(node.id));
+}
+
+/**
+ * Gets the previous nodes that lead to a given node based on edge connections
+ * 
+ * @param nodeId - ID of the current node
+ * @param edges - Array of edges
+ * @param nodes - Array of nodes
+ * @returns Array of previous nodes (sources of edges to this node)
+ */
+export function getPreviousNodes<T extends Node = Node>(
+  nodeId: string,
+  edges: Edge[],
+  nodes: T[]
+): T[] {
+  const incomingEdges = edges.filter((edge) => edge.target === nodeId);
+  const prevNodeIds = incomingEdges.map((edge) => edge.source);
+  return nodes.filter((node) => prevNodeIds.includes(node.id));
+}
+
+/**
+ * Finds all paths from start nodes to end nodes
+ * 
+ * @param nodes - Array of nodes
+ * @param edges - Array of edges
+ * @returns Array of paths, where each path is an array of node IDs
+ */
+export function findAllPaths<T extends Node = Node>(
+  nodes: T[],
+  edges: Edge[]
+): string[][] {
+  const { startNodes, endNodes } = orderNodesByEdges(nodes, edges);
+  const paths: string[][] = [];
+
+  const adjacencyList = new Map<string, string[]>();
+  nodes.forEach((node) => adjacencyList.set(node.id, []));
+  edges.forEach((edge) => {
+    if (adjacencyList.has(edge.source)) {
+      adjacencyList.get(edge.source)!.push(edge.target);
+    }
+  });
+
+  const dfs = (currentId: string, currentPath: string[], visited: Set<string>) => {
+    currentPath.push(currentId);
+    visited.add(currentId);
+
+    const neighbors = adjacencyList.get(currentId) || [];
+    
+    if (neighbors.length === 0 || endNodes.some((n) => n.id === currentId)) {
+      // Reached an end node or leaf
+      paths.push([...currentPath]);
+    } else {
+      neighbors.forEach((neighborId) => {
+        if (!visited.has(neighborId)) {
+          dfs(neighborId, currentPath, new Set(visited));
+        }
+      });
+    }
+
+    currentPath.pop();
+  };
+
+  startNodes.forEach((startNode) => {
+    dfs(startNode.id, [], new Set());
+  });
+
+  return paths;
+}
+
+/**
+ * Gets the execution order of nodes for a workflow, handling branches
+ * 
+ * @param nodes - Array of nodes
+ * @param edges - Array of edges
+ * @returns Object with execution sequence and branch information
+ */
+export function getWorkflowExecutionOrder<T extends Node = Node>(
+  nodes: T[],
+  edges: Edge[]
+): {
+  sequence: T[];
+  branches: { branchPoint: T; branches: T[][] }[];
+} {
+  const { orderedNodes, startNodes } = orderNodesByEdges(nodes, edges);
+  
+  const adjacencyList = new Map<string, string[]>();
+  nodes.forEach((node) => adjacencyList.set(node.id, []));
+  edges.forEach((edge) => {
+    if (adjacencyList.has(edge.source)) {
+      adjacencyList.get(edge.source)!.push(edge.target);
+    }
+  });
+
+  const nodeMap = new Map<string, T>();
+  nodes.forEach((node) => nodeMap.set(node.id, node));
+
+  // Find branch points (nodes with multiple outgoing edges)
+  const branches: { branchPoint: T; branches: T[][] }[] = [];
+  
+  orderedNodes.forEach((node) => {
+    const outgoing = adjacencyList.get(node.id) || [];
+    if (outgoing.length > 1) {
+      const branchPaths = outgoing.map((targetId) => {
+        const path: T[] = [];
+        let currentId = targetId;
+        const visited = new Set<string>();
+
+        while (currentId && !visited.has(currentId)) {
+          visited.add(currentId);
+          const currentNode = nodeMap.get(currentId);
+          if (currentNode) {
+            path.push(currentNode);
+          }
+          const nextNodes = adjacencyList.get(currentId) || [];
+          currentId = nextNodes[0]; // Follow first path for simplicity
+        }
+
+        return path;
+      });
+
+      branches.push({
+        branchPoint: node,
+        branches: branchPaths,
+      });
+    }
+  });
+
+  return {
+    sequence: orderedNodes,
+    branches,
+  };
+}
+
+/**
+ * Validates the node graph for execution
+ * 
+ * @param nodes - Array of nodes
+ * @param edges - Array of edges
+ * @returns Validation result with any errors
+ */
+export function validateNodeGraph<T extends Node = Node>(
+  nodes: T[],
+  edges: Edge[]
+): {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const { startNodes, endNodes, orphanNodes, hasCycles } = orderNodesByEdges(nodes, edges);
+
+  // Check for start nodes
+  if (startNodes.length === 0) {
+    errors.push('No start node found (no nodes without incoming edges)');
+  }
+
+  // Check for multiple start nodes
+  if (startNodes.length > 1) {
+    warnings.push(`Multiple start nodes found: ${startNodes.map((n) => n.id).join(', ')}`);
+  }
+
+  // Check for end nodes
+  if (endNodes.length === 0 && nodes.length > 0) {
+    warnings.push('No end node found (no nodes without outgoing edges)');
+  }
+
+  // Check for orphan nodes
+  if (orphanNodes.length > 0) {
+    warnings.push(`Found ${orphanNodes.length} orphan node(s) with no connections: ${orphanNodes.map((n) => n.id).join(', ')}`);
+  }
+
+  // Check for cycles
+  if (hasCycles) {
+    errors.push('Graph contains cycles - execution order may be undefined');
+  }
+
+  // Check for disconnected edges
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  edges.forEach((edge) => {
+    if (!nodeIds.has(edge.source)) {
+      errors.push(`Edge ${edge.id} has invalid source: ${edge.source}`);
+    }
+    if (!nodeIds.has(edge.target)) {
+      errors.push(`Edge ${edge.id} has invalid target: ${edge.target}`);
+    }
+  });
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+