@molecule/api-middleware-body-parser

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Body parser middleware for molecule.dev.

Core interface — the actual implementation is provided via bonds. Install a body parser bond (e.g., @molecule/api-middleware-body-parser-express) to provide JSON and multipart form data parsing.

Quick Start

import { createJsonParser } from '@molecule/api-middleware-body-parser'
// Webhook route FIRST, with a raw parser, so signature verification sees the exact bytes.
app.post(
  '/api/users/payment-notification/stripe',
  express.raw({ type: 'application/json' }),
  stripeWebhookHandler,
)
// Then the global JSON parser (bounded) for everything else.
app.use(createJsonParser({ limit: '1mb' }))

Type

middleware

Installation

npm install @molecule/api-middleware-body-parser @molecule/api-bond

API

Interfaces

JsonParserOptions

Options for JSON body parsing (limit, strict mode, content type).

interface JsonParserOptions {
  limit?: string | number
  strict?: boolean
  type?: string | string[]
}

Types

JsonParserFactory

Factory function type for creating JSON parsers with options.

type JsonParserFactory = (options?: JsonParserOptions) => Middleware

Middleware

Generic middleware type — framework-agnostic.

type Middleware = (req: unknown, res: unknown, next: (err?: unknown) => void) => void

Functions

bodyParser(req, res, next)

Default body parser middleware that delegates to the bonded implementation.

function bodyParser(req: unknown, res: unknown, next: (err?: unknown) => void): void

• req — The incoming request object.
• res — The response object.
• next — The next middleware function.

Returns: The result of the bonded body parser invocation.

createJsonParser(options)

Creates a JSON body parser with custom options via the bonded factory.

function createJsonParser(options?: JsonParserOptions): Middleware

• options — JSON parsing options (limit, strict mode, content type).

Returns: A middleware function that parses JSON request bodies.

getBodyParser()

Gets the bonded body parser middleware.

function getBodyParser(): Middleware

Returns: The bonded body parser middleware function.

getJsonParserFactory()

Gets the bonded JSON parser factory.

function getJsonParserFactory(): JsonParserFactory | null

Returns: The factory function, or null if none has been bonded.

hasBodyParser()

Checks if a body parser middleware has been bonded.

function hasBodyParser(): boolean

Returns: true if a body parser is available.

setBodyParser(parser)

Bonds a body parser middleware implementation for use by getBodyParser() and bodyParser.

function setBodyParser(parser: Middleware): void

• parser — The middleware function that parses request bodies.

setJsonParserFactory(factory)

Bonds a JSON parser factory for creating parsers with custom options (e.g., size limits).

function setJsonParserFactory(factory: JsonParserFactory): void

• factory — A function that creates JSON parser middleware from options.

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-bond ^1.0.1

Runtime Dependencies

• @molecule/api-bond

• Always set a limit ({@link JsonParserOptions}.limit, e.g. '1mb'). An unbounded body lets a client exhaust memory (DoS) — pick a cap that fits your largest legit payload.

• Provider webhooks need the RAW body — mount their route BEFORE the JSON parser. A JSON parser consumes + rewrites the body, which breaks signature verification (Stripe's constructEvent and friends hash the exact bytes). Give the webhook route express.raw(...) (or capture req.rawBody) and register it before the global JSON body parser. See @molecule/api-payments-stripe.