README

wrap-as-async

Utility method to

wrap a function which returns a Promise into a normal asynchronous function.
wrap a function into an asynchronous method using the common this.async() style, with browser compatibility.

Install

$ npm install wrap-as-async --save

Synopsis

var wrap = require('wrap-as-async');

// Wrap a synchronous function into an asynchronous one.
// Or wrap a function that using the `this.async()` style
//   into a normal asynchronous function.
// `wrapped` is an asynchronous function.
var wrapped = wrap(fn);

// The return value of function `wrapped` indicates
//   whether the original function is asynchronous,
//   which might be useful.
var is_async = wrapped(args, function(err, result){
  // The callback of either sync or async function
  //   will always has the `err` as the first argument.
});

Wrap a sync method into async

var wrapped = wrap(function (n){
  return n + 1;
});

var is_async = wrapped(1, function(err, result){
  console.log(err); // null
  console.log(result); // 2
});

is_async; // false

Wrap an async function using `this.async()`

var wrapped = wrap(function(n){
  var done = this.async();
  setTimeout(function(){
    if (n < 0) {
      return done(new Error('n should not less than 0'));
    }
    done(null, n + 1);
  }, 10)
});

var is_async = wrapped(1, function(err, result){
  console.log(err); // null
  console.log(result); // 2
});

is_async; // true

wrapped(-1, function(err){
  console.log(err); // Error
});

Handles `this` object

wrap-as-async handles this object, so the wrap()ped function could be assigned onto function prototypes, instances or singletons, acting like a decorator(such as python decorators), which will be really helpful.

function myClass (decorate) {
  this.decorate = wrap(decorate);
}

myClass.prototype.method = wrap(method);

And also could assign this object by using call:

wrap(function(n){
  return n + this.base

}).call({
  base: 2
}, 1, function(err, result){
  // result -> 3
});


wrap(function(n){
  // You could still use `this.async()` even with `call`
  var done = this.async();
  var base = this.base;
  setTimeout(function(){
    done(null, n + base)
  }, 10)

}).call({
  base: 2
}, 1, function(err, result){
  // result -> 3
});

Multiple arguments and `done` result

wrap(function(n, m){
  var done = this.async();
  done(null, n + 1, m + 1);

})(1, 2, function(err, result1, result2){
  // result1 -> 2
  // result2 -> 3
});

Synchronous and asynchronous Methods

function sync_method (arg...){
  return something
}

If the method to be wrapped returns an instance of Error, it will be treated as a failure instead, or the returnValue will be the result.

function async_method (arg...) {
  var done = this.async();
  someAsyncProcess(function(...){
    ...
    done(err, result);
  });
}

You could use this.async() to turn the method into an asynchonous method, and this.async will return the callback function.

`Promise` support

wrap(function(n){
  return Promise.resolve(n + 1)
})(1, (err, result) => {
  // result -> 2
})

License

MIT

Usage no npm install needed!