tunnckoCore
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.
Please consider following this project's author, Charlike Mike Reagent, and :star: the project to show your :heart: and support.
If you have any how-to kind of questions, please read the Contributing Guide and Code of Conduct documents. For bugs reports and feature requests, please create an issue or ping @tunnckoCore at Twitter.
![Minimum Required Nodejs][nodejs-img]
Project is semantically versioned & automatically released from GitHub Actions with Lerna.
| Topic | Contact |
|---|---|
| Any legal or licensing questions, like private or commerical use |  |
| For any critical problems and security reports |  |
| Consulting, professional support, personal or team training |  |
| For any questions about Open Source, partnerships and sponsoring |  |
Features
- Work for
koa@1andkoa@2(with deprecation messages), will also work inkoa@3with koa-convert - Totally flexible through
optionsand absolutely lightweight using lazy-cache - Accept few JSON types
- Accept JSON Patch [RFC6902] (koajs/bodyparser#8)
- Accept JSON API v1 (koajs/bodyparser#7)
- Accept JSON csp-report (#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
- Can parse correctly forms that accept multiple files - see #26 and dlau/koa-body#15
- Strict mode by default - see why on IETF Message Semantics: Section 6.1
- Custom JSON request detect function - koajs/bodyparser#f6a5ff
- Custom error handling function - koajs/bodyparser#19418129
- Extending types of request that your app can accept - koajs/bodyparser#ba7479b
- Using awesome formidable package - „battle-tested against hundreds of GB of file uploads“
- Passing a custom
formidable.IncomingForminstance, allowing awesome customization - Passing all options to
formidable.IncomingForm, allowing awesome control
Table of Contents
- Install
- API
- Working with
koa-router - Options
- Note about
options.extendTypes - Note about advanced
querystringparsing - Note about
strictmode - See Also
- Contributing
- Contributors
- License
(TOC generated by verb using markdown-toc)
Install
This project requires Node.js >=8.11 (see
Support & Release Policy).
Install it using yarn or
npm.
We highly recommend to use Yarn when you
think to contribute to this project.
$ yarn add koa-better-bodyAPI
Generated using jest-runner-docs.
koaBetterBody
Robust body parser for koa@1, also works for
koa@2(with deprecations). Will also work for futurekoa@3with koa-convert.
Signature
function(options)
Params
options{object} - see more on options sectionreturns{GeneratorFunction} - plugin for Koa
Examples
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
'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, text, buffer,
csp-report, 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. 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}: Defaultfalse, which means it will set fields onthis.request.fields. If you pass a string, for example'foo', you will have fields onthis.request.foo.files{Boolean|String}: Defaultfalse, which means it will set files onthis.request.files. If you pass a string, for example'bar', you will have files onthis.request.bar.multipart{Boolean}: Defaulttrue. If you passfalseit 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 ofopts.formLimit.jsonLimit{String}: Default'100kb'. Passed to bytes.parse method.bufferLimit{String}: Default'1mb'. Passed to bytes.parse method.jsonStrict{Boolean}: Defaulttrue. When set to true, JSON parser will only accept arrays and objects.detectJSON{Function}: Custom JSON request detect function -detectJSON(ctx).strict{Boolean}: Defaulttrue. Passfalseif 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. Allowing you to extend what your app can accept. By default works for JSON, JSON API v1, multipart, text, urlencoded and csp-report.IncomingForm{IncomingForm}: Pass an instance offormidable.IncomingFormto be able to handle formidable events.handler{GeneratorFunction}: Works withoptions.extendTypes.customto handle custom types of content-type -handler(ctx, options, next). More info below.querystring{Object}: Querystring module to be used. By default builtinquerystring. More info below.qs{Object}: Alias ofopts.querystring. Alloptsare also passed to qs or querystring module.delimiter{String}: Default is&. Delimiter of key/value pairs, passed to querystring libsep{String}: alias ofopts.delimiterbuffer{Boolean}: Defaultfalse, passtrueif 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. 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.
For example manually handle such content types foo/bar-x, text/quix:
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. 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.
Example
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).
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
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 are showing usage on non-strict and strict
mode.
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: A node.js module for parsing form data, especially file uploads. | homepage
- ip-filter: Validates valid IPs (IPv4 and IPv6) using micromatch - glob… more | homepage
- koa-body-parsers: collection of koa body parsers | homepage
- koa-bodyparser: a body parser for koa | homepage
- koa-ip-filter: Middleware for koa that filters IPs against glob patterns, RegExp… more | homepage
- koa: Koa web app framework | homepage
- koala: Koa Framework Suite | homepage
Contributing
Guides and Community
Please read the Contributing Guide and Code of Conduct documents for advices.
For bug reports and feature requests, please join our community 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 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? :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 and yarnpkg.com sites too! :rocket:
Not financial support? Okey! Pull requests, stars and all kind of contributions are always welcome. :sparkles:
Contributors
This project follows the all-contributors specification. Contributions of any kind are welcome!
Thanks goes to these wonderful people (emoji key), consider showing your support to them:
 Charlike Mike Reagent 🚇 💻 📖 🤔 🚧 ⚠️ |
License
Copyright (c) 2014-present, Charlike Mike Reagent
<opensource@tunnckocore.com> & contributors.
Released under the MPL-2.0 License.
[nodejs-img]: https://badgen.net/badge/node/>=8.11/green?cache=300