@procedures/dag 0.47.1 → 0.48.0

package/src/dag/traversal.ts

@@ -1,129 +0,0 @@
-/**
- * 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/graph/hub-order.ts

@@ -1,53 +0,0 @@
-/** An undirected edge between the nodes `a` and `b`. The default weight is 1. */
-export interface WeightedEdge {
-  readonly a: number;
-  readonly b: number;
-  readonly weight?: number | undefined;
-}
-
-/**
- * This function gives a breadth-first order of the nodes `0` to `n - 1` of an undirected weighted graph.
- *
- * - The hub of a component is the node with the largest sum of edge weights. `compare`, then the lower index, breaks a tie.
- * - The order starts at the hub of each component, and goes breadth-first. `compare`, then the lower index, orders the neighbours of a node.
- * - Without edges, each node is a component, so the order is the order of `compare`.
- * - An edge from a node to itself adds no weight.
- * - A bad `n`, an index outside the nodes, or a weight that is not a finite number above 0, throws a `RangeError`.
- *
- * The function is pure. It keeps no state, and it does not change its arguments.
- */
-export function hubBreadthFirstOrder(n: number, edges: readonly WeightedEdge[] = [], compare: (i: number, j: number) => number = () => 0): number[] {
-  if (!Number.isInteger(n) || n < 0) throw new RangeError(`The count of the nodes is a whole number from 0, not ${n}.`);
-  const degree = new Float64Array(n);
-  const next: number[][] = Array.from({ length: n }, () => []);
-  for (const { a, b, weight = 1 } of edges) {
-    if (!Number.isInteger(a) || !Number.isInteger(b) || a < 0 || b < 0 || a >= n || b >= n) {
-      throw new RangeError(`An edge joins the nodes ${a} and ${b}, but the indexes go from 0 to ${n - 1}.`);
-    }
-    if (!Number.isFinite(weight) || weight <= 0) throw new RangeError(`The weight of an edge is a finite number above 0, not ${weight}.`);
-    if (a === b) continue;
-    degree[a] = degree[a]! + weight;
-    degree[b] = degree[b]! + weight;
-    next[a]!.push(b);
-    next[b]!.push(a);
-  }
-  const order = (i: number, j: number): number => compare(i, j) || i - j;
-  const hubs = Array.from({ length: n }, (_, i) => i).sort((i, j) => degree[j]! - degree[i]! || order(i, j));
-  const seen = new Uint8Array(n);
-  const out: number[] = [];
-  for (const hub of hubs) {
-    if (seen[hub] === 1) continue;
-    seen[hub] = 1;
-    const queue = [hub];
-    for (let k = 0; k < queue.length; k++) {
-      const i = queue[k]!;
-      out.push(i);
-      for (const j of next[i]!.toSorted(order)) {
-        if (seen[j] === 1) continue;
-        seen[j] = 1;
-        queue.push(j);
-      }
-    }
-  }
-  return out;
-}

package/src/types.ts

@@ -1,87 +0,0 @@
-/**
- * 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>>;