recur-fs

A collection of recursive filesystem utilities.

Installation

npm install recur-fs

Usage

var fs = require('recur-fs');

// Gather all nested files and directories
fs.readdir('/some/directory', function(err, resources) {
  // Do something with 'resources'
});

API

readdir(directory, visitor(resource, stat, next), fn(err, resources)) Recursively read contents of directory, returning all resources. visitor is an optional function called on each resource. Calling next(false) from visitor will exclude resource from the collection.

fs.readdir('/some/directory', function (err, resources) {
  // Do something with 'resources'
});

fs.readdir('/some/other/directory', function (resource, stat, next) {
  // Return 'false' to skip adding to 'resources'
  next(stat.isFile());
}, function(err, resources) {
  // Do something with 'resources'
});

readdir.sync(directory, visitor(resource, stat)) Synchronously, recursively read contents of directory, returning all resources. visitor is an optional function called on each resource. Returning false from visitor will exclude resource from the collection.

var resources = fs.readdir.sync('/some/directory');

var files = fs.readdir.sync('/some/other/directory', function (resource, stat) {
  // Return 'false' to skip adding to 'resources'
  return stat.isFile();
});

walk(directory, visitor(resource, stat, next), fn(err)) Walk up filesystem tree from directory, passing all resources to visitor, and stopping when root directory is reached. Calling next(true) will abort walking before completion.

fs.walk('/some/directory', function (resource, stat, next) {
  // Return 'true' to stop walking
  next(resource == 'index.js');
}, function (err) {
  // Handle error
});

walk.sync(directory, visitor(resource, stat)) Synchronously walk up filesystem tree from directory, passing all resources to visitor, and stopping when root directory is reached, or visitor returns true.

fs.walk.sync('/some/directory', function (resource, stat) {
  // Do something with resource
});

hunt(directory, matcher(resource, stat, next), stopOnFirstMatch, fn(err, matches)) Walk up filesystem tree from directory, returning all resources matched with matcher, and stopping when root directory is reached, or after first match if stopOnFirstMatch=true.

matcher can be a glob-type string (see minimatch), or function calling next(true) to signal a match. In addition, next also accepts a second argument in order to abort before completion.

fs.hunt('/some/directory', '*.js', false, function (err, matches) {
  // Do something with matching js files
});

fs.hunt('/some/directory', '*.css', true, function (err, match) {
  // Do something with single matching css file
});

fs.hunt('/some/other/directory', function (resource, stat, next) {
  if (resource == 'index.js') {
    // Return second argument to stop walking
    next(true, true);
  } else {
    next(false);
  }
}, false, function (err, matches) {
  // Do something with matches
});

hunt.sync(directory, matcher(resource, stat), stopOnFirstMatch) Synchronously walk up filesystem tree from directory, returning all resources matched with matcher, and stopping when root directory is reached, or after first match if stopOnFirstMatch=true.

matcher can be a glob-type string (see minimatch), or function returning true to signal a match.

var jsFiles = fs.hunt.sync('/some/directory', '*.js', false);

var cssFile = fs.hunt.sync('/some/directory', '*.css', true);

var index = fs.hunt.sync('/some/other/directory', function (resource, stat) {
  return (resource == 'index.js');
}, true);

cp(source, destination, force, fn(err, filepath)) Recursively copy source to destination (cp -r). Copies contents of source directory if path contains a trailing /. force=true will overwrite destination if it already exists.

fs.cp('/some/file', '/some/destination', true, function(err, filepath) {
  // Do something with new 'filepath'
});

// Copy directory contents (note trailing slash)
fs.cp('/some/directory/contents/', '/some/destination', true, function(err, filepath) {
  // Do something with new 'filepath'
});

cp.sync(source, destination, force) Synchronously, recursively copy source to destination (cp -r). Copies contents of source directory if path contains a trailing /. force=true will overwrite destination if it already exists.

var filepath = fs.cp('/some/file', '/some/destination', true);

mkdir(directory, fn(err)) Recursively create nested directory (mkdir -p). If directory looks like a filepath (has .extension), directories will be created at path.dirname(directory).

fs.mkdir('/some/directory', function(err) {
  // Do something
});

mkdir.sync(directory) Synchronously, recursively create nested directory (mkdir -p). If directory looks like a filepath (has .extension), directories will be created at path.dirname(directory).

fs.mkdir.sync('/some/directory');

mv(source, destination, force, fn(err, filepath)) Move source to destination, including all contents of source if directory. force=true will overwrite destination if it already exists.

fs.mv('/some/file', '/some/destination', function(err, filepath) {
  // Do something with new 'filepath'
});

mv.sync(source, destination, force) Synchronously move source to destination, including all contents of source if directory. force=true will overwrite destination if it already exists.

fs.mv.sync('/some/file', '/some/destination');

rm(source, fn(err)) Recursively remove source (rm -rf). Prevents removal of resources outside of process.cwd().

fs.rm('/some/directory/and/children', function(err) {
  // Do something when complete
});

rm.sync(source) Synchronously, recursively remove source (rm -rf). Prevents removal of resources outside of process.cwd().

fs.rm.sync('/some/directory/and/children');

indir(directory, filepath) Check that filepath is likely child of directory. NOTE: only makes string comparison.

fs.indir('/some/directory', '/some/directory/file');