@procedures/dag 0.0.0-stage → 0.1.0

package/src/dag/index.ts

@@ -0,0 +1,23 @@
+/**
+ * DAG utilities
+ */
+
+export {
+  buildLeveledDAG,
+  getTopologicalOrder,
+  visualizeDAG,
+} from "./traversal.js";
+
+export {
+  executeDAG,
+  executeDAGSequential,
+  createProcessor,
+} from "./executor.js";
+
+export {
+  filterDAGFromRoot,
+  getAncestors,
+  getDescendants,
+  createNode,
+  buildNodeMap,
+} from "./builder.js";

package/src/dag/traversal.ts

@@ -0,0 +1,129 @@
+/**
+ * DAG Traversal using Kahn's Algorithm
+ *
+ * Implements topological sort with level assignment for parallel execution.
+ * Level 0 = leaves (no dependencies), higher levels depend on lower levels.
+ */
+
+import type { DAGNode, DependencyDAG } from "../types.js";
+
+/**
+ * Build a leveled DAG from nodes using Kahn's algorithm
+ *
+ * This assigns levels to each node where:
+ * - Level 0: Nodes with no dependencies (leaves)
+ * - Level N: Nodes whose dependencies are all at level < N
+ *
+ * Nodes at the same level can be processed in parallel.
+ *
+ * @throws Error if a cycle is detected
+ */
+export function buildLeveledDAG<TNode extends DAGNode>(
+  nodes: Map<string, TNode>
+): DependencyDAG<TNode> {
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, Set<string>>();
+
+  for (const [name, node] of nodes) {
+    // A set: a dependency that a node lists twice counts once. (`dependents` is a set, so it
+    // takes the in-degree down once: a repeated dependency was "Circular": deep dive DATA-21.)
+    const depsInDag = new Set(node.dependencies.filter((dep) => nodes.has(dep)));
+    inDegree.set(name, depsInDag.size);
+    dependents.set(name, new Set());
+  }
+
+  for (const [name, node] of nodes) {
+    for (const dep of node.dependencies) {
+      if (dependents.has(dep)) {
+        dependents.get(dep)!.add(name);
+      }
+    }
+  }
+
+  let queue: string[] = [];
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) {
+      queue.push(name);
+    }
+  }
+
+  const levels: TNode[][] = [];
+  const nodeLevel = new Map<string, number>();
+  let processedCount = 0;
+
+  while (queue.length > 0) {
+    const currentLevel = levels.length;
+    const levelNodes: TNode[] = [];
+    const nextQueue: string[] = [];
+
+    for (const name of queue) {
+      const node = nodes.get(name)!;
+      node.level = currentLevel;
+      nodeLevel.set(name, currentLevel);
+      levelNodes.push(node);
+      processedCount++;
+
+      for (const dependent of dependents.get(name) ?? []) {
+        const newDegree = inDegree.get(dependent)! - 1;
+        inDegree.set(dependent, newDegree);
+
+        if (newDegree === 0) {
+          nextQueue.push(dependent);
+        }
+      }
+    }
+
+    levels.push(levelNodes);
+    queue = nextQueue;
+  }
+
+  if (processedCount !== nodes.size) {
+    const cycleNodes = [...nodes.keys()].filter((n) => !nodeLevel.has(n));
+    throw new Error("Circular dependency detected involving: " + cycleNodes.join(", "));
+  }
+
+  const roots = [...nodes.keys()].filter((name) => {
+    const deps = dependents.get(name);
+    return !deps || deps.size === 0;
+  });
+
+  const leaves = [...nodes.keys()].filter((name) => {
+    const node = nodes.get(name)!;
+    const depsInDag = node.dependencies.filter((dep) => nodes.has(dep));
+    return depsInDag.length === 0;
+  });
+
+  return { nodes, levels, roots, leaves };
+}
+
+/**
+ * Get the topological order (flat list, leaves first)
+ */
+export function getTopologicalOrder<TNode extends DAGNode>(
+  dag: DependencyDAG<TNode>
+): TNode[] {
+  return dag.levels.flat();
+}
+
+/**
+ * Visualize the DAG structure (for debugging)
+ */
+export function visualizeDAG<TNode extends DAGNode>(
+  dag: DependencyDAG<TNode>
+): string {
+  const lines = ["DAG Structure:"];
+
+  for (let i = 0; i < dag.levels.length; i++) {
+    const level = dag.levels[i]!;
+    lines.push("  Level " + i + ":");
+    for (const node of level) {
+      const deps =
+        node.dependencies.length > 0
+          ? " -> [" + node.dependencies.join(", ") + "]"
+          : " (leaf)";
+      lines.push("    - " + node.id + deps);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * @procedures/dag
+ *
+ * Generic DAG (Directed Acyclic Graph) algorithms for dependency management.
+ *
+ * Features:
+ * - Kahn's algorithm for topological sorting with level assignment
+ * - Parallel execution with concurrency control
+ * - Cycle detection
+ * - Graph filtering and traversal utilities
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createNode,
+ *   buildNodeMap,
+ *   buildLeveledDAG,
+ *   executeDAG,
+ *   createProcessor
+ * } from "@procedures/dag";
+ *
+ * // Create nodes
+ * const nodes = buildNodeMap([
+ *   createNode("a", []),
+ *   createNode("b", ["a"]),
+ *   createNode("c", ["a", "b"]),
+ * ]);
+ *
+ * // Build leveled DAG
+ * const dag = buildLeveledDAG(nodes);
+ *
+ * // Execute in dependency order
+ * const processor = createProcessor(async (node) => {
+ *   console.log(`Processing ${node.id}`);
+ * });
+ *
+ * const result = await executeDAG(dag, processor, { concurrency: 2 });
+ * ```
+ */
+
+// Types
+export type {
+  DAGNode,
+  DependencyDAG,
+  DAGExecutionOptions,
+  NodeResult,
+  DAGResult,
+  NodeProcessor,
+} from "./types.js";
+
+// DAG utilities
+export {
+  buildLeveledDAG,
+  getTopologicalOrder,
+  visualizeDAG,
+  executeDAG,
+  executeDAGSequential,
+  createProcessor,
+  filterDAGFromRoot,
+  getAncestors,
+  getDescendants,
+  createNode,
+  buildNodeMap,
+} from "./dag/index.js";

package/src/types.ts

@@ -0,0 +1,87 @@
+/**
+ * Generic DAG Types
+ *
+ * These types are designed to be reusable across different use cases.
+ * For ecosystem-specific DAG building, see client-lib.
+ */
+
+/**
+ * A node in a dependency DAG
+ */
+export interface DAGNode<TData = unknown> {
+  /** Unique identifier for this node */
+  id: string;
+  /** Names/IDs of nodes this node depends on */
+  dependencies: string[];
+  /** Topological level (0 = leaves, computed by Kahn's algorithm) */
+  level?: number;
+  /** Optional user data associated with this node */
+  data?: TData | undefined;
+}
+
+/**
+ * A dependency DAG with level information for parallel execution
+ */
+export interface DependencyDAG<TNode extends DAGNode = DAGNode> {
+  /** All nodes in the DAG */
+  nodes: Map<string, TNode>;
+  /** Nodes grouped by level for parallel execution */
+  levels: TNode[][];
+  /** Root nodes (no dependents in the DAG) */
+  roots: string[];
+  /** Leaf nodes (no dependencies in the DAG) */
+  leaves: string[];
+}
+
+/**
+ * Options for DAG execution
+ */
+export interface DAGExecutionOptions<TNode extends DAGNode = DAGNode> {
+  /** Max parallel operations per level (default: 4) */
+  concurrency?: number;
+  /** Stop on first error vs continue (default: true) */
+  failFast?: boolean;
+  /** Callback for progress reporting */
+  onNodeStart?: (node: TNode) => void;
+  /** Callback when a node completes */
+  onNodeComplete?: (result: NodeResult<TNode>) => void;
+}
+
+/**
+ * Result of processing a single node
+ */
+export interface NodeResult<TNode extends DAGNode = DAGNode> {
+  /** The node that was processed */
+  node: TNode;
+  /** Whether processing succeeded */
+  success: boolean;
+  /** Error if failed */
+  error?: Error | undefined;
+  /** Duration in milliseconds */
+  duration: number;
+  /** Logs from processing */
+  logs: string[];
+  /** Optional output from the processor */
+  output?: unknown | undefined;
+}
+
+/**
+ * Result of executing an entire DAG
+ */
+export interface DAGResult<TNode extends DAGNode = DAGNode> {
+  /** Overall success */
+  success: boolean;
+  /** Results for each node */
+  results: Map<string, NodeResult<TNode>>;
+  /** Names of failed nodes */
+  failedNodes: string[];
+  /** Total duration in milliseconds */
+  totalDuration: number;
+}
+
+/**
+ * Processor function type
+ */
+export type NodeProcessor<TNode extends DAGNode = DAGNode> = (
+  node: TNode
+) => Promise<NodeResult<TNode>>;