body

Reads and parses the request body based on Content-Type. Supports JSON variants (including RFC 7386 merge-patch and RFC 6902 json-patch), application/x-www-form-urlencoded, and multipart/form-data. Includes a fast path for identity-encoded application/json that bypasses the full stream pipeline.

Pipeline stage: Validation

Import

import {body} from '@centralping/ergo';

Options

Option	Type	Default	Description
limit	number	1048576 (1 MiB)	Maximum body size in bytes
decompressedLimit	number	min(10 × limit, 10 MiB)	Maximum decompressed body size (bomb protection)
types	string[]	See below	Allowed Content-Type MIME types
charset	string	'utf-8'	Default character encoding

Default types

• application/vnd.api+json
• application/json
• application/merge-patch+json (RFC 7386)
• application/json-patch+json (RFC 6902)
• application/x-www-form-urlencoded
• multipart/form-data

Return Value

On success, the middleware returns a body descriptor stored on the domain accumulator at acc.body:

{
  type: 'application/json',
  charset: 'utf-8',
  encoding: 'identity',
  length: 42,
  received: 42,
  raw: '{"name":"Jane"}',
  parsed: {name: 'Jane'}
}

Property	Type	Description
type	string	Content-Type MIME type (e.g. 'application/json', 'application/merge-patch+json')
charset	string	Character encoding (e.g. 'utf-8')
encoding	string	Content-Encoding (e.g. 'identity', 'gzip')
length	number | undefined	Content-Length header value; undefined for chunked transfers
received	number	Actual bytes received
boundary	string | undefined	Multipart boundary; undefined for non-multipart types
raw	string	Raw body string before parsing
parsed	unknown | undefined	Parsed body (JSON object, URLSearchParams entries, or multipart parts array)

Content-type dispatch

The type field reflects the parsed MIME type from the request’s Content-Type header. For JSON variants (application/vnd.api+json, application/json, application/merge-patch+json, application/json-patch+json), the body is always parsed with JSON.parse — the type value carries the semantic distinction. Use acc.body.type in your execute handler to dispatch logic based on the content type the client sent. See the PATCH Semantics recipe for a complete dispatch pattern.

Multipart Parsed Shape

For multipart/form-data requests, acc.body includes a boundary field and parsed is an array of part objects — one per form field or file:

{
  type: 'multipart/form-data',
  charset: 'utf-8',
  encoding: 'identity',
  length: 4096,
  received: 4096,
  boundary: '----WebKitFormBoundary7MA4YWxkTrZu0gW',
  raw: '...',
  parsed: [
    {headers: {...}, name: 'avatar', filename: 'photo.png', body: Buffer},
    {headers: {...}, name: 'description', filename: undefined, body: Buffer},
  ],
}

Property	Type	Description
headers	object	RFC 7578 §4.8 headers (content-disposition, content-type, content-transfer-encoding) as {type, parameters} entries
name	string	The form field name from Content-Disposition
filename	string | undefined	The original filename (present only for file fields)
body	Buffer	The raw binary content of the part

File fields have a filename property; regular form fields do not. See the File Upload recipe for working examples of filtering files from text inputs in both standalone and ergo-router contexts.

Error Responses

Status	Condition
400 Bad Request	Content-Length mismatch, malformed body, or parse failure
411 Length Required	Neither Content-Length nor chunked encoding present
413 Payload Too Large	Body exceeds limit (or decompressed body exceeds decompressedLimit)
415 Unsupported Media Type	Unrecognized content type or unsupported Content-Encoding

Usage

Standalone

import {compose, body} from '@centralping/ergo';

const pipeline = compose(
  body({limit: 2 * 1024 * 1024}),
  // acc.body.parsed === { name: "Jane" }
);

ergo-router

router.post('/users', {
  body: {limit: 2 * 1024 * 1024},
  validate: {
    body: {
      type: 'object',
      properties: {name: {type: 'string'}},
      required: ['name'],
    },
  },
  execute: (req, res, acc) => ({
    response: {
      statusCode: 201,
      body: {id: '1', name: acc.body.parsed.name},
    },
  }),
});

RFC References

• RFC 7578 — multipart/form-data
• RFC 7386 — JSON Merge Patch
• RFC 6902 — JSON Patch

Related Recipes

• File Upload — Multipart file uploads with size limits and accessing parsed file content
• PATCH Semantics — RFC 7386 merge-patch and RFC 6902 JSON Patch with content-type enforcement

API Reference

See the auto-generated body API docs.