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.
You might also be interested in our recipes - working examples, answers, tips & tricks. Contribute a recipe?
Install
npm i koa-better-body --save
Features
- Work for
koa@1
andkoa@2
(with deprecation messages), will also work inkoa@3
with koa-convert - Totally flexible through
options
and 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.IncomingForm
instance, allowing awesome customization - Passing all options to
formidable.IncomingForm
, allowing awesome control
Usage
For more use-cases see the tests
const koaBetterBody =
koaBetterBody
Robust body parser for koa@1, also works for
koa@2
(with deprecations). Will also work for futurekoa@3
with koa-convert.
Params
options
{Object}: see more on options sectionreturns
{GeneratorFunction}
Example
var koa = var body = var app = app
Options
Sane defaults. ✨
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
and directly onthis.body
. If you pass a string, for example'foo'
, you will have fields onthis.body
and onthis.request.foo
.files
{Boolean|String}: Defaultfalse
, which means it will set files onthis.request.files
andthis.body.files
, if you pass a string, for example'bar'
, it will set files onthis.request.bar
andthis.body.bar
.multipart
{Boolean}: Defaulttrue
. If you passfalse
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.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
. Passfalse
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. 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.IncomingForm
to be able to handle formidable events.
strict
mode
A note about We are trying to follow standards. 🐈
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.
Related
You might also be interested in these packages:
- formidable: A node.js module for parsing form data, especially file uploads. | homepage
- ip-filter: Filters valid IPv4 or IPv6 against glob pattern, array, string and etc. If match… more | homepage
- koa-body-parsers: collection of koa body parsers | homepage
- koa-bodyparser: a body parser for koa | homepage
- koa-ip-filter: koa middleware to filter request IPs or custom ID with glob patterns, array, string,… more | homepage
- koa: Koa web app framework | homepage
- koala: Koa Framework Suite | homepage
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
But before doing anything, please read the CONTRIBUTING.md guidelines.
Contributing Recipes
Recipes are just different use cases, written in form of README in human language. Showing some "Pro Tips" and tricks, answering common questions and so on. They look like tests, but in more readable and understandable way for humans - mostly for beginners that not reads or understand enough the README or API and tests.
- They are in form of folders in the root
recipes/
folder: for examplerecipes/[short-meaningful-recipe-name]/
. - In recipe folder should exist
README.md
file: see recipes/multipart/README.md. - The examples from the recipe README.md should also exist as separate
.js
files. - Examples in recipe folder also should be working and actual.
It would be great if you follow these steps when you want to fix, update or create a recipes. 😎
- Title for recipe idea should start with
[recipe]
: for example[recipe] my awesome recipe
- Title for new recipe (PR) should also start with
[recipe]
. - Titles of Pull Requests or Issues for fixing/updating some existing recipes should start with
[recipe-fix]
.
It will help a lot, thanks in advance! 😋