tessl/npm-walkdir
Directory traversal library that walks file system trees with multiple interface options including callback, event emitter, synchronous, and promise-based patterns.
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-walkdir@0.4.0index.mddocs/
Walkdir
Walkdir is a Node.js library that provides comprehensive directory traversal capabilities with multiple interface options. It walks directory trees of any depth and emits events based on what it finds, offering callback, event emitter, synchronous, and promise-based patterns for maximum flexibility across different use cases.
Package Information
- Package Name: walkdir
- Package Type: npm
- Language: JavaScript
- Installation:
npm install walkdir
Core Imports
const walkdir = require('walkdir');Basic Usage
const walkdir = require('walkdir');
// Async with callback
walkdir('./my-directory', function(path, stat) {
console.log('Found:', path);
});
// Sync usage
const paths = walkdir.sync('./my-directory');
console.log('All paths:', paths);
// Promise-based
const result = await walkdir.async('./my-directory', {return_object: true});
// result is {[path]: stat} object
// Event emitter pattern
const emitter = walkdir('./my-directory');
emitter.on('file', (path, stat) => {
console.log('File found:', path);
});
emitter.on('directory', (path, stat) => {
console.log('Directory found:', path);
});
emitter.on('end', () => {
console.log('Walk completed');
});Architecture
Walkdir provides multiple interfaces for the same core functionality:
- Callback Pattern: Traditional Node.js callback interface for path iteration
- Event Emitter: EventEmitter-based interface for fine-grained control and event handling
- Synchronous: Blocking operations that return results immediately
- Promise-based: Modern async/await compatible interface
- Flexible Returns: Choose between path arrays or {path: stat} objects
- Stream Control: Pause, resume, and early termination capabilities
The library handles symlinks, implements inode tracking to prevent loops, supports custom filtering, and provides comprehensive error handling for robust file system traversal.
Capabilities
Core Walking Interface
Main directory traversal function with multiple calling patterns and return types based on options.
/**
* Walk a directory tree, emitting events or returning results based on options
* @param {string} path - Directory path to walk
* @param {WalkOptions|WalkEventListener} [options] - Walk options or event listener
* @param {WalkEventListener} [eventListener] - Optional event listener
* @returns {WalkEmitter|string[]|Object<string,fs.Stats>} - Emitter, array, or object based on sync/return_object options
*/
function walkdir(path, options, eventListener);Synchronous Operations
Blocking directory traversal that returns all results immediately.
/**
* Synchronously walk directory tree and return all paths
* @param {string} path - Directory path to walk
* @param {WalkOptions} [options] - Walk options
* @param {WalkEventListener} [eventListener] - Optional event listener
* @returns {string[]|Object<string,fs.Stats>} - Array of paths or object based on return_object option
*/
function walkdir.sync(path, options, eventListener);Promise-based Operations
Modern async/await compatible interface returning promises.
/**
* Walk directory tree and return promise of results
* @param {string} path - Directory path to walk
* @param {WalkOptions} [options] - Walk options
* @param {WalkEventListener} [eventListener] - Optional event listener
* @returns {Promise<string[]|Object<string,fs.Stats>>} - Promise resolving to paths array or object
*/
function walkdir.async(path, options, eventListener);Event System & Control
Event emitter interface with comprehensive file system events and flow control methods.
interface WalkEmitter extends EventEmitter {
/** Stop the walk immediately */
end(): void;
/** Pause event emission */
pause(): void;
/** Resume event emission */
resume(): void;
/** Ignore specific paths during traversal */
ignore(paths: string | string[]): void;
}Configuration Options
Comprehensive options for controlling traversal behavior, performance, and output format.
interface WalkOptions {
/** Follow symbolic links (default: false) */
follow_symlinks?: boolean;
/** Only traverse one level deep */
no_recurse?: boolean;
/** Maximum traversal depth */
max_depth?: number;
/** Track inodes to prevent loops (default: true) */
track_inodes?: boolean;
/** Return {path: stat} object instead of path array */
return_object?: boolean;
/** Don't build internal result collection (memory optimization) */
no_return?: boolean;
/** Filter function for file/directory names */
filter?: (directory: string, files: string[]) => string[] | Promise<string[]>;
/** Custom fs implementation (e.g., graceful-fs) */
fs?: any;
/** Use lstat vs stat for link detection (default: true) */
find_links?: boolean;
}Types
/**
* Event listener function called for each path found
* Bound to WalkEmitter context (this) providing access to control methods:
* - this.ignore(paths) - Skip specified paths
* - this.pause() - Pause traversal
* - this.resume() - Resume traversal
* - this.end() - Stop traversal
* - this.stop() - Stop traversal (alias for end)
* @param {string} path - Found file system path
* @param {fs.Stats} stat - File system stats object
* @param {number} depth - Current depth in directory tree
*/
type WalkEventListener = (this: WalkEmitter, path: string, stat: fs.Stats, depth: number) => void;
/**
* Walk emitter events - all include (path, stat, depth) parameters:
* - 'path': Any file system object found
* - 'file': Regular file found
* - 'directory': Directory found
* - 'link': Symbolic link found
* - 'socket': Socket found
* - 'fifo': FIFO/named pipe found
* - 'blockdevice': Block device found
* - 'characterdevice': Character device found
* - 'targetdirectory': Initial target directory (if directory)
* - 'empty': Empty directory found
* - 'end': Walk completed
* - 'error': Fatal error on target path
* - 'fail': Non-fatal error on nested path
* - 'maxdepth': Maximum depth reached
*/