@openaddresses/batch-schema 10.25.0 → 10.27.0

package/lib/schema.ts

@@ -4,15 +4,16 @@ import path from 'node:path';
 import morgan from 'morgan';
 import bodyparser from 'body-parser';
 import Err from '@openaddresses/batch-error';
-import { Type } from '@sinclair/typebox';
+import { Kind } from '@sinclair/typebox';
 import type { Static, TSchema } from '@sinclair/typebox';
 import { OpenAPIV3 as Doc } from 'openapi-types'
 import { Router } from 'express'
 import type { RequestHandler } from 'express'
 import { Ajv } from 'ajv'
-import type { ErrorObject } from 'ajv'
+import type { ErrorObject, ValidateFunction } from 'ajv'
 import addFormatsModule from 'ajv-formats'
-import type { RequestValidation } from './types.js';
+import type { RequestValidation, NormalizedBody } from './types.js';
+import { normalizeBody, matchContentType } from './types.js';
 import type { OpenAPIDocumentInput } from './openapi.js'
 import SchemaAPI from './api.js';
 import Docs from './openapi.js';
@@ -29,6 +30,82 @@ addFormatsModule.default(ajv);
 
 export type ErrorListItem = { type: 'Body' | 'Query' | 'Params'; errors: ErrorObject[] };
 
