{"id":13527666,"url":"https://github.com/koajs/koa-body","last_synced_at":"2025-05-13T17:04:33.284Z","repository":{"id":13724914,"uuid":"16419090","full_name":"koajs/koa-body","owner":"koajs","description":"koa body parser middleware","archived":false,"fork":false,"pushed_at":"2025-03-19T07:17:28.000Z","size":1012,"stargazers_count":950,"open_issues_count":53,"forks_count":132,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-12T12:24:13.045Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koajs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-01-31T20:03:05.000Z","updated_at":"2025-05-07T10:35:14.000Z","dependencies_parsed_at":"2022-09-04T23:01:36.022Z","dependency_job_id":"181cdd81-7aee-430b-a7ae-9d8f10f271b1","html_url":"https://github.com/koajs/koa-body","commit_stats":{"total_commits":190,"total_committers":46,"mean_commits":4.130434782608695,"dds":0.7157894736842105,"last_synced_commit":"c93a643f7cee87e3a348434b7a0421e4f1792cbc"},"previous_names":["dlau/koa-body"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-body","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-body/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-body/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-body/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koajs","download_url":"https://codeload.github.com/koajs/koa-body/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253990458,"owners_count":21995773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:01:56.230Z","updated_at":"2025-05-13T17:04:33.237Z","avatar_url":"https://github.com/koajs.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# koa-body\n\n[![CI](https://github.com/koajs/koa-body/actions/workflows/ci.yaml/badge.svg)](https://github.com/koajs/koa-body/actions/workflows/ci.yaml)\n[![KoaJs Slack](https://img.shields.io/badge/Koa.Js-Slack%20Channel-Slack.svg?longCache=true)](https://communityinviter.com/apps/koa-js/koajs)\n\n---\n\n\u003e A full-featured [`koa`](https://github.com/koajs/koa) body parser middleware. Supports `multipart`, `urlencoded`, and `json` request bodies. Provides the same functionality as Express's bodyParser - [`multer`](https://github.com/expressjs/multer).\n\n## Install\n\n\u003e Install with [npm](https://github.com/npm/npm)\n\n```\nnpm install koa-body\n```\n\n## Features\n\n- can handle requests such as:\n  - **multipart/form-data**\n  - **application/x-www-form-urlencoded**\n  - **application/json**\n  - **application/json-patch+json**\n  - **application/vnd.api+json**\n  - **application/csp-report**\n  - **text/xml**\n- option for patch to Koa or Node, or either\n- file uploads\n- body, fields and files size limiting\n\n## Hello World - Quickstart\n\n```sh\nnpm install koa koa-body # Note that Koa requires Node.js 7.6.0+ for async/await support\n```\n\nindex.js:\n\n```js\nconst Koa = require('koa');\nconst { koaBody } = require('koa-body');\n\nconst app = new Koa();\n\napp.use(koaBody());\napp.use((ctx) =\u003e {\n  ctx.body = `Request Body: ${JSON.stringify(ctx.request.body)}`;\n});\n\napp.listen(3000);\n```\n\n```sh\nnode index.js\ncurl -i http://localhost:3000/users -d \"name=test\"\n```\n\nOutput:\n\n```text\nHTTP/1.1 200 OK\nContent-Type: text/plain; charset=utf-8\nContent-Length: 29\nDate: Wed, 03 May 2017 02:09:44 GMT\nConnection: keep-alive\n\nRequest Body: {\"name\":\"test\"}%\n```\n\n**For a more comprehensive example, see** `examples/multipart.js`\n\n## Usage with [koa-router](https://github.com/alexmingoia/koa-router)\n\nIt'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.\n\n```js\nconst Koa = require('koa');\nconst app = new Koa();\nconst router = require('koa-router')();\nconst { koaBody } = require('koa-body');\n\nrouter.post('/users', koaBody(), (ctx) =\u003e {\n  console.log(ctx.request.body);\n  // =\u003e POST body\n  ctx.body = JSON.stringify(ctx.request.body);\n});\n\napp.use(router.routes());\n\napp.listen(3000);\nconsole.log('curl -i http://localhost:3000/users -d \"name=test\"');\n```\n\n## Usage with unsupported text body type\n\nFor unsupported text body type, for example, `text/xml`, you can use the unparsed request body at `ctx.request.body`. For the text content type, the `includeUnparsed` setting is not required.\n\n```js\n// xml-parse.js:\nconst Koa = require('koa');\nconst { koaBody } = require('koa-body');\nconst convert = require('xml-js');\n\nconst app = new Koa();\n\napp.use(koaBody());\napp.use((ctx) =\u003e {\n  const obj = convert.xml2js(ctx.request.body);\n  ctx.body = `Request Body: ${JSON.stringify(obj)}`;\n});\n\napp.listen(3000);\n```\n\n```sh\nnode xml-parse.js\ncurl -i http://localhost:3000/users -H \"Content-Type: text/xml\" -d '\u003c?xml version=\"1.0\"?\u003e\u003ccatalog id=\"1\"\u003e\u003c/catalog\u003e'\n```\n\nOutput:\n\n```text\nHTTP/1.1 200 OK\nContent-Type: text/plain; charset=utf-8\nContent-Length: 135\nDate: Tue, 09 Jun 2020 11:17:38 GMT\nConnection: keep-alive\n\nRequest Body: {\"declaration\":{\"attributes\":{\"version\":\"1.0\"}},\"elements\":[{\"type\":\"element\",\"name\":\"catalog\",\"attributes\":{\"id\":\"1\"}}]}%\n```\n\n## Options\n\n\u003e Options available for `koa-body`. Four custom options, and others are from `raw-body` and `formidable`.\n\n- `patchNode` **{Boolean}** Patch request body to Node's `ctx.req`, default `false`\n- `patchKoa` **{Boolean}** Patch request body to Koa's `ctx.request`, default `true`\n- `jsonLimit` **{String|Integer}** The byte (if integer) limit of the JSON body, default `1mb`\n- `formLimit` **{String|Integer}** The byte (if integer) limit of the form body, default `56kb`\n- `textLimit` **{String|Integer}** The byte (if integer) limit of the text body, default `56kb`\n- `encoding` **{String}** Sets encoding for incoming form fields, default `utf-8`\n- `multipart` **{Boolean}** Parse multipart bodies, default `false`\n- `urlencoded` **{Boolean}** Parse urlencoded bodies, default `true`\n- `text` **{Boolean}** Parse text bodies, such as XML, default `true`\n- `json` **{Boolean}** Parse JSON bodies, default `true`\n- `jsonStrict` **{Boolean}** Toggles co-body strict mode; if set to true - only parses arrays or objects, default `true`\n- `includeUnparsed` **{Boolean}** Toggles co-body returnRawBody option; if set to true, for form encoded and JSON requests the raw, unparsed request body will be attached to `ctx.request.body` using a `Symbol` ([see details](#a-note-about-unparsed-request-bodies)), default `false`\n- `formidable` **{Object}** Options to pass to the formidable multipart parser\n- `onError` **{Function}** Custom error handle, if throw an error, you can customize the response - onError(error, context), default will throw\n- `parsedMethods` **{String[]}** Declares the HTTP methods where bodies will be parsed, default `['POST', 'PUT', 'PATCH']`. Replaces `strict` option.\n\n## A note about `parsedMethods`\n\n\u003e see [http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-6.3](http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-6.3)\n\n- `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.\n- koa-body is strict by default, parsing only `POST`, `PUT`, and `PATCH` requests\n- you may use either the enumeration or strings to chose which methods to parse: For example, `HttpMethodEnum.PATCH`\n\n## File Support\n\nUploaded files are accessible via `ctx.request.files`.\n\n## A note about unparsed request bodies\n\nSome applications require cryptographic verification of request bodies, for example webhooks from slack or stripe. The unparsed body can be accessed if `includeUnparsed` is `true` in koa-body's options. When enabled, import the symbol for accessing the request body from `unparsed = require('koa-body/unparsed.js')`, or define your own accessor using `unparsed = Symbol.for('unparsedBody')`. Then the unparsed body is available using `ctx.request.body[unparsed]`.\n\n## Some options for formidable\n\n\u003e See [node-formidable](https://github.com/felixge/node-formidable) for a full list of options\n\n- `maxFields` **{Integer}** Limits the number of fields that the querystring parser will decode, default `1000`\n- `maxFieldsSize` **{Integer}** Limits the amount of memory all fields together (except files) can allocate in bytes. If this value is exceeded, an 'error' event is emitted, default `2mb (2 * 1024 * 1024)`\n- `uploadDir` **{String}** Sets the directory for placing file uploads in, default `os.tmpDir()`\n- `keepExtensions` **{Boolean}** Files written to `uploadDir` will include the extensions of the original files, default `false`\n- `hashAlgorithm` **{String}** If you want checksums calculated for incoming files, set this to either `'sha1'` or `'md5'`, default `false`\n- `multiples` **{Boolean}** Multiple file uploads or no, default `true`\n- `onFileBegin` **{Function}** Special callback on file begin. The function is executed directly by formidable. It can be used to rename files before saving them to disk. [See the docs](https://github.com/felixge/node-formidable#filebegin)\n\n## Changelog\n\nPlease see the [Changelog](./CHANGELOG.md) for a summary of changes.\n\n## Tests\n\n```\n$ npm test\n```\n\n## License\n\nThe MIT License, 2014 [Charlike Mike Reagent](https://github.com/tunnckoCore) ([@tunnckoCore](https://twitter.com/tunnckoCore)) and [Daryl Lau](https://github.com/dlau) ([@daryllau](https://twitter.com/daryllau))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoajs%2Fkoa-body","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoajs%2Fkoa-body","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoajs%2Fkoa-body/lists"}