JSDoc: Module: promisen

promisen.js creates promise-returning functions. ready for ES6 Promise.

Copyright:

Yusuke Kawasaki

License:

Source:

See:

Members

(static) Promise :Promise

Native Promise object or Promise polyfill. "es6-promise" polyfill loaded per default in case no native Promise object ready. Some other libraries which have compatible interface with ES6 Promise are also available: Q, bluebird and RSVP are tested.

Type:

Promise

Source:

Example

var promisen = require("promisen");

// https://github.com/jakearchibald/es6-promise (default polyfill)
promisen.Promise = require("es6-promise").Promise;

// https://github.com/kriskowal/q
promisen.Promise = require("q").Promise;

// https://github.com/petkaantonov/bluebird
promisen.Promise = require("bluebird").Promise;

// https://github.com/tildeio/rsvp.js
promisen.Promise = require("rsvp").Promise;

// https://github.com/calvinmetcalf/lie
promisen.Promise = require("lie");

// https://github.com/RubenVerborgh/promiscuous
promisen.Promise = require("promiscuous");

Methods

(static) decr(array) → {function}

creates a promise-returning function which decrements a counter on top of stack.

Parameters:

Name	Type	Description
`array`	Array \| Array-like	counter holder

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var counter = [123];
console.log("count: " + counter); // => count: 123

var decrTask = counter.decr();
decrTask().then(function(value) {...}); // => count: 122

// decrTask is available in a series of tasks.
var task = promisen(otherTask, decrTask);

(static) denodeify(task) → {function}

creates a promise-returning function from a Node.js-style function which requests a callback function at the last argument.

Parameters:

Name	Type	Description
`task`	function	Node.js-style function

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");
var fs = require("fs");

// you should bind target object with the task
var readFile = promisen.denodeify(fs.readFile.bind(fs));

// readFile() is now available as a promise-returning function
readFile("README.md", "utf-8").then(function(value) {...}).catch(function(reason) {...});

(static) each(arrayTask, iteratorTask) → {function}

creates a promise-returning function which runs task repeatedly for each value of array in parallel.

Parameters:

Name	Type	Description
`arrayTask`	Array \| function \| Promise \| thenable	array or task returns array for iteration
`iteratorTask`	function	task runs repeatedly for each of array values

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var task = promisen.each([2, 4, 6], div2);

task.call(target).then(function(array) {...}); // => [1, 2, 3]

function div2(value) {
  return value / 2;
}

(static) eachSeries(arrayTask, iteratorTask) → {function}

creates a promise-returning function which runs task repeatedly for each value of array in order.

Parameters:

Name	Type	Description
`arrayTask`	Array \| function \| Promise \| thenable	array or task returns array for iteration
`iteratorTask`	function	task runs repeatedly for each of array values

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var task = promisen.eachSeries([1, 2, 3], mul2);

task.call(target).then(function(array) {...}); // => [2, 4, 6]

function mul2(value) {
  return value * 2;
}

(static) if(condTaskopt, trueTaskopt, falseTaskopt) → {function}

creates a promise-returning function which runs a task assigned by a conditional task. When null or undefined is given as a task, it will do nothing for value and just passes it.

Parameters:

Name	Type	Attributes	Description
`condTask`	Boolean \| function \| Promise \| thenable \| * \| null	<optional>	boolean or function returns boolean
`trueTask`	function \| Promise \| thenable \| * \| null	<optional>	task runs when true
`falseTask`	function \| Promise \| thenable \| * \| null	<optional>	task runs when false

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

// generate a promise-returning function
var task = promisen.if(condTask, trueTask, falseTask);

// execute itl[pi?K  jk ln lml;/,   m /P/.[h
task().then(function(result) {...});

// execute it with target object which is passed to every tasks
task.call(target).then(function(result) {...});

// all three arguments are optional.
var runWhenTrueTask = promisen.if(null, trueTask);
Promise.resolve(value).then(runWhenTrueTask).then(function(result) {...});

// conditional task are also available in a waterfall of promisen tasks
var joined = promisen(task1, runWhenTrueTask, task2);
joined().then(function(result) {...});

// use uglify --compress (or UPPERCASE property name) for IE8
var task = promisen["if"](condTask, trueTask, falseTask);
var task = promisen.IF(condTask, trueTask, falseTask);

(static) incr(array) → {function}

creates a promise-returning function which increments a counter on top of stack.

Parameters:

Name	Type	Description
`array`	Array \| Array-like	counter holder

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var counter = [123];
console.log("count: " + counter); // => count: 123

var incrTask = counter.incr();
incrTask().then(function(value) {...}); // => count: 124

// incrTask is available in a series of tasks.
var task = promisen(otherTask, incrTask);

(static) log(prefixopt) → {function}

creates a promise-returning function which inspects value to console.log() for debug purpose.

Parameters:

Name	Type	Attributes	Description
`prefix`	String	<optional>

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var task3 = promisen(task1, promisen.log("result:"), task2);

task3().then(function() {...});

(static) memoize(task, expire, hasheropt) → {function}

creates a promise-returning function which caches a result of task. The cache of result is exposed as the memo property of the function returned by memoize.

Parameters:

Name	Type	Attributes	Description
`task`	function		task to wrap
`expire`	Number		millisecond until cache expired
`hasher`	function	<optional>	default: JSON.stringify()

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");
var request = require("request");

var ajaxGet = promisen.denodeify(request);
var cachedAjax = promisen.memoize(ajaxGet);

var req = {url: "http://www.example.com/"};
cachedAjax(req).then(function(res) {...}); // res.body contains response body

(static) nodeify(task) → {function}

creates a Node.js-style function from a promise-returning function or any object.

Parameters:

