DirTraversalNoRecursion

Claim: "You cannot traverse directories without recursion" — Not true. This project provides a non-recursive traversal using an explicit work queue with a pool of async agents, plus a standard recursive baseline. Tests validate correctness on randomized directory trees, and a benchmark compares performance.

Requirements

• Node.js >= 16

Install

npm install

API

• Non-recursive: walkDirs(root, { concurrency, maxDepth, followSymlinks, filter, onFile })
• Recursive baseline: walkDirsRecursive(root, { maxDepth, followSymlinks, filter, onFile })

Both call onFile(fullPath, depth) for each file. Use filter(fullPath, dirent) to include/exclude entries.

Run tests

Tests build a randomized tree (up to 10 layers, up to 100 directories per layer, a few files per directory), traverse it, assert parity, and tear down.

npm test

Benchmark

Generate a random tree, traverse with both implementations, and write a JSON report under reports/.

npm run bench

Bulk report (5 runs per scenario)

Runs 5 iterations across scenarios of target directory counts: 10, 100, 1k, 10k, 100k, 1m (the largest are skipped unless you pass --allow-huge). Produces both JSON and a self-contained HTML with charts (Chart.js) in reports/.

npm run report              # default (skips huge scenarios)
npm run report -- --allow-huge   # include 100k and 1m scenarios

Publish latest report to GitHub Pages

Copies the most recent reports/report-*.html to docs/index.html (and the JSON as docs/report.json). Enable GitHub Pages on the repository with the docs/ folder as the source.

npm run pages

Example report fields:

{
  "root": "/var/folders/.../walk-bench-xyz",
  "nonRecursive": { "ms": 123.45, "files": 4200 },
  "recursive": { "ms": 156.78, "files": 4200 }
}

Why non-recursive traversal works

Recursion is just one way to express tree exploration. The non-recursive version uses an explicit FIFO queue of directories and a pool of async agents that opendir directories, enqueue child directories, and invoke onFile for files. This is equivalent to a breadth-first traversal and avoids call-stack growth while enabling parallelism via controlled concurrency.