Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Walk a directory tree emitting events based on the contents. API compatable with node-findit. Walk a tree of any depth. Fast! Handles permission errors. Stoppable. windows support. Pull requests are awesome. watchers are appreciated.

branch: master
readme.md

Build Status

walkdir

Find files. Walks a directory tree emitting events based on what it finds. Presents a familliar callback/emitter/sync interface. Walk a tree of any depth. This is a performant option any pull requests to make it more so will be talken into consderation..

Example

var walk = require('walkdir');

//async with path callback 

walk('../',function(path,stat){
  console.log('found: ',path);
});

//use async emitter to capture more events

var emitter = walk('../');

emitter.on('file',function(filename,stat){
  console.log('file from emitter: ', filename);
});


//sync with callback

walk.sync('../',function(path,stat){
  console.log('found sync:',path);
});

//sync just need paths

var paths = walk.sync('../');
console.log('found paths sync: ',paths);

install

npm install walkdir

arguments

walkdir(path, [options], [callback]) walkdir.sync(path, [options], [callback]);

  • path

    • the starting point of your directory walk
  • options. supported options are

    • general

      {
      "follow_symlinks":false, // default is off 
      "no_recurse":false,      // only recurse one level deep
      "max_depth":undefined    // only recurse down to max_depth. if you need more than no_recurse
      }
      
    • sync only

      {
      "return_object":false, // if true the sync return will be in {path:stat} format instead of [path,path,...]
      "no_return":false, // if true null will be returned and no array or object will be created with found paths. useful for large listings
      }
      
  • callback

    • this is bound to the path event of the emitter. its optional in all cases.

      callback(path,stat)
      

events

non error type events are emitted with (path,stat). stat is an instanceof fs.Stats

path

fired for everything

file

fired only for regular files

directory

fired only for directories

link

fired when a symbolic link is found

end

fired when the entire tree has been read and emitted.

socket

fired when a socket descriptor is found

fifo

fired when a fifo is found

characterdevice

fired when a character device is found

blockdevice

fired when a block device is found

targetdirectory

fired for the stat of the path you provided as the first argument. is is only fired if it is a directory.

empty

fired for empty directory

error events

error type events are emitted with (path,error). error being the error object returned from an fs call or other opperation.

error

if the target path cannot be read an error event is emitted. this is the only failure case.

fail

when stat or read fails on a path somewhere in the walk and it is not your target path you get a fail event instead of error. This is handy if you want to find places you dont have access too.

notes

the async emitter returned supports 3 methods

end

stop a walk in progress

pause

pause the walk. no more events will be emitted until resume

resume

resume the walk

cancel a walk in progress

  //cancel a walk in progress within callback.

  var walk = require('walkdir');
  walk('../',function(path,stat){
    this.end();
  });

  //cancel a walk in progress with emitter handle
  var walk = require('walkdir');
  var emitter = walk('../');

  doSomethingAsync(function(){
    emitter.end();
  })

thanks

thanks to substack. the interface for this module is based off of node-findit

Something went wrong with that request. Please try again.