@parcel/graph 3.2.1-dev.3195 → 3.2.1-dev.3196

package/lib/AdjacencyList.js

@@ -240,7 +240,7 @@ class AdjacencyList {
    *
    * Note that this method does not increment the node count
    * (that only happens in `addEdge`), it _may_ preemptively resize
-   * the nodes array if it is at capacity, under the asumption that
+   * the nodes array if it is at capacity, under the assumption that
    * at least 1 edge to or from this new node will be added.
    *
    * Returns the id of the added node.

package/lib/Graph.js

@@ -7,6 +7,13 @@ exports.default = exports.ALL_EDGE_TYPES = void 0;
 exports.mapVisitor = mapVisitor;
 var _types = require("./types");
 var _AdjacencyList = _interopRequireDefault(require("./AdjacencyList"));
+function _featureFlags() {
+  const data = require("@parcel/feature-flags");
+  _featureFlags = function () {
+    return data;
+  };
+  return data;
+}
 var _BitSet = require("./BitSet");
 function _nullthrows() {
   const data = _interopRequireDefault(require("nullthrows"));
@@ -17,6 +24,15 @@ function _nullthrows() {
 }
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 const ALL_EDGE_TYPES = exports.ALL_EDGE_TYPES = -1;
+
+/**
+ * Internal type used for queue iterative DFS implementation.
+ */
+
+/**
+ * Options for DFS traversal.
+ */
+
 class Graph {
   constructor(opts) {
     this.nodes = (opts === null || opts === void 0 ? void 0 : opts.nodes) || [];
@@ -179,7 +195,11 @@ class Graph {
     if (type === ALL_EDGE_TYPES && enter && (typeof visit === 'function' || !visit.exit)) {
       return this.dfsFast(enter, startNodeId);
     } else {
-      return this.dfs({
+      return (0, _featureFlags().getFeatureFlag)('dfsFasterRefactor') ? this.dfsNew({
+        visit,
+        startNodeId,
+        getChildren: nodeId => this.getNodeIdsConnectedFrom(nodeId, type)
+      }) : this.dfs({
         visit,
         startNodeId,
         getChildren: nodeId => this.getNodeIdsConnectedFrom(nodeId, type)
@@ -301,6 +321,114 @@ class Graph {
     }
     this._visited = visited;
   }
+
+  /**
+   * Iterative implementation of DFS that supports all use-cases.
+   *
+   * This replaces `dfs` and will replace `dfsFast`.
+   */
+  dfsNew({
+    visit,
+    startNodeId,
+    getChildren
+  }) {
+    let traversalStartNode = (0, _nullthrows().default)(startNodeId ?? this.rootNodeId, 'A start node is required to traverse');
+    this._assertHasNodeId(traversalStartNode);
+    let visited;
+    if (!this._visited || this._visited.capacity < this.nodes.length) {
+      this._visited = new _BitSet.BitSet(this.nodes.length);
+      visited = this._visited;
+    } else {
+      visited = this._visited;
+      visited.clear();
+    }
+    // Take shared instance to avoid re-entrancy issues.
+    this._visited = null;
+    let stopped = false;
+    let skipped = false;
+    let actions = {
+      skipChildren() {
+        skipped = true;
+      },
+      stop() {
+        stopped = true;
+      }
+    };
+    const queue = [{
+      nodeId: traversalStartNode,
+      context: null
+    }];
+    const enter = typeof visit === 'function' ? visit : visit.enter;
+    while (queue.length !== 0) {
+      const command = queue.pop();
+      if (command.exit != null) {
+        let {
+          nodeId,
+          context,
+          exit
+        } = command;
+        let newContext = exit(nodeId, command.context, actions);
+        if (typeof newContext !== 'undefined') {
+          // $FlowFixMe[reassign-const]
+          context = newContext;
+        }
+        if (skipped) {
+          continue;
+        }
+        if (stopped) {
+          this._visited = visited;
+          return context;
+        }
+      } else {
+        let {
+          nodeId,
+          context
+        } = command;
+        if (!this.hasNode(nodeId) || visited.has(nodeId)) continue;
+        visited.add(nodeId);
+        skipped = false;
+        if (enter) {
+          let newContext = enter(nodeId, context, actions);
+          if (typeof newContext !== 'undefined') {
+            // $FlowFixMe[reassign-const]
+            context = newContext;
+          }
+        }
+        if (skipped) {
+          continue;
+        }
+        if (stopped) {
+          this._visited = visited;
+          return context;
+        }
+        if (typeof visit !== 'function' && visit.exit) {
+          queue.push({
+            nodeId,
+            exit: visit.exit,
+            context
+          });
+        }
+
+        // TODO turn into generator function
+        const children = getChildren(nodeId);
+        for (let i = children.length - 1; i > -1; i -= 1) {
+          const child = children[i];
+          if (visited.has(child)) {
+            continue;
+          }
+          queue.push({
+            nodeId: child,
+            context
+          });
+        }
+      }
+    }
+    this._visited = visited;
+  }
+
+  /**
+   * @deprecated Will be replaced by `dfsNew`
+   */
   dfs({
     visit,
     startNodeId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcel/graph",
-  "version": "3.2.1-dev.3195+7afdafedd",
+  "version": "3.2.1-dev.3196+c9a0ab031",
   "description": "Blazing fast, zero configuration web application bundler",
   "license": "MIT",
   "publishConfig": {
@@ -20,7 +20,8 @@
     "node": ">= 16.0.0"
   },
   "dependencies": {
+    "@parcel/feature-flags": "2.12.1-dev.3196+c9a0ab031",
     "nullthrows": "^1.1.1"
   },
-  "gitHead": "7afdafedd7f01d82b9868ec004b3966a88006300"
+  "gitHead": "c9a0ab031986a896a5991de16420b12988d013cd"
 }

package/src/AdjacencyList.js

@@ -30,7 +30,7 @@ export type AdjacencyListOptions<TEdgeType> = {|
   minGrowFactor?: number,
   /** The size after which to grow the capacity by the minimum factor. */
   peakCapacity?: number,
-  /** The percentage of deleted edges above which the capcity should shink. */
+  /** The percentage of deleted edges above which the capacity should shrink. */
   unloadFactor?: number,
   /** The amount by which to shrink the capacity. */
   shrinkFactor?: number,
@@ -328,7 +328,7 @@ export default class AdjacencyList<TEdgeType: number = 1> {
    *
    * Note that this method does not increment the node count
    * (that only happens in `addEdge`), it _may_ preemptively resize
-   * the nodes array if it is at capacity, under the asumption that
+   * the nodes array if it is at capacity, under the assumption that
    * at least 1 edge to or from this new node will be added.
    *
    * Returns the id of the added node.

package/src/Graph.js

@@ -3,6 +3,7 @@
 import {fromNodeId} from './types';
 import AdjacencyList, {type SerializedAdjacencyList} from './AdjacencyList';
 import type {Edge, NodeId} from './types';
+import {getFeatureFlag} from '@parcel/feature-flags';
 import type {
   TraversalActions,
   GraphVisitor,
@@ -28,6 +29,51 @@ export type SerializedGraph<TNode, TEdgeType: number = 1> = {|
 export type AllEdgeTypes = -1;
 export const ALL_EDGE_TYPES: AllEdgeTypes = -1;
 
+type DFSCommandVisit<TContext> = {|
+  nodeId: NodeId,
+  context: TContext | null,
+|};
+
+type DFSCommandExit<TContext> = {|
+  nodeId: NodeId,
+  exit: GraphTraversalCallback<NodeId, TContext>,
+  context: TContext | null,
+|};
+
+/**
+ * Internal type used for queue iterative DFS implementation.
+ */
+type DFSCommand<TContext> =
+  | DFSCommandVisit<TContext>
+  | DFSCommandExit<TContext>;
+
+/**
+ * Options for DFS traversal.
+ */
+export type DFSParams<TContext> = {|
+  visit: GraphVisitor<NodeId, TContext>,
+  /**
+   * Custom function to get next entries to visit.
+   *
+   * This can be a performance bottleneck as arrays are created on every node visit.
+   *
+   * @deprecated This will be replaced by a static `traversalType` set of orders in the future
+   *
+   * Currently, this is only used in 3 ways:
+   *
+   * - Traversing down the tree (normal DFS)
+   * - Traversing up the tree (ancestors)
+   * - Filtered version of traversal; which does not need to exist at the DFS level as the visitor
+   *   can handle filtering
+   * - Sorted traversal of BundleGraph entries, which does not have a clear use-case, but may
+   *   not be safe to remove
+   *
+   * Only due to the latter we aren't replacing this.
+   */
+  getChildren: (nodeId: NodeId) => Array<NodeId>,
+  startNodeId?: ?NodeId,
+|};
+
 export default class Graph<TNode, TEdgeType: number = 1> {
   nodes: Array<TNode | null>;
   adjacencyList: AdjacencyList<TEdgeType>;
@@ -289,11 +335,17 @@ export default class Graph<TNode, TEdgeType: number = 1> {
     ) {
       return this.dfsFast(enter, startNodeId);
     } else {
-      return this.dfs({
-        visit,
-        startNodeId,
-        getChildren: nodeId => this.getNodeIdsConnectedFrom(nodeId, type),
-      });
+      return getFeatureFlag('dfsFasterRefactor')
+        ? this.dfsNew({
+            visit,
+            startNodeId,
+            getChildren: nodeId => this.getNodeIdsConnectedFrom(nodeId, type),
+          })
+        : this.dfs({
+            visit,
+            startNodeId,
+            getChildren: nodeId => this.getNodeIdsConnectedFrom(nodeId, type),
+          });
     }
   }
 
@@ -449,15 +501,122 @@ export default class Graph<TNode, TEdgeType: number = 1> {
     return;
   }
 
+  /**
+   * Iterative implementation of DFS that supports all use-cases.
+   *
+   * This replaces `dfs` and will replace `dfsFast`.
+   */
+  dfsNew<TContext>({
+    visit,
+    startNodeId,
+    getChildren,
+  }: DFSParams<TContext>): ?TContext {
+    let traversalStartNode = nullthrows(
+      startNodeId ?? this.rootNodeId,
+      'A start node is required to traverse',
+    );
+    this._assertHasNodeId(traversalStartNode);
+
+    let visited;
+    if (!this._visited || this._visited.capacity < this.nodes.length) {
+      this._visited = new BitSet(this.nodes.length);
+      visited = this._visited;
+    } else {
+      visited = this._visited;
+      visited.clear();
+    }
+    // Take shared instance to avoid re-entrancy issues.
+    this._visited = null;
+
+    let stopped = false;
+    let skipped = false;
+    let actions: TraversalActions = {
+      skipChildren() {
+        skipped = true;
+      },
+      stop() {
+        stopped = true;
+      },
+    };
+
+    const queue: DFSCommand<TContext>[] = [
+      {nodeId: traversalStartNode, context: null},
+    ];
+    const enter = typeof visit === 'function' ? visit : visit.enter;
+    while (queue.length !== 0) {
+      const command = queue.pop();
+
+      if (command.exit != null) {
+        let {nodeId, context, exit} = command;
+        let newContext = exit(nodeId, command.context, actions);
+        if (typeof newContext !== 'undefined') {
+          // $FlowFixMe[reassign-const]
+          context = newContext;
+        }
+
+        if (skipped) {
+          continue;
+        }
+
+        if (stopped) {
+          this._visited = visited;
+          return context;
+        }
+      } else {
+        let {nodeId, context} = command;
+        if (!this.hasNode(nodeId) || visited.has(nodeId)) continue;
+        visited.add(nodeId);
+
+        skipped = false;
+        if (enter) {
+          let newContext = enter(nodeId, context, actions);
+          if (typeof newContext !== 'undefined') {
+            // $FlowFixMe[reassign-const]
+            context = newContext;
+          }
+        }
+
+        if (skipped) {
+          continue;
+        }
+
+        if (stopped) {
+          this._visited = visited;
+          return context;
+        }
+
+        if (typeof visit !== 'function' && visit.exit) {
+          queue.push({
+            nodeId,
+            exit: visit.exit,
+            context,
+          });
+        }
+
+        // TODO turn into generator function
+        const children = getChildren(nodeId);
+        for (let i = children.length - 1; i > -1; i -= 1) {
+          const child = children[i];
+          if (visited.has(child)) {
+            continue;
+          }
+
+          queue.push({nodeId: child, context});
+        }
+      }
+    }
+
+    this._visited = visited;
+  }
+
+  /**
+   * @deprecated Will be replaced by `dfsNew`
+   */
   dfs<TContext>({
     visit,
     startNodeId,
     getChildren,
-  }: {|
-    visit: GraphVisitor<NodeId, TContext>,
-    getChildren(nodeId: NodeId): Array<NodeId>,
-    startNodeId?: ?NodeId,
-  |}): ?TContext {
+  }: DFSParams<TContext>): ?TContext {
     let traversalStartNode = nullthrows(
       startNodeId ?? this.rootNodeId,
       'A start node is required to traverse',

package/test/Graph.test.js

@@ -2,9 +2,10 @@
 
 import assert from 'assert';
 import sinon from 'sinon';
+import type {TraversalActions} from '@parcel/types-internal';
 
-import Graph from '../src/Graph';
-import {toNodeId} from '../src/types';
+import Graph, {type DFSParams} from '../src/Graph';
+import {toNodeId, type NodeId} from '../src/types';
 
 describe('Graph', () => {
   it('constructor should initialize an empty graph', () => {
@@ -340,4 +341,229 @@ describe('Graph', () => {
     assert.deepEqual(graph.nodes.filter(Boolean), ['root']);
     assert.deepStrictEqual(Array.from(graph.getAllEdges()), []);
   });
+
+  describe('dfs(...)', () => {
+    function testSuite(
+      name: string,
+      dfsImpl: (graph: Graph<string>, DFSParams<mixed>) => mixed | null | void,
+    ) {
+      it(`${name} throws if the graph is empty`, () => {
+        const graph = new Graph();
+        const visit = sinon.stub();
+        const getChildren = sinon.stub();
+        assert.throws(() => {
+          dfsImpl(graph, {
+            visit,
+            startNodeId: 0,
+            getChildren,
+          });
+        }, /Does not have node 0/);
+      });
+
+      it(`${name} visits a single node`, () => {
+        const graph = new Graph();
+        graph.addNode('root');
+        const visit = sinon.stub();
+        const getChildren = () => [];
+        dfsImpl(graph, {
+          visit,
+          startNodeId: 0,
+          getChildren,
+        });
+
+        assert(visit.calledOnce);
+      });
+
+      it(`${name} visits all connected nodes in DFS order`, () => {
+        const graph = new Graph();
+        graph.addNode('0');
+        graph.addNode('1');
+        graph.addNode('2');
+        graph.addNode('3');
+        graph.addNode('disconnected-1');
+        graph.addNode('disconnected-2');
+        graph.addEdge(0, 1);
+        graph.addEdge(0, 2);
+        graph.addEdge(1, 3);
+        graph.addEdge(2, 3);
+
+        const order = [];
+        const visit = (node: NodeId) => {
+          order.push(node);
+        };
+        const getChildren = (node: NodeId) =>
+          graph.getNodeIdsConnectedFrom(node);
+        dfsImpl(graph, {
+          visit,
+          startNodeId: 0,
+          getChildren,
+        });
+
+        assert.deepEqual(order, [0, 1, 3, 2]);
+      });
+
+      describe(`${name} actions tests`, () => {
+        it(`${name} skips children if skip is called on a node`, () => {
+          const graph = new Graph();
+          graph.addNode('0');
+          graph.addNode('1');
+          graph.addNode('2');
+          graph.addNode('3');
+          graph.addNode('disconnected-1');
+          graph.addNode('disconnected-2');
+          graph.addEdge(0, 1);
+          graph.addEdge(1, 2);
+          graph.addEdge(0, 3);
+
+          const order = [];
+          const visit = (
+            node: NodeId,
+            context: mixed | null,
+            actions: TraversalActions,
+          ) => {
+            if (node === 1) actions.skipChildren();
+            order.push(node);
+          };
+          const getChildren = (node: NodeId) =>
+            graph.getNodeIdsConnectedFrom(node);
+          dfsImpl(graph, {
+            visit,
+            startNodeId: 0,
+            getChildren,
+          });
+
+          assert.deepEqual(order, [0, 1, 3]);
+        });
+
+        it(`${name} stops the traversal if stop is called`, () => {
+          const graph = new Graph();
+          graph.addNode('0');
+          graph.addNode('1');
+          graph.addNode('2');
+          graph.addNode('3');
+          graph.addNode('disconnected-1');
+          graph.addNode('disconnected-2');
+          graph.addEdge(0, 1);
+          graph.addEdge(1, 2);
+          graph.addEdge(1, 3);
+          graph.addEdge(0, 2);
+          graph.addEdge(2, 3);
+
+          const order = [];
+          const visit = (
+            node: NodeId,
+            context: mixed | null,
+            actions: TraversalActions,
+          ) => {
+            order.push(node);
+            if (node === 1) {
+              actions.stop();
+              return 'result';
+            }
+            return 'other';
+          };
+          const getChildren = (node: NodeId) =>
+            graph.getNodeIdsConnectedFrom(node);
+          const result = dfsImpl(graph, {
+            visit,
+            startNodeId: 0,
+            getChildren,
+          });
+
+          assert.deepEqual(order, [0, 1]);
+          assert.equal(result, 'result');
+        });
+      });
+
+      describe(`${name} context tests`, () => {
+        it(`${name} passes the context between visitors`, () => {
+          const graph = new Graph();
+          graph.addNode('0');
+          graph.addNode('1');
+          graph.addNode('2');
+          graph.addNode('3');
+          graph.addNode('disconnected-1');
+          graph.addNode('disconnected-2');
+          graph.addEdge(0, 1);
+          graph.addEdge(1, 2);
+          graph.addEdge(1, 3);
+          graph.addEdge(0, 2);
+          graph.addEdge(2, 3);
+
+          const contexts = [];
+          const visit = (node: NodeId, context: mixed | null) => {
+            contexts.push([node, context]);
+            return `node-${node}-created-context`;
+          };
+          const getChildren = (node: NodeId) =>
+            graph.getNodeIdsConnectedFrom(node);
+          const result = dfsImpl(graph, {
+            visit,
+            startNodeId: 0,
+            getChildren,
+          });
+
+          assert.deepEqual(contexts, [
+            [0, undefined],
+            [1, 'node-0-created-context'],
+            [2, 'node-1-created-context'],
+            [3, 'node-2-created-context'],
+          ]);
+          assert.equal(result, undefined);
+        });
+      });
+
+      describe(`${name} exit visitor tests`, () => {
+        it(`${name} calls the exit visitor`, () => {
+          const graph = new Graph();
+          graph.addNode('0');
+          graph.addNode('1');
+          graph.addNode('2');
+          graph.addNode('3');
+          graph.addNode('disconnected-1');
+          graph.addNode('disconnected-2');
+          graph.addEdge(0, 1);
+          graph.addEdge(1, 2);
+          graph.addEdge(1, 3);
+          graph.addEdge(0, 2);
+
+          const contexts = [];
+          const visit = (node: NodeId, context: mixed | null) => {
+            contexts.push([node, context]);
+            return `node-${node}-created-context`;
+          };
+          const visitExit = (node: NodeId, context: mixed | null) => {
+            contexts.push(['exit', node, context]);
+            return `node-exit-${node}-created-context`;
+          };
+          const getChildren = (node: NodeId) =>
+            graph.getNodeIdsConnectedFrom(node);
+          const result = dfsImpl(graph, {
+            visit: {
+              enter: visit,
+              exit: visitExit,
+            },
+            startNodeId: 0,
+            getChildren,
+          });
+
+          assert.deepEqual(contexts, [
+            [0, undefined],
+            [1, 'node-0-created-context'],
+            [2, 'node-1-created-context'],
+            ['exit', 2, 'node-2-created-context'],
+            [3, 'node-1-created-context'],
+            ['exit', 3, 'node-3-created-context'],
+            ['exit', 1, 'node-1-created-context'],
+            ['exit', 0, 'node-0-created-context'],
+          ]);
+          assert.equal(result, undefined);
+        });
+      });
+    }
+
+    testSuite('dfs', (graph, params) => graph.dfs(params));
+
+    testSuite('dfsNew', (graph, params) => graph.dfsNew(params));
+  });
 });