@mark1russell7/collections 0.5.0 → 0.7.0

package/build/dag/index.d.ts

@@ -38,6 +38,11 @@ interface DAGExecutionOptions<TNode extends DAGNode = DAGNode> {
   concurrency?: number;
   /** When this value is true, the run stops on the first error. The default is true. */
   failFast?: boolean;
+  /**
+   * When this value is true, a node whose dependency failed or was skipped does not start. Its result has `skipped: true`.
+   * The default is true. Give false only when the nodes do not use the work of their dependencies.
+   */
+  skipDependents?: boolean;
   /** Callback for progress reporting */
   onNodeStart?: (node: TNode) => void;
   /** Callback when a node completes */
@@ -59,6 +64,8 @@ interface NodeResult<TNode extends DAGNode = DAGNode> {
   logs: string[];
   /** Optional output from the processor */
   output?: unknown | undefined;
+  /** This value is true when the node did not start, because a dependency failed or was skipped. */
+  skipped?: boolean | undefined;
 }
 /**
  * The result of a run of an entire DAG
@@ -68,8 +75,10 @@ interface DAGResult<TNode extends DAGNode = DAGNode> {
   success: boolean;
   /** Results for each node */
   results: Map<string, NodeResult<TNode>>;
-  /** Names of failed nodes */
+  /** The ids of the nodes whose processor failed */
   failedNodes: string[];
+  /** The ids of the nodes that did not start, because a dependency failed or was skipped */
+  skippedNodes: string[];
   /** Total duration in milliseconds */
   totalDuration: number;
 }
@@ -107,6 +116,9 @@ export declare function visualizeDAG<TNode extends DAGNode>(dag: DependencyDAG<T
  * A processor that throws does NOT reject the whole run. The run records the throw
  * as a failed NodeResult, so partial results are always given.
  *
+ * With `skipDependents` (the default), a node whose dependency failed or was skipped does not start. Its result has
+ * `skipped: true` and an error that names those dependencies. A dependency outside the DAG does not count.
+ *
  * `failFast` operates at level granularity. When a node in a level fails, each
  * node already in flight in that level continues to completion. No later level
  * starts. (There is no mid-level cancellation.)

package/build/dag/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/dag/types.ts","../../src/dag/traversal.ts","../../src/dag/executor.ts","../../src/dag/builder.ts"],"mappings":";;;;;;;;;UAUiB,QAAQ;;EAEvB;;EAEA;;EAEA;;EAEA,OAAO;;;;;UAMQ,cAAc,cAAc,UAAU;;EAErD,OAAO,YAAY;;EAEnB,QAAQ;;EAER;;EAEA;;;;;UAMe,oBAAoB,cAAc,UAAU;;EAE3D;;EAEA;;EAEA,eAAe,MAAM;;EAErB,kBAAkB,QAAQ,WAAW;;;;;UAMtB,WAAW,cAAc,UAAU;;EAElD,MAAM;;EAEN;;EAEA,QAAQ;;EAER;;EAEA;;EAEA;;;;;UAMe,UAAU,cAAc,UAAU;;EAEjD;;EAEA,SAAS,YAAY,WAAW;;EAEhC;;EAEA;;;;;KAMU,cAAc,cAAc,UAAU,YAChD,MAAM,UACH,QAAQ,WAAW;;;;;;;;;;;;wBClER,gBAAgB,cAAc,SAC5C,OAAO,YAAY,SAClB,cAAc;;;;wBA+ED,oBAAoB,cAAc,SAChD,KAAK,cAAc,SAClB;;;;wBAOa,aAAa,cAAc,SACzC,KAAK,cAAc;;;;;;;;;;;;;;;wBCrCC,WAAW,cAAc,SAC7C,KAAK,cAAc,QACnB,YAAY,MAAM,UAAU,QAAQ,WAAW,SAC/C,UAAS,oBAAoB,SAC5B,QAAQ,UAAU;;;;wBAqEC,qBAAqB,cAAc,SACvD,KAAK,cAAc,QACnB,YAAY,MAAM,UAAU,QAAQ,WAAW,SAC/C,UAAS,KAAK,oBAAoB,yBACjC,QAAQ,UAAU;;;;wBAOL,gBAAgB,cAAc,SAC5C,KAAK,MAAM,UAAU,iBACnB,MAAM,UAAU,QAAQ,WAAW;;;;wBCvJvB,kBAAkB,cAAc,SAC9C,OAAO,YAAY,QACnB,iBACC,YAAY;;;;wBAyBC,aAAa,cAAc,SACzC,OAAO,YAAY,QACnB,aACC;;;;wBA0Ba,eAAe,cAAc,SAC3C,OAAO,YAAY,QACnB,aACC;;;;wBAmCa,WAAW,iBACzB,YACA,yBACA,OAAO,oBACN,QAAQ;;;;wBAWK,aAAa,cAAc,SACzC,OAAO,UACN,YAAY"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/dag/types.ts","../../src/dag/traversal.ts","../../src/dag/executor.ts","../../src/dag/builder.ts"],"mappings":";;;;;;;;;UAUiB,QAAQ;;EAEvB;;EAEA;;EAEA;;EAEA,OAAO;;;;;UAMQ,cAAc,cAAc,UAAU;;EAErD,OAAO,YAAY;;EAEnB,QAAQ;;EAER;;EAEA;;;;;UAMe,oBAAoB,cAAc,UAAU;;EAE3D;;EAEA;;;;;EAKA;;EAEA,eAAe,MAAM;;EAErB,kBAAkB,QAAQ,WAAW;;;;;UAMtB,WAAW,cAAc,UAAU;;EAElD,MAAM;;EAEN;;EAEA,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;;;;UAMe,UAAU,cAAc,UAAU;;EAEjD;;EAEA,SAAS,YAAY,WAAW;;EAEhC;;EAEA;;EAEA;;;;;KAMU,cAAc,cAAc,UAAU,YAChD,MAAM,UACH,QAAQ,WAAW;;;;;;;;;;;;wBC3ER,gBAAgB,cAAc,SAC5C,OAAO,YAAY,SAClB,cAAc;;;;wBA+ED,oBAAoB,cAAc,SAChD,KAAK,cAAc,SAClB;;;;wBAOa,aAAa,cAAc,SACzC,KAAK,cAAc;;;;;;;;;;;;;;;;;;wBClCC,WAAW,cAAc,SAC7C,KAAK,cAAc,QACnB,YAAY,MAAM,UAAU,QAAQ,WAAW,SAC/C,UAAS,oBAAoB,SAC5B,QAAQ,UAAU;;;;wBAwFC,qBAAqB,cAAc,SACvD,KAAK,cAAc,QACnB,YAAY,MAAM,UAAU,QAAQ,WAAW,SAC/C,UAAS,KAAK,oBAAoB,yBACjC,QAAQ,UAAU;;;;wBAOL,gBAAgB,cAAc,SAC5C,KAAK,MAAM,UAAU,iBACnB,MAAM,UAAU,QAAQ,WAAW;;;;wBC7KvB,kBAAkB,cAAc,SAC9C,OAAO,YAAY,QACnB,iBACC,YAAY;;;;wBAyBC,aAAa,cAAc,SACzC,OAAO,YAAY,QACnB,aACC;;;;wBA0Ba,eAAe,cAAc,SAC3C,OAAO,YAAY,QACnB,aACC;;;;wBAmCa,WAAW,iBACzB,YACA,yBACA,OAAO,oBACN,QAAQ;;;;wBAWK,aAAa,cAAc,SACzC,OAAO,UACN,YAAY"}

