* Rewrite docs to inlude examples
* Add proposed changes to README.md
* Add docs for logging
* Revert "Add docs for logging"
This reverts commit dff3225ae7bbfa2f6371370fb7923713cfcf50f9.
* Add instruction for port based on environment variable
* Remove command line indicator
* Added examples
* Add missing code block
* Api -> API
* Add README and package.json to all examples
* Fix linting errors
* Remove semicolons
* Ignore examples dir
<li><ahref="./examples/urlencoded-body-parsing">Parse urlencoded form (html `form` tag)</a></li>
</ul>
</details></p>
- This function is exposed as the `default` export.
- Use `require('micro')`.
- Returns a [`http.Server`](https://nodejs.org/dist/latest-v4.x/docs/api/http.html#http_class_http_server) that uses the provided `fn` as the request handler.
- The supplied function is run with `await`. It can be `async`!
- Example:
```js
const micro = require('micro');
const sleep = require('then-sleep');
const srv = micro(async function (req, res) {
await sleep(500);
res.writeHead(200);
res.end('woot');
});
srv.listen(3000);
```
#### json
For parsing the incoming request body we included an async function `json`
```js
const { json } = require('micro')
module.exports = async function (req, res) {
const data = await json(req)
console.log(data.price)
return ''
}
```
#### API
**`json(req, { limit = '1mb' })`**
@ -100,18 +116,23 @@ npm start
- Can be called multiple times, as it caches the raw request body the first time.
- `limit` is how much data is aggregated before parsing at max. Otherwise, an `Error` is thrown with `statusCode` set to `413` (see [Error Handling](#error-handling)). It can be a `Number` of bytes or [a string](https://www.npmjs.com/package/bytes) like `'1mb'`.
- If JSON parsing fails, an `Error` is thrown with `statusCode` set to `400` (see [Error Handling](#error-handling))
- Example:
```js
const { json, send } = require('micro');
module.exports = async function (req, res) {
const data = await json(req);
console.log(data.price);
send(res, 200);
}
```
#### send
For other types of data check the [examples](#body-parsing-examples)
### 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('micro')
module.exports = async function (req, res) {
const statusCode = 400
const data = { error: 'Custom error message' }
send(res, statusCode, data)
}
```
#### API
**`send(res, statusCode, data = null)`**
@ -123,62 +144,31 @@ npm start
- `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).
- Example
```js
const { send } = require('micro')
module.exports = async function (req, res) {
send(res, 400, { error: 'Please use a valid email' });
}
```
#### return
**`return val;`**
- Returning `val` from your function is shorthand for: `send(res, 200, val)`.
- Example
```js
module.exports = function (req, res) {
return {message: 'Hello!'};
}
```
- Returning a promise works as well!
- Example
```js
const sleep = require('then-sleep')
module.exports = async function (req, res) {
return new Promise(async (resolve) => {
await sleep(100);
resolve('I Promised');
});
}
```
### Programmatic use
#### sendError
You can use micro programmatically by requiring micro directly:
**`sendError(req, res, error)`**
```js
const micro = require('micro')
const sleep = require('then-sleep')
- 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`.
const server = micro(async function (req, res) {
await sleep(500)
return 'Hello world'
})
#### createError
server.listen(3000)
```
**`createError(code, msg, orig)`**
#### API
- 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).
**`micro(fn)`**
<aname="error-handling"></a>
- This function is exposed as the `default` export.
- Use `require('micro')`.
- Returns a [`http.Server`](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`
### Error handling
@ -191,26 +181,26 @@ If the `Error` object that's thrown contains a `statusCode` property, that's use
```js
const rateLimit = require('my-rate-limit')
module.exports = async function (req, res) {
await rateLimit(req);
await rateLimit(req)
// … your code
}
```
If the API endpoint is abused, it can throw an error like so:
If the API endpoint is abused, it can throw an error with ``createError`` like so:
```js
if (tooMany) {
const err = new Error('Rate limit exceeded');
err.statusCode = 429;
throw err;
throw createError(429, 'Rate limit exceeded')
}
```
Alternatively you can use ``createError`` as described above.
Alternatively you can create the `Error` object yourself
```js
if (tooMany) {
throw createError(429, 'Rate limit exceeded')
const err = new Error('Rate limit exceeded')
err.statusCode = 429
throw err
}
```
@ -218,11 +208,11 @@ The nice thing about this model is that the `statusCode` is merely a suggestion.
```js
try {
await rateLimit(req);
await rateLimit(req)
} catch (err) {
if (429 == err.statusCode) {
// perhaps send 500 instead?
send(res, 500);
send(res, 500)
}
}
```
@ -234,45 +224,64 @@ 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:
- 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).
### Testing
Micro makes tests compact and a pleasure to read and write.
We recommend [ava](https://github.com/sindresorhus/ava), a highly parallel micro test framework with built-in support for async tests:
```js
const micro = require('micro');
const test = require('ava');
const listen = require('test-listen');
const request = require('request-promise');
const micro = require('micro')
const test = require('ava')
const listen = require('test-listen')
const request = require('request-promise')
test('my endpoint', async t => {
const service = micro(async function (req, res) {
micro.send(res, 200, { test: 'woot' })
});
})
const url = await listen(service);
const body = await request(url);
t.deepEqual(JSON.parse(body).test, 'woot');
});
const url = await listen(service)
const body = await request(url)
t.deepEqual(JSON.parse(body).test, 'woot')
})
```
Look at the [test-listen](https://github.com/zeit/test-listen) for a
Look at [test-listen](https://github.com/zeit/test-listen) for a
function that returns a URL with an ephemeral port every time it's called.
### Transpilation
@ -312,6 +321,22 @@ You can use the `micro` CLI for `npm start`:
Then simply run `npm start`!
#### Port based on environment variable
When you want to set the port using an environment variable you can use:
```
micro -p $PORT
```
Optionally you can add a default if it suits your use case:
```
micro -p ${PORT:-3000}
```
`${PORT:-3000}` will allow a fallback to port `3000` when `$PORT` is not defined
## Contribute
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
Tim Neutkens
8 years ago
Leo Lamprecht