@synergenius/flow-weaver 0.2.0

package/dist/api/query.d.ts

@@ -0,0 +1,429 @@
+/**
+ * Query API for read-only workflow inspection
+ * All functions are pure and do not modify the workflow
+ */
+import type { TWorkflowAST, TNodeInstanceAST, TConnectionAST, TPortReference } from '../ast/types.js';
+import type { NodeFilter } from './helpers.js';
+/**
+ * Get a single node instance by ID
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - ID of node to retrieve
+ * @returns Node instance or undefined
+ *
+ * @example
+ * ```typescript
+ * const node = getNode(workflow, 'processor1');
+ * if (node) {
+ *   console.log(`Node type: ${node.nodeType}`);
+ * }
+ * ```
+ */
+export declare function getNode(ast: TWorkflowAST, nodeId: string): TNodeInstanceAST | undefined;
+/**
+ * Get all node instances, optionally filtered
+ *
+ * @param ast - Workflow to query
+ * @param filter - Optional filter criteria
+ * @returns Array of matching node instances
+ *
+ * @example
+ * ```typescript
+ * // Get all nodes
+ * const allNodes = getNodes(workflow);
+ *
+ * // Get nodes of specific type
+ * const processors = getNodes(workflow, { type: 'processor' });
+ *
+ * // Get nodes in specific scope
+ * const scopedNodes = getNodes(workflow, { scope: 'mainLoop' });
+ *
+ * // Custom filter
+ * const configured = getNodes(workflow, {
+ *   predicate: (node) => node.config !== undefined
+ * });
+ * ```
+ */
+export declare function getNodes(ast: TWorkflowAST, filter?: NodeFilter): TNodeInstanceAST[];
+/**
+ * Get all nodes of a specific type
+ *
+ * @param ast - Workflow to query
+ * @param nodeType - Node type (functionName) to filter by
+ * @returns Array of matching node instances
+ *
+ * @example
+ * ```typescript
+ * const processors = getNodesByType(workflow, 'process');
+ * console.log(`Found ${processors.length} processor nodes`);
+ * ```
+ */
+export declare function getNodesByType(ast: TWorkflowAST, nodeType: string): TNodeInstanceAST[];
+/**
+ * Get all nodes in a specific scope
+ *
+ * @param ast - Workflow to query
+ * @param scopeName - Name of scope
+ * @returns Array of node instances in the scope
+ *
+ * @example
+ * ```typescript
+ * const loopNodes = getNodesInScope(workflow, 'mainLoop');
+ * ```
+ */
+export declare function getNodesInScope(ast: TWorkflowAST, scopeName: string): TNodeInstanceAST[];
+/**
+ * Check if a node exists
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - ID of node to check
+ * @returns True if node exists
+ *
+ * @example
+ * ```typescript
+ * if (hasNode(workflow, 'processor1')) {
+ *   console.log('Node exists');
+ * }
+ * ```
+ */
+export declare function hasNode(ast: TWorkflowAST, nodeId: string): boolean;
+/**
+ * Find nodes by name pattern (searches in config.label)
+ *
+ * @param ast - Workflow to query
+ * @param pattern - String pattern or regex to match
+ * @param caseSensitive - Whether to match case-sensitively (default: false)
+ * @returns Array of matching node instances
+ *
+ * @example
+ * ```typescript
+ * // Find nodes with 'processor' in label
+ * const nodes = findNodesByName(workflow, 'processor');
+ *
+ * // Case-sensitive search
+ * const exact = findNodesByName(workflow, 'Processor', true);
+ *
+ * // Regex search
+ * const regex = findNodesByName(workflow, /^proc-\d+$/);
+ * ```
+ */
+export declare function findNodesByName(ast: TWorkflowAST, pattern: string | RegExp, caseSensitive?: boolean): TNodeInstanceAST[];
+/**
+ * Get all connections, optionally filtered by node
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Optional node ID to filter connections
+ * @returns Array of connections
+ *
+ * @example
+ * ```typescript
+ * // Get all connections
+ * const allConnections = getConnections(workflow);
+ *
+ * // Get all connections involving a specific node
+ * const nodeConnections = getConnections(workflow, 'processor1');
+ * ```
+ */
+export declare function getConnections(ast: TWorkflowAST, nodeId?: string): TConnectionAST[];
+/**
+ * Get all incoming connections to a node or port
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Target node ID
+ * @param portName - Optional port name to filter
+ * @returns Array of incoming connections
+ *
+ * @example
+ * ```typescript
+ * // Get all connections to a node
+ * const incoming = getIncomingConnections(workflow, 'processor1');
+ *
+ * // Get connections to specific port
+ * const inputConns = getIncomingConnections(workflow, 'processor1', 'input');
+ * ```
+ */
+export declare function getIncomingConnections(ast: TWorkflowAST, nodeId: string, portName?: string): TConnectionAST[];
+/**
+ * Get all outgoing connections from a node or port
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Source node ID
+ * @param portName - Optional port name to filter
+ * @returns Array of outgoing connections
+ *
+ * @example
+ * ```typescript
+ * // Get all connections from a node
+ * const outgoing = getOutgoingConnections(workflow, 'processor1');
+ *
+ * // Get connections from specific port
+ * const outputConns = getOutgoingConnections(workflow, 'processor1', 'output');
+ * ```
+ */
+export declare function getOutgoingConnections(ast: TWorkflowAST, nodeId: string, portName?: string): TConnectionAST[];
+/**
+ * Check if two ports are connected
+ *
+ * @param ast - Workflow to query
+ * @param from - Source port reference (string or object)
+ * @param to - Target port reference (string or object)
+ * @returns True if connected
+ *
+ * @example
+ * ```typescript
+ * if (isConnected(workflow, 'node1.output', 'node2.input')) {
+ *   console.log('Nodes are connected');
+ * }
+ * ```
+ */
+export declare function isConnected(ast: TWorkflowAST, from: string | TPortReference, to: string | TPortReference): boolean;
+/**
+ * Get all ports connected to a node
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Node ID to check
+ * @returns Object with incoming and outgoing port references
+ *
+ * @example
+ * ```typescript
+ * const ports = getConnectedPorts(workflow, 'processor1');
+ * console.log('Incoming:', ports.incoming);
+ * console.log('Outgoing:', ports.outgoing);
+ * ```
+ */
+export declare function getConnectedPorts(ast: TWorkflowAST, nodeId: string): {
+    incoming: TPortReference[];
+    outgoing: TPortReference[];
+};
+/**
+ * Get all unconnected ports for a node
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Node ID to check
+ * @returns Object with unconnected input and output port names
+ *
+ * @example
+ * ```typescript
+ * const unconnected = getUnconnectedPorts(workflow, 'processor1');
+ * console.log('Unconnected inputs:', unconnected.inputs);
+ * console.log('Unconnected outputs:', unconnected.outputs);
+ * ```
+ */
+export declare function getUnconnectedPorts(ast: TWorkflowAST, nodeId: string): {
+    inputs: string[];
+    outputs: string[];
+};
+/**
+ * Get direct dependencies of a node (nodes that feed into it)
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Node ID to analyze
+ * @returns Array of node IDs that this node depends on
+ *
+ * @example
+ * ```typescript
+ * const deps = getDependencies(workflow, 'processor1');
+ * console.log('Direct dependencies:', deps);
+ * ```
+ */
+export declare function getDependencies(ast: TWorkflowAST, nodeId: string): string[];
+/**
+ * Get data-only dependencies of a node (excludes control flow connections)
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Node ID to analyze
+ * @returns Array of node IDs that provide data inputs to this node
+ */
+export declare function getDataDependencies(ast: TWorkflowAST, nodeId: string): string[];
+/**
+ * Get direct dependents of a node (nodes that consume its output)
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Node ID to analyze
+ * @returns Array of node IDs that depend on this node
+ *
+ * @example
+ * ```typescript
+ * const dependents = getDependents(workflow, 'processor1');
+ * console.log('Direct dependents:', dependents);
+ * ```
+ */
+export declare function getDependents(ast: TWorkflowAST, nodeId: string): string[];
+/**
+ * Get transitive dependencies (all upstream nodes)
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Node ID to analyze
+ * @returns Array of all node IDs in the dependency chain
+ *
+ * @example
+ * ```typescript
+ * const allDeps = getTransitiveDependencies(workflow, 'finalProcessor');
+ * console.log('All upstream nodes:', allDeps);
+ * ```
+ */
+export declare function getTransitiveDependencies(ast: TWorkflowAST, nodeId: string): string[];
+/**
+ * Find a path between two nodes (BFS)
+ *
+ * @param ast - Workflow to query
+ * @param fromNodeId - Source node ID
+ * @param toNodeId - Target node ID
+ * @returns Array of node IDs representing the path, or null if no path exists
+ *
+ * @example
+ * ```typescript
+ * const path = findPath(workflow, 'input', 'output');
+ * if (path) {
+ *   console.log('Path:', path.join(' → '));
+ * } else {
+ *   console.log('No path exists');
+ * }
+ * ```
+ */
+export declare function findPath(ast: TWorkflowAST, fromNodeId: string, toNodeId: string): string[] | null;
+/**
+ * Get topological order of all nodes (for execution planning)
+ *
+ * @param ast - Workflow to query
+ * @returns Array of node IDs in topological order
+ * @throws {Error} If workflow contains cycles
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const order = getTopologicalOrder(workflow);
+ *   console.log('Execution order:', order);
+ * } catch (error) {
+ *   console.error('Workflow has cycles!');
+ * }
+ * ```
+ */
+export declare function getTopologicalOrder(ast: TWorkflowAST): string[];
+/**
+ * Group nodes by execution level (nodes at same level can execute in parallel)
+ *
+ * @param ast - Workflow to query
+ * @returns Array of arrays, where each sub-array contains node IDs at that level
+ * @throws {Error} If workflow contains cycles
+ *
+ * @example
+ * ```typescript
+ * const groups = getExecutionGroups(workflow);
+ * groups.forEach((group, level) => {
+ *   console.log(`Level ${level}:`, group.join(', '));
+ * });
+ * ```
+ */
+export declare function getExecutionGroups(ast: TWorkflowAST): string[][];
+/**
+ * Count nodes, optionally filtered
+ *
+ * @param ast - Workflow to query
+ * @param filter - Optional filter criteria
+ * @returns Number of matching nodes
+ *
+ * @example
+ * ```typescript
+ * const total = countNodes(workflow);
+ * const processors = countNodes(workflow, { type: 'process' });
+ * ```
+ */
+export declare function countNodes(ast: TWorkflowAST, filter?: NodeFilter): number;
+/**
+ * Count connections, optionally for a specific node
+ *
+ * @param ast - Workflow to query
+ * @param nodeId - Optional node ID to filter
+ * @returns Number of connections
+ *
+ * @example
+ * ```typescript
+ * const total = countConnections(workflow);
+ * const nodeConns = countConnections(workflow, 'processor1');
+ * ```
+ */
+export declare function countConnections(ast: TWorkflowAST, nodeId?: string): number;
+/**
+ * Count node types defined in workflow
+ *
+ * @param ast - Workflow to query
+ * @returns Number of node type definitions
+ *
+ * @example
+ * ```typescript
+ * const typeCount = countNodeTypes(workflow);
+ * ```
+ */
+export declare function countNodeTypes(ast: TWorkflowAST): number;
+/**
+ * Find isolated nodes (no connections)
+ *
+ * @param ast - Workflow to query
+ * @returns Array of isolated node IDs
+ *
+ * @example
+ * ```typescript
+ * const isolated = findIsolatedNodes(workflow);
+ * if (isolated.length > 0) {
+ *   console.warn('Isolated nodes:', isolated);
+ * }
+ * ```
+ */
+export declare function findIsolatedNodes(ast: TWorkflowAST): string[];
+/**
+ * Find unused node types (no instances)
+ *
+ * @param ast - Workflow to query
+ * @returns Array of unused node type names
+ *
+ * @example
+ * ```typescript
+ * const unused = findUnusedNodeTypes(workflow);
+ * if (unused.length > 0) {
+ *   console.warn('Unused node types:', unused);
+ * }
+ * ```
+ */
+export declare function findUnusedNodeTypes(ast: TWorkflowAST): string[];
+/**
+ * Find dead-end nodes (output never reaches Exit)
+ *
+ * @param ast - Workflow to query
+ * @returns Array of dead-end node IDs
+ *
+ * @example
+ * ```typescript
+ * const deadEnds = findDeadEnds(workflow);
+ * if (deadEnds.length > 0) {
+ *   console.warn('Dead-end nodes:', deadEnds);
+ * }
+ * ```
+ */
+export declare function findDeadEnds(ast: TWorkflowAST): string[];
+/**
+ * Find output ports that are not connected to anything.
+ * Excludes control flow ports (onSuccess/onFailure) and scoped ports.
+ *
+ * @param ast - Workflow to query
+ * @returns Array of objects with nodeId and their disconnected output port names
+ */
+/**
+ * Find dead-end details: both dead-end nodes and disconnected output ports.
+ * Combines findDeadEnds() and findDisconnectedOutputPorts() into a single result.
+ *
+ * @param ast - Workflow to query
+ * @returns Object with deadEndNodes and disconnectedOutputs
+ */
+export declare function findDeadEndDetails(ast: TWorkflowAST): {
+    deadEndNodes: string[];
+    disconnectedOutputs: Array<{
+        nodeId: string;
+        ports: string[];
+    }>;
+};
+export declare function findDisconnectedOutputPorts(ast: TWorkflowAST): Array<{
+    nodeId: string;
+    ports: string[];
+}>;
+//# sourceMappingURL=query.d.ts.map