Node.js File System Directory Walker

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use `import walk from 'walk';` or `import { walk } from 'walk';` in a Node.js environment configured for CommonJS, or in an ESM file without proper CJS interop.
  fix If in CommonJS, use `const walk = require('walk');`. If in ESM, consider using `@root/walk` or explicitly configuring Node.js to handle CommonJS imports within an ESM context (e.g., using a `.cjs` file extension or `package.json` `exports` field).

• TypeError: walker.on is not a function

  cause This error occurs when attempting to attach event listeners (`.on()`) directly to the result of `walk.walkSync()`. The synchronous walker's primary event mechanism is through `options.listeners`, not the `EventEmitter` interface returned by `walk.walkSync` (which doesn't return an EventEmitter).
  fix For `walkSync`, pass event handlers via the `options.listeners` object instead of calling `.on()` on the returned value. Example: `walk.walkSync(path, { listeners: { file: (r, s, n) => { /*...*/ n(); } } });`

Warnings

• deprecated The package author explicitly recommends migrating to `@root/walk` for new projects due to its simpler, faster, and more modern design. While `walk` remains functional, it is considered superseded.
  Fix: For new projects or refactoring, install and use `@root/walk` instead: `npm install @root/walk`.
• gotcha This package was developed for CommonJS environments (`require`). Attempting to use `import` statements directly in an ESM module without specific Node.js loader configuration for CJS interop will result in errors.
  Fix: Use `const walk = require('walk');` in CommonJS modules. For ESM projects, consider using `@root/walk` or configuring `package.json` with `"type": "commonjs"` or explicit `.cjs` file extensions.
• gotcha The `walkSync` function, despite using synchronous `fs` methods, still uses `EventEmitter` internally which relies on `process.nextTick()`. For truly synchronous, blocking behavior where control flow should not yield, `options.listeners` must be used instead of `.on()` event handlers.
  Fix: When using `walkSync`, provide event handlers via the `options.listeners` object: `walk.walkSync(path, { listeners: { file: (r, s, n) => { /*...*/ n(); } } });`
• gotcha For asynchronous `walk` operations, it is crucial to call `next()` in every `file`, `directory`, and `errors` event handler. Failing to call `next()` will halt the directory traversal indefinitely, as it acts as a flow control mechanism.
  Fix: Ensure `next()` is called at the end of all `walker.on('event', function(root, stats, next) { ... next(); });` callbacks.

Install

• npm install walk npm
• yarn add walk yarn
• pnpm add walk pnpm

Imports

• walk (module object)
  wrong:

  import walkModule from 'walk';

  correct:

  const walkModule = require('walk');

  This package is primarily designed for CommonJS. For ESM, consider using `@root/walk` or configuring Node.js for CJS-ESM interop.
• walk (asynchronous function)
  wrong:

  import { walk } from 'walk';

  correct:

  const { walk } = require('walk');

  The `walk` function is a method on the module's default export. Direct ESM `import` statements will typically fail in modern Node.js environments without specific CJS interop configuration.
• walkSync (synchronous function)
  wrong:

  import { walkSync } from 'walk';

  correct:

  const { walkSync } = require('walk');

  The `walkSync` function is also a method on the module's default export. It uses synchronous `fs` methods but its `EventEmitter` behavior relies on `process.nextTick()`, meaning truly blocking behavior requires `options.listeners`.

Quickstart

Demonstrates asynchronous directory traversal, creating a temporary file structure, collecting file and directory paths via EventEmitter callbacks, and cleaning up afterwards.

const walk = require('walk');
const fs = require('fs');
const path = require('path');

const testDir = path.join(__dirname, 'temp_walk_dir');
const subDir = path.join(testDir, 'sub_dir');
const file1 = path.join(testDir, 'file1.txt');
const file2 = path.join(subDir, 'file2.txt');

// Setup: Create a temporary directory structure
fs.mkdirSync(testDir, { recursive: true });
fs.mkdirSync(subDir, { recursive: true });
fs.writeFileSync(file1, 'content for file1');
fs.writeFileSync(file2, 'content for file2');

console.log(`Starting walk in: ${testDir}`);

let filesFound = [];
let directoriesFound = [];
let errorsEncountered = [];

const options = {};
const walker = walk.walk(testDir, options);

walker.on('file', function (root, fileStats, next) {
  filesFound.push(path.join(root, fileStats.name));
  // console.log(`Found file: ${path.join(root, fileStats.name)}`);
  next(); // Crucial to call next() to continue the walk
});

walker.on('directory', function (root, dirStats, next) {
  directoriesFound.push(path.join(root, dirStats.name));
  // console.log(`Found directory: ${path.join(root, dirStats.name)}`);
  next(); // Crucial to call next() to continue the walk
});

walker.on('errors', function (root, nodeStatsArray, next) {
  nodeStatsArray.forEach(nodeStats => {
    errorsEncountered.push({ path: path.join(root, nodeStats.name), error: nodeStats.error ? nodeStats.error.message : 'Unknown error' });
  });
  console.error(`Errors encountered in ${root}:`, errorsEncountered);
  next(); // Crucial to call next() to continue the walk
});

walker.on('end', function () {
  console.log('\n--- Walk Complete ---');
  console.log('Files found:', filesFound.sort());
  console.log('Directories found:', directoriesFound.sort());
  if (errorsEncountered.length > 0) {
    console.error('Final errors summary:', errorsEncountered);
  }

  // Cleanup: Remove the temporary directory
  fs.rmSync(testDir, { recursive: true, force: true });
  console.log('\nTemporary directory cleaned up.');
});