koa-body

What is koa-body?

koa-body is a middleware for Koa that parses incoming request bodies in various formats, including JSON, URL-encoded, and multipart forms. It simplifies handling file uploads and form submissions in Koa applications.

What are koa-body's main functionalities?

JSON Body Parsing

This feature allows you to parse JSON bodies from incoming requests. The middleware automatically parses the JSON and makes it available in `ctx.request.body`.

const Koa = require('koa');
const koaBody = require('koa-body');
const app = new Koa();

app.use(koaBody());

app.use(async ctx => {
  if (ctx.method === 'POST') {
    ctx.body = `Received JSON data: ${JSON.stringify(ctx.request.body)}`;
  } else {
    ctx.body = 'Send a POST request with JSON data';
  }
});

app.listen(3000);

URL-encoded Body Parsing

This feature allows you to parse URL-encoded bodies from incoming requests. The middleware automatically parses the URL-encoded data and makes it available in `ctx.request.body`.

const Koa = require('koa');
const koaBody = require('koa-body');
const app = new Koa();

app.use(koaBody({ urlencoded: true }));

app.use(async ctx => {
  if (ctx.method === 'POST') {
    ctx.body = `Received URL-encoded data: ${JSON.stringify(ctx.request.body)}`;
  } else {
    ctx.body = 'Send a POST request with URL-encoded data';
  }
});

app.listen(3000);

Multipart Form Parsing

This feature allows you to parse multipart form data, which is commonly used for file uploads. The middleware automatically parses the multipart data and makes it available in `ctx.request.files`.

const Koa = require('koa');
const koaBody = require('koa-body');
const app = new Koa();

app.use(koaBody({ multipart: true }));

app.use(async ctx => {
  if (ctx.method === 'POST') {
    const files = ctx.request.files;
    ctx.body = `Received files: ${JSON.stringify(files)}`;
  } else {
    ctx.body = 'Send a POST request with multipart form data';
  }
});

app.listen(3000);

Other packages similar to koa-body

koa-bodyparser

koa-bodyparser is a middleware for Koa that parses JSON and URL-encoded request bodies. It is simpler and more lightweight compared to koa-body, but it does not support multipart form data parsing.

koa-multer

koa-multer is a middleware for handling multipart/form-data, which is primarily used for uploading files. It is similar to koa-body in terms of file upload capabilities but does not handle JSON or URL-encoded bodies.

koa-better-body

koa-better-body is a more feature-rich alternative to koa-body, supporting JSON, URL-encoded, and multipart form data parsing. It also offers additional features like custom body parsers and file renaming.

README

koa-body

KoaJS middleware that patch body (to Koa#req.body or Node#request.body, or bother) and parse body to json/form with co-body. koa middleware for parsing a request body. This is a simple wrapper around co-body. Provides similar functionality to the express's request body parser

Doesn't support multipart. Discuss

Install

$ npm install koa-body

Options

Initialize koa-better-body middleware with the given options:

• patchNode Set the body parameter in the Node request object this.req.body defauls to false
• patchKoa Set the body parameter in the Koa request object this.request.body defaults to true
• jsonLimit limits application/json request body, co-body's option defauls to '1mb'
• formLimit limits application/x-www-form-urlencoded request body, co-body's option defauls to '56kb'
• encoding request encoding, co-body's option defauls to 'utf-8'

Usage

var app        = require('koa')()
  , betterBody = require('./index');
  
/**
 * By default body is patching to
 * Koa's ctx.request
 */
app.use(betterBody({patchNode: false, jsonLimit: '1kb', formLimit: '1kb'}));

app.use(function *(next){
  var patchKoa  = (this.request.body) ? this.request.body : 'patchKoa=true, by default';
  var patchNode = (this.req.body) ? this.req.body : 'patchNode=false, by default';

  if (this.request.method == 'POST') {
    this.status = 201;
  } else if (this.request.method == 'GET') {
    this.status = 200
  }

  this.body = JSON.stringify({koa: patchKoa, node: patchNode});

  if (this.request.method == 'PUT') {
    this.status = 200;
    this.body = 'resource updated successfully';
  }
  if (this.request.method == 'DELETE') {
    this.status = 204;
    this.body = 'resource deleted successfully';
  }
});

var port = process.env.PORT || 3333;
app.listen(port);
console.log('Koa server start listening to port '+port);

Usage with koa-router

It's generally better to only parse the body as needed, if using a router that supports middleware composition, we can inject it only for certain routes.

var app     = require('koa')(),
    router  = require('koa-router'),
    koaBody = require('koa-body')();

app.use(router());

app.post('/users', koaBody,
  function *(next) {
    console.log(this.request.body);
    // => POST body
  }
);

Features

• 14 passing (174ms) tests
• co-body options: jsonLimit, formLimit, encoding
• freedom to choose - patch body to
  • KoaJS Context this.request.body
  • NodeJS Context this.req.body
• only 1 dependency: co-body

Test, Bench, Example

First run npm install before run anything.

npm test
npm start

Credit

Daryl Lau (creator)	George Yanev (contrib)

LICENSE

The MIT License, 2014 Daryl Lau (@daryllau), Charlike Mike Reagent (@tunnckoCore)