+/**
+ * Per-route body validation state, compiled once at route registration:
+ * ajv validators keyed by content-type, the normalized map used for
+ * content-type matching, and the precomputed supported-types string
+ * used in error messages.
+ */
+export type CompiledBodyValidation = {
+    validators: Map<string, true | ValidateFunction>;
+    matcher: NormalizedBody;
+    supported: string;
+};
+
+type RouteMethod =
+    | Doc.HttpMethods.GET
+    | Doc.HttpMethods.DELETE
+    | Doc.HttpMethods.POST
+    | Doc.HttpMethods.PATCH
+    | Doc.HttpMethods.PUT;
+
+const MAX_LOGGED_RESPONSE = 4096;
+
+/**
+ * Deep-clone a value following JSON.stringify semantics: toJSON() support
+ * (Date => ISO string), undefined/function/symbol omission, NaN/Infinity
+ * => null, and circular reference detection. Response validation needs the
+ * serialized shape of the payload (Dates must already be strings), and ajv's
+ * removeAdditional/useDefaults mutate the object they validate, so the
+ * caller's object must be protected. A single-pass clone does both without
+ * the cost of JSON.parse(JSON.stringify()) building an intermediate string.
+ */
+function jsonClone(value: unknown, seen?: Set<object>): unknown {
+    if (value !== null && typeof value === 'object' && typeof (value as { toJSON?: unknown }).toJSON === 'function') {
+        value = (value as { toJSON: () => unknown }).toJSON();
+    }
+
+    if (value === null) return null;
+
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return value;
+        case 'number':
+            return Number.isFinite(value) ? value : null;
+        case 'bigint':
+            throw new TypeError('Do not know how to serialize a BigInt');
+        case 'object':
+            break;
+        default:
+            return undefined; // undefined | function | symbol are omitted, as in JSON.stringify
+    }
+
+    if (!seen) seen = new Set();
+    if (seen.has(value as object)) throw new TypeError('Converting circular structure to JSON');
+    seen.add(value as object);
+
+    let out: unknown;
+    if (Array.isArray(value)) {
+        const arr = new Array(value.length);
+        for (let i = 0; i < value.length; i++) {
+            const v = jsonClone(value[i], seen);
+            arr[i] = v === undefined ? null : v;
+        }
+        out = arr;
+    } else {
+        const obj: Record<string, unknown> = {};
+        for (const key of Object.keys(value)) {
+            const v = jsonClone((value as Record<string, unknown>)[key], seen);
+            if (v !== undefined) obj[key] = v;
+        }
+        out = obj;
+    }
+
+    seen.delete(value as object);
+    return out;
+}
+
 /**
  * @class
  *
@@ -53,6 +130,71 @@ export default class Schemas {
         return new Err(400, null, `Validation Error ${String(method).toUpperCase()} ${path}`);
     }
 
+    /**
+     * Compile body validators keyed by content-type. Returns null when no
+     * body validation is configured. Each validator entry is either `true`
+     * (any body accepted for this content-type) or a compiled ajv validator.
+     * The content-type matcher and supported-types error string are
+     * precomputed here so no per-request allocation is needed.
+     */
+    compileBodyValidators(
+        body: RequestValidation<TSchema, TSchema, TSchema, TSchema>['body']
+    ): CompiledBodyValidation | null {
+        const normalized = normalizeBody(body);
+        if (!normalized) return null;
+
+        const validators = new Map<string, true | ValidateFunction>();
+        for (const ct of Object.keys(normalized)) {
+            const schema = normalized[ct].schema;
+            if (schema === true || schema === undefined) {
+                validators.set(ct, true);
+            } else {
+                validators.set(ct, ajv.compile(schema));
+            }
+        }
+
+        return {
+            validators,
+            matcher: normalized,
+            supported: Object.keys(normalized).join(', ')
+        };
+    }
+
+    /**
+     * Validate the incoming request body against the compiled validation
+     * state for the route. Pushes a Body error onto `errors` if validation
+     * fails; returns an Err to respond with for an unsupported content-type.
+     *
+     * If `opts.required` is false and the request has no body / no
+     * content-type, validation is skipped.
+     */
+    validateBody(
+        req: Request,
+        compiled: CompiledBodyValidation,
+        errors: Array<ErrorListItem>,
+        opts: { required?: boolean } = {}
+    ): Err | null {
+        const raw = (req.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
+        const required = opts.required !== false;
+
+        if (!raw && !required) return null;
+
+        const matched = matchContentType(raw, compiled.matcher);
+        const validator = matched ? compiled.validators.get(matched) : undefined;
+
+        if (!validator) {
+            return new Err(400, null, `Content-Type ${raw || '(none)'} not supported. Supported: ${compiled.supported}`);
+        }
+
+        if (validator !== true) {
+            if (!validator(req.body)) {
+                errors.push({ type: 'Body', errors: validator.errors as ErrorObject[] });
+            }
+        }
+
+        return null;
+    }
+
     constructor(
         router: Router,
         opts: {
@@ -74,8 +216,16 @@ export default class Schemas {
             this.router.use(morgan('combined', morganOptions));
         }
 
-        this.router.use(bodyparser.urlencoded({ extended: true }));
+        this.router.use(bodyparser.urlencoded({ extended: true, limit: `${opts.limit || 50}mb` }));
         this.router.use(bodyparser.json({ limit: `${opts.limit || 50}mb` }));
+        this.router.use(bodyparser.text({
+            limit: `${opts.limit || 50}mb`,
+            type: ['text/*', 'application/xml', 'application/*+xml']
+        }));
+        this.router.use(bodyparser.raw({
+            limit: `${opts.limit || 50}mb`,
+            type: ['application/octet-stream']
+        }));
 
         if (opts.error) {
             this.error = opts.error;
@@ -150,21 +300,48 @@ export default class Schemas {
         await bp_fn(this, config);
     }
 
-    async get<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+    /**
+     * Compile the response validator for a route. Type.Any and Type.Unknown
+     * impose no constraints, so they are skipped entirely — routes with an
+     * open response schema (or none) bypass response validation and its
+     * clone at request time.
+     */
+    private compileResponseValidation(res?: TSchema): ValidateFunction | null {
+        if (!res) return null;
+        if (res[Kind] === 'Any' || res[Kind] === 'Unknown') return null;
+        return ajv.compile(res);
+    }
+
+    /**
+     * Shared route registration: compiles all validators once, then installs
+     * a request handler that validates params/query/body and — only when a
+     * response schema requires it — wraps res.json with response validation.
+     */
+    private route<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+        method: RouteMethod,
         path: string,
-        opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
-        handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
-    ) {
+        opts: RequestValidation<TParams, TQuery, TBody, TResponse>,
+        handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>,
+        allowBody: boolean
+    ): void {
+        const methodUpper = String(method).toUpperCase();
+
         try {
             const validation = this.normalizeValidation(opts);
 
-            this.docs.push({ method: Doc.HttpMethods.GET, path: path }, validation);
-            this.schemas.set(`GET ${path}`, validation);
+            this.docs.push({ method, path }, validation);
+            this.schemas.set(`${methodUpper} ${path}`, validation);
 
-            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
+            const resValidation = this.compileResponseValidation(validation.res);
             const paramsValidation = validation.params && ajv.compile(validation.params);
             const queryValidation = validation.query && ajv.compile(validation.query);
-            if (validation.body) throw new Error(`Body not allowed`);
+
+            let bodyValidation: CompiledBodyValidation | null = null;
+            if (allowBody) {
+                bodyValidation = this.compileBodyValidators(validation.body);
+            } else if (validation.body) {
+                throw new Error(`Body not allowed`);
+            }
 
             const _handler: RequestHandler = (req, res, next) => {
                 if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
@@ -177,77 +354,52 @@ export default class Schemas {
                 const errors: Array<ErrorListItem> = [];
                 if (paramsValidation && !paramsValidation(req.params)) errors.push({ type: 'Params', errors: paramsValidation.errors as ErrorObject[] });
                 if (queryValidation && !queryValidation(req.query)) errors.push({ type: 'Query', errors: queryValidation.errors as ErrorObject[] });
-                if (errors.length) return Err.respond(this.validationError(Doc.HttpMethods.GET, path), res, errors);
-
-                const json = res.json;
-                res.json = function(obj) {
-                    obj = JSON.parse(JSON.stringify(obj)) // Here as Date => String needs to happen
-                    if ((res.statusCode === null || res.statusCode === 200) && resValidation && !resValidation(obj)) {
-                        res.status(400);
-                        console.error(`Response Validation Error: ${JSON.stringify(obj)}`);
-                        return json.call(this, { type: 'Response', errors: resValidation.errors as ErrorObject[] });
-                    } else {
+                if (bodyValidation) {
+                    const ctErr = this.validateBody(req, bodyValidation, errors, { required: validation.bodyRequired });
+                    if (ctErr) return Err.respond(ctErr, res);
+                }
+                if (errors.length) return Err.respond(this.validationError(method, path), res, errors);
+
+                if (resValidation) {
+                    const json = res.json;
+                    res.json = function(obj) {
+                        if (res.statusCode === null || res.statusCode === 200) {
+                            obj = jsonClone(obj); // Date => String needs to happen before validation
+                            if (!resValidation(obj)) {
+                                res.status(400);
+                                const logged = JSON.stringify(obj);
+                                console.error(`Response Validation Error: ${methodUpper} ${path}: ${logged && logged.length > MAX_LOGGED_RESPONSE ? logged.slice(0, MAX_LOGGED_RESPONSE) + '... (truncated)' : logged}`);
+                                return json.call(this, { type: 'Response', errors: resValidation.errors as ErrorObject[] });
+                            }
+                        }
                         return json.call(this, obj);
-                    }
-                };
+                    };
+                }
 
                 return handler(req, res, next);
             };
 
-            this.router.get(path, _handler);
+            this.router[method as 'get' | 'delete' | 'post' | 'patch' | 'put'](path, _handler);
         } catch (err) {
-            throw new Error(`Get: ${path}: ` + err, { cause: err })
+            const label = methodUpper.charAt(0) + methodUpper.slice(1).toLowerCase();
+            throw new Error(`${label}: ${path}: ` + String(err), { cause: err })
         }
     }
 
-    async delete<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+    async get<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
         path: string,
         opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
-        try {
-            const validation = this.normalizeValidation(opts);
-
-            this.docs.push({ method: Doc.HttpMethods.DELETE, path: path }, validation);
-            this.schemas.set(`DELETE ${path}`, validation);
-
-            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
-            const paramsValidation = validation.params && ajv.compile(validation.params);
-            const queryValidation = validation.query && ajv.compile(validation.query);
-            if (validation.body) throw new Error(`Body not allowed`);
-
-            const _handler: RequestHandler = (req, res, next) => {
-                if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
-                    Object.defineProperty(req, 'query', {
-                        writable: true,
-                        value: { ...req.query },
-                    })
-                }
-
-                const errors: Array<ErrorListItem> = [];
-                if (paramsValidation && !paramsValidation(req.params)) errors.push({ type: 'Params', errors: paramsValidation.errors as ErrorObject[] });
-                if (queryValidation && !queryValidation(req.query)) errors.push({ type: 'Query', errors: queryValidation.errors as ErrorObject[] });
-                if (errors.length) return Err.respond(this.validationError(Doc.HttpMethods.DELETE, path), res, errors);
-
-                const json = res.json;
-                res.json = function(obj) {
-                    obj = JSON.parse(JSON.stringify(obj)) // Here as Date => String needs to happen
-                    if ((res.statusCode === null || res.statusCode === 200) && resValidation && !resValidation(obj)) {
-                        res.status(400);
-                        console.error(`Response Validation Error: ${JSON.stringify(obj)}`);
-                        return json.call(this, { type: 'Response', errors: resValidation.errors as ErrorObject[] });
-                    } else {
-                        return json.call(this, obj);
-                    }
-                };
-
-                return handler(req, res, next);
-            };
+        this.route(Doc.HttpMethods.GET, path, opts, handler, false);
+    }
 
-            this.router.delete(path, _handler);
-        } catch (err) {
-            throw new Error(`Delete: ${path}: ` + String(err), { cause: err })
-        }
+    async delete<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+        path: string,
+        opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
+        handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
+    ) {
+        this.route(Doc.HttpMethods.DELETE, path, opts, handler, false);
     }
 
     async post<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
@@ -255,50 +407,7 @@ export default class Schemas {
         opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
-        try {
-            const validation = this.normalizeValidation(opts);
-
-            this.docs.push({ method: Doc.HttpMethods.POST, path: path }, validation);
-            this.schemas.set(`POST ${path}`, validation);
-
-            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
-            const paramsValidation = validation.params && ajv.compile(validation.params);
-            const queryValidation = validation.query && ajv.compile(validation.query);
-            const bodyValidation = validation.body && ajv.compile(validation.body);
-
-            const _handler: RequestHandler = (req, res, next) => {
-                if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
-                    Object.defineProperty(req, 'query', {
-                        writable: true,
-                        value: { ...req.query },
-                    })
-                }
-
-                const errors: Array<ErrorListItem> = [];
-                if (paramsValidation && !paramsValidation(req.params)) errors.push({ type: 'Params', errors: paramsValidation.errors as ErrorObject[] });
-                if (queryValidation && !queryValidation(req.query)) errors.push({ type: 'Query', errors: queryValidation.errors as ErrorObject[] });
-                if (bodyValidation && !bodyValidation(req.body)) errors.push({ type: 'Body', errors: bodyValidation.errors as ErrorObject[] });
-                if (errors.length) return Err.respond(this.validationError(Doc.HttpMethods.POST, path), res, errors);
-
-                const json = res.json;
-                res.json = function(obj) {
-                    obj = JSON.parse(JSON.stringify(obj)) // Here as Date => String needs to happen
-                    if ((res.statusCode === null || res.statusCode === 200) && resValidation && !resValidation(obj)) {
-                        res.status(400);
-                        console.error(`Response Validation Error: ${JSON.stringify(obj)}`);
-                        return json.call(this, { type: 'Response', errors: resValidation.errors as ErrorObject[] });
-                    } else {
-                        return json.call(this, obj);
-                    }
-                };
-
-                return handler(req, res, next);
-            };
-
-            this.router.post(path, _handler);
-        } catch (err) {
-            throw new Error(`Post: ${path}: ` + String(err), { cause: err })
-        }
+        this.route(Doc.HttpMethods.POST, path, opts, handler, true);
     }
 
     async patch<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
