Last commit july 5th

spa/node_modules/treeverse/LICENSE

@@ -0,0 +1,15 @@
+The ISC License
+
+Copyright (c) npm, Inc. and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

spa/node_modules/treeverse/README.md

@@ -0,0 +1,129 @@
+# treeverse
+
+Walk any kind of tree structure depth- or breadth-first. Supports promises
+and advanced map-reduce operations with a very small API.
+
+Treeverse does not care what kind of tree it is, it will traverse it for
+you just fine.  It does the right thing with functions that return
+Promises, and returns a non-Promise value if your functions don't return
+Promises.
+
+Rather than imposing a specific structure, like requiring you to have child
+nodes stored in a `children` array, it calls the supplied `getChildren()`
+function, so the children can be anywhere (or not even exist yet!)  This
+makes it suitable for _creating_ an optimized tree from a set of dependency
+manifests, for example.
+
+## USAGE
+
+```js
+const {depth, breadth} = require('treeverse')
+
+// depth-first traversal
+// returns a promise if any visit/leave function returns a promise
+// otherwise returns the result of leave, or visit if no leave function
+// provided.
+depth({
+  // the root node where we start the traversal
+  tree: rootNode,
+
+  visit (node) {
+    // optional
+    // called upon descent into the node.
+    // return a promise, or a mapped value, or nothing to just leave it
+    // as-is
+  },
+  leave (node, children) {
+    // optional
+    // called as we ascend back to the root of the tree.
+    // return a promise, or a reduced value, or nothing to leave it as is
+    // the children array is a list of the child nodes that have been
+    // visited (and potentially left) already.  If the tree is acyclic,
+    // then leave() will have been called on all of them.  If it has
+    // cycles, then the children may not have been left yet.
+  },
+  getChildren (node, nodeResult) {
+    // required
+    // return an array of child nodes in the tree, if any exist
+    // returning a promise is totally ok, of course.
+    // the first argument is the original value of the node.  The second
+    // argument is the result of visit(node).
+  },
+  filter (node) {
+    // optional
+    // return true if the node should be visited, false otherwise
+    // initial tree is always visited, so this only filters children
+    // note that filtering a node _also_ filters all of its children.
+  },
+})
+
+// breadth first traversal
+// returns a promise if any visit function returns a promise
+// otherwise returns the result of the top-level node.
+// note that only a visit() function is supported here, since a node's
+// children are typically traversed much later in the process.
+breadth({
+  // the root node where we start the traversal
+  tree: rootNode,
+
+  visit (node) {
+    // optional, but a no-op if not provided.
+    // called when this node is encountered in the traversal.
+    // return a promise, or a mapped value, or nothing to leave as-is.
+  },
+  getChildren (node, nodeResult) {
+    // required, same as depth()
+  },
+  filter (node) {
+    // optional, same as depth()
+  },
+})
+```
+
+## API
+
+Both functions take a single options object as an argument, and return
+either the result value, or a Promise to the result value if the
+methods in the options argument ever return a Promise.
+
+* `treeverse.breadth` - Perform a breadth-first traversal.  That is, walk
+  across node siblings before traversing node children.
+* `treeverse.depth` - Perform a depth-first traversal.  That is, walk
+  down into child nodes before traversing siblings.
+
+## OPTIONS
+
+All function options can return a Promise or actual value.
+
+The return value is the result of the top level visit function if no leave
+function is provided, or leave.  If any method along the way returns a
+promise, then the top level function will return a promise which resolves
+to the result of visiting (and leaving) the top node in the tree.
+
+* `tree` - The initial node where the traversal begins.
+* `visit(node)` - Function to call upon visiting a node.
+* `leave(node, children)` - (Depth only) Function to call upon leaving a
+  node, once all of its children have been visited, and potentially left.
+  `children` is an array of child node visit results.  If the graph is
+  cyclic, then some children _may_ have been visited but not left.
+* `getChildren(node, nodeResult)` - Get an array of child nodes to process.
+* `filter` - Filter out child nodes from the traversal.  Note that this
+  filters the entire branch of the tree, not just that one node.  That is,
+  children of filtered nodes are not traversed either.
+
+## STACK DEPTH WARNING
+
+When a `leave` method is specified, then recursion is used, because
+maintaining state otherwise is challenging.  This means that using `leave`
+with a synchronous depth first traversal of very deeply nested trees will
+result in stack overflow errors.
+
+To avoid this, either make one or more of the functions async, or do all of
+the work in the `visit` method.
+
+Breadth-first traversal always uses a loop, and is stack-safe.
+
+It is _possible_ to implement depth first traversal with a leave method
+using a loop rather than recursion, but maintaining the `leave(node,
+[children])` API surface would be challenging, and is not implemented at
+this time.

