micro2/README.md

**Micro2** — Node.js based asynchronous micro-library (WIP)

[![NPM Version](https://img.shields.io/npm/v/micro2.svg)](https://www.npmjs.com/package/micro2)
[![node](https://img.shields.io/node/v/micro2.svg)](https://nodejs.org)
[![Build Status](https://travis-ci.org/rjoydip/micro2.svg?branch=master)](https://travis-ci.org/rjoydip/micro2)
[![Build status](https://ci.appveyor.com/api/projects/status/qe5x7i3ift8q7rkv/branch/master?svg=true)](https://ci.appveyor.com/project/rjoydip/micro2/branch/master)
[![dependencies Status](https://david-dm.org/rjoydip/micro2/status.svg)](https://david-dm.org/rjoydip/micro2?type=dev)
[![devDependencies Status](https://david-dm.org/rjoydip/micro2/dev-status.svg)](https://david-dm.org/rjoydip/micro2?type=dev)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://img.shields.io/badge/license-MIT-blue.svg)
[![install size](https://packagephobia.now.sh/badge?p=micro2)](https://packagephobia.now.sh/result?p=micro2)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://reactjs.org/docs/how-to-contribute.html#your-first-pull-request)

## Features

* **Easy**: Designed for usage with `async` and `await`
* **Middleware**: Support middleware
* **Logging**: It has very low overhead logging method built. [pino](https://www.npmjs.com/package/pino)	

## Installation

**Important:** Right now `Micro2` not ready for production application. For making `micro2` a goal is to faster moduler application development. Make your application with moduler way.

```bash
npm install --save micro2
```

## Usage

Create an `index.js` file and export a function that accepts the standard [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) and [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) objects:

```js
module.exports = (req, res) => {
  res.end('Welcome to Micro2')
}
```

or

```js
module.exports = () => 'Welcome to Micro2'
```

### `async` & `await`

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/external-api-call">Fetch external api</a></li></ul>
</details></p>

Micro2 is built for usage with async/await. You can read more about async / await.

```js
const sleep = require('then-sleep')

module.exports = async (req, res) => {
  await sleep(500)
  return 'Ready!'
}
```
### API

##### `send(res, statusCode, data = null)`

- Use `require('micro2').send`.
- `statusCode` is a `Number` with the HTTP status code, and must always be supplied.
- If `data` is supplied it is sent in the response. Different input types are processed appropriately, and `Content-Type` and `Content-Length` are automatically set.
	- `string`: `data` is written as-is.
- If JSON serialization fails (for example, if a cyclical reference is found), a `400` error is thrown.


### Sending a different status code

So far we have used `return` to send data to the client. `return 'Hello World'` is the equivalent of `send(res, 200, 'Hello World')`.

```js
const {send} = require('micro2')

module.exports = async (req, res) => {
  const statusCode = 400
  const data = { error: 'Custom error message' }

  send(res, statusCode, data)
}
```


##### `send(res, statusCode, data = null)`

- Use `require('micro').send`.
- `statusCode` is a `Number` with the HTTP status code, and must always be supplied.
- If `data` is supplied it is sent in the response. Different input types are processed appropriately, and `Content-Type` and `Content-Length` are automatically set.
  - `Stream`: `data` is piped as an `octet-stream`. Note: it is _your_ responsibility to handle the `error` event in this case (usually, simply logging the error and aborting the response is enough).
  - `Buffer`: `data` is written as an `octet-stream`.
  - `object`: `data` is serialized as JSON.
  - `string`: `data` is written as-is.
- If JSON serialization fails (for example, if a cyclical reference is found), a `400` error is thrown. See [Error Handling](#error-handling).

### Programmatic use

You can use Micro2 programmatically by requiring Micro2 directly:

```js
const micro2 = require('micro2')
const sleep = require('then-sleep')

const server = micro2(async (req, res) => {
  await sleep(500)
  return 'Hello world'
})

server.listen(3000)
```

### Middleware support

You can applied middleware with server.

```js
server.use((req, res, next) => { // err, req, res
	log.info('middleware 1')
	next()
})
```

### Logger

Micro2 uses [pino](https://www.npmjs.com/package/pino) for logging. You could enable logging conditionaly. `process.env.NODE_ENV`

```js
const log = server.log({
	enabled: true
})
```

##### micro2(fn)

- This function is exposed as the `default` export.
- Use `require('micro2')`.
- Returns a [`http.createServer`](https://nodejs.org/dist/latest-v6.x/docs/api/http.html#http_class_http_server) that uses the provided `function` as the request handler.
- The supplied function is run with `await`. So it can be `async`.

##### sendError(req, res, error)

- Use `require('micro').sendError`.
- Used as the default handler for errors thrown.
- Automatically sets the status code of the response based on `error.statusCode`.
- Sends the `error.message` as the body.
- Stacks are printed out with `console.error` and during development (when `NODE_ENV` is set to `'development'`) also sent in responses.
- Usually, you don't need to invoke this method yourself, as you can use the [built-in error handling](#error-handling) flow with `throw`.

##### createError(code, msg, orig)

- Use `require('micro').createError`.
- Creates an error object with a `statusCode`.
- Useful for easily throwing errors with HTTP status codes, which are interpreted by the [built-in error handling](#error-handling).
- `orig` sets `error.originalError` which identifies the original error (if any).

## Error Handling

Micro2 allows you to write robust microservices. This is accomplished primarily by bringing sanity back to error handling and avoiding callback soup.

If an error is thrown and not caught by you, the response will automatically be `500`. **Important:** Error stacks will be printed as `error` and during development mode (if the env variable `NODE_ENV` is `'development'`), they will also be included in the responses.

If the `Error` object that's thrown contains a `statusCode` property, that's used as the HTTP code to be sent. Let's say you want to write a rate limiting module:

```js
const rateLimit = require('my-rate-limit')

module.exports = async (req, res) => {
  await rateLimit(req)
  // ... your code
}
```

Alternatively you can create the `Error` object yourself

```js
if (tooMany) {
  const err = new Error('Rate limit exceeded')
  err.statusCode = 429
  throw err
}
```

The nice thing about this model is that the `statusCode` is merely a suggestion. The user can override it:

```js
try {
  await rateLimit(req)
} catch (err) {
  if (429 == err.statusCode) {
    // perhaps send 500 instead?
    send(res, 500)
  }
}
```

If the error is based on another error that **Micro2** caught, like a `JSON.parse` exception, then `originalError` will point to it. If a generic error is caught, the status will be set to `500`.

In order to set up your own error handling mechanism, you can use composition in your handler:

```js
const {send} = require('micro2')

const handleErrors = fn => async (req, res) => {
  try {
    return await fn(req, res)
  } catch (err) {
    console.log(err.stack)
    send(res, 500, 'My custom error!')
  }
}

module.exports = handleErrors(async (req, res) => {
  throw new Error('What happened here?')
})
```

## Testing

TODO

## Contributing

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device

As always, you can run the [Jest](https://jestjs.io) tests using: `npm test` and [ESLint](http://eslint.org) lint using: `npm run lint`