# koa-better-body
> Full-featured [koa][] body parser! Support parsing text, buffer, json, json patch, json api, csp-report, multipart, form and urlencoded bodies. Works for koa@1, koa@2 and will work for koa@3.
Latest version **3.3.9** (published 2020-03-28) · MPL-2.0 license · 0 weekly downloads
## Install
```sh
npm install koa-better-body
pnpm add koa-better-body
yarn add koa-better-body
bun add koa-better-body
```
## Health
**Score 23/100 (F)** — status: abandoned.
Positive: has types package; esm support; no vulnerabilities.
Warnings: low downloads.
Negative: insecure dependencies; abandoned.
## Facts
| | |
|---|---|
| Version | 3.3.9 |
| Published | 2020-03-28 |
| First published | 2014-05-10 |
| Weekly downloads | 0 |
| License | MPL-2.0 |
| TypeScript types | separate (@types/koa-better-body) |
| Module format | ESM + CommonJS |
| Node | >=8.11 |
| Dependencies | 3 |
| Unpacked size | 91.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 486 |
| Author | Charlike Mike Reagent |
| Maintainers | tunnckocore, vanchoy |
| Keywords | api, awesome, better, body, body-parser, buffer, csp, csp-report, error, extendable, feature, features, flexible, form, forms, full, full-feature, handling, json, json-api, koa, koa-better-body, multipart, parse, parser, text, urlencoded |
## Links
- npm: https://www.npmjs.com/package/koa-better-body
- Repository: https://github.com/tunnckoCore/opensource
- Homepage: https://tunnckocore.com/opensource
- Issues: https://github.com/tunnckoCore/opensource/issues
- Funding: https://ko-fi.com/tunnckoCore/commissions
- npm.io page: https://npm.io/package/koa-better-body
## Dependencies (3)
- [formidable](https://npm.io/package/formidable.md) ^1.2.1
- [extend-shallow](https://npm.io/package/extend-shallow.md) ^3.0.2
- [koa-body-parsers](https://npm.io/package/koa-body-parsers.md) github:tunnckocore/body-parsers#patch-1
## Alternatives
- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads
## Recent versions
- 3.3.9 (latest) — 2020-03-28
- 3.3.8 — 2020-03-28
- 3.3.7 — 2020-03-27
- 3.3.6 — 2020-03-27
- 3.3.5 — 2020-02-29
- 3.3.4 — 2020-02-04
- 3.3.3 — 2020-02-04
- 3.3.2 — 2020-02-03
- 3.3.1 — 2020-01-24
- 3.3.0 — 2020-01-24
- 3.2.3 — 2020-01-19
- 3.2.2 — 2020-01-19
- 3.2.1 — 2020-01-19
- 3.2.0 — 2019-11-21
- 3.1.15 — 2019-11-20
- … 51 more at https://npm.io/package/koa-better-body/versions
## README
# koa-better-body [![npm version][npmv-img]][npmv-url] [![License][license-img]][license-url] [![Libera Manifesto][libera-manifesto-img]][libera-manifesto-url]
> Full-featured [koa][] body parser! Support parsing text, buffer, json, json
> patch, json api, csp-report, multipart, form and urlencoded bodies. Works for
> koa@1, koa@2 and will work for koa@3.
Please consider following this project's author,
[Charlike Mike Reagent](https://github.com/tunnckoCore), and :star: the project
to show your :heart: and support.
[![Code style][codestyle-img]][codestyle-url]
[![CircleCI linux build][linuxbuild-img]][linuxbuild-url]
[![CodeCov coverage status][codecoverage-img]][codecoverage-url]
[![Renovate App Status][renovateapp-img]][renovateapp-url]
[![Make A Pull Request][prs-welcome-img]][prs-welcome-url]
[![Time Since Last Commit][last-commit-img]][last-commit-url]
If you have any _how-to_ kind of questions, please read the [Contributing
Guide][contributing-url] and [Code of Conduct][code_of_conduct-url] documents.
For bugs reports and feature requests, [please create an issue][open-issue-url]
or ping [@tunnckoCore](https://twitter.com/tunnckoCore) at Twitter.
[![Conventional Commits][ccommits-img]][ccommits-url]
[![Minimum Required Nodejs][nodejs-img]][npmv-url]
[![NPM Downloads Monthly][downloads-monthly-img]][npmv-url]
[![NPM Downloads Total][downloads-total-img]][npmv-url]
[![Share Love Tweet][twitter-share-img]][twitter-share-url]
[![Twitter][twitter-img]][twitter-url]
Project is [semantically](https://semver.org) versioned & automatically released
from [GitHub Actions](https://github.com/features/actions) with
[Lerna](https://github.com/lerna/lerna).
[![Become a Patron][patreon-img]][patreon-url]
[![Buy me a Kofi][kofi-img]][kofi-url]
[![PayPal Donation][paypal-img]][paypal-url]
[![Bitcoin Coinbase][bitcoin-img]][bitcoin-url]
[![Keybase PGP][keybase-img]][keybase-url]
| Topic | Contact |
| :--------------------------------------------------------------- | ------------------------------------------------: |
| Any legal or licensing questions, like private or commerical use | ![tunnckocore_legal][tunnckocore_legal] |
| For any critical problems and security reports | ![tunnckocore_security][tunnckocore_security] |
| Consulting, professional support, personal or team training | ![tunnckocore_consulting][tunnckocore_consulting] |
| For any questions about Open Source, partnerships and sponsoring | ![tunnckocore_opensource][tunnckocore_opensource] |
## Features
- Work for `koa@1` and `koa@2` (with deprecation messages), will also work in
`koa@3` with [koa-convert][]
- Totally flexible through `options` and absolutely lightweight using
[lazy-cache][]
- Accept few JSON types
- Accept [JSON Patch [RFC6902]](https://tools.ietf.org/html/rfc6902)
([koajs/bodyparser#8](https://github.com/koajs/bodyparser/pull/8))
- Accept [JSON API v1](http://jsonapi.org/)
([koajs/bodyparser#7](https://github.com/koajs/bodyparser/pull/7))
- Accept [JSON csp-report](https://mathiasbynens.be/notes/csp-reports)
([#3](https://github.com/tunnckoCore/koa-better-body/issues/3))
- Accept text and buffer bodies
- Accept urlencoded and forms bodies
- Accept multipart form data files and fields
- Can parse correctly array data from forms - e.g. multiple fields to have same
name - [dlau/koa-body#15](https://github.com/dlau/koa-body/pull/15)
- Can parse correctly forms that accept multiple files - see
[#26](https://github.com/tunnckoCore/koa-better-body/issues/26) and
[dlau/koa-body#15](https://github.com/dlau/koa-body/pull/15)
- Strict mode by default - see why on
[IETF Message Semantics: Section 6.1](https://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-6.1)
- Custom JSON request detect function -
[koajs/bodyparser#f6a5ff](https://github.com/koajs/bodyparser/commit/f6a5ff7ef6162702540b101de5dde71ee5ad19cd)
- Custom error handling function -
[koajs/bodyparser#19418129](https://github.com/koajs/bodyparser/commit/194181298fe3bffce6b5fcf3cfebc35b8cda6c89)
- Extending types of request that your app can accept -
[koajs/bodyparser#ba7479b](https://github.com/koajs/bodyparser/commit/ba7479baf893fc3391fcdb88d3d8173ac4df05e7)
- Using awesome [formidable][] package -
[„battle-tested against hundreds of GB of file uploads“](https://github.com/felixge/node-formidable#current-status)
- Passing a custom `formidable.IncomingForm` instance, allowing awesome
customization
- Passing all options to `formidable.IncomingForm`, allowing awesome control
## Table of Contents
- [Install](#install)
- [API](#api)
- [koaBetterBody](#koabetterbody)
- [Working with `koa-router`](#working-with-koa-router)
- [Options](#options)
- [Note about `options.extendTypes`](#note-about-optionsextendtypes)
- [Note about advanced `querystring` parsing](#note-about-advanced-querystring-parsing)
- [Note about `strict` mode](#note-about-strict-mode)
- [See Also](#see-also)
- [Contributing](#contributing)
- [Guides and Community](#guides-and-community)
- [Support the project](#support-the-project)
- [Contributors](#contributors)
- [License](#license)
_(TOC generated by [verb](https://github.com/verbose/verb) using
[markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
## Install
This project requires [**Node.js**](https://nodejs.org) **>=8.11** _(see
[Support & Release Policy](https://github.com/tunnckoCoreLabs/support-release-policy))_.
Install it using [**yarn**](https://yarnpkg.com) or
[**npm**](https://npmjs.com). _We highly recommend to use Yarn when you
think to contribute to this project._
```bash
$ yarn add koa-better-body
```
## API
_Generated using [jest-runner-docs](https://ghub.now.sh/jest-runner-docs)._
### [koaBetterBody](./src/index.js#L36)
> Robust body parser for [koa][]@1, also works for `koa@2` (with deprecations).
> Will also work for future `koa@3` with [koa-convert][].
#### Signature
```ts
function(options)
```
#### Params
- `options` **{object}** - see more on [options section](#options)
- `returns` **{GeneratorFunction}** - plugin for Koa
#### Examples
```js
var koa = require('koa');
var body = require('koa-better-body');
var app = koa();
app
.use(body())
.use(function* () {
console.log(this.request.body); // if buffer or text
console.log(this.request.files); // if multipart or urlencoded
console.log(this.request.fields); // if json
})
.listen(8080, function () {
console.log('koa server start listening on port 8080');
});
```
## Working with `koa-router`
using [koa-router][]
```js
'use strict';
var app = require('koa')();
var body = require('koa-better-body');
var router = require('koa-router')();
router.post('/upload', body(), function* (next) {
console.log(this.request.files);
console.log(this.request.fields);
// there's no `.body` when `multipart`,
// `urlencoded` or `json` request
console.log(this.request.body);
// print it to the API requester
this.body = JSON.stringify(
{
fields: this.request.fields,
files: this.request.files,
body: this.request.body || null,
},
null,
2,
);
yield next;
});
app.use(router.routes());
app.listen(4292);
var format = require('util').format;
var host = 'http://localhost:4292';
var cmd = 'curl -i %s/upload -F "source=@%s/.editorconfig"';
console.log('Try it out with below CURL for `koa-better-body` repository.');
console.log(format(cmd, host, __dirname));
```
## Options
Sane defaults. :sparkles:
Accepts JSON, [JSON API v1](http://jsonapi.org/), text, buffer,
[csp-report](https://mathiasbynens.be/notes/csp-reports), multipart and
urlencoded/form bodies. If you want to disallow accepting and parsing multipart
body you should pass `multipart: false`. Most of the defaults you can see at
[utils.defaultOptions and utils.defaultTypes](./utils.js). **All `options` are
also been passed to [formidable][].IncomingForm!** Even you can pass
IncomingForm instance to be able to handle the different formidable events.
- `fields` **{Boolean|String}**: Default `false`, which means it will set fields
on `this.request.fields`. If you pass a string, for example `'foo'`, you will
have fields on `this.request.foo`.
- `files` **{Boolean|String}**: Default `false`, which means it will set files
on `this.request.files`. If you pass a string, for example `'bar'`, you will
have files on `this.request.bar`.
- `multipart` **{Boolean}**: Default `true`. If you pass `false` it won't
accept/parse multipart bodies.
- `textLimit` **{String}**: Default `'100kb'`. Passed to [bytes][].parse method.
- `formLimit` **{String}**: Default `'100kb'`. Passed to [bytes][].parse method.
- `urlencodedLimit` **{String}**: Default `'100kb'`. Alias of `opts.formLimit`.
- `jsonLimit` **{String}**: Default `'100kb'`. Passed to [bytes][].parse method.
- `bufferLimit` **{String}**: Default `'1mb'`. Passed to [bytes][].parse method.
- `jsonStrict` **{Boolean}**: Default `true`. When set to true, JSON parser will
only accept arrays and objects.
- `detectJSON` **{Function}**: Custom JSON request detect function -
`detectJSON(ctx)`.
- `strict` **{Boolean}**: Default `true`. Pass `false` if you want to allow
parsing GET, DELETE and HEAD requests.
- `onerror` **{Function}**: Custom error handle, if throw an error, you can
customize the response - `onerror(err, ctx)`.
- `extendTypes` **{Object}**: Default accepting types can find on
[utils.defaultTypes function](./utils.js#L83-L104). Allowing you to extend
what your app can accept. By default works for JSON,
[JSON API v1](http://jsonapi.org/), multipart, text, urlencoded and
[csp-report](https://mathiasbynens.be/notes/csp-reports).
- `IncomingForm` **{IncomingForm}**: Pass an instance of
`formidable.IncomingForm` to be able to handle formidable events.
- `handler` **{GeneratorFunction}**: Works with `options.extendTypes.custom` to
handle custom types of content-type - `handler(ctx, options, next)`. More info
below.
- `querystring` **{Object}**: Querystring module to be used. By default builtin
[`querystring`](https://nodejs.org/api/querystring.html). More info below.
- `qs` **{Object}**: Alias of `opts.querystring`. All `opts` are also passed to
[qs][] or [querystring module](https://nodejs.org/api/querystring.html).
- `delimiter` **{String}**: Default is `&`. Delimiter of key/value pairs, passed
to querystring lib
- `sep` **{String}**: alias of `opts.delimiter`
- `buffer` **{Boolean}**: Default `false`, pass `true` if you want to get body
as buffer.
## Note about `options.extendTypes`
ExandTypes option gives you a flexible way to handle different content-types and
modify the defaults which can be found
[at utils.defaultTypes function](./utils.js#L83-L104). In addition you can pass
combination of `options.extendTypes.custom` and `options.handler`. When the
request has some of the "custom" content type, this middleware will call the
`handler` **generator** function with `ctx, options, next`. You can see more at
[issue #52](https://github.com/tunnckoCore/koa-better-body/issues/52).
For example manually handle such content types `foo/bar-x`, `text/quix`:
```js
const app = require('koa')()
const body = require('koa-better-body')
app.use(body({
textLimit: '300kb'
extendTypes: {
custom: [
'foo/bar-x',
'text/quix'
]
},
handler: function * (ctx, opts) {
// `ctx` is equal to `this` and `app`
// `opts` is current options object
// passed to `koa-better-body`
ctx.body = yield this.request.text(opts.textLimit)
}
}))
app.use(function * showBody () {
// `this.body` is text
console.log(this.body)
})
```
## Note about advanced `querystring` parsing
Because this middleware is fully based and integrated with [koa-body-parsers][],
by default it uses Node's built-in module for that thing
[querystring](https://nodejs.org/api/querystring.html). So if you have some
issues with forms, think to add custom querystring module like [qs][] to
`options.querystring` or `app.querystring`. Related to this is
[issue #45](https://github.com/tunnckoCore/koa-better-body/issues/45).
**Example**
```js
const app = require('koa')()
const body = require('koa-better-body')
app.use(body({
multipart: false
querystring: require('qs')
}))
```
It's intentional that it's not included in the deps by default. In `v2` it was
also working by passing it to `app.querystring`, because [koa-body-parsers][]
works
[that way (index.js#L53)](https://github.com/koajs/body-parsers/blob/master/index.js#L53).
## Note about `strict` mode
We are trying to follow standards. :cat2:
You can pass `strict:false`, but see
[IETF HTTP/1.1 Message Semantics: Section 6.1](https://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-6.1)
to understand why we stay to _"strict mode"_ by default. GET, HEAD, and DELETE
requests have no defined semantics for the request body, but this doesn't mean
they may not be valid in certain use cases. Last two tests at
[test/options.js](./test/options.js) are showing usage on non-strict and strict
mode.
**[back to top](#readme)**
## See Also
Some of these projects are used here or were inspiration for this one, others
are just related. So, thanks for your existance!
- [formidable](https://www.npmjs.com/package/formidable): A node.js module for
parsing form data, especially file uploads. |
[homepage](https://github.com/node-formidable/formidable 'A node.js module for parsing form data, especially file uploads.')
- [ip-filter](https://www.npmjs.com/package/ip-filter): Validates valid IPs
(IPv4 and IPv6) using [micromatch][] - glob…
[more](https://tunnckocore.com/opensource) |
[homepage](https://tunnckocore.com/opensource 'Validates valid IPs (IPv4 and IPv6) using [micromatch][] - glob patterns, RegExp, string or array of globs. If match returns the IP, otherwise null.')
- [koa-body-parsers](https://www.npmjs.com/package/koa-body-parsers): collection
of koa body parsers |
[homepage](https://github.com/koajs/body-parsers#readme 'collection of koa body parsers')
- [koa-bodyparser](https://www.npmjs.com/package/koa-bodyparser): a body parser
for koa |
[homepage](https://github.com/koajs/body-parser 'a body parser for koa')
- [koa-ip-filter](https://www.npmjs.com/package/koa-ip-filter): Middleware for
[koa][] that filters IPs against glob patterns, RegExp…
[more](https://github.com/tunnckocore/koa-ip-filter#readme) |
[homepage](https://github.com/tunnckocore/koa-ip-filter#readme 'Middleware for [koa][] that filters IPs against glob patterns, RegExp, string or array of globs. Support custom `403 Forbidden` message and custom ID.')
- [koa](https://www.npmjs.com/package/koa): Koa web app framework |
[homepage](https://github.com/koajs/koa#readme 'Koa web app framework')
- [koala](https://www.npmjs.com/package/koala): Koa Framework Suite |
[homepage](https://github.com/koajs/koala#readme 'Koa Framework Suite')
**[back to top](#readme)**
## Contributing
### Guides and Community
Please read the [Contributing Guide][contributing-url] and [Code of
Conduct][code_of_conduct-url] documents for advices.
For bug reports and feature requests, please join our [community][community-url]
forum and open a thread there with prefixing the title of the thread with the
name of the project if there's no separate channel for it.
Consider reading the
[Support and Release Policy](https://github.com/tunnckoCoreLabs/support-release-policy)
guide if you are interested in what are the supported Node.js versions and how
we proceed. In short, we support latest two even-numbered Node.js release lines.
### Support the project
[Become a Partner or Sponsor?][kofi-url] :dollar: Check the **OpenSource**
Commision (tier). :tada: You can get your company logo, link & name on this
file. It's also rendered on package's page in [npmjs.com][npmv-url] and
[yarnpkg.com](https://yarnpkg.com/en/package/koa-better-body) sites too!
:rocket:
Not financial support? Okey!
[Pull requests](https://github.com/tunnckoCoreLabs/contributing#opening-a-pull-request),
stars and all kind of
[contributions](https://opensource.guide/how-to-contribute/#what-it-means-to-contribute)
are always welcome. :sparkles:
## Contributors
This project follows the
[all-contributors](https://github.com/all-contributors/all-contributors)
specification. Contributions of any kind are welcome!
Thanks goes to these wonderful people
([emoji key](https://allcontributors.org/docs/en/emoji-key)), consider showing
your [support](#support-the-project) to them:
