Transfix

callback to event-based flow transformer for javascript

motivation

Transfix is used to convert callbacks into event-based workflow. It may be used as a flattener of asynchronous nodejs-style code, but it actually can work with any type of asynchronous code. It can be used in browser too.

Please note that in case if you can use ES6 generators for your project, you might be also interested in using divert.

Transfix can be used as an alternative to promises approach.

basic usage:

var emitter = new Transfix();
 
emitter.on('start', function() {
   fs.readFile('something.txt', 'utf8', emitter.to('done'));
});
 
emitter.on('done', function(result) {
   console.log(result);
});
 
emitter.on('error', function(e) {
   console.log('Cannot read the file.');
   console.error(e);
});
 
emitter.emit('start');

installation

$ npm install transfix

example

Consider the following phantomjs-node-based code, based on callbacks:

var phantom = require('phantom');
 
phantom.create(function(instance) {
   return instance.createPage(function(page) {
      return page.open('http://www.google.com', function(status) {
         console.log('Status is: ' + status);
         return page.evaluate((function() {
               return document.title;
            }), function(title) {
               console.log('Page title is: ' + title);
               return instance.exit();
            });
      });
  });
});

Compare it with the same code flattened by transfix:

var phantom = require('phantom');
var Transfix = require('transfix');
 
var tx = new Transfix({});
 
tx.on('phantom', function(ctx) {
   ctx.phantom.create(tx.to('instance'));
});
 
tx.on('instance', function(ctx) {
   ctx.instance.createPage(tx.to('page'));
});
 
tx.on('page', function(ctx) {
   ctx.page.open('http://www.google.com', tx.to('status'));
});
 
tx.on('status', function(ctx) {
   console.log('Status is: ' + ctx.status);
   ctx.page.evaluate((function() { return document.title; } ), tx.to('title'));
});
 
tx.on('title', function(ctx) {
   console.log('Page title is: ' + ctx.title);
   return ctx.instance.exit();
});
 
tx.to('phantom')(phantom);

API

require('transfix') returns Transfix constructor. In browser Transfix constructor is available by including sources of lib/transfix.js file.

• new Transfix(context, options) can be used to create transfix implementation of event emitter.
  • context optional parameter which can be used to aggregate results through sequence of events. It can be one of the following types:
    • array: each new value is pushed to the end of the array.
    • object: each new value is added as a property with the same name as emitted event.
    • function: each new value is mapped through the function before propagating to handler.
    • null or undefined: each new value is propagated to all handlers as is.
  • options optional object instance which may contain the following properties:
    • errorEventName name of event, which is triggered in case if Error instance is passed to callback. Default value is "error".
    • errorIsUntouched specify whether errors should be aggregated in context. Default value is true.
    • EventEmitter custom implementation of event emitter. Transfix inherits the object passed to this parameter. By default <div/> element is used in browser as implementation for event emitter and dispatcher. In nodejs, require("events").EventEmitter is used as default.
    • eventEmitterConfig configuration parameter which is passed to EventEmitter constructor. This can be useful for custom non-default emitters. Default value is undefined.

Transfix instance extends EventEmitter and adds one method:

• to(event, map)
  • event obligatory string parameter with name of the event to be emitted in case of success.
  • map optional function to refine result before its aggregation to context.
  • return callback function to be passed as a parameter into asynchronous function invocation.

The callback returned by to invocation may accept arguments in any of the following notations:

• Node-style:
  • Error event is emitted if first parameter of callback is an instance of Error.
  • A value is propagated to appropriate handler in case if first parameter of callback is null and second parameter is some meaningful value.
  • An array of values is propagated to appropriate handler if first parameter of callback is null and more than one parameter is passed after it.
• Raw:
  • A value is propagated to appropriate handler in case if single parameter of callback is not an instance of Error.
  • An array of values is propagated to appropriate handler in case if multiple parameters are passed to callback and first parameter is not an instance of Error.

License

The MIT License (MIT)

Copyright (c) 2015 Volodymyr Frolov

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.