readdirp Build Status

NPM

Recursive version of fs.readdir. Exposes a stream api.

var readdirp = require('readdirp')
  , path = require('path')
  , es = require('event-stream');

// print out all JavaScript files along with their size

var stream = readdirp({ root: path.join(__dirname), fileFilter: '*.js' });
stream
  .on('warn', function (err) { 
    console.error('non-fatal error', err); 
    // optionally call stream.destroy() here in order to abort and cause 'close' to be emitted
  })
  .on('error', function (err) { console.error('fatal error', err); })
  .pipe(es.mapSync(function (entry) { 
    return { path: entry.path, size: entry.stat.size };
  }))
  .pipe(es.stringify())
  .pipe(process.stdout);

Meant to be one of the recursive versions of fs functions, e.g., like mkdirp.

Table of Contents generated with DocToc

Installation

npm install readdirp

API

var entryStream = readdirp (options)

Reads given root recursively and returns a stream of entry infos.

entry stream

Behaves as follows:

options

entry info

Has the following properties:

Filters

There are three different ways to specify filters for files and directories respectively.

Directories that do not pass a filter will not be recursed into.

Callback API

Although the stream api is recommended, readdirp also exposes a callback based api.

readdirp (options, callback1 [, callback2])

If callback2 is given, callback1 functions as the fileProcessed callback, and callback2 as the allProcessed callback.

If only callback1 is given, it functions as the allProcessed callback.

allProcessed

fileProcessed

More Examples

on('error', ..), on('warn', ..) and on('end', ..) handling omitted for brevity

var readdirp = require('readdirp');

// Glob file filter
readdirp({ root: './test/bed', fileFilter: '*.js' })
  .on('data', function (entry) {
    // do something with each JavaScript file entry
  });

// Combined glob file filters
readdirp({ root: './test/bed', fileFilter: [ '*.js', '*.json' ] })
  .on('data', function (entry) {
    // do something with each JavaScript and Json file entry 
  });

// Combined negated directory filters
readdirp({ root: './test/bed', directoryFilter: [ '!.git', '!*modules' ] })
  .on('data', function (entry) {
    // do something with each file entry found outside '.git' or any modules directory 
  });

// Function directory filter
readdirp({ root: './test/bed', directoryFilter: function (di) { return di.name.length === 9; } })
  .on('data', function (entry) {
    // do something with each file entry found inside directories whose name has length 9
  });

// Limiting depth
readdirp({ root: './test/bed', depth: 1 })
  .on('data', function (entry) {
    // do something with each file entry found up to 1 subdirectory deep
  });

// callback api
readdirp(
    { root: '.' }
  , function(fileInfo) { 
      // do something with file entry here
    } 
  , function (err, res) {
      // all done, move on or do final step for all file entries here
    }
);

Try more examples by following instructions on how to get going.

stream api

stream-api.js

Demonstrates error and data handling by listening to events emitted from the readdirp stream.

stream api pipe

stream-api-pipe.js

Demonstrates error handling by listening to events emitted from the readdirp stream and how to pipe the data stream into another destination stream.

grep

grep.js

Very naive implementation of grep, for demonstration purposes only.

using callback api

callback-api.js

Shows how to pass callbacks in order to handle errors and/or data.

tests

The readdirp tests also will give you a good idea on how things work.