README

stream-from-factory

Create streams from sync and async factories.

npm install stream-from-factory --save

About Factories

A factory is simply a function creating a product (i.e. a JavaScript value, like numbers, objects, etc.) and sends it back to its caller.

(The term factory refers to the idea of Joshua Blochs static factory methods, not to abstract factories, nor to factory methods.)

Synchronous Factories

Synchronous Factories are functions returning a single product - other than undefined - or throwing an arbitrary JavaScript value:

function syncFactory() {
  if (...) {
    throw new Error('sth. went wrong...'); // typically Errors are thrown
  }
  return null; // that's ok (typeof null !== 'undefined'), but see below (API)
}

Asynchronous Factories

Asynchronous Factories working with callbacks (in node style), but don't return a value;

function asyncFactory(done) {
  if (...) {
    // return an error:
    done(new Error('sth. went wrong...'));
    return; // that's ok (!)
  }
  // return a result:
  done(null, ['a', 'string', 'array']);
}

Usage

Factories creating `String | Buffer`s

var StreamFromFactory = require('stream-from-factory');

function syncFactory() {
  return new Buffer('buff!');
}

function asyncFactory(done) {
  setTimeout(function() {
    done(null, 'strrrring!');
  }, 1000);
}


StreamFromFactory(syncFactory)
  .pipe(process.stdout); // output: buff!

StreamFromFactory(asyncFactory)
  .pipe(process.stdout); // output: strrrring!

Factories creating arbitrary JavaScript values

var StreamFromFactory = require('stream-from-factory');

function logFunc(){
  console.log('func!?!');
};

function asyncFactory(done) {
  setTimeout(function() {
    done(null, logFunc);
  }, 1000);
}

StreamFromFactory.obj(asyncFactory)
  .on('data', function(fn){
    fn(); // output: func!?!
  });

Errors

var StreamFromFactory = require('stream-from-factory');

function syncFactory() {
  throw new Error('sth. went wrong ;-)');
}

function asyncFactory(done) {
  setTimeout(function() {
    done(new Error('sth. went wrong ;-)'));
  }, 1000);
}

StreamFromFactory(syncFactory)
  .on('error', function(err){
    console.log(err); // output: [Error: sth. went wrong ;-)]
  })
  .on('data', function(data){
    // do something awsome
  });

Gulp File Factories

Gulp files are vinyl files:

npm install vinyl

Test some awsome Gulp plugin:

var StreamFromFactory = require('stream-from-factory'),
    File = require('vinyl');

function creatTestFile(){
  return new File({
    cwd: '/',
    base: '/hello/',
    path: '/hello/hello.js',
    contents: new Buffer('console.log("Hello");')
  });
}

StreamFromFactory.obj(creatTestFile)
  .pipe(someAwsomeGulpPlugin())
  .on('data', function(file){
    console.log(file.contents.toString()); // dunno what someAwsomeGulpPlugin does :)
  });

See also stream-recorder for testing gulp plugins.

API

Class: StreamFromFactory

StreamFromFactorys are Readable streams.

new StreamFromFactory(factory, [options])

factory Function Async or sync factory.
options Object passed through new Readable([options])

Notes:

The new operator can be omitted.
null is special for streams (signals end-of-stream). Using a factory returning null will result in an empty stream.

StreamFromFactory#obj(factory, [options])

A convenience wrapper for new StreamFromFactory(factory, {objectMode: true, ...}).

License

Licensed under the MIT license.

Usage no npm install needed!