0
# Koa Body Parser
1

2
Koa Body Parser is a body parser middleware for Koa.js applications that parses HTTP request bodies in multiple formats including JSON, URL-encoded forms, text, and XML. Built on top of co-body, it offers configurable size limits for different content types, support for custom content-type detection, error handling customization, and the ability to dynamically disable parsing on a per-request basis.
3

4
## Package Information
5

6
- **Package Name**: koa-bodyparser
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install koa-bodyparser`
10

11
## Core Imports
12

13
```javascript
14
const bodyParser = require('koa-bodyparser');
15
```
16

17
**Note**: This package only supports CommonJS. ES module import is not officially supported.
18

19
## Basic Usage
20

21
```javascript
22
const Koa = require('koa');
23
const bodyParser = require('koa-bodyparser');
24

25
const app = new Koa();
26

27
// Use with default options
28
app.use(bodyParser());
29

30
app.use(async ctx => {
31
  // Parsed body will be in ctx.request.body
32
  // Raw body will be in ctx.request.rawBody
33
  console.log('Parsed body:', ctx.request.body);
34
  console.log('Raw body:', ctx.request.rawBody);
35
  ctx.body = ctx.request.body;
36
});
37

38
app.listen(3000);
39
```
40

41
## Architecture
42

43
Koa Body Parser is designed as a middleware factory that creates Koa-compatible middleware functions. The architecture includes:
44

45
- **Factory Function**: The main export creates configured middleware instances
46
- **Content Type Detection**: Uses `type-is` library for robust content type matching
47
- **Parsing Engine**: Delegates to `co-body` for actual parsing operations
48
- **Option Processing**: Internal utilities for handling configuration options
49
- **Error Handling**: Configurable error handling with sensible defaults
50

51
The middleware follows Koa's async/await pattern and integrates seamlessly with the Koa context object.
52

53
## Capabilities
54

55
### Body Parser Factory Function
56

57
The main export is a factory function that creates a Koa middleware function for parsing HTTP request bodies in multiple formats.
58

59
```javascript { .api }
60
/**
61
 * Creates a body parser middleware for Koa applications
62
 * @param {BodyParserOptions} [options] - Configuration options
63
 * @returns {KoaMiddleware} Koa middleware function: (ctx, next) => Promise<void>
64
 */
65
function bodyParser(options);
66

67
/**
68
 * Default export of the koa-bodyparser module
69
 */
70
module.exports = bodyParser;
71

72
/**
73
 * Koa middleware function signature
74
 * @typedef {Function} KoaMiddleware
75
 * @param {Context} ctx - Koa context object
76
 * @param {Function} next - Next middleware function
77
 * @returns {Promise<void>}
78
 */
79
```
80

81
**Usage Examples:**
82

83
```javascript
84
// Basic usage with defaults
85
app.use(bodyParser());
86

87
// With custom options
88
app.use(bodyParser({
89
  jsonLimit: '2mb',
90
  formLimit: '100kb',
91
  enableTypes: ['json', 'form', 'text'],
92
  strict: false,
93
  onerror: (err, ctx) => {
94
    ctx.throw(422, 'Body parsing failed');
95
  }
96
}));
97

98
// With custom JSON detection
99
app.use(bodyParser({
100
  detectJSON: (ctx) => {
101
    return /\.json$/i.test(ctx.path);
102
  }
103
}));
104

105
// With extended content types
106
app.use(bodyParser({
107
  extendTypes: {
108
    json: ['application/x-javascript'],
109
    form: ['application/x-my-form'],
110
    text: ['text/html']
111
  }
112
}));
113
```
114

115
### Dynamic Disabling
116

117
The middleware can be disabled on a per-request basis by setting a context property.
118

119
```javascript { .api }
120
/**
121
 * Disable body parsing for specific requests
122
 * Set ctx.disableBodyParser = true before the bodyParser middleware
123
 */
124
ctx.disableBodyParser = true;
125
```
126

127
**Usage Example:**
128

129
```javascript
130
app.use(async (ctx, next) => {
131
  // Disable parsing for specific routes
132
  if (ctx.path === '/webhook' || ctx.path.startsWith('/upload/')) {
133
    ctx.disableBodyParser = true;
134
  }
135
  await next();
136
});
137

138
app.use(bodyParser());
139
```
140

141
## Configuration Options
142

143
### BodyParserOptions
144

145
```javascript { .api }
146
/**
147
 * Configuration options for the body parser
148
 * @typedef {Object} BodyParserOptions
149
 */
