Package Exports

fallback-stream

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (fallback-stream) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

fallback-stream

Create a readable stream that swithes to the fallback on error

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

fallbackStream([
  fs.createReadStream('foo.txt'), // foo.txt doesn't exist
  fs.createReadStream('bar.txt'), // bar.txt: 'Hello!'
  fs.createReadStream('baz.txt')  // baz.txt doesn't exist
])
  .pipe(process.stdout); // yields 'Hello!'

Installation

Use npm.

npm install fallback-stream

API

var fallbackStream = require('fallback-stream');

stream = fallbackStream(array, [, options])

array: Array (directly passed to multistream)
options: Object, Function or RegExp
Return: Object (stream.Readable)

It returns a readable stream. When the first stream emits an error, the next one starts, and so on until one of the streams ends successfully. In other words, when the one of the streams ended, the rest won't be used.

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

var firstStream = fs.createReadStream('path/to/file/foo');

var fallback = fs.createReadStream('path/to/file/bar');

// a function that returns a readable stream
var fallbackFn = function() {
  return fs.createReadStream('path/to/file/baz');
};

fallbackStream([
  firstStream,
  fallback,
  fallbackFn
]);

options

The option object will be directly passed to stream.Readable options.

Additionally, fallback-stream accepts errorFilter option.

options.errorFilter

Type: Function or RegExp
Default: function() { return true }

Filter errors that streams emit. If the filtering result is falsy, the created stream emits an error immediately and won't use the rest of streams.

var fallbackStream = require('fallback-stream');
var through = require('through2'); // npm install through2

function createErrorStream(err) {
  var stream = through();
  process.nextTick(function() {
    stream.emit('error', err);
  });
  return stream;
}


createStreams = function() {
  return [
    createErrorStream(new TypeError()),
    createErrorStream(new RangeError()),
    createErrorStream(new SyntaxError())
  ];
}

fallbackStream(createStreams(), {}).on('error', function(err) {
  err.name; //=> 'SyntaxError'
});

fallbackStream(createStreams(), {
  errorFilter: function(err) {
    return err.name === 'RangeError';
  }
}).on('error', function(err) {
  err.name; //=> 'TypeError'
});

fallbackStream(createStreams(), {
  errorFilter: /TypeError/
}).on('error', function(err) {
  err.name; //=> 'RangeError'
});

You can directly pass a Function or RegExp to the second argument to specify the error filter simply, instead of passing an object.

fallbackStream([/* streams */], /ENOENT/);

stream._errors

Type: Array
Default: []

The errors that streams were supposed to emit but didn't.

License

Licensed under the MIT License.