@thi.ng/arrays 2.3.10 → 2.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-10-03T16:07:55Z
+- **Last updated**: 2022-10-31T23:01:45Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,15 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.4.0) (2022-10-31)
+
+#### 🚀 Features
+
+- add topoSort() ([f7f2e20](https://github.com/thi-ng/umbrella/commit/f7f2e20))
+  - add topoSort() as lightweight alt for [@thi.ng/dgraph](https://github.com/thi-ng/umbrella/tree/main/packages/dgraph)
+  - add tests
+  - update readme
+
 ## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/arrays@2.3.0) (2022-07-08)
 
 #### 🚀 Features

package/README.md

@@ -51,7 +51,7 @@ node --experimental-repl-await
 > const arrays = await import("@thi.ng/arrays");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 2.51 KB
+Package sizes (gzipped, pre-treeshake): ESM: 2.64 KB
 
 ## Dependencies
 
@@ -90,6 +90,7 @@ Package sizes (gzipped, pre-treeshake): ESM: 2.51 KB
 - [startsWith()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/starts-with.ts)
 - [swap()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/swap.ts)
 - [swizzle()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/swizzle.ts)
+- [topoSort()](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays/src/topo-sort.ts)
 
 ### Binary search result predicates
 

package/index.d.ts

@@ -21,4 +21,5 @@ export * from "./sort-cached.js";
 export * from "./starts-with.js";
 export * from "./swap.js";
 export * from "./swizzle.js";
+export * from "./topo-sort.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -21,3 +21,4 @@ export * from "./sort-cached.js";
 export * from "./starts-with.js";
 export * from "./swap.js";
 export * from "./swizzle.js";
+export * from "./topo-sort.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/arrays",
-  "version": "2.3.10",
+  "version": "2.4.0",
   "description": "Array / Arraylike utilities",
   "type": "module",
   "module": "./index.js",
@@ -34,29 +34,33 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.4.3",
-    "@thi.ng/checks": "^3.3.1",
-    "@thi.ng/compare": "^2.1.13",
-    "@thi.ng/equiv": "^2.1.11",
-    "@thi.ng/errors": "^2.2.2",
-    "@thi.ng/random": "^3.3.12"
+    "@thi.ng/api": "^8.4.4",
+    "@thi.ng/checks": "^3.3.2",
+    "@thi.ng/compare": "^2.1.14",
+    "@thi.ng/equiv": "^2.1.12",
+    "@thi.ng/errors": "^2.2.3",
+    "@thi.ng/random": "^3.3.13"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.31.1",
-    "@thi.ng/testament": "^0.3.3",
+    "@microsoft/api-extractor": "^7.33.5",
+    "@thi.ng/testament": "^0.3.4",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.22.17",
-    "typescript": "^4.8.3"
+    "typedoc": "^0.23.18",
+    "typescript": "^4.8.4"
   },
   "keywords": [
     "aos",
     "array",
     "binary",
+    "distance",
     "fuzzy",
+    "levenshtein",
     "search",
     "shuffle",
+    "sort",
     "swizzle",
+    "topology",
     "typescript"
   ],
   "publishConfig": {
@@ -141,10 +145,13 @@
     },
     "./swizzle": {
       "default": "./swizzle.js"
+    },
+    "./topo-sort": {
+      "default": "./topo-sort.js"
     }
   },
   "thi.ng": {
     "year": 2018
   },
-  "gitHead": "cc61bc0a890288bea00b8df81ffd73bc4851ffd3\n"
+  "gitHead": "7eff3051eb395f460421727b8cf5ef79f09faaa9\n"
 }

package/topo-sort.d.ts

@@ -0,0 +1,36 @@
+import type { Fn, Nullable, IObjectOf } from "@thi.ng/api";
+/**
+ * Takes an object describing a DAG of nodes of type T with keys being node IDs.
+ * Also takes a function which will be applied to each node and either returns
+ * an array of node IDs the given node depends on or null if the node has no
+ * dependencies. Traverses all nodes in the graph (object) and returns an array
+ * of node IDs in topological dependency order.
+ *
+ * @remarks
+ * An error will be thrown if the graph contains cycles. In this case, the full
+ * cycle will be part of the error message (see second example below).
+ *
+ * @example
+ * ```ts
+ * const graph = {
+ *   a: { deps: ["c", "b"] },
+ *   b: {},
+ *   c: { deps: ["d"] },
+ *   d: { deps: ["b"] }
+ * };
+ * topoSort(graph, (node) => node.deps);
+ * // [ "b", "d", "c", "a" ]
+ *
+ * // An error will be thrown if the graph contains cycles...
+ * graph.d.deps.push("a");
+ *
+ * topoSort(graph, (node) => node.deps);
+ * // Uncaught Error: illegal state: dependency cycle: a -> c -> d -> a
+ * ```
+ *
+ * @param nodes
+ * @param deps
+ * @returns
+ */
+export declare const topoSort: <T>(nodes: IObjectOf<T>, deps: Fn<T, Nullable<string[]>>) => string[];
+//# sourceMappingURL=topo-sort.d.ts.map

package/topo-sort.js

@@ -0,0 +1,54 @@
+import { illegalState } from "@thi.ng/errors";
+/**
+ * Takes an object describing a DAG of nodes of type T with keys being node IDs.
+ * Also takes a function which will be applied to each node and either returns
+ * an array of node IDs the given node depends on or null if the node has no
+ * dependencies. Traverses all nodes in the graph (object) and returns an array
+ * of node IDs in topological dependency order.
+ *
+ * @remarks
+ * An error will be thrown if the graph contains cycles. In this case, the full
+ * cycle will be part of the error message (see second example below).
+ *
+ * @example
+ * ```ts
+ * const graph = {
+ *   a: { deps: ["c", "b"] },
+ *   b: {},
+ *   c: { deps: ["d"] },
+ *   d: { deps: ["b"] }
+ * };
+ * topoSort(graph, (node) => node.deps);
+ * // [ "b", "d", "c", "a" ]
+ *
+ * // An error will be thrown if the graph contains cycles...
+ * graph.d.deps.push("a");
+ *
+ * topoSort(graph, (node) => node.deps);
+ * // Uncaught Error: illegal state: dependency cycle: a -> c -> d -> a
+ * ```
+ *
+ * @param nodes
+ * @param deps
+ * @returns
+ */
+export const topoSort = (nodes, deps) => {
+    const cycles = {};
+    const topology = [];
+    const sort = (id, path) => {
+        if (cycles[id])
+            illegalState(`dependency cycle: ${path.join(" -> ")}`);
+        cycles[id] = true;
+        const nodeDeps = deps(nodes[id]);
+        if (nodeDeps) {
+            for (let d of nodeDeps)
+                sort(d, [...path, d]);
+        }
+        cycles[id] = false;
+        if (!topology.includes(id))
+            topology.push(id);
+    };
+    for (let id in nodes)
+        sort(id, [id]);
+    return topology;
+};