tessl/npm-walkdir

Directory traversal library that walks file system trees with multiple interface options including callback, event emitter, synchronous, and promise-based patterns.

—

Pending

Overview

Eval results

Files

Core Walking Interface

Name: tessl/npm-walkdir
Author: tessl

The main walkdir function provides the foundational directory traversal functionality with multiple calling patterns and return types based on configuration options.

Capabilities

Main Walkdir Function

The primary entry point for directory traversal with flexible return types.

/**
 * 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 function
 * @param {WalkEventListener} [eventListener] - Optional event listener function
 * @returns {WalkEmitter|string[]|Object<string,fs.Stats>} - Return type depends on options
 */
function walkdir(path, options, eventListener);

Return Behavior:

Async mode (default): Returns WalkEmitter for event-based handling
Sync mode (options.sync: true): Returns string[] or {[path]: stat} object
Return object (options.return_object: true): Returns object with path keys and stat values

Usage Examples:

const walkdir = require('walkdir');

// Event emitter (async)
const emitter = walkdir('./directory');
emitter.on('path', (path, stat) => {
  console.log('Found:', path);
});

// With callback
walkdir('./directory', (path, stat) => {
  console.log('Path:', path, 'Type:', stat.isDirectory() ? 'dir' : 'file');
});

// With options and callback
walkdir('./directory', { max_depth: 2 }, (path, stat) => {
  console.log('Found at depth ≤2:', path);
});

// Callback has access to emitter control methods via 'this'
walkdir('./project', function(path, stat) {
  console.log('Processing:', path);
  
  // Skip node_modules directories using this.ignore()
  if (path.endsWith('node_modules')) {
    this.ignore(path); // 'this' refers to the WalkEmitter
  }
  
  // Can also use this.pause(), this.resume(), this.end(), this.stop()
  if (someCondition) {
    this.end(); // Stop the walk from within the callback
  }
});

// Sync mode - returns array
const paths = walkdir('./directory', { sync: true });
console.log('All paths:', paths);

// Sync mode - returns object
const stats = walkdir('./directory', { sync: true, return_object: true });
for (const [path, stat] of Object.entries(stats)) {
  console.log(path, stat.size);
}

Function Aliases

The main walkdir function is available under multiple names for convenience.

/**
 * All three are identical - just different names for the same function
 */
walkdir.find === walkdir.walk === walkdir; // true

// These all work exactly the same:
walkdir('./directory', options, callback);
walkdir.find('./directory', options, callback);  
walkdir.walk('./directory', options, callback);

Parameter Flexibility

The main function supports flexible parameter patterns:

// Path only - returns emitter
walkdir('./dir')

// Path + callback - returns emitter, calls callback for each path
walkdir('./dir', (path, stat) => {})

// Path + options - returns emitter or sync result based on options.sync
walkdir('./dir', { max_depth: 3 })

// Path + options + callback - full parameter set
walkdir('./dir', { max_depth: 3 }, (path, stat) => {})

The function automatically detects whether the second parameter is an options object or callback function based on its type.

Error Handling

The core function handles errors differently based on mode:

Async mode: Emits error events for target path issues, fail events for nested path issues
Sync mode: Throws exceptions for target path issues, silently skips problematic nested paths
Promise mode: Rejects promise for target path issues, includes failed paths in error details

Install with Tessl CLI