Registry / walk

walk

JSON →
library0.3.5jsnpmunverified

The `walk` package for Node.js provides a comprehensive utility for traversing file system directories, drawing inspiration from Python's `os.walk` function. It primarily operates asynchronously using the EventEmitter pattern, allowing for event-driven processing of files and directories as they are discovered. The library, currently at version 2.3.15, also includes a synchronous counterpart. Key features include built-in flow control and an optimization strategy that minimizes the number of open file descriptors, making it suitable for environments with traditional hard disks. However, it's important to note that the package was initially developed during the Node.js v0.x era and has remained largely unchanged for approximately a decade. Consequently, its API design reflects an older Node.js paradigm. The author now explicitly recommends considering `@root/walk` as a more modern, simpler, and faster alternative for new projects, indicating that `walk` is largely in a maintenance or superseded state rather than active development.

npm install walk
package ↗homepage ↗
INSTALL
IMPORT
SIG · WALK
W
walk
javascriptv0.3.5
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

walk (module object)
✓ const walkModule = require('walk');
✗ import walkModule from '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)
✓ const { walk } = require('walk');
✗ import { walk } from '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)
✓ const { walkSync } = require('walk');
✗ import { walkSync } from '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`.

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.'); });
Debug
Known issues
deprecatedThe 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`.
affects: >=2.0.0
gotchaThis 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.
affects: >=0.0.0
gotchaThe `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(); } } });`
affects: >=0.0.0
gotchaFor 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.
affects: >=0.0.0
Errors
Common errors & fixes
SyntaxError: Cannot use import statement outside a module
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
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(); } } });`
Upgrade
Version history
0.3.5latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources
packagehttps://www.npmjs.com/package/walk ↗
homepagehttps://git.coolaj86.com/coolaj86/fs-walk.js ↗
walk — npm install walk · libregistry