spa/node_modules/treeverse/lib/breadth.js

@@ -0,0 +1,67 @@
+// Perform a breadth-first walk of a tree, either logical or physical
+// This one only visits, it doesn't leave.  That's because
+// in a breadth-first traversal, children may be visited long
+// after their parent, so the "exit" pass ends up being just
+// another breadth-first walk.
+//
+// Breadth-first traversals are good for either creating a tree (ie,
+// reifying a dep graph based on a package.json without a node_modules
+// or package-lock), or mutating it in-place.  For a map-reduce type of
+// walk, it doesn't make a lot of sense, and is very expensive.
+const breadth = ({
+  visit,
+  filter = () => true,
+  getChildren,
+  tree,
+}) => {
+  const queue = []
+  const seen = new Map()
+
+  const next = () => {
+    while (queue.length) {
+      const node = queue.shift()
+      const res = visitNode(node)
+      if (isPromise(res)) {
+        return res.then(() => next())
+      }
+    }
+    return seen.get(tree)
+  }
+
+  const visitNode = (visitTree) => {
+    if (seen.has(visitTree)) {
+      return seen.get(visitTree)
+    }
+
+    seen.set(visitTree, null)
+    const res = visit ? visit(visitTree) : visitTree
+    if (isPromise(res)) {
+      const fullResult = res.then(resThen => {
+        seen.set(visitTree, resThen)
+        return kidNodes(visitTree)
+      })
+      seen.set(visitTree, fullResult)
+      return fullResult
+    } else {
+      seen.set(visitTree, res)
+      return kidNodes(visitTree)
+    }
+  }
+
+  const kidNodes = (kidTree) => {
+    const kids = getChildren(kidTree, seen.get(kidTree))
+    return isPromise(kids) ? kids.then(processKids) : processKids(kids)
+  }
+
+  const processKids = (kids) => {
+    kids = (kids || []).filter(filter)
+    queue.push(...kids)
+  }
+
+  queue.push(tree)
+  return next()
+}
+
+const isPromise = p => p && typeof p.then === 'function'
+
+module.exports = breadth

spa/node_modules/treeverse/lib/depth-descent.js

@@ -0,0 +1,88 @@
+// Perform a depth-first walk of a tree, ONLY doing the descent (visit)
+//
+// This uses a stack rather than recursion, so that it can handle deeply
+// nested trees without call stack overflows.  (My kingdom for proper TCO!)
+//
+// This is only used for cases where leave() is not specified.
+//
+// a
+// +-- b
+// |   +-- 1
+// |   +-- 2
+// +-- c
+//     +-- 3
+//     +-- 4
+//
+// Expect:
+// visit a
+// visit b
+// visit 1
+// visit 2
+// visit c
+// visit 3
+// visit 4
+//
+// stack.push(tree)
+// while stack not empty
+//   pop T from stack
+//   VISIT(T)
+//   get children C of T
+//   push each C onto stack
+
+const depth = ({
+  visit,
+  filter,
+  getChildren,
+  tree,
+}) => {
+  const stack = []
+  const seen = new Map()
+
+  const next = () => {
+    while (stack.length) {
+      const node = stack.pop()
+      const res = visitNode(node)
+      if (isPromise(res)) {
+        return res.then(() => next())
+      }
+    }
+    return seen.get(tree)
+  }
+
+  const visitNode = (visitTree) => {
+    if (seen.has(visitTree)) {
+      return seen.get(visitTree)
+    }
+
+    seen.set(visitTree, null)
+    const res = visit ? visit(visitTree) : visitTree
+    if (isPromise(res)) {
+      const fullResult = res.then(resThen => {
+        seen.set(visitTree, resThen)
+        return kidNodes(visitTree)
+      })
+      seen.set(visitTree, fullResult)
+      return fullResult
+    } else {
+      seen.set(visitTree, res)
+      return kidNodes(visitTree)
+    }
+  }
+
+  const kidNodes = (kidTree) => {
+    const kids = getChildren(kidTree, seen.get(kidTree))
+    return isPromise(kids) ? kids.then(processKids) : processKids(kids)
+  }
+
+  const processKids = (kids) => {
+    kids = (kids || []).filter(filter)
+    stack.push(...kids)
+  }
+
+  stack.push(tree)
+  return next()
+}
+
+const isPromise = p => p && typeof p.then === 'function'
+
+module.exports = depth

