@mark1russell7/collections 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @mark1russell7/collections
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@mark1russell7/collections?color=2346c4)](https://www.npmjs.com/package/@mark1russell7/collections)
+
+Collections for TypeScript with no dependencies: lists, maps, queues, a summary tree, channels, lazy operations and dependency graphs.
+
+```sh
+npm i @mark1russell7/collections
+```
+
+## Lists, maps and behaviors
+
+```ts
+import { arrayList, compose, hashMap, lruMap } from "@mark1russell7/collections";
+
+const list = arrayList<number>();
+list.add(1);
+list.add(2);
+
+const cache = compose(lruMap<string, number>({ capacity: 2 }))(hashMap<string, number>());
+cache.set("a", 1);
+cache.set("b", 2);
+cache.set("c", 3);
+cache.has("a"); // false: the map removed the oldest key
+```
+
+## The summary tree
+
+A summary tree is a persistent sequence. Each node keeps the sum of its leaves in a monoid. Each change gives a new tree in logarithmic time, and the old tree stays the same.
+
+```ts
+import { summaryTree, type SummarySpec } from "@mark1russell7/collections";
+
+const text: SummarySpec<string, string> = {
+  monoid: { empty: "", combine: (a, b) => a + b },
+  measure: (leaf) => leaf,
+};
+const tree = summaryTree(text, ["a", "b", "c"]);
+tree.summary; // "abc"
+```
+
+## Dependency graphs
+
+The entry `./dag` gives the levels of a graph, and a run of each level with a limit of concurrency.
+
+```ts
+import { buildLeveledDAG, getTopologicalOrder } from "@mark1russell7/collections/dag";
+
+const nodes = new Map([
+  ["app", { id: "app", dependencies: ["lib"] }],
+  ["lib", { id: "lib", dependencies: [] }],
+]);
+getTopologicalOrder(buildLeveledDAG(nodes)).map((node) => node.id); // ["lib", "app"]
+```
+
+The entry `./graph` gives `hubBreadthFirstOrder`: the order of a weighted graph, from its largest hub, with no other imports.
+
+```ts
+import { hubBreadthFirstOrder } from "@mark1russell7/collections/graph";
+
+hubBreadthFirstOrder(3, [{ a: 0, b: 1 }, { a: 1, b: 2 }]); // [1, 0, 2]
+```
+
+## Contract checks
+
+The entry `./testing` gives the small checks of a contract suite: `holds`, `same`, `rejects`, `deepEqual`, `show` and `ContractViolation`. These checks import no test framework.
+
+## Entries
+
+| Entry | Contents |
+| --- | --- |
+| `@mark1russell7/collections` | Lists, sets, maps, queues, the summary tree, behaviors, channels, lazy operations, `keyBetween` and the other functions of ranks |
+| `@mark1russell7/collections/dag` | Levels, topological order, a run with a limit of concurrency, filters |
+| `@mark1russell7/collections/graph` | `hubBreadthFirstOrder` |
+| `@mark1russell7/collections/testing` | The checks of a contract suite |
+
+## License
+
+MIT

package/build/dag/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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
+ */
+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
+ */
+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
+ */
+interface DAGExecutionOptions<TNode extends DAGNode = DAGNode> {
+  /** Max parallel operations per level (default: 4) */
+  concurrency?: number;
+  /** When this value is true, the run stops on the first error. The default is 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
+ */
+interface NodeResult<TNode extends DAGNode = DAGNode> {
+  /** The node that was processed */
+  node: TNode;
+  /** If processing succeeded */
+  success: boolean;
+  /** Error if failed */
+  error?: Error | undefined;
+  /** Duration in milliseconds */
+  duration: number;
+  /** This value logs from processing */
+  logs: string[];
+  /** Optional output from the processor */
+  output?: unknown | undefined;
+}
+/**
+ * The result of a run of an entire DAG
+ */
+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
+ */
+type NodeProcessor<TNode extends DAGNode = DAGNode> = (node: TNode) => Promise<NodeResult<TNode>>;
+/**
+ * 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 declare function buildLeveledDAG<TNode extends DAGNode>(nodes: Map<string, TNode>): DependencyDAG<TNode>;
+/**
+ * Get the topological order (flat list, leaves first)
+ */
+export declare function getTopologicalOrder<TNode extends DAGNode>(dag: DependencyDAG<TNode>): TNode[];
+/**
+ * Visualize the DAG structure (for debugging)
+ */
+export declare function visualizeDAG<TNode extends DAGNode>(dag: DependencyDAG<TNode>): string;
+/**
+ * Start DAG with level-based parallelization
+ *
+ * - Levels are processed sequentially (level 0 first, then level 1, and so on)
+ * - Within each level, nodes are processed in parallel up to concurrency limit
+ * - Supports fail-fast or continue-on-error modes
+ *
+ * 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.
+ *
+ * `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.)
+ */
+export declare function executeDAG<TNode extends DAGNode>(dag: DependencyDAG<TNode>, processor: (node: TNode) => Promise<NodeResult<TNode>>, options?: DAGExecutionOptions<TNode>): Promise<DAGResult<TNode>>;
+/**
+ * Start DAG sequentially (no parallelization)
+ */
+export declare function executeDAGSequential<TNode extends DAGNode>(dag: DependencyDAG<TNode>, processor: (node: TNode) => Promise<NodeResult<TNode>>, options?: Omit<DAGExecutionOptions<TNode>, "concurrency">): Promise<DAGResult<TNode>>;
+/**
+ * Make a simple processor that wraps an async function
+ */
+export declare function createProcessor<TNode extends DAGNode>(fn: (node: TNode) => Promise<void>): (node: TNode) => Promise<NodeResult<TNode>>;
+/**
+ * Filter DAG to only include nodes reachable from a root
+ */
+export declare function filterDAGFromRoot<TNode extends DAGNode>(nodes: Map<string, TNode>, rootId: string): Map<string, TNode>;
+/**
+ * Get all ancestors of a node (nodes that this node depends on, transitively)
+ */
+export declare function getAncestors<TNode extends DAGNode>(nodes: Map<string, TNode>, id: string): Set<string>;
+/**
+ * Get all descendants of a node (nodes that depend on this node, transitively)
+ */
+export declare function getDescendants<TNode extends DAGNode>(nodes: Map<string, TNode>, id: string): Set<string>;
+/**
+ * Make a DAG node from minimal input
+ */
+export declare function createNode<TData = unknown>(id: string, dependencies?: string[], data?: TData | undefined): DAGNode<TData>;
+/**
+ * Build a Map of nodes from an array
+ */
+export declare function buildNodeMap<TNode extends DAGNode>(nodes: TNode[]): Map<string, TNode>;
+export type { DAGExecutionOptions, DAGNode, DAGResult, DependencyDAG, NodeProcessor, NodeResult };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/build/dag/index.js

@@ -0,0 +1,294 @@
+// src/dag/traversal.ts
+/**
+* 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
+*/
+function buildLeveledDAG(nodes) {
+	const inDegree = /* @__PURE__ */ new Map();
+	const dependents = /* @__PURE__ */ new Map();
+	for (const [name, node] of nodes) {
+		const depsInDag = new Set(node.dependencies.filter((dep) => nodes.has(dep)));
+		inDegree.set(name, depsInDag.size);
+		dependents.set(name, /* @__PURE__ */ 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 = [];
+	for (const [name, degree] of inDegree) if (degree === 0) queue.push(name);
+	const levels = [];
+	const nodeLevel = /* @__PURE__ */ new Map();
+	let processedCount = 0;
+	while (queue.length > 0) {
+		const currentLevel = levels.length;
+		const levelNodes = [];
+		const nextQueue = [];
+		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(", "));
+	}
+	return {
+		nodes,
+		levels,
+		roots: [...nodes.keys()].filter((name) => {
+			const deps = dependents.get(name);
+			return !deps || deps.size === 0;
+		}),
+		leaves: [...nodes.keys()].filter((name) => {
+			return nodes.get(name).dependencies.filter((dep) => nodes.has(dep)).length === 0;
+		})
+	};
+}
+/**
+* Get the topological order (flat list, leaves first)
+*/
+function getTopologicalOrder(dag) {
+	return dag.levels.flat();
+}
+/**
+* Visualize the DAG structure (for debugging)
+*/
+function visualizeDAG(dag) {
+	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");
+}
+// src/dag/executor.ts
+/**
+* Start a batch of items with concurrency limit
+*/
+async function executeWithConcurrency(items, fn, limit) {
+	const results = [];
+	const executing = /* @__PURE__ */ new Set();
+	for (const item of items) {
+		const promise = fn(item).then((result) => {
+			results.push(result);
+		}).finally(() => {
+			executing.delete(promise);
+		});
+		executing.add(promise);
+		if (executing.size >= limit) await Promise.race(executing);
+	}
+	await Promise.all(executing);
+	return results;
+}
+/**
+* Call a listener. A listener that throws does not stop the run: the function gives a log
+* line for its error (deep dive DATA-21).
+*/
+function notify(name, listener, arg) {
+	if (!listener) return void 0;
+	try {
+		listener(arg);
+		return;
+	} catch (error) {
+		return name + " threw: " + (error instanceof Error ? error.message : String(error));
+	}
+}
+/**
+* Start DAG with level-based parallelization
+*
+* - Levels are processed sequentially (level 0 first, then level 1, and so on)
+* - Within each level, nodes are processed in parallel up to concurrency limit
+* - Supports fail-fast or continue-on-error modes
+*
+* 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.
+*
+* `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 results = /* @__PURE__ */ new Map();
+	const failedNodes = [];
+	const startTime = Date.now();
+	let shouldStop = false;
+	for (const level of dag.levels) {
+		if (shouldStop) break;
+		const levelResults = await executeWithConcurrency(level, async (node) => {
+			const startError = notify("onNodeStart", onNodeStart, node);
+			const nodeStart = Date.now();
+			let result;
+			try {
+				result = await processor(node);
+			} catch (error) {
+				const err = error instanceof Error ? error : new Error(String(error));
+				result = {
+					node,
+					success: false,
+					error: err,
+					duration: Date.now() - nodeStart,
+					logs: ["Processor threw: " + err.message]
+				};
+			}
+			const listenerErrors = [startError, notify("onNodeComplete", onNodeComplete, result)].filter((line) => line !== void 0);
+			if (listenerErrors.length > 0) result = {
+				...result,
+				logs: [...result.logs ?? [], ...listenerErrors]
+			};
+			return result;
+		}, concurrency);
+		for (const result of levelResults) {
+			results.set(result.node.id, result);
+			if (!result.success) {
+				failedNodes.push(result.node.id);
+				if (failFast) shouldStop = true;
+			}
+		}
+	}
+	return {
+		success: failedNodes.length === 0,
+		results,
+		failedNodes,
+		totalDuration: Date.now() - startTime
+	};
+}
+/**
+* Start DAG sequentially (no parallelization)
+*/
+async function executeDAGSequential(dag, processor, options = {}) {
+	return executeDAG(dag, processor, {
+		...options,
+		concurrency: 1
+	});
+}
+/**
+* Make a simple processor that wraps an async function
+*/
+function createProcessor(fn) {
+	return async (node) => {
+		const startTime = Date.now();
+		const logs = [];
+		try {
+			logs.push("Starting " + node.id);
+			await fn(node);
+			logs.push("Completed " + node.id);
+			return {
+				node,
+				success: true,
+				duration: Date.now() - startTime,
+				logs
+			};
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			logs.push("Failed " + node.id + ": " + err.message);
+			return {
+				node,
+				success: false,
+				error: err,
+				duration: Date.now() - startTime,
+				logs
+			};
+		}
+	};
+}
+// src/dag/builder.ts
+/**
+* Filter DAG to only include nodes reachable from a root
+*/
+function filterDAGFromRoot(nodes, rootId) {
+	const filtered = /* @__PURE__ */ new Map();
+	const visited = /* @__PURE__ */ new Set();
+	function visit(id) {
+		if (visited.has(id)) return;
+		visited.add(id);
+		const node = nodes.get(id);
+		if (!node) return;
+		filtered.set(id, node);
+		for (const dep of node.dependencies) visit(dep);
+	}
+	visit(rootId);
+	return filtered;
+}
+/**
+* Get all ancestors of a node (nodes that this node depends on, transitively)
+*/
+function getAncestors(nodes, id) {
+	const ancestors = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	function visit(n) {
+		if (visited.has(n)) return;
+		visited.add(n);
+		const node = nodes.get(n);
+		if (!node) return;
+		for (const dep of node.dependencies) if (nodes.has(dep)) {
+			ancestors.add(dep);
+			visit(dep);
+		}
+	}
+	visit(id);
+	return ancestors;
+}
+/**
+* Get all descendants of a node (nodes that depend on this node, transitively)
+*/
+function getDescendants(nodes, id) {
+	const descendants = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const dependents = /* @__PURE__ */ new Map();
+	for (const [nodeId, node] of nodes) for (const dep of node.dependencies) {
+		if (!dependents.has(dep)) dependents.set(dep, /* @__PURE__ */ new Set());
+		dependents.get(dep).add(nodeId);
+	}
+	function visit(n) {
+		if (visited.has(n)) return;
+		visited.add(n);
+		const deps = dependents.get(n);
+		if (!deps) return;
+		for (const dep of deps) {
+			descendants.add(dep);
+			visit(dep);
+		}
+	}
+	visit(id);
+	return descendants;
+}
+/**
+* Make a DAG node from minimal input
+*/
+function createNode(id, dependencies = [], data) {
+	const node = {
+		id,
+		dependencies
+	};
+	if (data !== void 0) node.data = data;
+	return node;
+}
+/**
+* Build a Map of nodes from an array
+*/
+function buildNodeMap(nodes) {
+	return new Map(nodes.map((n) => [n.id, n]));
+}
+export { buildLeveledDAG, buildNodeMap, createNode, createProcessor, executeDAG, executeDAGSequential, filterDAGFromRoot, getAncestors, getDescendants, getTopologicalOrder, visualizeDAG };
+
+//# sourceMappingURL=index.js.map

package/build/dag/index.js.map

@@ -0,0 +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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"}

package/build/graph/index.d.ts

@@ -0,0 +1,20 @@
+/** An undirected edge between the nodes `a` and `b`. The default weight is 1. */
+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 declare function hubBreadthFirstOrder(n: number, edges?: readonly WeightedEdge[], compare?: (i: number, j: number) => number): number[];
+export type { WeightedEdge };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/graph/hub-order.ts"],"mappings":";UACiB;WACN;WACA;WACA;;;;;;;;;;;;;wBAcK,qBAAqB,WAAW,iBAAgB,gBAAqB,WAAU,WAAW"}

package/build/graph/index.js

@@ -0,0 +1,48 @@
+// src/graph/hub-order.ts
+/**
+* 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.
+*/
+function hubBreadthFirstOrder(n, edges = [], compare = () => 0) {
+	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 = 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, j) => 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 = [];
+	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;
+}
+export { hubBreadthFirstOrder };
+
+//# sourceMappingURL=index.js.map

package/build/graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/graph/hub-order.ts"],"sourcesContent":["/** An undirected edge between the nodes `a` and `b`. The default weight is 1. */\nexport interface WeightedEdge {\n  readonly a: number;\n  readonly b: number;\n  readonly weight?: number | undefined;\n}\n\n/**\n * This function gives a breadth-first order of the nodes `0` to `n - 1` of an undirected weighted graph.\n *\n * - The hub of a component is the node with the largest sum of edge weights. `compare`, then the lower index, breaks a tie.\n * - The order starts at the hub of each component, and goes breadth-first. `compare`, then the lower index, orders the neighbours of a node.\n * - Without edges, each node is a component, so the order is the order of `compare`.\n * - An edge from a node to itself adds no weight.\n * - A bad `n`, an index outside the nodes, or a weight that is not a finite number above 0, throws a `RangeError`.\n *\n * The function is pure. It keeps no state, and it does not change its arguments.\n */\nexport function hubBreadthFirstOrder(n: number, edges: readonly WeightedEdge[] = [], compare: (i: number, j: number) => number = () => 0): number[] {\n  if (!Number.isInteger(n) || n < 0) throw new RangeError(`The count of the nodes is a whole number from 0, not ${n}.`);\n  const degree = new Float64Array(n);\n  const next: number[][] = Array.from({ length: n }, () => []);\n  for (const { a, b, weight = 1 } of edges) {\n    if (!Number.isInteger(a) || !Number.isInteger(b) || a < 0 || b < 0 || a >= n || b >= n) {\n      throw new RangeError(`An edge joins the nodes ${a} and ${b}, but the indexes go from 0 to ${n - 1}.`);\n    }\n    if (!Number.isFinite(weight) || weight <= 0) throw new RangeError(`The weight of an edge is a finite number above 0, not ${weight}.`);\n    if (a === b) continue;\n    degree[a] = degree[a]! + weight;\n    degree[b] = degree[b]! + weight;\n    next[a]!.push(b);\n    next[b]!.push(a);\n  }\n  const order = (i: number, j: number): number => compare(i, j) || i - j;\n  const hubs = Array.from({ length: n }, (_, i) => i).sort((i, j) => degree[j]! - degree[i]! || order(i, j));\n  const seen = new Uint8Array(n);\n  const out: number[] = [];\n  for (const hub of hubs) {\n    if (seen[hub] === 1) continue;\n    seen[hub] = 1;\n    const queue = [hub];\n    for (let k = 0; k < queue.length; k++) {\n      const i = queue[k]!;\n      out.push(i);\n      for (const j of next[i]!.toSorted(order)) {\n        if (seen[j] === 1) continue;\n        seen[j] = 1;\n        queue.push(j);\n      }\n    }\n  }\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;AAkBA,SAAgB,qBAAqB,GAAW,QAAiC,CAAC,GAAG,gBAAkD,GAAa;CAClJ,IAAI,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,WAAW,wDAAwD,EAAE,EAAE;CACpH,MAAM,SAAS,IAAI,aAAa,CAAC;CACjC,MAAM,OAAmB,MAAM,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;CAC3D,KAAK,MAAM,EAAE,GAAG,GAAG,SAAS,OAAO,OAAO;EACxC,IAAI,CAAC,OAAO,UAAU,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,KAAK,IAAI,KAAK,KAAK,KAAK,KAAK,GACnF,MAAM,IAAI,WAAW,2BAA2B,EAAE,OAAO,EAAE,iCAAiC,IAAI,EAAE,EAAE;EAEtG,IAAI,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,GAAG,MAAM,IAAI,WAAW,yDAAyD,OAAO,EAAE;EACpI,IAAI,MAAM,GAAG;EACb,OAAO,KAAK,OAAO,KAAM;EACzB,OAAO,KAAK,OAAO,KAAM;EACzB,KAAK,EAAE,CAAE,KAAK,CAAC;EACf,KAAK,EAAE,CAAE,KAAK,CAAC;CACjB;CACA,MAAM,SAAS,GAAW,MAAsB,QAAQ,GAAG,CAAC,KAAK,IAAI;CACrE,MAAM,OAAO,MAAM,KAAK,EAAE,QAAQ,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,OAAO,KAAM,OAAO,MAAO,MAAM,GAAG,CAAC,CAAC;CACzG,MAAM,OAAO,IAAI,WAAW,CAAC;CAC7B,MAAM,MAAgB,CAAC;CACvB,KAAK,MAAM,OAAO,MAAM;EACtB,IAAI,KAAK,SAAS,GAAG;EACrB,KAAK,OAAO;EACZ,MAAM,QAAQ,CAAC,GAAG;EAClB,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;GACrC,MAAM,IAAI,MAAM;GAChB,IAAI,KAAK,CAAC;GACV,KAAK,MAAM,KAAK,KAAK,EAAE,CAAE,SAAS,KAAK,GAAG;IACxC,IAAI,KAAK,OAAO,GAAG;IACnB,KAAK,KAAK;IACV,MAAM,KAAK,CAAC;GACd;EACF;CACF;CACA,OAAO;AACT"}