@vukoa/koa-better-body

    3.3.9 • Public • Published

    koa-better-body npm version License Libera Manifesto

    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 the project to show your ❤️ and support.

    Code style CircleCI linux build CodeCov coverage status Renovate App Status Make A Pull Request Time Since Last Commit

    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.

    Conventional Commits Minimum Required Nodejs NPM Downloads Monthly NPM Downloads Total Share Love Tweet Twitter

    Project is semantically versioned & automatically released from GitHub Actions with Lerna.

    Become a Patron Buy me a Kofi PayPal Donation Bitcoin Coinbase Keybase PGP

    Topic Contact
    Any legal or licensing questions, like private or commerical use tunnckocore_legal
    For any critical problems and security reports tunnckocore_security
    Consulting, professional support, personal or team training tunnckocore_consulting
    For any questions about Open Source, partnerships and sponsoring tunnckocore_opensource

    Features

    Table of Contents

    (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-body

    API

    Generated using jest-runner-docs.

    koaBetterBody

    Robust body parser for koa@1, also works for koa@2 (with deprecations). Will also work for future koa@3 with koa-convert.

    Signature

    function(options)

    Params

    • options {object} - see more on options section
    • returns {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.

    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}: 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. 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 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. More info below.
    • qs {Object}: Alias of opts.querystring. All opts are also passed to qs or querystring module.
    • 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. 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. 🐈

    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.

    back to top

    See Also

    Some of these projects are used here or were inspiration for this one, others are just related. So, thanks for your existance!

    back to top

    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? 💵 Check the OpenSource Commision (tier). 🎉 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! 🚀

    Not financial support? Okey! Pull requests, stars and all kind of contributions are always welcome.

    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

    🚇 💻 📖 🤔 🚧 ⚠️

    back to top

    License

    Copyright (c) 2014-present, Charlike Mike Reagent <opensource@tunnckocore.com> & contributors.
    Released under the MPL-2.0 License.

    Install

    npm i @vukoa/koa-better-body

    DownloadsWeekly Downloads

    5

    Version

    3.3.9

    License

    MPL-2.0

    Unpacked Size

    51.4 kB

    Total Files

    3

    Last publish

    Collaborators

    • avatar
    • avatar