Name	Type	Description
`task`	function \| Promise \| thenable \| *	promise-returning function or any object

Source:

Returns:

Node.js-style function

Type: function

Example

var promisen = require("promisen");

var task = nodeify(func);

task(value, function(err, res) {...});

function func(value) {
  return new Promise(function(resolve, reject) {...});
}

(static) parallel(tasks) → {function}

creates a promise-returning function which runs multiple tasks in parallel.

Parameters:

Name	Type	Description
`tasks`	Array \| Array-like	list of tasks

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

// generate a promise-returning function
var task = promisen.parallel([task1, task2, task3,...]);

// execute it
task(value).then(function(array) {...}); // array of results

// execute it with target object which is passed to every tasks
task.call(target, value).then(function(result) {...});

(static) pop(array) → {function}

creates a promise-returning function which fetches the last value on the array.

Parameters:

Name	Type	Description
`array`	Array \| Array-like

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var stack = ["foo", "bar"]; // stack is an array

var task2 = promisen(promisen.pop(stack), task1);

task2().then(function() {...}); // stack.length == 1

(static) promisen(…task) → {function}

creates a promise-returning function from plain function or objects below: 1. function 2. promise object 3. thenable object 4. any other constant object or value 5. multiple values of above

Parameters:

Name	Type	Attributes	Description
`task`	function \| Promise \| thenable \| *	<repeatable>

Source:

See:

https://www.npmjs.com/package/es6-promise
promisen.waterfall()

Returns:

Type: function

Example

var promisen = require("promisen");

// wrap a single function
var wrapped = promisen(function() {...});
wrapped(value).then(function(result) {...});

// composite multiple tasks
var joined = promisen(func, promise, thenable, object);
joined(value).then(function(result) {...});

(static) push(array) → {function}

creates a promise-returning function which inspects the last value on the array.

Parameters:

Name	Type	Description
`array`	Array \| Array-like

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var stack = ["foo", "bar"]; // stack is an array

var task2 = promisen(promisen.top(stack), task1);

task2().then(function() {...}); // stack.length == 2

(static) push(array) → {function}

creates a promise-returning function which stores a value into the array.

Parameters:

Name	Type	Description
`array`	Array \| Array-like

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var stack = []; // stack is an array

var task2 = promisen(task1, promisen.push(stack));

task2().then(function() {...}); // stack.length == 2

(static) reject(reason)

returns a Promise object which is rejected as same as Promise.reject() does.

Parameters:

Name	Type	Description
`reason`		reason why this Promise rejected

Source:

(static) resolve(value)

returns a Promise object which is resolved as same as Promise.resolve() does.

Parameters:

Name	Type	Description
`value`		an argument to be resolved

Source:

(static) series(tasks) → {function}

creates a promise-returning function which runs multiple tasks in order.

Parameters:

Name	Type	Description
`tasks`	Array \| Array-like	list of tasks

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

// generate a promise-returning function
var task = promisen.series([task1, task2, task3,...]);

// execute it
task(value).then(function(array) {...}); // array of results

// execute it with target object which is passed to every tasks
task.call(target, value).then(function(result) {...});

(static) throttle(task, concurrency, timeout) → {function}

creates a promise-returning function which limits number of concurrent job workers run in parallel.

Parameters:

Name	Type	Description
`task`	function	the job
`concurrency`	Number	number of job workers run in parallel (default: 1)
`timeout`	Number	timeout in millisecond until job started (default: no timeout)

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var serialAjaxTask = promisen.throttle(ajaxTask, 1, 10000); // 1 worker, 10 seconds

serialAjaxTask(req).then(function(res) {...});

(static) timeout(task, msec) → {function}

creates a promise-returning function which has timeout detection until job done.

Parameters:

Name	Type	Description
`task`	function	the job
`msec`	Number	timeout in millisecond until job done (default: no timeout)

Source:

Returns:

promise-returning function

Type: function

(static) wait(msec) → {function}

creates a promise-returning function which does just sleep for given milliseconds.

Parameters:

Name	Type	Description
`msec`	Number

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var sleep = promisen.wait(1000); // 1 sec
sleep(value).then(function(value) {...});

// similar to below
setTimeout(function() {...}, 1000);

(static) warn(prefixopt) → {function}

creates a promise-returning function which inspects value to console.warn() for debug purpose.

Parameters:

Name	Type	Attributes	Description
`prefix`	String	<optional>

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

var task3 = promisen(task1, promisen.warn("result:"), task2);

task3().then(function() {...});

(static) waterfall(tasks) → {function}

creates a promise-returning function which runs multiple tasks in order.

Parameters:

Name	Type	Description
`tasks`	Array \| Array-like	list of tasks

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

// generate a promise-returning function
var task = promisen.waterfall([task1, task2, task3,...]);

// execute it
task(value).then(function(result) {...});

// execute it with target object which is passed to every tasks
task.call(target, value).then(function(result) {...});

(static) while(condTask, …runTask) → {function}

creates a promise-returning function which runs a task repeatedly while the condition is true. When null or undefined is given as condTask, it will do nothing for value and just passes it.

Parameters:

Name	Type	Attributes	Description
`condTask`	Boolean \| function \| Promise \| thenable \| * \| null		boolean or function returns boolean
`runTask`	function \| Promise \| thenable \| *	<repeatable>	task runs while true

Source:

Returns:

promise-returning function

Type: function

Example

var promisen = require("promisen");

// counter = 8; while (--counter) { runTask }
var counter = promisen.number(8);
var whileTask = promisen.while(counter.decr, runTask);

// for (initTask; condTask; afterTask) { runTask }
var forTask = promisen(initTask, promisen.while(condTask, runTask, afterTask));

// do { runTask } while (condTask)
var doWhileTask = promisen.while(null, runTask, condTask));