spa/node_modules/treeverse/lib/depth.js

@@ -0,0 +1,76 @@
+// Perform a depth-first walk of a tree.
+//
+// `visit(node)` is called when the node is first encountered.
+// `leave(node, children)` is called when all of the node's children
+// have been left or (in the case of cyclic graphs) visited.
+//
+// Only one of visit or leave is required.  (Technically both are optional,
+// but if you don't provide at least one, the tree is just walked without
+// doing anything, which is a bit pointless.)  If visit is provided, and
+// leave is not, then this is a root->leaf traversal.  If leave is provided,
+// and visit is not, then it's leaf->root.  Both can be provided for a
+// map-reduce operation.
+//
+// If either visit or leave return a Promise for any node, then the
+// walk returns a Promise.
+
+const depthDescent = require('./depth-descent.js')
+const depth = ({
+  visit,
+  leave,
+  filter = () => true,
+  seen = new Map(),
+  getChildren,
+  tree,
+}) => {
+  if (!leave) {
+    return depthDescent({ visit, filter, getChildren, tree })
+  }
+
+  if (seen.has(tree)) {
+    return seen.get(tree)
+  }
+
+  seen.set(tree, null)
+
+  const visitNode = () => {
+    const res = visit ? visit(tree) : tree
+    if (isPromise(res)) {
+      const fullResult = res.then(resThen => {
+        seen.set(tree, resThen)
+        return kidNodes()
+      })
+      seen.set(tree, fullResult)
+      return fullResult
+    } else {
+      seen.set(tree, res)
+      return kidNodes()
+    }
+  }
+
+  const kidNodes = () => {
+    const kids = getChildren(tree, seen.get(tree))
+    return isPromise(kids) ? kids.then(processKids) : processKids(kids)
+  }
+
+  const processKids = nodes => {
+    const kids = (nodes || []).filter(filter).map(kid =>
+      depth({ visit, leave, filter, seen, getChildren, tree: kid }))
+    return kids.some(isPromise)
+      ? Promise.all(kids).then(leaveNode)
+      : leaveNode(kids)
+  }
+
+  const leaveNode = kids => {
+    const res = leave(seen.get(tree), kids)
+    seen.set(tree, res)
+    // if it's a promise at this point, the caller deals with it
+    return res
+  }
+
+  return visitNode()
+}
+
+const isPromise = p => p && typeof p.then === 'function'
+
+module.exports = depth

spa/node_modules/treeverse/lib/index.js

@@ -0,0 +1,4 @@
+module.exports = {
+  breadth: require('./breadth.js'),
+  depth: require('./depth.js'),
+}

spa/node_modules/treeverse/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "treeverse",
+  "version": "3.0.0",
+  "description": "Walk any kind of tree structure depth- or breadth-first. Supports promises and advanced map-reduce operations with a very small API.",
+  "author": "GitHub Inc.",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/npm/treeverse.git"
+  },
+  "scripts": {
+    "test": "tap",
+    "snap": "tap",
+    "lint": "eslint \"**/*.js\"",
+    "postlint": "template-oss-check",
+    "template-oss-apply": "template-oss-apply --force",
+    "lintfix": "npm run lint -- --fix",
+    "posttest": "npm run lint"
+  },
+  "tap": {
+    "100": true,
+    "coverage-map": "test/coverage-map.js",
+    "nyc-arg": [
+      "--exclude",
+      "tap-snapshots/**"
+    ]
+  },
+  "devDependencies": {
+    "@npmcli/eslint-config": "^3.0.1",
+    "@npmcli/template-oss": "4.5.1",
+    "tap": "^16.0.1"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "main": "lib/index.js",
+  "keywords": [
+    "tree",
+    "traversal",
+    "depth first search",
+    "breadth first search"
+  ],
+  "engines": {
+    "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
+  },
+  "templateOSS": {
+    "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.",
+    "version": "4.5.1"
+  }
+}