package/build/dag/index.js

@@ -122,19 +122,43 @@ function notify(name, listener, arg) {
 * A processor that throws does NOT reject the whole run. The run records the throw
 * as a failed NodeResult, so partial results are always given.
 *
+* With `skipDependents` (the default), a node whose dependency failed or was skipped does not start. Its result has
+* `skipped: true` and an error that names those dependencies. A dependency outside the DAG does not count.
+*
 * `failFast` operates at level granularity. When a node in a level fails, each
 * node already in flight in that level continues to completion. No later level
 * starts. (There is no mid-level cancellation.)
 */
 async function executeDAG(dag, processor, options = {}) {
-	const { concurrency = 4, failFast = true, onNodeStart, onNodeComplete } = options;
+	const { concurrency = 4, failFast = true, skipDependents = true, onNodeStart, onNodeComplete } = options;
 	const results = /* @__PURE__ */ new Map();
 	const failedNodes = [];
+	const skippedNodes = [];
+	const blocked = /* @__PURE__ */ new Set();
 	const startTime = Date.now();
 	let shouldStop = false;
 	for (const level of dag.levels) {
 		if (shouldStop) break;
-		const levelResults = await executeWithConcurrency(level, async (node) => {
+		const runnable = [];
+		for (const node of level) {
+			const blockers = skipDependents ? node.dependencies.filter((dep) => blocked.has(dep)) : [];
+			if (blockers.length === 0) {
+				runnable.push(node);
+				continue;
+			}
+			const message = "Skipped " + node.id + ": the dependencies " + blockers.join(", ") + " failed or were skipped";
+			results.set(node.id, {
+				node,
+				success: false,
+				skipped: true,
+				error: new Error(message),
+				duration: 0,
+				logs: [message]
+			});
+			skippedNodes.push(node.id);
+			blocked.add(node.id);
+		}
+		const levelResults = await executeWithConcurrency(runnable, async (node) => {
 			const startError = notify("onNodeStart", onNodeStart, node);
 			const nodeStart = Date.now();
 			let result;
@@ -161,14 +185,16 @@ async function executeDAG(dag, processor, options = {}) {
 			results.set(result.node.id, result);
 			if (!result.success) {
 				failedNodes.push(result.node.id);
+				blocked.add(result.node.id);
 				if (failFast) shouldStop = true;
 			}
 		}
 	}
 	return {
-		success: failedNodes.length === 0,
+		success: failedNodes.length === 0 && skippedNodes.length === 0,
 		results,
 		failedNodes,
+		skippedNodes,
 		totalDuration: Date.now() - startTime
 	};
 }

package/build/dag/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/dag/traversal.ts","../../src/dag/executor.ts","../../src/dag/builder.ts"],"sourcesContent":["/**\n * DAG Traversal using Kahn's Algorithm\n *\n * This module implements topological sort with level assignment for parallel execution.\n * Level 0 = leaves (no dependencies), higher levels depend on lower levels.\n */\n\nimport type { DAGNode, DependencyDAG } from \"./types.js\";\n\n/**\n * Build a leveled DAG from nodes using Kahn's algorithm\n *\n * This assigns levels to each node where:\n * - Level 0: Nodes with no dependencies (leaves)\n * - Level N: Nodes whose dependencies are all at level < N\n *\n * Nodes at the same level can be processed in parallel.\n *\n * @throws Error if a cycle is detected\n */\nexport function buildLeveledDAG<TNode extends DAGNode>(\n  nodes: Map<string, TNode>\n): DependencyDAG<TNode> {\n  const inDegree = new Map<string, number>();\n  const dependents = new Map<string, Set<string>>();\n\n  for (const [name, node] of nodes) {\n    // A set: a dependency that a node lists twice counts once. (`dependents` is a set, so it\n    // takes the in-degree down once: a repeated dependency was \"Circular\": deep dive DATA-21.)\n    const depsInDag = new Set(node.dependencies.filter((dep) => nodes.has(dep)));\n    inDegree.set(name, depsInDag.size);\n    dependents.set(name, new Set());\n  }\n\n  for (const [name, node] of nodes) {\n    for (const dep of node.dependencies) {\n      if (dependents.has(dep)) {\n        dependents.get(dep)!.add(name);\n      }\n    }\n  }\n\n  let queue: string[] = [];\n  for (const [name, degree] of inDegree) {\n    if (degree === 0) {\n      queue.push(name);\n    }\n  }\n\n  const levels: TNode[][] = [];\n  const nodeLevel = new Map<string, number>();\n  let processedCount = 0;\n\n  while (queue.length > 0) {\n    const currentLevel = levels.length;\n    const levelNodes: TNode[] = [];\n    const nextQueue: string[] = [];\n\n    for (const name of queue) {\n      const node = nodes.get(name)!;\n      node.level = currentLevel;\n      nodeLevel.set(name, currentLevel);\n      levelNodes.push(node);\n      processedCount++;\n\n      for (const dependent of dependents.get(name) ?? []) {\n        const newDegree = inDegree.get(dependent)! - 1;\n        inDegree.set(dependent, newDegree);\n\n        if (newDegree === 0) {\n          nextQueue.push(dependent);\n        }\n      }\n    }\n\n    levels.push(levelNodes);\n    queue = nextQueue;\n  }\n\n  if (processedCount !== nodes.size) {\n    const cycleNodes = [...nodes.keys()].filter((n) => !nodeLevel.has(n));\n    throw new Error(\"Circular dependency detected involving: \" + cycleNodes.join(\", \"));\n  }\n\n  const roots = [...nodes.keys()].filter((name) => {\n    const deps = dependents.get(name);\n    return !deps || deps.size === 0;\n  });\n\n  const leaves = [...nodes.keys()].filter((name) => {\n    const node = nodes.get(name)!;\n    const depsInDag = node.dependencies.filter((dep) => nodes.has(dep));\n    return depsInDag.length === 0;\n  });\n\n  return { nodes, levels, roots, leaves };\n}\n\n/**\n * Get the topological order (flat list, leaves first)\n */\nexport function getTopologicalOrder<TNode extends DAGNode>(\n  dag: DependencyDAG<TNode>\n): TNode[] {\n  return dag.levels.flat();\n}\n\n/**\n * Visualize the DAG structure (for debugging)\n */\nexport function visualizeDAG<TNode extends DAGNode>(\n  dag: DependencyDAG<TNode>\n): string {\n  const lines = [\"DAG Structure:\"];\n\n  for (let i = 0; i < dag.levels.length; i++) {\n    const level = dag.levels[i]!;\n    lines.push(\"  Level \" + i + \":\");\n    for (const node of level) {\n      const deps =\n        node.dependencies.length > 0\n          ? \" -> [\" + node.dependencies.join(\", \") + \"]\"\n          : \" (leaf)\";\n      lines.push(\"    - \" + node.id + deps);\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n","/**\n * DAG Executor with parallel level-based execution\n */\n\nimport type {\n  DependencyDAG,\n  DAGNode,\n  DAGExecutionOptions,\n  NodeResult,\n  DAGResult,\n} from \"./types.js\";\n\n/**\n * Start a batch of items with concurrency limit\n */\nasync function executeWithConcurrency<T, R>(\n  items: T[],\n  fn: (item: T) => Promise<R>,\n  limit: number\n): Promise<R[]> {\n  const results: R[] = [];\n  const executing = new Set<Promise<void>>();\n\n  for (const item of items) {\n    const promise = fn(item)\n      .then((result) => {\n        results.push(result);\n      })\n      .finally(() => {\n        // Rejection-safe cleanup: always remove the settled promise from the\n        // executing set, even if `fn` rejected, so the set never leaks a\n        // settled (possibly rejected) promise into later `race`/`all` waits.\n        executing.delete(promise);\n      });\n\n    executing.add(promise);\n\n    if (executing.size >= limit) {\n      await Promise.race(executing);\n    }\n  }\n\n  await Promise.all(executing);\n  return results;\n}\n\n/**\n * Call a listener. A listener that throws does not stop the run: the function gives a log\n * line for its error (deep dive DATA-21).\n */\nfunction notify<T>(name: string, listener: ((arg: T) => void) | undefined, arg: T): string | undefined {\n  if (!listener) return undefined;\n  try {\n    listener(arg);\n    return undefined;\n  } catch (error) {\n    return name + \" threw: \" + (error instanceof Error ? error.message : String(error));\n  }\n}\n\n/**\n * Start DAG with level-based parallelization\n *\n * - Levels are processed sequentially (level 0 first, then level 1, and so on)\n * - Within each level, nodes are processed in parallel up to concurrency limit\n * - Supports fail-fast or continue-on-error modes\n *\n * A processor that throws does NOT reject the whole run. The run records the throw\n * as a failed NodeResult, so partial results are always given.\n *\n * `failFast` operates at level granularity. When a node in a level fails, each\n * node already in flight in that level continues to completion. No later level\n * starts. (There is no mid-level cancellation.)\n */\nexport async function executeDAG<TNode extends DAGNode>(\n  dag: DependencyDAG<TNode>,\n  processor: (node: TNode) => Promise<NodeResult<TNode>>,\n  options: DAGExecutionOptions<TNode> = {}\n): Promise<DAGResult<TNode>> {\n  const {\n    concurrency = 4,\n    failFast = true,\n    onNodeStart,\n    onNodeComplete,\n  } = options;\n\n  const results = new Map<string, NodeResult<TNode>>();\n  const failedNodes: string[] = [];\n  const startTime = Date.now();\n  let shouldStop = false;\n\n  for (const level of dag.levels) {\n    if (shouldStop) break;\n\n    const levelResults = await executeWithConcurrency(\n      level,\n      async (node) => {\n        const startError = notify(\"onNodeStart\", onNodeStart, node);\n        const nodeStart = Date.now();\n        let result: NodeResult<TNode>;\n        try {\n          result = await processor(node);\n        } catch (error) {\n          // Convert a thrown processor error into a failed NodeResult instead\n          // of rejecting the entire run and discarding partial results.\n          const err =\n            error instanceof Error ? error : new Error(String(error));\n          result = {\n            node,\n            success: false,\n            error: err,\n            duration: Date.now() - nodeStart,\n            logs: [\"Processor threw: \" + err.message],\n          };\n        }\n        const completeError = notify(\"onNodeComplete\", onNodeComplete, result);\n        const listenerErrors = [startError, completeError].filter((line): line is string => line !== undefined);\n        if (listenerErrors.length > 0) {\n          result = { ...result, logs: [...(result.logs ?? []), ...listenerErrors] };\n        }\n        return result;\n      },\n      concurrency\n    );\n\n    for (const result of levelResults) {\n      results.set(result.node.id, result);\n      if (!result.success) {\n        failedNodes.push(result.node.id);\n        if (failFast) {\n          shouldStop = true;\n        }\n      }\n    }\n  }\n\n  return {\n    success: failedNodes.length === 0,\n    results,\n    failedNodes,\n    totalDuration: Date.now() - startTime,\n  };\n}\n\n/**\n * Start DAG sequentially (no parallelization)\n */\nexport async function executeDAGSequential<TNode extends DAGNode>(\n  dag: DependencyDAG<TNode>,\n  processor: (node: TNode) => Promise<NodeResult<TNode>>,\n  options: Omit<DAGExecutionOptions<TNode>, \"concurrency\"> = {}\n): Promise<DAGResult<TNode>> {\n  return executeDAG(dag, processor, { ...options, concurrency: 1 });\n}\n\n/**\n * Make a simple processor that wraps an async function\n */\nexport function createProcessor<TNode extends DAGNode>(\n  fn: (node: TNode) => Promise<void>\n): (node: TNode) => Promise<NodeResult<TNode>> {\n  return async (node: TNode): Promise<NodeResult<TNode>> => {\n    const startTime = Date.now();\n    const logs: string[] = [];\n\n    try {\n      logs.push(\"Starting \" + node.id);\n      await fn(node);\n      logs.push(\"Completed \" + node.id);\n\n      return {\n        node,\n        success: true,\n        duration: Date.now() - startTime,\n        logs,\n      };\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n      logs.push(\"Failed \" + node.id + \": \" + err.message);\n\n      return {\n        node,\n        success: false,\n        error: err,\n        duration: Date.now() - startTime,\n        logs,\n      };\n    }\n  };\n}\n","/**\n * DAG Builder utilities\n */\n\nimport type { DAGNode } from \"./types.js\";\n\n/**\n * Filter DAG to only include nodes reachable from a root\n */\nexport function filterDAGFromRoot<TNode extends DAGNode>(\n  nodes: Map<string, TNode>,\n  rootId: string\n): Map<string, TNode> {\n  const filtered = new Map<string, TNode>();\n  const visited = new Set<string>();\n\n  function visit(id: string): void {\n    if (visited.has(id)) return;\n    visited.add(id);\n\n    const node = nodes.get(id);\n    if (!node) return;\n\n    filtered.set(id, node);\n\n    for (const dep of node.dependencies) {\n      visit(dep);\n    }\n  }\n\n  visit(rootId);\n  return filtered;\n}\n\n/**\n * Get all ancestors of a node (nodes that this node depends on, transitively)\n */\nexport function getAncestors<TNode extends DAGNode>(\n  nodes: Map<string, TNode>,\n  id: string\n): Set<string> {\n  const ancestors = new Set<string>();\n  const visited = new Set<string>();\n\n  function visit(n: string): void {\n    if (visited.has(n)) return;\n    visited.add(n);\n\n    const node = nodes.get(n);\n    if (!node) return;\n\n    for (const dep of node.dependencies) {\n      if (nodes.has(dep)) {\n        ancestors.add(dep);\n        visit(dep);\n      }\n    }\n  }\n\n  visit(id);\n  return ancestors;\n}\n\n/**\n * Get all descendants of a node (nodes that depend on this node, transitively)\n */\nexport function getDescendants<TNode extends DAGNode>(\n  nodes: Map<string, TNode>,\n  id: string\n): Set<string> {\n  const descendants = new Set<string>();\n  const visited = new Set<string>();\n\n  // Build reverse dependency map\n  const dependents = new Map<string, Set<string>>();\n  for (const [nodeId, node] of nodes) {\n    for (const dep of node.dependencies) {\n      if (!dependents.has(dep)) {\n        dependents.set(dep, new Set());\n      }\n      dependents.get(dep)!.add(nodeId);\n    }\n  }\n\n  function visit(n: string): void {\n    if (visited.has(n)) return;\n    visited.add(n);\n\n    const deps = dependents.get(n);\n    if (!deps) return;\n\n    for (const dep of deps) {\n      descendants.add(dep);\n      visit(dep);\n    }\n  }\n\n  visit(id);\n  return descendants;\n}\n\n/**\n * Make a DAG node from minimal input\n */\nexport function createNode<TData = unknown>(\n  id: string,\n  dependencies: string[] = [],\n  data?: TData | undefined\n): DAGNode<TData> {\n  const node: DAGNode<TData> = { id, dependencies };\n  if (data !== undefined) {\n    node.data = data;\n  }\n  return node;\n}\n\n/**\n * Build a Map of nodes from an array\n */\nexport function buildNodeMap<TNode extends DAGNode>(\n  nodes: TNode[]\n): Map<string, TNode> {\n  return new Map(nodes.map((n) => [n.id, n]));\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/dag/traversal.ts","../../src/dag/executor.ts","../../src/dag/builder.ts"],"sourcesContent":["/**\n * DAG Traversal using Kahn's Algorithm\n *\n * This module implements topological sort with level assignment for parallel execution.\n * Level 0 = leaves (no dependencies), higher levels depend on lower levels.\n */\n\nimport type { DAGNode, DependencyDAG } from \"./types.js\";\n\n/**\n * Build a leveled DAG from nodes using Kahn's algorithm\n *\n * This assigns levels to each node where:\n * - Level 0: Nodes with no dependencies (leaves)\n * - Level N: Nodes whose dependencies are all at level < N\n *\n * Nodes at the same level can be processed in parallel.\n *\n * @throws Error if a cycle is detected\n */\nexport function buildLeveledDAG<TNode extends DAGNode>(\n  nodes: Map<string, TNode>\n): DependencyDAG<TNode> {\n  const inDegree = new Map<string, number>();\n  const dependents = new Map<string, Set<string>>();\n\n  for (const [name, node] of nodes) {\n    // A set: a dependency that a node lists twice counts once. (`dependents` is a set, so it\n    // takes the in-degree down once: a repeated dependency was \"Circular\": deep dive DATA-21.)\n    const depsInDag = new Set(node.dependencies.filter((dep) => nodes.has(dep)));\n    inDegree.set(name, depsInDag.size);\n    dependents.set(name, new Set());\n  }\n\n  for (const [name, node] of nodes) {\n    for (const dep of node.dependencies) {\n      if (dependents.has(dep)) {\n        dependents.get(dep)!.add(name);\n      }\n    }\n  }\n\n  let queue: string[] = [];\n  for (const [name, degree] of inDegree) {\n    if (degree === 0) {\n      queue.push(name);\n    }\n  }\n\n  const levels: TNode[][] = [];\n  const nodeLevel = new Map<string, number>();\n  let processedCount = 0;\n\n  while (queue.length > 0) {\n    const currentLevel = levels.length;\n    const levelNodes: TNode[] = [];\n    const nextQueue: string[] = [];\n\n    for (const name of queue) {\n      const node = nodes.get(name)!;\n      node.level = currentLevel;\n      nodeLevel.set(name, currentLevel);\n      levelNodes.push(node);\n      processedCount++;\n\n      for (const dependent of dependents.get(name) ?? []) {\n        const newDegree = inDegree.get(dependent)! - 1;\n        inDegree.set(dependent, newDegree);\n\n        if (newDegree === 0) {\n          nextQueue.push(dependent);\n        }\n      }\n    }\n\n    levels.push(levelNodes);\n    queue = nextQueue;\n  }\n\n  if (processedCount !== nodes.size) {\n    const cycleNodes = [...nodes.keys()].filter((n) => !nodeLevel.has(n));\n    throw new Error(\"Circular dependency detected involving: \" + cycleNodes.join(\", \"));\n  }\n\n  const roots = [...nodes.keys()].filter((name) => {\n    const deps = dependents.get(name);\n    return !deps || deps.size === 0;\n  });\n\n  const leaves = [...nodes.keys()].filter((name) => {\n    const node = nodes.get(name)!;\n    const depsInDag = node.dependencies.filter((dep) => nodes.has(dep));\n    return depsInDag.length === 0;\n  });\n\n  return { nodes, levels, roots, leaves };\n}\n\n/**\n * Get the topological order (flat list, leaves first)\n */\nexport function getTopologicalOrder<TNode extends DAGNode>(\n  dag: DependencyDAG<TNode>\n): TNode[] {\n  return dag.levels.flat();\n}\n\n/**\n * Visualize the DAG structure (for debugging)\n */\nexport function visualizeDAG<TNode extends DAGNode>(\n  dag: DependencyDAG<TNode>\n): string {\n  const lines = [\"DAG Structure:\"];\n\n  for (let i = 0; i < dag.levels.length; i++) {\n    const level = dag.levels[i]!;\n    lines.push(\"  Level \" + i + \":\");\n    for (const node of level) {\n      const deps =\n        node.dependencies.length > 0\n          ? \" -> [\" + node.dependencies.join(\", \") + \"]\"\n          : \" (leaf)\";\n      lines.push(\"    - \" + node.id + deps);\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n","/**\n * DAG Executor with parallel level-based execution\n */\n\nimport type {\n  DependencyDAG,\n  DAGNode,\n  DAGExecutionOptions,\n  NodeResult,\n  DAGResult,\n} from \"./types.js\";\n\n/**\n * Start a batch of items with concurrency limit\n */\nasync function executeWithConcurrency<T, R>(\n  items: T[],\n  fn: (item: T) => Promise<R>,\n  limit: number\n): Promise<R[]> {\n  const results: R[] = [];\n  const executing = new Set<Promise<void>>();\n\n  for (const item of items) {\n    const promise = fn(item)\n      .then((result) => {\n        results.push(result);\n      })\n      .finally(() => {\n        // Rejection-safe cleanup: always remove the settled promise from the\n        // executing set, even if `fn` rejected, so the set never leaks a\n        // settled (possibly rejected) promise into later `race`/`all` waits.\n        executing.delete(promise);\n      });\n\n    executing.add(promise);\n\n    if (executing.size >= limit) {\n      await Promise.race(executing);\n    }\n  }\n\n  await Promise.all(executing);\n  return results;\n}\n\n/**\n * Call a listener. A listener that throws does not stop the run: the function gives a log\n * line for its error (deep dive DATA-21).\n */\nfunction notify<T>(name: string, listener: ((arg: T) => void) | undefined, arg: T): string | undefined {\n  if (!listener) return undefined;\n  try {\n    listener(arg);\n    return undefined;\n  } catch (error) {\n    return name + \" threw: \" + (error instanceof Error ? error.message : String(error));\n  }\n}\n\n/**\n * Start DAG with level-based parallelization\n *\n * - Levels are processed sequentially (level 0 first, then level 1, and so on)\n * - Within each level, nodes are processed in parallel up to concurrency limit\n * - Supports fail-fast or continue-on-error modes\n *\n * A processor that throws does NOT reject the whole run. The run records the throw\n * as a failed NodeResult, so partial results are always given.\n *\n * With `skipDependents` (the default), a node whose dependency failed or was skipped does not start. Its result has\n * `skipped: true` and an error that names those dependencies. A dependency outside the DAG does not count.\n *\n * `failFast` operates at level granularity. When a node in a level fails, each\n * node already in flight in that level continues to completion. No later level\n * starts. (There is no mid-level cancellation.)\n */\nexport async function executeDAG<TNode extends DAGNode>(\n  dag: DependencyDAG<TNode>,\n  processor: (node: TNode) => Promise<NodeResult<TNode>>,\n  options: DAGExecutionOptions<TNode> = {}\n): Promise<DAGResult<TNode>> {\n  const {\n    concurrency = 4,\n    failFast = true,\n    skipDependents = true,\n    onNodeStart,\n    onNodeComplete,\n  } = options;\n\n  const results = new Map<string, NodeResult<TNode>>();\n  const failedNodes: string[] = [];\n  const skippedNodes: string[] = [];\n  // The ids of the nodes that failed or were skipped\n  const blocked = new Set<string>();\n  const startTime = Date.now();\n  let shouldStop = false;\n\n  for (const level of dag.levels) {\n    if (shouldStop) break;\n\n    const runnable: TNode[] = [];\n    for (const node of level) {\n      const blockers = skipDependents ? node.dependencies.filter((dep) => blocked.has(dep)) : [];\n      if (blockers.length === 0) {\n        runnable.push(node);\n        continue;\n      }\n      const message = \"Skipped \" + node.id + \": the dependencies \" + blockers.join(\", \") + \" failed or were skipped\";\n      results.set(node.id, { node, success: false, skipped: true, error: new Error(message), duration: 0, logs: [message] });\n      skippedNodes.push(node.id);\n      blocked.add(node.id);\n    }\n\n    const levelResults = await executeWithConcurrency(\n      runnable,\n      async (node) => {\n        const startError = notify(\"onNodeStart\", onNodeStart, node);\n        const nodeStart = Date.now();\n        let result: NodeResult<TNode>;\n        try {\n          result = await processor(node);\n        } catch (error) {\n          // Convert a thrown processor error into a failed NodeResult instead\n          // of rejecting the entire run and discarding partial results.\n          const err =\n            error instanceof Error ? error : new Error(String(error));\n          result = {\n            node,\n            success: false,\n            error: err,\n            duration: Date.now() - nodeStart,\n            logs: [\"Processor threw: \" + err.message],\n          };\n        }\n        const completeError = notify(\"onNodeComplete\", onNodeComplete, result);\n        const listenerErrors = [startError, completeError].filter((line): line is string => line !== undefined);\n        if (listenerErrors.length > 0) {\n          result = { ...result, logs: [...(result.logs ?? []), ...listenerErrors] };\n        }\n        return result;\n      },\n      concurrency\n    );\n\n    for (const result of levelResults) {\n      results.set(result.node.id, result);\n      if (!result.success) {\n        failedNodes.push(result.node.id);\n        blocked.add(result.node.id);\n        if (failFast) {\n          shouldStop = true;\n        }\n      }\n    }\n  }\n\n  return {\n    success: failedNodes.length === 0 && skippedNodes.length === 0,\n    results,\n    failedNodes,\n    skippedNodes,\n    totalDuration: Date.now() - startTime,\n  };\n}\n\n/**\n * Start DAG sequentially (no parallelization)\n */\nexport async function executeDAGSequential<TNode extends DAGNode>(\n  dag: DependencyDAG<TNode>,\n  processor: (node: TNode) => Promise<NodeResult<TNode>>,\n  options: Omit<DAGExecutionOptions<TNode>, \"concurrency\"> = {}\n): Promise<DAGResult<TNode>> {\n  return executeDAG(dag, processor, { ...options, concurrency: 1 });\n}\n\n/**\n * Make a simple processor that wraps an async function\n */\nexport function createProcessor<TNode extends DAGNode>(\n  fn: (node: TNode) => Promise<void>\n): (node: TNode) => Promise<NodeResult<TNode>> {\n  return async (node: TNode): Promise<NodeResult<TNode>> => {\n    const startTime = Date.now();\n    const logs: string[] = [];\n\n    try {\n      logs.push(\"Starting \" + node.id);\n      await fn(node);\n      logs.push(\"Completed \" + node.id);\n\n      return {\n        node,\n        success: true,\n        duration: Date.now() - startTime,\n        logs,\n      };\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n      logs.push(\"Failed \" + node.id + \": \" + err.message);\n\n      return {\n        node,\n        success: false,\n        error: err,\n        duration: Date.now() - startTime,\n        logs,\n      };\n    }\n  };\n}\n","/**\n * DAG Builder utilities\n */\n\nimport type { DAGNode } from \"./types.js\";\n\n/**\n * Filter DAG to only include nodes reachable from a root\n */\nexport function filterDAGFromRoot<TNode extends DAGNode>(\n  nodes: Map<string, TNode>,\n  rootId: string\n): Map<string, TNode> {\n  const filtered = new Map<string, TNode>();\n  const visited = new Set<string>();\n\n  function visit(id: string): void {\n    if (visited.has(id)) return;\n    visited.add(id);\n\n    const node = nodes.get(id);\n    if (!node) return;\n\n    filtered.set(id, node);\n\n    for (const dep of node.dependencies) {\n      visit(dep);\n    }\n  }\n\n  visit(rootId);\n  return filtered;\n}\n\n/**\n * Get all ancestors of a node (nodes that this node depends on, transitively)\n */\nexport function getAncestors<TNode extends DAGNode>(\n  nodes: Map<string, TNode>,\n  id: string\n): Set<string> {\n  const ancestors = new Set<string>();\n  const visited = new Set<string>();\n\n  function visit(n: string): void {\n    if (visited.has(n)) return;\n    visited.add(n);\n\n    const node = nodes.get(n);\n    if (!node) return;\n\n    for (const dep of node.dependencies) {\n      if (nodes.has(dep)) {\n        ancestors.add(dep);\n        visit(dep);\n      }\n    }\n  }\n\n  visit(id);\n  return ancestors;\n}\n\n/**\n * Get all descendants of a node (nodes that depend on this node, transitively)\n */\nexport function getDescendants<TNode extends DAGNode>(\n  nodes: Map<string, TNode>,\n  id: string\n): Set<string> {\n  const descendants = new Set<string>();\n  const visited = new Set<string>();\n\n  // Build reverse dependency map\n  const dependents = new Map<string, Set<string>>();\n  for (const [nodeId, node] of nodes) {\n    for (const dep of node.dependencies) {\n      if (!dependents.has(dep)) {\n        dependents.set(dep, new Set());\n      }\n      dependents.get(dep)!.add(nodeId);\n    }\n  }\n\n  function visit(n: string): void {\n    if (visited.has(n)) return;\n    visited.add(n);\n\n    const deps = dependents.get(n);\n    if (!deps) return;\n\n    for (const dep of deps) {\n      descendants.add(dep);\n      visit(dep);\n    }\n  }\n\n  visit(id);\n  return descendants;\n}\n\n/**\n * Make a DAG node from minimal input\n */\nexport function createNode<TData = unknown>(\n  id: string,\n  dependencies: string[] = [],\n  data?: TData | undefined\n): DAGNode<TData> {\n  const node: DAGNode<TData> = { id, dependencies };\n  if (data !== undefined) {\n    node.data = data;\n  }\n  return node;\n}\n\n/**\n * Build a Map of nodes from an array\n */\nexport function buildNodeMap<TNode extends DAGNode>(\n  nodes: TNode[]\n): Map<string, TNode> {\n  return new Map(nodes.map((n) => [n.id, n]));\n}\n"],"mappings":"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"}

package/build/index.d.ts

@@ -1,4 +1,5 @@
 import { i as Layer, s as Stacked, t as Chain } from "./layers.js";
+import { Optional, Result } from "@mark1russell7/optional";
 /**
  * Core traits and capability interfaces for the collections framework.
  *
@@ -138,191 +139,6 @@ export interface Freezable<T> {
   /** This value gives true if this collection is frozen. */
   readonly isFrozen: boolean;
 }
-/**
- * Functional effect types for error handling and optional values.
- *
- * This module gives Option<T> and Result<T,E> types for explicit, type-safe
- * error handling without exceptions. This module includes async variants.
- */
-/**
- * This type represents the absence of a value.
- */
-export interface None {
-  readonly _tag: "None";
-}
-/**
- * This type represents the presence of a value.
- */
-export interface Some<T> {
-  readonly _tag: "Some";
-  readonly value: T;
-}
-/**
- * Option<T> represents a value that is present or absent.
- * This is a type-safe alternative to null/undefined.
- *
- * @example
- * function findUser(id: string): Option<User> {
- *   const user = db.get(id);
- *   return user ? Some(user) : None;
- * }
- */
-export type Option<T> = None | Some<T>;
-/**
- * The singleton None value.
- */
-export declare const None: None;
-/**
- * This function constructs a Some value containing the given value.
- */
-export declare const Some: <T>(value: T) => Some<T>;
-/**
- * Type guard to check if an Option is None.
- */
-export declare const isNone: <T>(opt: Option<T>) => opt is None;
-/**
- * Type guard to check if an Option is Some.
- */
-export declare const isSome: <T>(opt: Option<T>) => opt is Some<T>;
-/**
- * This function extracts the value from a Some, or gives the default value if None.
- */
-export declare const getOrElse: <T>(opt: Option<T>, defaultValue: T) => T;
-/**
- * This function extracts the value from a Some, or throws an error if None.
- */
-export declare const unwrap: <T>(opt: Option<T>) => T;
-/**
- * This function maps a function over the value in a Some, or gives None.
- */
-export declare const mapOption: <T, U>(opt: Option<T>, f: (value: T) => U) => Option<U>;
-/**
- * Chains Option-returning operations.
- */
-export declare const flatMapOption: <T, U>(opt: Option<T>, f: (value: T) => Option<U>) => Option<U>;
-/**
- * This function converts a nullable value to an Option.
- */
-export declare const fromNullable: <T>(value: T | null | undefined) => Option<T>;
-/**
- * This function converts an Option to a nullable value.
- */
-export declare const toNullable: <T>(opt: Option<T>) => T | undefined;
-/**
- * This type represents a successful result containing a value.
- */
-export interface Ok<T> {
-  readonly _tag: "Ok";
-  readonly value: T;
-  /** This method calls the `Ok` case with the value. */
-  match<U>(cases: {
-    Ok: (value: T) => U;
-    Err: (error: never) => U;
-  }): U;
-}
-/**
- * This type represents a failed result containing an error.
- */
-export interface Err<E> {
-  readonly _tag: "Err";
-  readonly error: E;
-  /** This method calls the `Err` case with the error. */
-  match<U>(cases: {
-    Ok: (value: never) => U;
-    Err: (error: E) => U;
-  }): U;
-}
-/**
- * Result<T, E> represents the result of an operation that can fail.
- * It contains either a success value (Ok) or an error value (Err).
- *
- * @example
- * function divide(a: number, b: number): Result<number, string> {
- *   if (b === 0) return Err("Division by zero");
- *   return Ok(a / b);
- * }
- */
-export type Result<T, E> = Ok<T> | Err<E>;
-/**
- * This function constructs an Ok result containing the given value.
- */
-export declare const Ok: <T>(value: T) => Ok<T>;
-/**
- * This function constructs an Err result containing the given error.
- */
-export declare const Err: <E>(error: E) => Err<E>;
-/**
- * Type guard to check if a Result is Ok.
- */
-export declare const isOk: <T, E>(result: Result<T, E>) => result is Ok<T>;
-/**
- * Type guard to check if a Result is Err.
- */
-export declare const isErr: <T, E>(result: Result<T, E>) => result is Err<E>;
-/**
- * This function extracts the value from an Ok, or gives the default value if Err.
- */
-export declare const getOrElseResult: <T, E>(result: Result<T, E>, defaultValue: T) => T;
-/**
- * This function extracts the value from an Ok, or throws the error if Err.
- */
-export declare const unwrapResult: <T, E>(result: Result<T, E>) => T;
-/**
- * This function maps a function over the value in an Ok, or gives the Err unchanged.
- */
-export declare const mapResult: <T, U, E>(result: Result<T, E>, f: (value: T) => U) => Result<U, E>;
-/**
- * This function maps a function over the error in an Err, or gives the Ok unchanged.
- */
-export declare const mapError: <T, E, F>(result: Result<T, E>, f: (error: E) => F) => Result<T, F>;
-/**
- * Chains Result-returning operations.
- */
-export declare const flatMapResult: <T, U, E>(result: Result<T, E>, f: (value: T) => Result<U, E>) => Result<U, E>;
-/**
- * This function converts a throwing function into a Result-returning function.
- */
-export declare const tryCatch: <T, E = unknown>(fn: () => T, onError?: (error: unknown) => E) => Result<T, E>;
-/**
- * This function converts an async throwing function into a Result-returning async function.
- */
-export declare const tryCatchAsync: <T, E = unknown>(fn: () => Promise<T>, onError?: (error: unknown) => E) => Promise<Result<T, E>>;
-/**
- * Async variant of Option<T>.
- */
-export type AsyncOption<T> = Promise<Option<T>>;
-/**
- * Async variant of Result<T, E>.
- */
-export type AsyncResult<T, E> = Promise<Result<T, E>>;
-/**
- * This function maps a function over an async Option.
- */
-export declare const mapAsyncOption: <T, U>(opt: AsyncOption<T>, f: (value: T) => U | Promise<U>) => AsyncOption<U>;
-/**
- * This function maps a function over an async Result.
- */
-export declare const mapAsyncResult: <T, U, E>(result: AsyncResult<T, E>, f: (value: T) => U | Promise<U>) => AsyncResult<U, E>;
-/**
- * This function converts an Option to a Result.
- * None becomes Err with the given error.
- */
-export declare const optionToResult: <T, E>(opt: Option<T>, error: E) => Result<T, E>;
-/**
- * This function converts a Result to an Option.
- * Err becomes None, discarding the error.
- */
-export declare const resultToOption: <T, E>(result: Result<T, E>) => Option<T>;
-/**
- * This function combines multiple Options into an Option of an array.
- * This function gives None if any input is None.
- */
-export declare const sequence: <T>(opts: Option<T>[]) => Option<T[]>;
-/**
- * This function combines multiple Results into a Result of an array.
- * This function gives the first Err encountered, or Ok with all values.
- */
-export declare const sequenceResults: <T, E>(results: Result<T, E>[]) => Result<T[], E>;
 /**
  * Policy types for configurable collection behaviors.
  *
@@ -2418,6 +2234,8 @@ export declare class HashMap<K, V> implements MapLike<K, V> {
   get(key: K): V;
   getOrUndefined(key: K): V | undefined;
   getOrDefault(key: K, defaultValue: V): V;
+  /** This method finds the node of a key, or gives `null`. */
+  private findNode;
   containsValue(value: V): boolean;
   set(key: K, value: V): V | undefined;
   setIfAbsent(key: K, value: V): V;
@@ -3382,9 +3200,9 @@ export declare const unmodifiableCollection: typeof readonlyCollection;
  */
 export interface SafeListOperations<T> {
   /**
-   * Get element at index, giving Option.
+   * Get element at index, as an optional.
    */
-  get(index: number): Option<T>;
+  get(index: number): Optional<T>;
   /**
    * Set element at index, giving Result with old value or error.
    */
@@ -3394,72 +3212,72 @@ export interface SafeListOperations<T> {
    */
   removeAt(index: number): Result<T, string>;
   /**
-   * Get first element as Option.
+   * Get first element as an optional.
    */
-  first(): Option<T>;
+  first(): Optional<T>;
   /**
-   * Get last element as Option.
+   * Get last element as an optional.
    */
-  last(): Option<T>;
+  last(): Optional<T>;
   /**
-   * Pop element, giving Option.
+   * Pop element, as an optional.
    */
-  pop(): Option<T>;
+  pop(): Optional<T>;
   /**
-   * Shift element, giving Option.
+   * Shift element, as an optional.
    */
-  shift(): Option<T>;
+  shift(): Optional<T>;
 }
 /**
  * Safe operations for Queue.
  */
 export interface SafeQueueOperations<T> {
   /**
-   * Peek at head element as Option.
+   * Peek at head element as an optional.
    */
-  peek(): Option<T>;
+  peek(): Optional<T>;
   /**
-   * Poll element as Option.
+   * Poll element as an optional.
    */
-  poll(): Option<T>;
+  poll(): Optional<T>;
   /**
-   * Dequeue element as Option.
+   * Dequeue element as an optional.
    */
-  dequeue(): Option<T>;
+  dequeue(): Optional<T>;
 }
 /**
  * Safe operations for Deque.
  */
 export interface SafeDequeOperations<T> extends SafeQueueOperations<T> {
   /**
-   * Peek at first element as Option.
+   * Peek at first element as an optional.
    */
-  peekFirst(): Option<T>;
+  peekFirst(): Optional<T>;
   /**
-   * Peek at last element as Option.
+   * Peek at last element as an optional.
    */
-  peekLast(): Option<T>;
+  peekLast(): Optional<T>;
   /**
-   * Poll first element as Option.
+   * Poll first element as an optional.
    */
-  pollFirst(): Option<T>;
+  pollFirst(): Optional<T>;
   /**
-   * Poll last element as Option.
+   * Poll last element as an optional.
    */
-  pollLast(): Option<T>;
+  pollLast(): Optional<T>;
   /**
-   * Pop element as Option.
+   * Pop element as an optional.
    */
-  pop(): Option<T>;
+  pop(): Optional<T>;
 }
 /**
  * Safe operations for Map.
  */
 export interface SafeMapOperations<K, V> {
   /**
-   * Get value for key as Option.
+   * Get value for key as an optional.
    */
-  get(key: K): Option<V>;
+  get(key: K): Optional<V>;
   /**
    * Set value for key, giving Result with old value or success.
    */
@@ -3472,7 +3290,7 @@ export interface SafeMapOperations<K, V> {
 /**
  * This function makes a safe List middleware.
  *
- * This function exposes a `safe` property with Option/Result-based operations.
+ * This function exposes a `safe` property with Optional/Result-based operations.
  */
 export declare function safeList<T>(): Middleware<List<T>, List<T> & {
   safe: SafeListOperations<T>;