laps/README.md

Simple flow-control lib for Node.js: combine sync/async steps, organize your spaghetti-code

# Laps

Simple flow-control lib for [Node.js](http://nodejs.org): combine sync/async steps, organize your spaghetti-code

`laps` style:

```js
new Laps()
.lap(function() {			
	nextPrime(startNum, this.cb('calc'));						
}).lap(function() {
	nextPrime(this.val, this.cb('calc'));
}).lap(function() {
	nextPrime(this.val, this.cb('calc'));
}).lap(function() {
	nextPrime(this.val, this.cb('calc'));
}).lap(function() {
	nextPrime(this.val, this.cb('calc'));
}).lap(function() {
	nextPrime(this.val, this.cb('calc'));
}).lap(function() {
	nextPrime(this.val, this.cb('calc'));
}).lap(function() {
	nextPrime(this.val, this.cb('calc'));
}).lap(function() {
	nextPrime(this.val, this.cb('calc'));
}).cmd('calc', function(val) {
	this.val = val;
}).on('finish', function() {
	console.log (this.val);
}).run();
```

[Node.js](http://nodejs.org) style:

```js
nextPrime(startNum, function(val){
	nextPrime(val, function(val){
		nextPrime(val, function(val){
			nextPrime(val, function(val){
				nextPrime(val, function(val){
					nextPrime(val, function(val){
						nextPrime(val, function(val){
							nextPrime(val, function(val){
								nextPrime(val, function(val){										
									console.log (val);
								});
							});
						});
					});
				});
			});
		});
	});
});
```


## Installation

    $ npm install laps

## About

`laps` does not require anything from you. You can use it internally, you can return it as a result (promise-like), or you can use it eventually to reorganize some part of code.

It can work with any asynchronous API, and you do not need to wrap API method, you can wrap the callback. 

The main thing you need to know: every `lap` is asynchronous internally but the sequence of `laps` will be executed synchronously. The next `lap` won't be started until the completion of all asynchronous callbacks of the previous `lap`. 
Every wrapped callback become the command and you can also create and execute the commands manually. In addition, you can subscribe to events: `start` of the execution, `finish` of the execution, `begin` of the lap, `end` of the lap, `error`.

  
## Examples

### Synchronous

It is often necessary to organize the sequence of asynchronous calls in a chain.

Consider this example:

```js
var dns = require('dns');

var count = 0;
var handler = null;
var callback = function() {
	if (--count <= 0 && handler) {
		count = 0;
		handler();
	}
};
var error = function(err) {
	console.log('Error: ' + err.message);
	callback();
};
var reverse = function(type, adr) {
	return function(err, data) {
		if (err) return error(err);
		console.log(type + ', reverse for ' + adr + ': ' + JSON.stringify(data));
		callback();
	}
};
var resolve = function(type) {
	return function(err, addresses) {
		if (err) return error(err);
		for (var i = 0; i < addresses.length; i++) {
			var adr = addresses[i];
			++count;
			dns.reverse(adr, reverse(type, adr));            
		};
	}
};
handler = function () {
	handler = function () {
		handler = null;
		dns.resolve4('google.com', resolve('google'));
	};
	dns.resolve4('microsoft.com', resolve('microsoft'));		
};
dns.resolve4('unknown.unk', resolve('unknown'));
```

And here is the same code with `laps`:

```js
var dns = require('dns');
var Laps = require('laps');

new Laps().lap(function() {
	dns.resolve4('unknown.unk', this.cb('resolve', 'unknown'));
}).lap(function() {
	dns.resolve4('microsoft.com', this.cb('resolve', 'microsoft'));
}).lap(function() {
	dns.resolve4('google.com', this.cb('resolve', 'google'));
}).cmd('resolve', function(type, err, addresses) {
	if (err) throw err;
	for (var i = 0; i < addresses.length; i++) {
		var adr = addresses[i];
		dns.reverse(adr, this.cb('reverse', type, adr));            
	};
}).cmd('reverse', function(type, adr, err, data) {
	if (err) throw err;
	console.log(type + ', reverse for ' + adr + ': ' + JSON.stringify(data));
}).on('error', function(err) {
	console.log('Error: ' + err.message);
}).run();
```

### Asynchronous

The sequence of asynchronous calls can also be a problem if you need to process the final result only.

Here is the `laps` example for such situation:

```js
var dns = require('dns');
var Laps = require('laps');

new Laps().lap(function() {
	this.results = {};
	dns.resolve4('unknown.unk', this.cb('resolve', 'unknown'));
	dns.resolve4('microsoft.com', this.cb('resolve', 'microsoft'));
	dns.resolve4('google.com', this.cb('resolve', 'google'));
}).cmd('resolve', function(type, err, addresses) {
	if (err) throw err;
	this.results[type] = [];
	for (var i = 0; i < addresses.length; i++) {
		var adr = addresses[i];
		dns.reverse(adr, this.cb('reverse', type, adr));            
	};
}).cmd('reverse', function(type, adr, err, data) {
	if (err) throw err;
	// Store your results
	this.results[type].push(data); 
}).on('error', function(err) {
	console.log('Error: ' + err.message);
}).on('finish', function(err) {
	// Process your results from all async callbacks
	// this.results ...
}).run();
```

	
## Contributors
  
  Author: [MileAit](http://github.com/mileait)  
  
## License

Public Domain - [Unlicense](http://unlicense.org/)

All the code is original, written from the scratch to avoid any possible license conflicts.