fs-stream

A wrapper and a set of utilities around glob-stream to handle simple files manipulation through streams.

Usage

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

fs('**/*.*')
  .pipe(fs.rename(function (path) {
    return path.replace('/\.txt$/', '.md');
  }))
  .pipe(fs.move('target/dir'))
  .pipe(fs.copy('another/target/dir'))
  .pipe(fs.remove('*.js'))
  .pipe(fs.filter(function (path) {
    return (/\.md$/i).test(path);
  }))
  .pipe(fs.read(function (readStream) {
    readStream.pipe(process.stdout);
  }), {})
  .pipe(fs.watch(function (path) {
    console.log(path, 'has changed.');
  }))
  .pipe(fs.write('\nHi!', 'a'))

API

module(globPattern, [options])

Return a duplex stream of files and directories. For a full documentation of options and glob patterns, take a look at the glob-stream documentation.

For each file, the stream provides a description object with the following properties:

• path : The full path to the file or directory,
• cwd : The path to the current working directory used by the glob pattern,
• stats : An fs.Stats object providing the stats about the file or directory

copy(dir, [options])

Copy all the files in the stream. dir can be:

• String: The path to the directory where to copy all the files
• Function: This function get the actual path to the file and must return the path to the directory where the file must be copied.

NOTE: relative path are resolved against the same base cwd as the one used to set up the stream.

The optional options parameter is an object with the following optional keys:

• override: A boolean indicating if the copy must override an existing file with the same name (default: false)
• add: A boolean or a string indicating if the copied file must be added to the stream. (default: false). If the value is replace the copied file is added to the stream and the original file is removed from the stream.

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

fs('/files/*.md')
  .pipe(fs.copy('/files/markdown'), {add: true});

create(path, [options])

Create a file or directory within each directory in the stream. path can be

• String: The relative path to the file to be created.
• Function: This function get the actual path to the directory and must return the relative path to the file to be created.

NOTE: The relative path of each file is resolved from the related directory from the stream.

The optional options parameter is an object with the following optionnal keys:

• type: Either file or directory (default: file)
• add: A boolean indicating if the created file must be added to the stream. (default: true)

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

fs('/files')
  .pipe(fs.create('markdown', { type: 'directory' }))
  .pipe(fs.create(function (dir) {
    if ((/\/markdown$/).test(dir)) {
      return 'foo.md';
    }
  }));

filter(pattern, keep)

Filter the files in the stream. pattern can be:

• String: A glob pattern that files must match.
• Function: This function get the actual path to the file and must return a boolean.

NOTE: relative patterns are resolved against the same base cwd as the one used to set up the stream.

The optional keep parameter indicate if files matching the pattern must be kept in the stream and the others to be excluded (true), or the other way around (false) (default: true)

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

fs('/files/*.*')
  .pipe(fs.filter('/files/*.md'));

move(dir, [override])

Move all the files in the stream. dir can be:

• String: The path to the directory where to move all the files
• Function: This function get the actual path to the file and must return the path to the directory where the file must be moved.

NOTE: relative path are resolved against the same base cwd as the one used to set up the stream.

The optional override parameter indicate if a file with the same name in the target directory must be overridden (default: true)

If the provided path is something else than a directory, the parent directory will be used. If the directory provided does not exist, it is created automatically.

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

fs('/files/*.md')
  .pipe(fs.move('/files/markdown'));

read(callback, [options])

Help reading each file in the stream.

callback is a function that will get the file content. The nature of the content depend on the options parameter:

• If options is null, callback will get a buffer object.
• If options is a string representing an encoding, callback will get a string.
• If options is a stream configuration object, callback will get a readable stream.

The default value for options is utf8.

NOTE: If the file is actually a directory, the callback function will get an array of all the files in the directory instead of a buffer or a string. See fs.readdir for details.

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

fs('/files/*.*')
  .pipe(fs.read(function (fileContent) {
    console.log(fileContent);
  }));

remove(pattern)

Delete all files that match the pattern. pattern can be:

• String: A glob pattern that files must match to be deleted.
• Function: This function get the actual path to the file and must return true (remove the file) or false (keep the file).

NOTE: relative patterns are resolved against the same base cwd as the one used to set up the stream.

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

fs('/files/*.*')
  .pipe(fs.remove('/files/*.md'));

rename(name, [override])

Change the name of all the files in the stream. name can be:

• String: Rename the first file in the stream or override all of them up to the last.
• Function: This function get the actual path to the file and must return a string which is the new name of the file.

The optional override parameter indicate if a file with the same name must be overridden (default: false). Careful as this can take long on large file system. It's more efficient to remove the unnecessary files as they transit through the stream then renaming the last one. It's also worth noting that the order of the files in the stream is not guaranteed.

var path = require('path');
var fs   = require('fs-stream');

fs('**/*.md')
  .pipe(fs.rename(function (file) {
    var name = path.parse(file.path).base;
    return name.replace(/\.md$/, '.txt');
  }));

watch(listener)

Watch for changes on each files of the stream.

When a change occurs, the listener function is called and get the full path of the changed file. It worth noting that the listener function is called in the context of the FSWatcher object. As the watcher is persistent, calling this.close() is the only way to stop the watcher.

NOTE: Watching files is subject to the restrictions documented with the fs.watch function, however the listener function is guaranteed to get the full path to the changed file.

NOTE: If you need more robust watch solution you should consider using proper robust watcher such as Chokidar or Gaze

var path = require('path');
var fs   = require('fs-stream');

fs('**/*.md')
  .pipe(fs.watch(function (file) {
    var name = path.parse(file.path).base;
    console.log(name, 'as changed!');
  }));

write(data, [mode])

Perform a simple writing action on all files from the stream. data can be:

• String: The content to push inside each files
• Function: This function get the actual path to the file and must return a string which is the content to push into the file.

mode define either how the new content must be pushed into the files:

There are two cases:

• If data is a string and
  • mode value is w then the content of the files will be replaced.
  • mode value is a then the content will be append at the end of each file.

In that case, the default value for mode is w;

• If data is a function and
  • mode value is w then the content of the files will be replaced by what is return out of the function.
  • mode value is a then the the value returned out of the function will be append at the end of each file.
  • mode value is a stream configuration object, the function will get a writable stream.

In that case, the default value for mode is the default writing stream configuration object.

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

fs('**/*.log')
  .pipe(fs.write(function (file) {
    return '\nLast update: ' + Date.now()
  }, 'a'));

fs('**/*.txt')
  .pipe(fs.write(function (stream) {
    stream.end('Hi!')
  }))