@@ -306,50 +415,7 @@ export default class Schemas {
         opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
-        try {
-            const validation = this.normalizeValidation(opts);
-
-            this.docs.push({ method: Doc.HttpMethods.PATCH, path: path }, validation);
-            this.schemas.set(`PATCH ${path}`, validation);
-
-            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
-            const paramsValidation = validation.params && ajv.compile(validation.params);
-            const queryValidation = validation.query && ajv.compile(validation.query);
-            const bodyValidation = validation.body && ajv.compile(validation.body);
-
-            const _handler: RequestHandler = (req, res, next) => {
-                if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
-                    Object.defineProperty(req, 'query', {
-                        writable: true,
-                        value: { ...req.query },
-                    })
-                }
-
-                const errors: Array<ErrorListItem> = [];
-                if (paramsValidation && !paramsValidation(req.params)) errors.push({ type: 'Params', errors: paramsValidation.errors as ErrorObject[] });
-                if (queryValidation && !queryValidation(req.query)) errors.push({ type: 'Query', errors: queryValidation.errors as ErrorObject[] });
-                if (bodyValidation && !bodyValidation(req.body)) errors.push({ type: 'Body', errors: bodyValidation.errors as ErrorObject[] });
-                if (errors.length) return Err.respond(this.validationError(Doc.HttpMethods.PATCH, path), res, errors);
-
-                const json = res.json;
-                res.json = function(obj) {
-                    obj = JSON.parse(JSON.stringify(obj)) // Here as Date => String needs to happen
-                    if ((res.statusCode === null || res.statusCode === 200) && resValidation && !resValidation(obj)) {
-                        res.status(400);
-                        console.error(`Response Validation Error: ${JSON.stringify(obj)}`);
-                        return json.call(this, { type: 'Response', errors: resValidation.errors as ErrorObject[] });
-                    } else {
-                        return json.call(this, obj);
-                    }
-                };
-
-                return handler(req, res, next);
-            };
-
-            this.router.patch(path, _handler);
-        } catch (err) {
-            throw new Error(`Patch: ${path}: ` + String(err), { cause: err })
-        }
+        this.route(Doc.HttpMethods.PATCH, path, opts, handler, true);
     }
 
     async put<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
