PromiseTimeOut

This lib helps you to deal with Promises that have a lifetime limit regardless the implementation.

What is a Promise ?

Promise its a solution that triggers an event after its execution. It can be a success function or fail function. Its normally used for async calls.

It patterns looks this way:

#!javascript

var promise = new Promise(function(resolve, reject) {
		//do async
		if(ok) {  
			resolve(myData); 
		} else { 
			reject(myError); 
		}
	});
	var	successCallback = function(myData) {
	   console.log("Success! ", myData);
    };
    var errorCallback = function(myError) {
		console.log("Failed! ", myError);
	}
	promise.then(successCallback, errorCallback);

How it looks PromiseTimeOut

There are only 3 differences:

1. Adition of parameters timeOut and message.

2. The async function now receive an object holder that contains resolve and reject functions.

3. In errorCallback, now you have an object that represents timeOut.

#!javascript

var timeOut = 3000; //3s
	var message = "You have only 3s to execute it!";

	var promise = new PromiseTimeOut(function(holder) {
		//do async
		if(ok) {  
			holder.resolve(myData); 
		} else { 
			holder.reject(myError); 
		}
	}, timeOut, message);
	
	var	successCallback = function(myData) {
	   console.log("Success! ", myData);
    };
    var errorCallback = function(myError) {
	    if(myError.timeOut) {
		    console.log(myError.message); // You have only 3s to execute it!
		} else {
			console.log("Failed! ", myError);
		}
	}
	promise.then(successCallback, errorCallback);

Motivation

It was born due to the construction of a lib that let the developer deal with an Promise - he can do whatever he wants, but if the developer have forgotten to put the resolve() function, the whole application would stop and probably it would take a long time to see what is the problem. With this solution, I can warn the developer: "Have you remembered to put resolve() ?"

Complete examples

Your execution is faster than the timeout

#!javascript

new PromiseTimeOut(function (holder) {
		console.log("[B] Searching...");
		
		timer.wait(1000).then(function () {
			holder.resolve({ 'info': 'info "B"' });
		});
	}, 2000, "[B] time > 2 seconds.").then(
		function (success) {
			console.log("[B] Success: " + success.info);
		}, function (err) {
			console.log("[B] Error: " + err.message);
		}
	);

Result:

[B] Searching...
[B] Success: info "B"

Your execution is faster than the timeout

#!javascript

var timer = require("./timer")();
	new PromiseTimeOut(function (holder) {

		console.log("[A] Searching...");
	
		timer.wait(4000).then(function () {
			holder.resolve({ 'info': ' info "A"' });
		});
	}, 3000, "[A] time > 3 seconds.").then(
		function (success) {
			console.log("[A] Success: " + success.info);
		}, function (err) {
			console.log("[A] Error: " + err.message);
		}
	);

Result:

[A] Searching...
[A] Error: [A] time > 3 seconds.

Two executions simultaneous

A needs 4 seconds to execute, but has only 3s. It will happen timeOut. B needs 1 second to execute and has 2s. It will return its message.

#!javascript

var PromiseTimeOut = require("./promiseTimeOut");
	var timer = require("./timer")();
	
	new PromiseTimeOut(function (holder) {
		console.log("[A] Searching...");
		timer.wait(4000).then(function () {
			holder.resolve({ 'info': ' info "A"' });
		});
	}, 3000, "[A] time > 3 seconds.").then(
		function (success) {
			console.log("[A] Success: " + success.info);
		}, function (err) {
			console.log("[A] Error: " + err.message);
		}
	);
	
	//Need to instanciate again to work.
	timer = require("./timer")();
	
	
	new PromiseTimeOut(function (holder) {
		console.log("[B] Searching...");
		
		timer.wait(1000).then(function () {
			holder.resolve({ 'info': 'info "B"' });
		});
	
	}, 2000, "[B] time > 2 seconds.").then(
		function (success) {
			console.log("[B] Success: " + success.info);
		}, function (err) {
			console.log("[B] Error: " + err.message);
		}
	);

Results

[A] Searching...
[B] Searching...
[B] Success: info "B"
[A] Error: [A] time > 3 seconds.

Requirements

This lib is based in Promise lib. You can know more about here: https://www.npmjs.com/package/promise