async-time/README.md

Time async functions using async-done for execution and completion.

async-time
==========

[![Build Status](https://travis-ci.org/phated/async-time.svg?branch=master)](https://travis-ci.org/phated/async-time)

Time async functions using async-done for execution and completion.

## Usage

```js
var EE = require('events').EventEmitter;

var createTimer = require('async-time');

var bus = new EE();
var asyncTime = createTimer(bus);

// listen for timing events
bus.on('start', function(evt){
  // function has started
  console.log(evt);
});

bus.on('stop', function(evt){
  // function has stopped
  console.log(evt);
});

asyncTime(function(cb){
  // do async things
  cb(null, 2);
}, function(err, res){
  // `error` will be undefined on successful execution of the first function.
  // `result` will be the result from the first function.
})
```

## API

__Once a timing function is created, it is used the same as [`async-done`](https://github.com/phated/async-done).__

### `createTimer(EventEmitter)` => Function

The main export is a function that allows you to create a timing function.

You must pass it an `EventEmitter` instance (or an object with `emit` and `on` methods) or it will throw.

The `EventEmitter` instance is the bus timing events are published on.

### `asyncTime(fn, callback)`

See [`async-done`](https://github.com/phated/async-done) docs.

### Events

#### `start`

The event fired when a function begins.

__Properties:__
* `id`: uuid generated for each function. Useful for tying start and end events together.
* `name`: name property of the function given to `asyncTime`.
* `timestamp`: timestamp of when the function started.

#### `stop`

The event fired when a function finishes.

__Properties:__
* `id`: uuid generated for each function. Useful for tying start and end events together.
* `name`: name property of the function given to `asyncTime`.
* `timestamp`: timestamp of when the function started.
* `duration`: high resolution time between start and stop events. Generated by `process.hrtime(startTime)`