@@ -357,50 +423,7 @@ export default class Schemas {
         opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
-        try {
-            const validation = this.normalizeValidation(opts);
-
-            this.docs.push({ method: Doc.HttpMethods.PUT, path: path }, validation);
-            this.schemas.set(`PUT ${path}`, validation);
-
-            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
-            const paramsValidation = validation.params && ajv.compile(validation.params);
-            const queryValidation = validation.query && ajv.compile(validation.query);
-            const bodyValidation = validation.body && ajv.compile(validation.body);
-
-            const _handler: RequestHandler = (req, res, next) => {
-                if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
-                    Object.defineProperty(req, 'query', {
-                        writable: true,
-                        value: { ...req.query },
-                    })
-                }
-
-                const errors: Array<ErrorListItem> = [];
-                if (paramsValidation && !paramsValidation(req.params)) errors.push({ type: 'Params', errors: paramsValidation.errors as ErrorObject[] });
-                if (queryValidation && !queryValidation(req.query)) errors.push({ type: 'Query', errors: queryValidation.errors as ErrorObject[] });
-                if (bodyValidation && !bodyValidation(req.body)) errors.push({ type: 'Body', errors: bodyValidation.errors as ErrorObject[] });
-                if (errors.length) return Err.respond(this.validationError(Doc.HttpMethods.PUT, path), res, errors);
-
-                const json = res.json;
-                res.json = function(obj) {
-                    obj = JSON.parse(JSON.stringify(obj)) // Here as Date => String needs to happen
-                    if ((res.statusCode === null || res.statusCode === 200) && resValidation && !resValidation(obj)) {
-                        res.status(400);
-                        console.error(`Response Validation Error: ${JSON.stringify(obj)}`);
-                        return json.call(this, { type: 'Response', errors: resValidation.errors as ErrorObject[] });
-                    } else {
-                        return json.call(this, obj);
-                    }
-                };
-
-                return handler(req, res, next);
-            };
-
-            this.router.put(path, _handler);
-        } catch (err) {
-            throw new Error(`Put: ${path}: ` + String(err), { cause: err })
-        }
+        this.route(Doc.HttpMethods.PUT, path, opts, handler, true);
     }
 
     not_found() {

package/lib/types.ts

@@ -1,5 +1,88 @@
+import { Kind } from '@sinclair/typebox';
 import type { TSchema } from '@sinclair/typebox';
 
+/**
+ * Per-content-type body entry. May be:
+ *   - a TypeBox schema (validated, no example)
+ *   - `true` (any body accepted, no validation)
+ *   - an object with optional `schema` (TSchema | true), `example`, `examples`
+ *     (forwarded to the OpenAPI media type object)
+ */
+export type BodyEntryConfig = {
+    schema?: TSchema | true;
+    example?: unknown;
+    examples?: Record<string, { summary?: string; description?: string; value: unknown }>;
+};
+
+export type BodyEntry = TSchema | true | BodyEntryConfig;
+
+/**
+ * Body validation can either be:
+ *   - a TypeBox schema (treated as `application/json` for backwards compatibility)
+ *   - a record mapping content-type strings to a `BodyEntry`. Content-type
+ *     keys may include wildcards: `text/*`, `application/*`, or `* / *`.
+ */
+export type BodyValidation<TBody extends TSchema> =
+    | TBody
+    | Record<string, BodyEntry>;
+
+/**
+ * Normalized internal representation: every entry has the expanded
+ * `BodyEntryConfig` shape with `schema` always set (defaulting to `true`).
+ */
+export type NormalizedBody = Record<string, Required<Pick<BodyEntryConfig, 'schema'>> & BodyEntryConfig>;
+
+/**
+ * Detect whether a given value is a TypeBox schema. TypeBox attaches a
+ * `[Kind]` symbol to every schema instance which is what we use to
+ * distinguish a schema from a content-type-keyed body record.
+ */
+export function isTSchema(value: unknown): value is TSchema {
+    return !!value && typeof value === 'object' && Kind in (value as object);
+}
+
+function normalizeEntry(entry: BodyEntry): NormalizedBody[string] {
+    if (entry === true) return { schema: true };
+    if (isTSchema(entry)) return { schema: entry };
+    return { schema: true, ...entry };
+}
+
+/**
+ * Normalize the body option into a `NormalizedBody` map. A bare TypeBox
+ * schema is mapped to `application/json` for backwards compatibility.
+ */
+export function normalizeBody(
+    body: TSchema | Record<string, BodyEntry> | undefined
+): NormalizedBody | undefined {
+    if (!body) return undefined;
+    if (isTSchema(body)) return { 'application/json': { schema: body } };
+
+    const out: NormalizedBody = {};
+    for (const ct of Object.keys(body)) {
+        out[ct.toLowerCase()] = normalizeEntry(body[ct]);
+    }
+    return out;
+}
+
+/**
+ * Match an incoming content-type against a normalized body map, honoring
+ * wildcard entries like `text/*` or `*\/*`. Exact matches always win.
+ */
+export function matchContentType(
+    incoming: string,
+    normalized: NormalizedBody
+): string | undefined {
+    if (!incoming) {
+        return normalized['*/*'] ? '*/*' : undefined;
+    }
+    if (normalized[incoming]) return incoming;
+
+    const [type] = incoming.split('/');
+    if (type && normalized[`${type}/*`]) return `${type}/*`;
+    if (normalized['*/*']) return '*/*';
+    return undefined;
+}
+
 export type RequestValidation<
     TParams extends TSchema,
     TQuery extends TSchema,
@@ -13,6 +96,8 @@ export type RequestValidation<
   description?: string;
   params?: TParams;
   query?: TQuery;
-  body?: TBody;
+  body?: BodyValidation<TBody>;
+  /** Whether the request body is required. Defaults to true when `body` is set. */
+  bodyRequired?: boolean;
   res?: TResponse
 };

package/package.json

@@ -4,7 +4,7 @@
     "root": true,
     "main": "dist/index.js",
     "types": "index.ts",
-    "version": "10.25.0",
+    "version": "10.27.0",
     "description": "Strongly Validated JSON Schema support for address",
     "repository": {
         "type": "git",