promisetimeout/readme

Adds a lifecycle to a Promise.

# 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