README

double-done

Preface
ABSTRACT
API definition

Preface

I always liked JavaScript, but when I deeply understood its power, I felt in love with it!

One of the greatest aspect of JavaScript is that it helps saving the most expensive resource of the whole software life cycle: developers time.

ABSTRACT

Single Done desing pattern

From now on: SD

In my experience often happens that I have to write an async function which has to call some other async functions to achieve its ojective. Many of the functions I wrote look like:

function myAsyncFunctionSD(param1, done) {
  otherAsyncFunction1(function(err, param2) {
    if(err)
      return done(err);

    otherAsyncFunction2(param1, param2, function(err, param3) {
      if(err)
        return done(err);

      otherAsyncFunction3(param1, param3, function(err, param4) {
        if(err)
          return done(err);

        done(null, param2, param4);
      });
    });
  });
}

What I think is that the continuously repeated block

  if(err)
    return done(err);

is just a time waster, both when writing and reading the code.

Hard Double Done desing pattern

From now on: HDD

An environment where async functions accept two done functions, one called in case of error and one called in case of success could help saving that time. My same async function would look like:

function myAsyncFunctionHDD(param1, doneErr, doneOk) {
  otherAsyncFunction1HDD(doneErr, function(param2) {
    otherAsyncFunction2HDD(param1, param2, doneErr, function(param3) {
      otherAsyncFunction3HDD(param1, param3, doneErr, function(param4) {
        doneOk(param2, param4);
      });
    });
  });
}

Soft Double Done desing pattern

or simply: Double Done design pattern

From now on: SDD or simply: DD

I immediately realized that changing myAsyncFunctionSD in myAsyncFunctionHDD would be a breaking change. Beside this I had to consider that calling an HDD async function is not always more comfortable than calling a SD async function (i.e.: when we have to do something both in cases of error or success).

For these two reasons I decided to write this package which may helps writing DD async functions.

A DD async funciotn should be documented as follows:

 # myAsyncFunctionDD(param1, done[, doneOk])

in case of error, done will be called with the error as first parameter; in case of success, if the caller have not passed a doneOk function, (as in SD design pattern) done function will be called with null as first parameter followed by other parameters (which are the myAsyncFunctionDD result), otherwise doneOk function will be called passing to it only the parameters which are the myAsyncFunctionDD result.

Back to: top - Table of contents

Installation

With npm:

npm install double-done

API definition

require('double-done');

Returns the double-done utility function.

dd(done, doneOk)

Returns the doneOk function which must be called in case of success regardless if the caller passed it or not.

var dd = require('double-done');

function myAsyncFunctionDD(param1, done, doneOk) {
  doneOk = dd(done, doneOk);

From now on done and doneOk are the functions to be called respectively in case of error or success.

doneOk.dd(callbackOk)

This function lets us call an SD async function writing only the callbackOk function, if the called async function gets an error, doneOk.dd makes it calling the original done function.

function myAsyncFunctionDD(param1, done, doneOk) {
  doneOk = dd(done, doneOk);

  otherAsyncFunction1SD(doneOk.dd(function(param2) {
    // if otherAsyncFunction1SD gets an error, done will be called
    // otherwise this function is executed 
  }));

doneOk.try(throwing, callbackOk)

This utility function helps to write more compact code in another common case: when we need to call a function which may throw an exception, in an async function. Following two code snippets have exactly the same effect.

function myAsyncFunction(param1, done, doneOk) {
  doneOk = dd(done, doneOk);

  var ret;

  try { ret = throwingFunction(param1); }
  catch(e) { return process.nextTick(done.bind(null, e)); }

  doneOk(somethingElse(ret));
}

function myAsyncFunction(param1, done, doneOk) {
  doneOk = dd(done, doneOk);

  doneOk.try(throwingFunction.bind(null, param1), function(ret) {
    doneOk(somethingElse(ret));
  });
}

Back to: top - Table of contents

Compatibility

The package it tested under several Node.js versions.

Required: Node.js 0.10

Licence

MIT Licence

Bugs

Do not hesitate to report any bug or consideration @github.

ChangeLog

2017-02-01 - v0.1.1
- Enabled node.js v0.10
2017-01-19 - v0.1.0
- Fixed documentation
2017-01-18 - v0.0.5
- Added doneOk.try
2017-01-17 - v0.0.4
- Dependencies update
2017-01-09 - v0.0.3
- README review and optimization
2017-01-05 - v0.0.2
- Cosmetics
2017-01-05 - v0.0.1
- First release
2016-12-30 - v0.0.0
- First idea

Usage no npm install needed!