150
interface BodyParserOptions {
151
  /** 
152
   * Parser will only parse when request type matches these types
153
   * @default ['json', 'form']
154
   */
155
  enableTypes?: ('json' | 'form' | 'text' | 'xml')[];
156

157
  /** 
158
   * Requested encoding for parsing
159
   * @default 'utf-8'
160
   */
161
  encoding?: string;
162

163
  /** 
164
   * Limit for JSON body size
165
   * @default '1mb'
166
   */
167
  jsonLimit?: string;
168

169
  /** 
170
   * Limit for URL-encoded form body size
171
   * @default '56kb'
172
   */
173
  formLimit?: string;
174

175
  /** 
176
   * Limit for text body size
177
   * @default '1mb'
178
   */
179
  textLimit?: string;
180

181
  /** 
182
   * Limit for XML body size
183
   * @default '1mb'
184
   */
185
  xmlLimit?: string;
186

187
  /** 
188
   * When true, JSON parser only accepts arrays and objects, not primitives
189
   * @default true
190
   */
191
  strict?: boolean;
192

193
  /** 
194
   * Custom function to detect if request should be parsed as JSON
195
   * @default null
196
   */
197
  detectJSON?: (ctx: Context) => boolean;
198

199
  /** 
200
   * Extend supported content types for each parser
201
   * @default {}
202
   */
203
  extendTypes?: {
204
    json?: string | string[];
205
    form?: string | string[];
206
    text?: string | string[];
207
    xml?: string | string[];
208
  };
209

210
  /** 
211
   * Custom error handler for parsing errors
212
   * @default undefined
213
   */
214
  onerror?: (err: Error, ctx: Context) => void;
215
}
216

217
/**
218
 * Koa context object (subset of properties used by body parser)
219
 * @typedef {Object} Context
220
 */
221
interface Context {
222
  /** Request object containing body and rawBody after parsing */
223
  request: {
224
    /** Parsed body content - set by the middleware */
225
    body?: any;
226
    /** Raw body string - set by the middleware when parsing occurs */
227
    rawBody?: string;
228
    /** Get request header value */
229
    get(field: string): string | undefined;
230
    /** Check if request matches given content types */
231
    is(types: string | string[]): string | false | null;
232
  };
233
  /** Set to true to disable body parsing for this request */
234
  disableBodyParser?: boolean;
235
  /** Koa's throw method for error handling */
236
  throw(status: number, message?: string): never;
237
}
238
```
239

240
## Context Properties
241

242
The middleware adds the following properties to the Koa context:
243

244
### ctx.request.body
245

246
```javascript { .api }
247
/**
248
 * Parsed request body content - set by the middleware after parsing
249
 * @type {any}
250
 * @description
251
 * - JSON: Parsed as object/array (or primitive if strict=false)
252
 * - Form: Parsed as object with URL-decoded properties  
253
 * - Text/XML: Parsed as string
254
 * - No parseable content: Empty object {}
255
 * - undefined: Before middleware runs or when parsing is disabled
256
 */
257
ctx.request.body;
258
```
259

260
### ctx.request.rawBody
261

262
```javascript { .api }
263
/**
264
 * Raw request body as string - set by the middleware when parsing occurs
265
 * @type {string|undefined}
266
 * @description Only set when parsing occurs and wasn't previously set
267
 */
268
ctx.request.rawBody;
269
```
270

271
### ctx.disableBodyParser
272

273
```javascript { .api }
274
/**
275
 * Flag to skip body parsing for the current request
276
 * @type {boolean}
277
 * @description When set to true before the middleware runs, skips body parsing
278
 */
279
ctx.disableBodyParser;
280
```
281

282
## Default Content Types
283

284
The middleware recognizes these content types by default:
285

286
**JSON Types:**
287
- `'application/json'`
288
- `'application/json-patch+json'`
289
- `'application/vnd.api+json'`
290
- `'application/csp-report'`
291
- `'application/scim+json'`
292

293
**Form Types:**
294
- `'application/x-www-form-urlencoded'`
295

296
**Text Types:**
297
- `'text/plain'`
298

299
**XML Types:**
300
- `'text/xml'`
301
- `'application/xml'`
302

303
## Error Handling
304

305
The middleware handles the following error scenarios:
306

307
- **413 Payload Too Large**: When body size exceeds configured limits (`jsonLimit`, `formLimit`, `textLimit`, `xmlLimit`)
308
- **400 Bad Request**: For invalid JSON in strict mode
309
- **Custom Error Handling**: Via the `onerror` option for customized error responses
310

311
**Error Handling Example:**
312

313
```javascript
314
app.use(bodyParser({
315
  onerror: (err, ctx) => {
316
    // Log the error
317
    console.error('Body parsing error:', err.message);
318
    
319
    // Send custom error response
320
    if (err.status === 413) {
321
      ctx.throw(413, 'Request body too large');
322
    } else if (err.status === 400) {
323
      ctx.throw(400, 'Invalid request body format');
324
    } else {
325
      ctx.throw(422, 'Unable to parse request body');
326
    }
327
  }
328
}));
329
```
330

331
## Limitations
332

333
- **Multipart Forms**: Does not support `multipart/form-data` parsing. Use `@koa/multer` for file uploads and multipart data.
334
- **Node.js Version**: Requires Node.js >= 8.0.0
335
- **Koa Version**: Designed for Koa v2+. Use `koa-bodyparser@2` for Koa v1 compatibility.
336
- **Memory Usage**: Large request bodies are loaded into memory. Configure appropriate size limits to prevent memory exhaustion.
337

338
## Dependencies
339

340
The middleware depends on these core libraries:
341

342
- **co-body**: Core parsing functionality for different content types
343
- **copy-to**: Object copying utility for option handling
344
- **type-is**: Content type detection and matching