@rvoh/psychic 2.3.9 → 3.0.0-alpha.1

package/dist/esm/src/router/index.js

@@ -1,12 +1,12 @@
 import { DataIncompatibleWithDatabaseField, RecordNotFound, ValidationError } from '@rvoh/dream/errors';
 import { camelize } from '@rvoh/dream/utils';
-import { Router } from 'express';
+import KoaRouter from '@koa/router';
 import util, { debuglog } from 'node:util';
 import pluralize from 'pluralize-esm';
 import ParamValidationError from '../error/controller/ParamValidationError.js';
 import ParamValidationErrors from '../error/controller/ParamValidationErrors.js';
 import OpenapiRequestValidationFailure from '../error/openapi/OpenapiRequestValidationFailure.js';
-import CannotCommitRoutesWithoutExpressApp from '../error/router/cannot-commit-routes-without-express-app.js';
+import CannotCommitRoutesWithoutKoaApp from '../error/router/cannot-commit-routes-without-koa-app.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import errorIsRescuableHttpError from '../helpers/error/errorIsRescuableHttpError.js';
 import PsychicApp from '../psychic-app/index.js';
@@ -31,19 +31,25 @@ export default class PsychicRouter {
     commit() {
         const app = this.app;
         if (!app)
-            throw new CannotCommitRoutesWithoutExpressApp();
+            throw new CannotCommitRoutesWithoutKoaApp();
+        const router = new KoaRouter();
         this.routes.forEach(route => {
             if (route.middleware) {
                 const routeConf = route;
-                app[routeConf.httpMethod](routePath(routeConf.path), ...(Array.isArray(routeConf.middleware) ? routeConf.middleware : [routeConf.middleware]));
+                const middlewares = Array.isArray(routeConf.middleware)
+                    ? routeConf.middleware
+                    : [routeConf.middleware];
+                router[routeConf.httpMethod](routePath(routeConf.path), ...middlewares);
             }
             else {
                 const routeConf = route;
-                app[routeConf.httpMethod](routePath(routeConf.path), (req, res) => {
-                    this.handle(routeConf.controller, routeConf.action, { req, res }).catch(() => { });
+                router[routeConf.httpMethod](routePath(routeConf.path), async (ctx) => {
+                    await this.handle(routeConf.controller, routeConf.action, { ctx });
                 });
             }
         });
+        app.use(router.routes());
+        app.use(router.allowedMethods());
     }
     get(path, controller, action) {
         this.crud('get', path, controller, action);
@@ -72,7 +78,7 @@ export default class PsychicRouter {
         this.checkPathForInvalidChars(path);
         const isMiddleware = (typeof controllerOrMiddleware === 'function' || Array.isArray(controllerOrMiddleware)) &&
             !controllerOrMiddleware?.isPsychicController;
-        // devs can provide custom express middleware which bypasses
+        // devs can provide custom Koa middleware which bypasses
         // the normal Controller#action paradigm.
         if (isMiddleware) {
             this.routeManager.addMiddleware({
@@ -98,7 +104,7 @@ export default class PsychicRouter {
         if (path.includes('{'))
             throw new Error(`
 The provided route "${path}" contains characters that are not supported.
-If you are trying to write a uri param, you will need to use expressjs
+If you are trying to write a uri param, you will need to use the
 param syntax, which is a prefixing colon, rather than using brackets
 to surround the param.
 
@@ -236,10 +242,10 @@ suggested fix:  "${convertRouteParams(path)}"
      * By default, do not provide an attacker with any visibility into which layer
      * of the application rejected their request.
      */
-    async handle(controller, action, { req, res, }) {
-        const controllerInstance = this._initializeController(controller, req, res, action);
+    async handle(controller, action, { ctx, }) {
+        const controllerInstance = this._initializeController(controller, ctx, action);
         if (typeof controllerInstance[action] !== 'function') {
-            controllerInstance['expressSendStatus'](404);
+            controllerInstance['koaSendStatus'](404);
             return;
         }
         try {
@@ -250,20 +256,20 @@ suggested fix:  "${convertRouteParams(path)}"
             if (errorIsRescuableHttpError(err)) {
                 const httpErr = err;
                 if (httpErr.data) {
-                    controllerInstance['expressSendJson'](httpErr.data, httpErr.status);
+                    controllerInstance['koaSendJson'](httpErr.data, httpErr.status);
                 }
                 else {
-                    controllerInstance['expressSendStatus'](httpErr.status);
+                    controllerInstance['koaSendStatus'](httpErr.status);
                 }
             }
             else if (err instanceof RecordNotFound) {
-                controllerInstance['expressSendStatus'](404);
+                controllerInstance['koaSendStatus'](404);
             }
             else if (err instanceof DataIncompatibleWithDatabaseField) {
                 /**
                  * See comment at top of this method for philosophy of 400
                  */
-                controllerInstance['expressSendStatus'](400);
+                controllerInstance['koaSendStatus'](400);
             }
             else if (err instanceof ValidationError) {
                 if (this.validationErrorLoggingEnabled) {
@@ -275,7 +281,7 @@ suggested fix:  "${convertRouteParams(path)}"
                 /**
                  * See comment at top of this method for philosophy of 400
                  */
-                controllerInstance['expressSendStatus'](400);
+                controllerInstance['koaSendStatus'](400);
             }
             else if (err instanceof OpenapiRequestValidationFailure) {
                 if (this.validationErrorLoggingEnabled) {
@@ -288,7 +294,7 @@ suggested fix:  "${convertRouteParams(path)}"
                 /**
                  * See comment at top of this method for philosophy of 400
                  */
-                controllerInstance['expressSendStatus'](400);
+                controllerInstance['koaSendStatus'](400);
             }
             else if (err instanceof ParamValidationError) {
                 if (this.validationErrorLoggingEnabled) {
@@ -302,7 +308,7 @@ suggested fix:  "${convertRouteParams(path)}"
                 /**
                  * See comment at top of this method for philosophy of 400
                  */
-                controllerInstance['expressSendStatus'](400);
+                controllerInstance['koaSendStatus'](400);
             }
             else if (err instanceof ParamValidationErrors) {
                 if (this.validationErrorLoggingEnabled) {
@@ -314,14 +320,14 @@ suggested fix:  "${convertRouteParams(path)}"
                 /**
                  * See comment at top of this method for philosophy of 400
                  */
-                controllerInstance['expressSendStatus'](400);
+                controllerInstance['koaSendStatus'](400);
             }
             else {
                 PsychicApp.logWithLevel('error', util.inspect(err, { depth: ERROR_LOGGING_DEPTH }));
                 if (PsychicApp.getOrFail().specialHooks.serverError.length) {
                     try {
                         for (const hook of PsychicApp.getOrFail().specialHooks.serverError) {
-                            await hook(err, req, res);
+                            await hook(err, ctx);
                         }
                     }
                     catch (error) {
@@ -348,17 +354,17 @@ suggested fix:  "${convertRouteParams(path)}"
             }
         }
     }
-    _initializeController(ControllerClass, req, res, action) {
-        return new ControllerClass(req, res, {
+    _initializeController(ControllerClass, ctx, action) {
+        return new ControllerClass(ctx, {
             action,
         });
     }
 }
 export class PsychicNestedRouter extends PsychicRouter {
     router;
-    constructor(expressApp, routeManager, { namespaces = [], } = {}) {
-        super(expressApp);
-        this.router = Router();
+    constructor(koaApp, routeManager, { namespaces = [], } = {}) {
+        super(koaApp);
+        this.router = new KoaRouter();
         this.currentNamespaces = namespaces;
         this.routeManager = routeManager;
     }

package/dist/esm/src/server/helpers/startPsychicServer.js

@@ -17,6 +17,7 @@ export default async function startPsychicServer({ app, port, sslCredentials, })
 }
 export function createPsychicHttpInstance(app, sslCredentials) {
     const psychicApp = PsychicApp.getOrFail();
+    const callback = app.callback();
     if (sslCredentials?.key && sslCredentials?.cert) {
         return https.createServer({
             key: fs.readFileSync(sslCredentials.key),
@@ -24,10 +25,13 @@ export function createPsychicHttpInstance(app, sslCredentials) {
             ca: sslCredentials.ca?.map(filePath => fs.readFileSync(filePath)),
             rejectUnauthorized: sslCredentials?.rejectUnauthorized,
             ...psychicApp.httpServerOptions,
-        }, app);
+        }, 
+        // eslint-disable-next-line @typescript-eslint/no-misused-promises
+        callback);
     }
     else {
-        return http.createServer(psychicApp.httpServerOptions, app);
+        // eslint-disable-next-line @typescript-eslint/no-misused-promises
+        return http.createServer(psychicApp.httpServerOptions, callback);
     }
 }
 function welcomeMessage({ port }) {

package/dist/esm/src/server/index.js

@@ -1,7 +1,9 @@
 import { closeAllDbConnections } from '@rvoh/dream/db';
-import * as cookieParser from 'cookie-parser';
-import * as cors from 'cors';
-import * as express from 'express';
+import cors from '@koa/cors';
+import Koa from 'koa';
+import koaBodyparser from 'koa-bodyparser';
+import conditional from 'koa-conditional-get';
+import etag from 'koa-etag';
 import logIfDevelopment from '../controller/helpers/logIfDevelopment.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import PsychicApp from '../psychic-app/index.js';
@@ -15,14 +17,14 @@ export default class PsychicServer {
     static createPsychicHttpInstance(app, sslCredentials) {
         return createPsychicHttpInstance(app, sslCredentials);
     }
-    expressApp;
+    koaApp;
     httpServer;
     booted = false;
     constructor() {
         this.buildApp();
     }
     async routes() {
-        const r = new PsychicRouter(this.expressApp);
+        const r = new PsychicRouter(this.koaApp);
         await PsychicApp.getOrFail().routesCb(r);
         return r.routes;
     }
@@ -31,16 +33,19 @@ export default class PsychicServer {
             return;
         const psychicApp = PsychicApp.getOrFail();
         this.setSecureDefaultHeaders();
-        this.expressApp.use((_, res, next) => {
+        this.koaApp.use(async (ctx, next) => {
             Object.keys(psychicApp.defaultResponseHeaders).forEach(key => {
-                res.setHeader(key, psychicApp.defaultResponseHeaders[key]);
+                ctx.set(key, psychicApp.defaultResponseHeaders[key]);
             });
-            next();
+            await next();
         });
         for (const serverInitBeforeMiddlewareHook of PsychicApp.getOrFail().specialHooks
             .serverInitBeforeMiddleware) {
             await serverInitBeforeMiddlewareHook(this);
         }
+        // ETag support (Express has this built-in, Koa needs middleware)
+        this.koaApp.use(conditional());
+        this.koaApp.use(etag());
         this.initializeCors();
         this.initializeJSON();
         try {
@@ -69,29 +74,23 @@ export default class PsychicServer {
     applyNotFoundMiddleware() {
         if (!EnvInternal.isDevelopment)
             return;
-        this.expressApp.use((req, res, next) => {
-            // express by default will set the 200 status code. If a user explicitly
-            // provides anything other than 200, we should assume that a prior middleware
-            // would have have sent headers, which would prevent any of this from happening.
-            // this means that if we are here, we should not be sending a 200. Future middleware
-            // by express will automatically pick this up and turn it into a 404, so we are
-            // going to automatically set the status to 404 now, so that our logger can
-            // pick up the correct status code.
-            if (res.statusCode === 200)
-                res.status(404);
-            logIfDevelopment({ req, res, startTime: Date.now(), fallbackStatusCode: 404 });
-            // call next to let express handle sending the 404
-            next();
+        this.koaApp.use(async (ctx, next) => {
+            await next();
+            // Koa defaults to 404 for unmatched routes. If nothing set the body,
+            // log the 404 in development.
+            if (ctx.status === 404 && !ctx.body) {
+                logIfDevelopment({ ctx, startTime: Date.now(), fallbackStatusCode: 404 });
+            }
         });
     }
     setSecureDefaultHeaders() {
-        this.expressApp.disable('x-powered-by');
-        this.expressApp.use((_, res, next) => {
-            res.setHeader('X-Content-Type-Options', 'nosniff');
+        // Koa doesn't send x-powered-by by default, no need to disable it.
+        this.koaApp.use(async (ctx, next) => {
+            ctx.set('X-Content-Type-Options', 'nosniff');
             if (EnvInternal.isProduction) {
-                res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+                ctx.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
             }
-            next();
+            await next();
         });
     }
     // TODO: use config helper for fetching default port
@@ -104,7 +103,7 @@ export default class PsychicServer {
         }
         else {
             const httpServer = await startPsychicServer({
-                app: this.expressApp,
+                app: this.koaApp,
                 port: port || psychicApp.port,
                 sslCredentials: PsychicApp.getOrFail().sslCredentials,
             });
@@ -146,26 +145,24 @@ export default class PsychicServer {
         await this.boot();
         let server;
         await new Promise(accept => {
-            server = this.expressApp.listen(port, () => accept({}));
+            server = this.koaApp.listen(port, () => accept({}));
         });
         await block();
         server.close();
         return true;
     }
     buildApp() {
-        this.expressApp = express.default();
-        this.expressApp.use(cookieParser.default());
+        this.koaApp = new Koa();
     }
     initializeCors() {
-        this.expressApp.use(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        cors.default(PsychicApp.getOrFail().corsOptions));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+        this.koaApp.use(cors(PsychicApp.getOrFail().corsOptions));
     }
     initializeJSON() {
-        this.expressApp.use(express.json(PsychicApp.getOrFail().jsonOptions));
+        this.koaApp.use(koaBodyparser(PsychicApp.getOrFail().jsonOptions));
     }
     async buildRoutes() {
-        const r = new PsychicRouter(this.expressApp);
+        const r = new PsychicRouter(this.koaApp);
         await PsychicApp.getOrFail().routesCb(r);
         r.commit();
     }

package/dist/esm/src/session/index.js

@@ -3,31 +3,28 @@ import cookieMaxAgeFromCookieOpts from '../helpers/cookieMaxAgeFromCookieOpts.js
 import EnvInternal from '../helpers/EnvInternal.js';
 import PsychicApp from '../psychic-app/index.js';
 export default class Session {
-    req;
-    res;
-    constructor(req, res) {
-        this.req = req;
-        this.res = res;
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
     }
     getCookie(name) {
-        const cookies = this.req.cookies;
-        const value = cookies[name];
+        const value = this.ctx.cookies.get(name);
         if (value)
             return InternalEncrypt.decryptCookie(value);
         return null;
     }
     setCookie(name, data, opts = {}) {
-        this.res.cookie(name, InternalEncrypt.encryptCookie(data), {
-            secure: EnvInternal.isProduction,
-            httpOnly: true,
+        this.ctx.cookies.set(name, InternalEncrypt.encryptCookie(data), {
             ...opts,
+            secure: opts.secure ?? EnvInternal.isProduction,
+            httpOnly: opts.httpOnly ?? true,
             maxAge: opts.maxAge
                 ? cookieMaxAgeFromCookieOpts(opts.maxAge)
-                : PsychicApp.getOrFail().cookieOptions?.maxAge,
+                : (PsychicApp.getOrFail().cookieOptions?.maxAge ?? cookieMaxAgeFromCookieOpts()),
         });
     }
     clearCookie(name) {
-        this.res.clearCookie(name);
+        this.ctx.cookies.set(name, '', { maxAge: 0 });
     }
     daysToMilliseconds(numDays) {
         return numDays * 60 * 60 * 24 * 1000;

package/dist/types/src/controller/helpers/logIfDevelopment.d.ts

@@ -1,7 +1,6 @@
-import { Request, Response } from 'express';
-export default function logIfDevelopment({ req, res, startTime, fallbackStatusCode, }: {
-    req: Request;
-    res: Response;
+import Koa from 'koa';
+export default function logIfDevelopment({ ctx, startTime, fallbackStatusCode, }: {
+    ctx: Koa.Context;
     startTime: number;
     fallbackStatusCode?: number;
 }): void;

package/dist/types/src/controller/index.d.ts

@@ -1,7 +1,7 @@
 import { Dream } from '@rvoh/dream';
 import { OpenapiSchemaBody } from '@rvoh/dream/openapi';
 import { DreamParamSafeAttributes, DreamParamSafeColumnNames, SerializerRendererOpts, StrictInterface } from '@rvoh/dream/types';
-import { Request, Response } from 'express';
+import Koa from 'koa';
 import { ControllerHook } from '../controller/hooks.js';
 import { HttpStatusCodeInt, HttpStatusSymbol } from '../error/http/status-codes.js';
 import OpenapiEndpointRenderer from '../openapi-renderer/endpoint.js';
@@ -101,13 +101,13 @@ export default class PsychicController {
      * and non-controllers
      */
     get isPsychicControllerInstance(): boolean;
-    req: Request;
-    res: Response;
+    ctx: Koa.Context;
     session: Session;
     action: string;
     renderOpts: SerializerRendererOpts;
     private startTime;
-    constructor(req: Request, res: Response, { action, }: {
+    private _responseSent;
+    constructor(ctx: Koa.Context, { action, }: {
         action: string;
     });
     /**
@@ -384,9 +384,20 @@ export default class PsychicController {
      * @param data - the data to validate and render
      */
     private validateAndRenderJsonResponse;
-    private expressSendJson;
-    private expressSendStatus;
-    private expressRedirect;
+    private koaSendJson;
+    /**
+     * @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
+     */
+    private getFastJsonStringifyFunction;
+    private koaSendStatus;
+    private koaRedirect;
     private logIfDevelopment;
     protected defaultSerializerPassthrough: SerializerResult;
     /**

package/dist/types/src/error/router/cannot-commit-routes-without-koa-app.d.ts

@@ -0,0 +1,3 @@
+export default class CannotCommitRoutesWithoutKoaApp extends Error {
+    get message(): string;
+}

package/dist/types/src/helpers/cookieMaxAgeFromCookieOpts.d.ts

@@ -1,2 +1,2 @@
 import { CustomCookieMaxAgeOptions } from '../psychic-app/index.js';
-export default function cookieMaxAgeFromCookieOpts(cookieOpts: CustomCookieMaxAgeOptions | undefined): number;
+export default function cookieMaxAgeFromCookieOpts(cookieOpts?: CustomCookieMaxAgeOptions): number;

package/dist/types/src/helpers/toJson.d.ts

@@ -1 +1 @@
-export default function toJson<T>(data: T, sanitize: boolean): string;
+export default function toJson<T>(data: T): string;

package/dist/types/src/helpers/validateOpenApiSchema.d.ts

@@ -1,4 +1,4 @@
-import { Ajv, type JSONSchemaType, type ValidateFunction } from 'ajv';
+import { Ajv, type ErrorObject, type JSONSchemaType, type ValidateFunction } from 'ajv';
 /**
  * @internal
  *
@@ -56,6 +56,10 @@ export declare function validateObject<T = unknown>(data: unknown, schema: JSONS
  * @returns A validator function that can be reused for multiple validations
  */
 export declare function createValidator<T = unknown>(schema: JSONSchemaType<T> | object, options?: ValidateOpenapiSchemaOptions): ValidateFunction<T>;
+/**
+ * Formats AJV errors into a more readable format
+ */
+export declare function formatAjvErrors(ajvErrors: ErrorObject[]): ValidationError[];
 export interface ValidationResult<T = unknown> {
     isValid: boolean;
     data?: T;

package/dist/types/src/openapi-renderer/helpers/OpenapiPayloadValidator.d.ts

@@ -98,6 +98,27 @@ export default class OpenapiPayloadValidator {
      * @param statusCode - the status code used to render
      */
     validateOpenapiResponseBody(data: any, statusCode: number): void;
+    /**
+     * @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: number): object | undefined;
+    /**
+     * @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: number): object | undefined;
     /**
      * @internal
      *
@@ -137,6 +158,26 @@ export default class OpenapiPayloadValidator {
      * @param headers - the request headers
      */
     private validateOrFail;
+    /**
+     * @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
+     */
+    private getCacheKey;
+    /**
+     * @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
+     */
+    private compileAndCacheValidator;
     /**
      * @internal
      *

package/dist/types/src/openapi-renderer/helpers/stringify-cache.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @internal
+ *
+ * Retrieves a cached stringify function if it exists.
+ *
+ * @param cacheKey - The cache key identifying the stringify function
+ * @returns The cached stringify function, or undefined if not found
+ */
+export declare function getCachedStringify(cacheKey: string): ((data: any) => string) | undefined;
+/**
+ * @internal
+ *
+ * Stores a compiled stringify function in the cache.
+ *
+ * @param cacheKey - The cache key identifying the stringify function
+ * @param stringifyFn - The compiled fast-json-stringify function to cache
+ */
+export declare function cacheStringify(cacheKey: string, stringifyFn: (data: any) => string): void;
+/**
+ * @internal
+ *
+ * Clears a specific stringify function from the cache.
+ * Used in test environments to ensure test isolation.
+ *
+ * @param cacheKey - The cache key identifying the stringify function to clear
+ */
+export declare function _testOnlyClearStringify(cacheKey: string): void;
+/**
+ * @internal
+ *
+ * Clears all stringify functions from the cache.
+ * Used in test environments to ensure test isolation.
+ */
+export declare function _testOnlyClearStringifyCache(): void;

package/dist/types/src/openapi-renderer/helpers/validator-cache.d.ts

@@ -0,0 +1,35 @@
+import { ValidateFunction } from 'ajv';
+/**
+ * @internal
+ *
+ * Retrieves a cached validator function if it exists.
+ *
+ * @param cacheKey - The cache key identifying the validator
+ * @returns The cached validator function, or undefined if not found
+ */
+export declare function getCachedValidator(cacheKey: string): ValidateFunction | undefined;
+/**
+ * @internal
+ *
+ * Stores a compiled validator function in the cache.
+ *
+ * @param cacheKey - The cache key identifying the validator
+ * @param validator - The compiled AJV validator function to cache
+ */
+export declare function cacheValidator(cacheKey: string, validator: ValidateFunction): void;
+/**
+ * @internal
+ *
+ * Clears a specific validator from the cache.
+ * Used in test environments to ensure test isolation.
+ *
+ * @param cacheKey - The cache key identifying the validator to clear
+ */
+export declare function _testOnlyClearValidator(cacheKey: string): void;
+/**
+ * @internal
+ *
+ * Clears all validators from the cache.
+ * Used in test environments to ensure test isolation.
+ */
+export declare function _testOnlyClearValidatorCache(): void;