@rvoh/psychic 2.3.8 → 3.0.0-alpha.1

package/dist/cjs/src/cli/index.js

@@ -32,6 +32,10 @@ ${INDENT}    - date
 ${INDENT}    - date[]
 ${INDENT}    - datetime
 ${INDENT}    - datetime[]
+${INDENT}    - time
+${INDENT}    - time[]
+${INDENT}    - timetz
+${INDENT}    - timetz[]
 ${INDENT}    - integer
 ${INDENT}    - integer[]
 ${INDENT}

package/dist/cjs/src/controller/helpers/logIfDevelopment.js

@@ -3,20 +3,20 @@ import colorize from '../../cli/helpers/colorize.js';
 import EnvInternal from '../../helpers/EnvInternal.js';
 import { httpMethodBgColor } from './httpMethodColor.js';
 import { statusCodeBgColor } from './statusCodeColor.js';
-export default function logIfDevelopment({ req, res, startTime, fallbackStatusCode = 200, }) {
+export default function logIfDevelopment({ ctx, startTime, fallbackStatusCode = 200, }) {
     if (!EnvInternal.isDevelopment)
         return;
-    const method = colorize(` ${req.method.toUpperCase()} `, {
+    const method = colorize(` ${ctx.method.toUpperCase()} `, {
         color: 'black',
-        bgColor: httpMethodBgColor(req.method.toLowerCase()),
+        bgColor: httpMethodBgColor(ctx.method.toLowerCase()),
     });
-    const computedStatus = res.statusCode || fallbackStatusCode;
+    const computedStatus = ctx.status || fallbackStatusCode;
     const statusBgColor = statusCodeBgColor(computedStatus);
     const status = colorize(` ${computedStatus} `, {
         color: 'black',
         bgColor: statusBgColor,
     });
-    const url = colorize(req.url, { color: 'green' });
+    const url = colorize(ctx.url, { color: 'green' });
     const benchmark = colorize(`${Date.now() - startTime}ms`, { color: 'gray' });
     DreamCLI.logger.log(`${method} ${url} ${status} ${benchmark}`, { logPrefix: '' });
 }

package/dist/cjs/src/controller/index.js

@@ -1,6 +1,7 @@
 import { Dream, DreamApp } from '@rvoh/dream';
 import { GlobalNameNotSet } from '@rvoh/dream/errors';
 import { DreamSerializerBuilder, ObjectSerializerBuilder } from '@rvoh/dream/system';
+import fastJsonStringify from 'fast-json-stringify';
 import ParamValidationError from '../error/controller/ParamValidationError.js';
 import HttpStatusBadGateway from '../error/http/BadGateway.js';
 import HttpStatusBadRequest from '../error/http/BadRequest.js';
@@ -36,6 +37,7 @@ import HttpStatusUnsupportedMediaType from '../error/http/UnsupportedMediaType.j
 import EnvInternal from '../helpers/EnvInternal.js';
 import toJson from '../helpers/toJson.js';
 import OpenapiPayloadValidator from '../openapi-renderer/helpers/OpenapiPayloadValidator.js';
+import { cacheStringify, getCachedStringify } from '../openapi-renderer/helpers/stringify-cache.js';
 import PsychicApp from '../psychic-app/index.js';
 import Params from '../server/params.js';
 import Session from '../session/index.js';
@@ -60,6 +62,10 @@ export const PsychicParamsPrimitiveLiterals = [
     'number[]',
     'string',
     'string[]',
+    'time',
+    'time[]',
+    'timetz',
+    'timetz[]',
     'uuid',
     'uuid[]',
 ];
@@ -169,17 +175,20 @@ export default class PsychicController {
     get isPsychicControllerInstance() {
         return true;
     }
-    req;
-    res;
+    ctx;
     session;
     action;
     renderOpts;
     startTime;
-    constructor(req, res, { action, }) {
+    _responseSent = false;
+    constructor(ctx, { action, }) {
         this.startTime = Date.now();
-        this.req = req;
-        this.res = res;
-        this.session = new Session(req, res);
+        this.ctx = ctx;
+        // Koa defaults ctx.status to 404, but Express defaulted res.statusCode to 200.
+        // Set 200 here so controller response methods (ok, json, etc.) and OpenAPI
+        // response-body validation see the correct default status.
+        this.ctx.status = 200;
+        this.session = new Session(ctx);
         this.action = action;
         // TODO: read casing from Dream app config
         this.renderOpts = {
@@ -204,7 +213,7 @@ export default class PsychicController {
      * ```
      */
     get headers() {
-        return this.req.headers;
+        return this.ctx.request.headers;
     }
     /**
      * Gets the combined parameters from the HTTP request. This includes URL parameters,
@@ -230,10 +239,14 @@ export default class PsychicController {
     get params() {
         this.validateParams();
         const query = this.getCachedQuery();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+        const body = this.ctx.request.body ?? {};
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+        const routeParams = this.ctx.params ?? {};
         const params = {
             ...query,
-            ...this.req.body,
-            ...this.req.params,
+            ...body,
+            ...routeParams,
         };
         return params;
     }
@@ -245,7 +258,7 @@ export default class PsychicController {
         if (this._cachedQuery)
             return this._cachedQuery;
         const openapiEndpointRenderer = this.currentOpenapiRenderer;
-        const query = this.req.query;
+        const query = this.ctx.request.query;
         if (openapiEndpointRenderer) {
             // validateOpenapiQuery will modify the query passed into it to conform
             // to the openapi shape with regards to arrays, since these are notoriously
@@ -581,26 +594,90 @@ export default class PsychicController {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     data) {
         this.validateOpenapiResponseBody(data);
-        this.expressSendJson(data);
+        this.koaSendJson(data);
     }
-    expressSendJson(
+    koaSendJson(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    data, statusCode = this.res.statusCode) {
-        this.res.type('json').status(statusCode).send(toJson(data, PsychicApp.getOrFail().sanitizeResponseJson));
+    data, statusCode = this.ctx.status || 200) {
+        // In Express, calling res.json() after a response was already sent was a no-op.
+        // In Koa, ctx.body/ctx.status are plain assignments, so the last write wins.
+        // Guard here to preserve Express-like semantics for user code that falls through
+        // after sending a response (e.g. this.noContent() without a return).
+        if (this._responseSent)
+            return;
+        this.ctx.status = statusCode;
+        // Try to use fast-json-stringify if an OpenAPI schema exists for this endpoint
+        const stringifyFn = this.getFastJsonStringifyFunction(statusCode);
+        if (stringifyFn) {
+            this.ctx.type = 'application/json';
+            this.ctx.body = stringifyFn(data);
+        }
+        else {
+            // Fall back to toJson() if no OpenAPI schema exists
+            this.ctx.type = 'json';
+            this.ctx.body = toJson(data);
+        }
+        this._responseSent = true;
         this.logIfDevelopment();
     }
-    expressSendStatus(statusCode) {
-        this.res.sendStatus(statusCode);
+    /**
+     * @internal
+     *
+     * Attempts to retrieve or create a cached fast-json-stringify function
+     * for the current endpoint and status code. Returns undefined if no
+     * OpenAPI schema exists or if the controller's globalName is not set.
+     *
+     * @param statusCode - the HTTP status code
+     * @returns A stringify function, or undefined if no schema exists
+     */
+    getFastJsonStringifyFunction(statusCode) {
+        const openapiEndpointRenderer = this.currentOpenapiRenderer;
+        if (!openapiEndpointRenderer)
+            return undefined;
+        const controllerClass = this.constructor;
+        // If globalName is not set (e.g., in some unit tests), fall back to toJson()
+        if (!controllerClass._globalName)
+            return undefined;
+        // Try each openapiName until we find a schema
+        for (const openapiName of this.computedOpenapiNames) {
+            const validator = new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer);
+            const schemaWithComponents = validator.getResponseSchemaWithComponents(statusCode);
+            if (!schemaWithComponents)
+                continue;
+            // Generate cache key
+            const cacheKey = `${controllerClass.globalName}#${this.action}|${openapiName}|${statusCode}`;
+            // Check cache first
+            const cachedStringify = getCachedStringify(cacheKey);
+            if (cachedStringify)
+                return cachedStringify;
+            // Compile and cache the stringify function
+            // If compilation fails, let the error propagate (dead programs tell no lies)
+            const stringifyFn = fastJsonStringify(schemaWithComponents);
+            cacheStringify(cacheKey, stringifyFn);
+            return stringifyFn;
+        }
+        return undefined;
+    }
+    koaSendStatus(statusCode) {
+        if (this._responseSent)
+            return;
+        this.ctx.status = statusCode;
+        this.ctx.body = '';
+        this._responseSent = true;
         this.logIfDevelopment();
     }
-    expressRedirect(statusCode, newLocation) {
-        this.res.redirect(statusCode, newLocation);
+    koaRedirect(statusCode, newLocation) {
+        if (this._responseSent)
+            return;
+        this.ctx.status = statusCode;
+        this.ctx.redirect(newLocation);
+        this._responseSent = true;
         this.logIfDevelopment();
     }
     logIfDevelopment() {
         if (!EnvInternal.isDevelopment)
             return;
-        logIfDevelopment({ req: this.req, res: this.res, startTime: this.startTime });
+        logIfDevelopment({ ctx: this.ctx, startTime: this.startTime });
     }
     defaultSerializerPassthrough = {};
     /**
@@ -658,7 +735,7 @@ export default class PsychicController {
      */
     respond(data = {}, opts = {}) {
         const openapiData = this.constructor.openapi[this.action];
-        this.res.status(openapiData?.['status'] || 200);
+        this.ctx.status = openapiData?.['status'] || 200;
         this.json(data, opts);
     }
     /**
@@ -691,7 +768,7 @@ export default class PsychicController {
         const realStatus = (typeof HttpStatusCodeMap[status] === 'string'
             ? HttpStatusCodeMap[HttpStatusCodeMap[status]]
             : HttpStatusCodeMap[status]);
-        this.res.status(realStatus);
+        this.ctx.status = realStatus;
         this.json(body);
     }
     /**
@@ -710,7 +787,7 @@ export default class PsychicController {
      * ```
      */
     redirect(path) {
-        this.res.redirect(path);
+        this.ctx.redirect(path);
     }
     // begin: http status codes
     /**
@@ -752,7 +829,7 @@ export default class PsychicController {
      */
     // 201
     created(data = {}, opts = {}) {
-        this.res.status(201);
+        this.ctx.status = 201;
         this.json(data, opts);
     }
     /**
@@ -774,17 +851,17 @@ export default class PsychicController {
      */
     // 202
     accepted(data = {}, opts = {}) {
-        this.res.status(202);
+        this.ctx.status = 202;
         this.json(data, opts);
     }
     // 203
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     nonAuthoritativeInformation(message = undefined) {
         if (message) {
-            this.expressSendJson(message, 203);
+            this.koaSendJson(message, 203);
         }
         else {
-            this.expressSendStatus(203);
+            this.koaSendStatus(203);
         }
     }
     /**
@@ -804,39 +881,39 @@ export default class PsychicController {
      */
     // 204
     noContent() {
-        this.expressSendStatus(204);
+        this.koaSendStatus(204);
     }
     // 205
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     resetContent(message = undefined) {
-        this.res.status(205);
+        this.ctx.status = 205;
         this.json(message);
     }
     // 208
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     alreadyReported(message = undefined) {
-        this.res.status(208);
+        this.ctx.status = 208;
         this.json(message);
     }
     // 301
     movedPermanently(newLocation) {
-        this.expressRedirect(301, newLocation);
+        this.koaRedirect(301, newLocation);
     }
     // 302
     found(newLocation) {
-        this.expressRedirect(302, newLocation);
+        this.koaRedirect(302, newLocation);
     }
     // 303
     seeOther(newLocation) {
-        this.expressRedirect(303, newLocation);
+        this.koaRedirect(303, newLocation);
     }
     // 307
     temporaryRedirect(newLocation) {
-        this.expressRedirect(307, newLocation);
+        this.koaRedirect(307, newLocation);
     }
     // 308
     permanentRedirect(newLocation) {
-        this.expressRedirect(308, newLocation);
+        this.koaRedirect(308, newLocation);
     }
     /**
      * Throws an HTTP 400 Bad Request error. Use this when the client request
@@ -1073,7 +1150,7 @@ export default class PsychicController {
      */
     async runAction() {
         await this.runBeforeActions();
-        if (this.res.headersSent)
+        if (this._responseSent || this.ctx.headerSent)
             return;
         this.validateParams();
         // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
@@ -1100,8 +1177,10 @@ export default class PsychicController {
         const openapiEndpointRenderer = this.currentOpenapiRenderer;
         if (!openapiEndpointRenderer)
             return;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+        const body = this.ctx.request.body;
         this.computedOpenapiNames.forEach(openapiName => {
-            new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer).validateOpenapiRequestBody(this.req.body);
+            new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer).validateOpenapiRequestBody(body);
         });
     }
     /**
@@ -1117,7 +1196,7 @@ export default class PsychicController {
         if (!openapiEndpointRenderer)
             return;
         this.computedOpenapiNames.forEach(openapiName => {
-            new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer).validateOpenapiHeaders(this.req.headers);
+            new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer).validateOpenapiHeaders(this.ctx.request.headers);
         });
     }
     /**
@@ -1133,7 +1212,7 @@ export default class PsychicController {
         if (!openapiEndpointRenderer)
             return;
         this.computedOpenapiNames.forEach(openapiName => {
-            new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer).validateOpenapiQuery(this.req.query);
+            new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer).validateOpenapiQuery(this.ctx.request.query);
         });
     }
     /**
@@ -1152,7 +1231,7 @@ export default class PsychicController {
         if (!openapiEndpointRenderer)
             return;
         this.computedOpenapiNames.forEach(openapiName => {
-            new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer).validateOpenapiResponseBody(data, this.res.statusCode);
+            new OpenapiPayloadValidator(openapiName, openapiEndpointRenderer).validateOpenapiResponseBody(data, this.ctx.status);
         });
     }
     /**
@@ -1171,7 +1250,7 @@ export default class PsychicController {
     async runBeforeActions() {
         const beforeActions = this.constructor.controllerHooks.filter(hook => hook.shouldFireForAction(this.action));
         for (const hook of beforeActions) {
-            if (this.res.headersSent)
+            if (this._responseSent || this.ctx.headerSent)
                 return;
             if (hook.isStatic) {
                 // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access

package/dist/cjs/src/devtools/helpers/launchDevServer.js

@@ -6,7 +6,7 @@ import UnexpectedUndefined from '../../error/UnexpectedUndefined.js';
 import PsychicApp from '../../psychic-app/index.js';
 const devServerProcesses = {};
 const debugEnabled = debuglog('psychic').enabled;
-export async function launchDevServer(key, { port = 3000, cmd = 'pnpm client', timeout = 5000 } = {}) {
+export async function launchDevServer(key, { port = 3000, cmd = 'pnpm client', timeout = 5000, onStdOut } = {}) {
     if (devServerProcesses[key])
         return;
     if (debugEnabled)
@@ -20,6 +20,20 @@ export async function launchDevServer(key, { port = 3000, cmd = 'pnpm client', t
             ...process.env,
         },
     });
+    // NOTE: adding this stdout spy so that
+    // when this cli utility runs node commands,
+    // it can properly hijack the stdout from the command
+    proc.stdout?.on('data', chunk => {
+        const txt = chunk?.toString()?.trim();
+        if (typeof txt !== 'string' || !txt)
+            return;
+        if (onStdOut) {
+            onStdOut(txt);
+        }
+        else {
+            console.log(txt);
+        }
+    });
     devServerProcesses[key] = proc;
     await waitForPort(key, port, timeout);
     proc.on('error', err => {

package/dist/cjs/src/error/openapi/UnrecognizedDbTypeFoundWhileComputingOpenapiAttribute.js

@@ -0,0 +1,44 @@
+export default class UnrecognizedDbTypeFoundWhileComputingOpenapiAttribute extends Error {
+    source;
+    attributeName;
+    dbType;
+    constructor(source, attributeName, dbType) {
+        super();
+        this.source = source;
+        this.attributeName = attributeName;
+        this.dbType = dbType;
+    }
+    get message() {
+        return `
+While trying to compute the openapi shape for either a serializer or a controller's
+request body, we ran into a db type that we didn't know how to automatically infer the
+openapi shape for. In these cases, we recommend that you provide an explicit openapi
+shape for these attributes, so that the openapi shape can be properly generated.
+
+source:               ${this.source}
+attribute:            ${this.attributeName}
+unexpected db type:   ${this.dbType}
+
+If the culprit is a serializer attribute, you should provide an explicit openapi definition
+to the attribute causing your problems, like so:
+
+  .attribute('${this.attributeName}', { openapi: { type: 'string' }})
+
+If, instead, it is a controller's request body causing your problems, identify the controller
+method responsible for this exception, and ensure that the openapi request body shape is explicitly
+defined, so that you do not force psychic to autocompute the openapi body shape for this endpoint.
+
+    @OpenAPI(MyModel, {
+      requestBody: {
+        type: 'object',
+        properties: {
+          ${this.attributeName}: {
+            type: 'string',
+          }
+        }
+      }
+    })
+  
+`;
+    }
+}

package/dist/cjs/src/error/router/cannot-commit-routes-without-koa-app.js

@@ -0,0 +1,12 @@
+export default class CannotCommitRoutesWithoutKoaApp extends Error {
+    get message() {
+        return `
+      When instantiating a PsychicRouter, if no Koa app is provided as the
+      first argument, you are not able to commit your routes. Make sure
+      to provide an actual Koa app before commiting, like so:
+
+        const app = new Koa()
+        new PsychicRouter(app, ...)
+    `;
+    }
+}

package/dist/cjs/src/helpers/toJson.js

@@ -1,15 +1,9 @@
-import { sanitizeString } from '@rvoh/dream/utils';
-export default function toJson(data, sanitize) {
+export default function toJson(data) {
     /**
      * 'undefined' is invalid json, and `JSON.stringify(undefined)` returns `undefined`
      * so follow the pattern established by Express and return '{}' for `undefined`
      */
     if (data === undefined)
         return '{}';
-    if (sanitize) {
-        return JSON.stringify(data, (_, x) => (typeof x !== 'string' ? x : sanitizeString(x))).replace(/\\\\/g, '\\');
-    }
-    else {
-        return JSON.stringify(data);
-    }
+    return JSON.stringify(data);
 }

package/dist/cjs/src/helpers/validateOpenApiSchema.js

@@ -126,7 +126,7 @@ const BIGINT_REGEX = /^-?\d+(\.0*)?$/;
 /**
  * Formats AJV errors into a more readable format
  */
-function formatAjvErrors(ajvErrors) {
+export function formatAjvErrors(ajvErrors) {
     return ajvErrors.map(error => ({
         instancePath: error.instancePath,
         schemaPath: error.schemaPath,

package/dist/cjs/src/openapi-renderer/SerializerOpenapiRenderer.js

@@ -14,7 +14,7 @@ import NoSerializerFoundForRendersOneAndMany from '../error/openapi/NoSerializer
 import ObjectSerializerRendersOneAndManyRequireClassType from '../error/openapi/ObjectSerializerRendersOneAndManyRequireClassType.js';
 import allSerializersFromHandWrittenOpenapi from './helpers/allSerializersFromHandWrittenOpenapi.js';
 import allSerializersToRefsInOpenapi from './helpers/allSerializersToRefsInOpenapi.js';
-import { dreamColumnOpenapiShape } from './helpers/dreamAttributeOpenapiShape.js';
+import { dreamColumnOpenapiShape } from './helpers/dreamColumnOpenapiShape.js';
 import openapiShorthandToOpenapi from './helpers/openapiShorthandToOpenapi.js';
 const NULL_OBJECT_OPENAPI = { type: 'null' };
 export default class SerializerOpenapiRenderer {
@@ -153,7 +153,7 @@ export default class SerializerOpenapiRenderer {
                             target = DataTypeForOpenapi;
                         }
                         accumulator[outputAttributeName] = allSerializersToRefsInOpenapi(target?.isDream
-                            ? dreamColumnOpenapiShape(target, attribute.name, openapi, {
+                            ? dreamColumnOpenapiShape(this.serializer.globalName, target, attribute.name, openapi, {
                                 suppressResponseEnums: this.suppressResponseEnums,
                             })
                             : openapiShorthandToOpenapi(openapi));

package/dist/cjs/src/openapi-renderer/endpoint.js

@@ -10,7 +10,7 @@ import openapiParamNamesForDreamClass from '../server/helpers/openapiParamNamesF
 import OpenapiSegmentExpander from './body-segment.js';
 import { DEFAULT_OPENAPI_RESPONSES } from './defaults.js';
 import cursorPaginationParamOpenapiProperty from './helpers/cursorPaginationParamOpenapiProperty.js';
-import { dreamColumnOpenapiShape } from './helpers/dreamAttributeOpenapiShape.js';
+import { dreamColumnOpenapiShape } from './helpers/dreamColumnOpenapiShape.js';
 import openapiOpts from './helpers/openapiOpts.js';
 import openapiRoute from './helpers/openapiRoute.js';
 import paginationPageParamOpenapiProperty from './helpers/paginationPageParamOpenapiProperty.js';
@@ -545,7 +545,7 @@ export default class OpenapiEndpointRenderer {
             paramsShape.required = required;
         }
         paramsShape.properties = paramSafeColumns.reduce((acc, columnName) => {
-            acc[columnName] = dreamColumnOpenapiShape(dreamClass, columnName, undefined, {
+            acc[columnName] = dreamColumnOpenapiShape(this.controllerClass.controllerActionPath(this.action), dreamClass, columnName, undefined, {
                 allowGenericJson: true,
             });
             return acc;

package/dist/cjs/src/openapi-renderer/helpers/OpenapiPayloadValidator.js

@@ -1,8 +1,9 @@
 import OpenapiRequestValidationFailure from '../../error/openapi/OpenapiRequestValidationFailure.js';
 import OpenapiResponseValidationFailure from '../../error/openapi/OpenapResponseValidationFailure.js';
-import validateOpenApiSchema from '../../helpers/validateOpenApiSchema.js';
+import { createValidator, formatAjvErrors, } from '../../helpers/validateOpenApiSchema.js';
 import PsychicApp from '../../psychic-app/index.js';
 import suppressResponseEnumsConfig from './suppressResponseEnumsConfig.js';
+import { cacheValidator, getCachedValidator } from './validator-cache.js';
 /**
  * @internal
  *
@@ -157,16 +158,46 @@ export default class OpenapiPayloadValidator {
         const openapiEndpointRenderer = this.openapiEndpointRenderer;
         const openapiName = this.openapiName;
         if (openapiEndpointRenderer.shouldValidateResponseBody(openapiName)) {
-            const openapiResponseBody = openapiEndpointRenderer['parseResponses']({
-                openapiName,
-                renderOpts: this.renderOpts,
-            }).openapi?.[statusCode.toString()];
-            const schema = openapiResponseBody?.['content']?.['application/json']?.['schema'];
+            const schema = this.getResponseSchema(statusCode);
             if (schema) {
                 this.validateOrFail(data, schema, 'responseBody');
             }
         }
     }
+    /**
+     * @internal
+     *
+     * Retrieves the OpenAPI response schema for a given status code.
+     * Returns undefined if no schema is defined for this endpoint/status code.
+     *
+     * @param statusCode - the HTTP status code
+     * @returns The response schema, or undefined if not found
+     */
+    getResponseSchema(statusCode) {
+        const openapiEndpointRenderer = this.openapiEndpointRenderer;
+        const openapiName = this.openapiName;
+        const openapiResponseBody = openapiEndpointRenderer['parseResponses']({
+            openapiName,
+            renderOpts: this.renderOpts,
+        }).openapi?.[statusCode.toString()];
+        return openapiResponseBody?.['content']?.['application/json']?.['schema'];
+    }
+    /**
+     * @internal
+     *
+     * Retrieves the OpenAPI response schema for a given status code with
+     * all components merged in. This is the schema format needed by
+     * fast-json-stringify and AJV validators.
+     *
+     * @param statusCode - the HTTP status code
+     * @returns The response schema with components, or undefined if not found
+     */
+    getResponseSchemaWithComponents(statusCode) {
+        const schema = this.getResponseSchema(statusCode);
+        if (!schema)
+            return undefined;
+        return this.addComponentsToSchema(schema);
+    }
     /**
      * @internal
      *
@@ -241,12 +272,47 @@ export default class OpenapiPayloadValidator {
     validateOrFail(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     data, openapiSchema, target) {
-        const validationResults = validateOpenApiSchema(data || {}, this.addComponentsToSchema(openapiSchema), this.getAjvOptions(target));
-        if (!validationResults.isValid) {
+        const cacheKey = this.getCacheKey(target);
+        const schemaWithComponents = this.addComponentsToSchema(openapiSchema);
+        const ajvOptions = this.getAjvOptions(target);
+        const validator = getCachedValidator(cacheKey) ||
+            this.compileAndCacheValidator(cacheKey, schemaWithComponents, ajvOptions);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const clonedData = structuredClone(data || {});
+        const isValid = validator(clonedData);
+        if (!isValid) {
             const errorClass = target === 'responseBody' ? OpenapiResponseValidationFailure : OpenapiRequestValidationFailure;
-            throw new errorClass(validationResults.errors || [], target);
+            throw new errorClass(formatAjvErrors(validator.errors || []), target);
         }
     }
+    /**
+     * @internal
+     *
+     * Generates a cache key for the validator based on controller, action, openapiName, and target.
+     *
+     * @param target - the validation target (one of: 'requestBody', 'query', 'headers', 'responseBody')
+     * @returns cache key string
+     */
+    getCacheKey(target) {
+        const controllerClass = this.openapiEndpointRenderer['controllerClass'];
+        const actionName = this.openapiEndpointRenderer['action'];
+        return `${controllerClass.globalName}#${actionName}|${this.openapiName}|${target}`;
+    }
+    /**
+     * @internal
+     *
+     * Compiles a validator using AJV and caches it for future use.
+     *
+     * @param cacheKey - the cache key for this validator
+     * @param schema - the schema to compile
+     * @param options - AJV options
+     * @returns compiled validator function
+     */
+    compileAndCacheValidator(cacheKey, schema, options) {
+        const validator = createValidator(schema, options);
+        cacheValidator(cacheKey, validator);
+        return validator;
+    }
     /**
      * @internal
      *