Skip to content

koajs/bodyparser

Folders and files

NameName
Last commit message
Last commit date

Latest commit

031348a · Jun 14, 2024
Jun 25, 2023
Jun 25, 2023
Jun 14, 2024
Jun 14, 2024
Jun 25, 2023
Apr 17, 2020
Jun 25, 2023
Mar 25, 2024
Feb 17, 2014
Jul 8, 2023
Jun 25, 2023
Apr 8, 2024
Jun 25, 2023
Jun 25, 2023

Repository files navigation

NPM version build status Coveralls node version

Koa body parsing middleware, based on co-body. support json, form and text type body.

Parse incoming request bodies in a middleware before your handlers, available under the ctx.request.body property.

⚠ Notice: This module doesn't support parsing multipart format data, please use @koa/multer to parse multipart format data.

Install

NPM

$ npm i @koa/bodyparser --save

Usage

const Koa = require("koa");
const { bodyParser } = require("@koa/bodyparser");

const app = new Koa();
app.use(bodyParser());

app.use((ctx) => {
  // the parsed body will store in ctx.request.body
  // if nothing was parsed, body will be an empty object {}
  ctx.body = ctx.request.body;
});

Options

  • patchNode: patch request body to Node's ctx.req, default is false.

  • enableTypes: parser will only parse when request type hits enableTypes, support json/form/text/xml, default is ['json', 'form'].

  • encoding: requested encoding. Default is utf-8 by co-body.

  • formLimit: limit of the urlencoded body. If the body ends up being larger than this limit, a 413 error code is returned. Default is 56kb.

  • jsonLimit: limit of the json body. Default is 1mb.

  • textLimit: limit of the text body. Default is 1mb.

  • xmlLimit: limit of the xml body. Default is 1mb.

  • jsonStrict: when set to true, JSON parser will only accept arrays and objects. Default is true. See strict mode in co-body. In strict mode, ctx.request.body will always be an object(or array), this avoid lots of type judging. But text body will always return string type.

  • detectJSON: custom json request detect function. Default is null.

    app.use(
      bodyParser({
        detectJSON(ctx) {
          return /\.json$/i.test(ctx.path);
        },
      })
    );
  • extendTypes: support extend types:

    app.use(
      bodyParser({
        extendTypes: {
          // will parse application/x-javascript type body as a JSON string
          json: ["application/x-javascript"],
        },
      })
    );
  • onError: support custom error handle, if koa-bodyparser throw an error, you can customize the response like:

    app.use(
      bodyParser({
        onError(err, ctx) {
          ctx.throw(422, "body parse error");
        },
      })
    );
  • enableRawChecking: support the already parsed body on the raw request by override and prioritize the parsed value over the sended payload. (default is false)

  • parsedMethods: declares the HTTP methods where bodies will be parsed, default ['POST', 'PUT', 'PATCH'].

  • disableBodyParser: you can dynamic disable body parser by set ctx.disableBodyParser = true.

    app.use((ctx, next) => {
      if (ctx.path === "/disable") ctx.disableBodyParser = true;
      return next();
    });
    app.use(bodyParser());

Raw Body

You can access raw request body by ctx.request.rawBody after koa-bodyparser when:

  1. koa-bodyparser parsed the request body.
  2. ctx.request.rawBody is not present before koa-bodyparser.

Koa v1.x.x Support

To use koa-bodyparser with koa@1.x.x, please use bodyparser 2.x.

$ npm install koa-bodyparser@2 --save

usage

const Koa = require("koa");
const bodyParser = require("@koa/bodyparser");

const app = new Koa();
app.use(bodyParser());

app.use((ctx) => {
  // the parsed body will store in ctx.request.body
  // if nothing was parsed, body will be an empty object {}
  ctx.body = ctx.request.body;
});

Licences

MIT