@rvoh/psychic 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+## v1.1.0
+
+Provides easier access to express middleware by exposing `PsychicApp#use`, which enables a developer to provide express middleware directly through the psychcic application, without tapping into any hooks.
+
+```ts
+psy.use((_, res) => {
+  res.send(
+    'this will be run after psychic middleware (i.e. cors and bodyParser) are processed, but before routes are processed',
+  )
+})
+```
+
+Some middleware needs to be run before other middleware, so we expose an optional first argument which can be provided so explicitly send your middleware into express at various stages of the psychic configuration process. For example, to inject your middleware before cors and bodyParser are configured, provide `before-middleware` as the first argument. To initialize your middleware after the psychic default middleware, but before your routes have been processed, provide `after-middleware` as the first argument (or simply provide a callback function directly, since this is the default). To run after routes have been processed, provide `after-routes` as the first argument.
+
+```ts
+psy.use('before-middleware', (_, res) => {
+  res.send('this will be run before psychic has configured any default middleware')
+})
+
+psy.use('after-middleware', (_, res) => {
+  res.send('this will be run after psychic has configured default middleware')
+})
+
+psy.use('after-routes', (_, res) => {
+  res.send('this will be run after psychic has processed all the routes in your conf/routes.ts file')
+})
+```
+
+Additionally, a new overload has been added to all CRUD methods on the PsychicRouter class, enabling you to provide RequestHandler middleware directly to psychic, like so:
+
+```ts
+// conf/routes.ts
+
+r.get('helloworld', (req, res, next) => {
+  res.json({ hello: 'world' })
+})
+```
+
+## 1.1.1
+
+Fix route printing regression causing route printouts to show the path instead of the action

package/dist/cjs/src/bin/helpers/printRoutes.js

@@ -25,10 +25,14 @@ async function printRoutes() {
 }
 function buildExpressions(routes) {
     return routes.map(route => {
+        const formattedPath = '/' + route.path.replace(/^\//, '');
         const method = route.httpMethod.toUpperCase();
         const numMethodSpaces = 8 - method.length;
-        const beginningOfExpression = `${route.httpMethod.toUpperCase()}${' '.repeat(numMethodSpaces)}${route.path}`;
-        const endOfExpression = route.controller.disaplayName + '#' + route.action;
+        const beginningOfExpression = `${route.httpMethod.toUpperCase()}${' '.repeat(numMethodSpaces)}${formattedPath}`;
+        const controllerRouteConf = route;
+        const endOfExpression = controllerRouteConf.controller
+            ? controllerRouteConf.controller.controllerActionPath(controllerRouteConf.action)
+            : 'middleware';
         return [beginningOfExpression, endOfExpression];
     });
 }
@@ -53,5 +57,5 @@ function calculateNumSpacesInLastGap(expressions) {
         if (expression.length > desiredSpaceCount)
             desiredSpaceCount = expression.length;
     });
-    return desiredSpaceCount + 3;
+    return desiredSpaceCount;
 }

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

@@ -242,7 +242,10 @@ class OpenapiEndpointRenderer {
     getCurrentRouteConfig(routes) {
         // if the action is update, we want to specifically find the 'patch' route,
         // otherwise we find any route that matches
-        const filteredRoutes = routes.filter(routeConfig => routeConfig.controller === this.controllerClass && routeConfig.action === this.action);
+        const filteredRoutes = routes.filter(routeConfig => {
+            const controllerRouteConf = routeConfig;
+            return (controllerRouteConf.controller === this.controllerClass && controllerRouteConf.action === this.action);
+        });
         const route = this.action === 'update'
             ? filteredRoutes.find(routeConfig => routeConfig.httpMethod === 'patch')
             : filteredRoutes.at(0);

package/dist/cjs/src/psychic-app/index.js

@@ -290,6 +290,35 @@ Try setting it to something valid, like:
         await this.inflections?.();
         this.booted = true;
     }
+    use(pathOrOnOrHandler, maybeHandler) {
+        if (maybeHandler) {
+            const eventType = pathOrOnOrHandler;
+            const handler = maybeHandler;
+            const wrappedHandler = (server) => {
+                server.expressApp.use(handler);
+            };
+            switch (eventType) {
+                case 'before-middleware':
+                    this.on('server:init:before-middleware', wrappedHandler);
+                    break;
+                case 'after-middleware':
+                    this.on('server:init:after-middleware', wrappedHandler);
+                    break;
+                case 'after-routes':
+                    this.on('server:init:after-routes', wrappedHandler);
+                    break;
+                default:
+                    throw new Error(`missing required case handler for PsychicApp#use: "${eventType}"`);
+            }
+            return;
+        }
+        else {
+            const wrappedHandler = (server) => {
+                server.expressApp.use(pathOrOnOrHandler);
+            };
+            this.on('server:init:after-middleware', wrappedHandler);
+        }
+    }
     plugin(cb) {
         this._plugins.push(cb);
     }

package/dist/cjs/src/psychic-app/types.js

@@ -1,2 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PsychicUseEventTypeValues = void 0;
+exports.PsychicUseEventTypeValues = ['before-middleware', 'after-middleware', 'after-routes'];

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

@@ -36,9 +36,18 @@ class PsychicRouter {
     // this is called after all routes have been processed.
     commit() {
         this.routes.forEach(route => {
-            this.app[route.httpMethod]((0, helpers_js_1.routePath)(route.path), (req, res) => {
-                this.handle(route.controller, route.action, { req, res }).catch(() => { });
-            });
+            if (route.middleware) {
+                const routeConf = route;
+                this.app[routeConf.httpMethod]((0, helpers_js_1.routePath)(routeConf.path), (req, res, next) => {
+                    this.handleMiddleware(routeConf.middleware, { req, res, next }).catch(() => { });
+                });
+            }
+            else {
+                const routeConf = route;
+                this.app[routeConf.httpMethod]((0, helpers_js_1.routePath)(routeConf.path), (req, res) => {
+                    this.handle(routeConf.controller, routeConf.action, { req, res }).catch(() => { });
+                });
+            }
         });
     }
     get(path, controller, action) {
@@ -64,17 +73,30 @@ class PsychicRouter {
             return str;
         return '/' + this.currentNamespacePaths.join('/') + '/' + str;
     }
-    crud(httpMethod, path, controller, action) {
-        controller ||= (0, helpers_js_1.lookupControllerOrFail)(this, { path, httpMethod });
-        action ||= path.replace(/^\//, '');
-        if (action.match(/\//))
-            throw new Error('action cant have a slash in it - action was inferred from path');
-        this.routeManager.addRoute({
-            httpMethod,
-            path: this.prefixPathWithNamespaces(path),
-            controller,
-            action,
-        });
+    crud(httpMethod, path, controllerOrMiddleware, action) {
+        const isMiddleware = typeof controllerOrMiddleware === 'function' &&
+            !controllerOrMiddleware?.isPsychicController;
+        // devs can provide custom express middleware which bypasses
+        // the normal Controller#action paradigm.
+        if (isMiddleware) {
+            this.routeManager.addMiddleware({
+                httpMethod,
+                path: this.prefixPathWithNamespaces(path),
+                middleware: controllerOrMiddleware,
+            });
+        }
+        else {
+            controllerOrMiddleware ||= (0, helpers_js_1.lookupControllerOrFail)(this, { path, httpMethod });
+            action ||= path.replace(/^\//, '');
+            if (action.match(/\//))
+                throw new Error('action cant have a slash in it - action was inferred from path');
+            this.routeManager.addRoute({
+                httpMethod,
+                path: this.prefixPathWithNamespaces(path),
+                controller: controllerOrMiddleware,
+                action,
+            });
+        }
     }
     namespace(namespace, cb) {
         const nestedRouter = new PsychicNestedRouter(this.app, this.config, this.routeManager, {
@@ -187,6 +209,9 @@ class PsychicRouter {
         if (nestedRouter)
             nestedRouter.currentNamespaces = this.currentNamespaces;
     }
+    async handleMiddleware(middleware, { req, res, next, }) {
+        await middleware(req, res, next);
+    }
     async handle(controller, action, { req, res, }) {
         const controllerInstance = this._initializeController(controller, req, res, action);
         try {

package/dist/cjs/src/router/route-manager.js

@@ -10,5 +10,12 @@ class RouteManager {
             action,
         });
     }
+    addMiddleware({ httpMethod, path, middleware, }) {
+        this.routes.push({
+            httpMethod,
+            path,
+            middleware,
+        });
+    }
 }
 exports.default = RouteManager;

package/dist/esm/src/bin/helpers/printRoutes.js

@@ -19,10 +19,14 @@ export default async function printRoutes() {
 }
 function buildExpressions(routes) {
     return routes.map(route => {
+        const formattedPath = '/' + route.path.replace(/^\//, '');
         const method = route.httpMethod.toUpperCase();
         const numMethodSpaces = 8 - method.length;
-        const beginningOfExpression = `${route.httpMethod.toUpperCase()}${' '.repeat(numMethodSpaces)}${route.path}`;
-        const endOfExpression = route.controller.disaplayName + '#' + route.action;
+        const beginningOfExpression = `${route.httpMethod.toUpperCase()}${' '.repeat(numMethodSpaces)}${formattedPath}`;
+        const controllerRouteConf = route;
+        const endOfExpression = controllerRouteConf.controller
+            ? controllerRouteConf.controller.controllerActionPath(controllerRouteConf.action)
+            : 'middleware';
         return [beginningOfExpression, endOfExpression];
     });
 }
@@ -47,5 +51,5 @@ function calculateNumSpacesInLastGap(expressions) {
         if (expression.length > desiredSpaceCount)
             desiredSpaceCount = expression.length;
     });
-    return desiredSpaceCount + 3;
+    return desiredSpaceCount;
 }

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

@@ -236,7 +236,10 @@ export default class OpenapiEndpointRenderer {
     getCurrentRouteConfig(routes) {
         // if the action is update, we want to specifically find the 'patch' route,
         // otherwise we find any route that matches
-        const filteredRoutes = routes.filter(routeConfig => routeConfig.controller === this.controllerClass && routeConfig.action === this.action);
+        const filteredRoutes = routes.filter(routeConfig => {
+            const controllerRouteConf = routeConfig;
+            return (controllerRouteConf.controller === this.controllerClass && controllerRouteConf.action === this.action);
+        });
         const route = this.action === 'update'
             ? filteredRoutes.find(routeConfig => routeConfig.httpMethod === 'patch')
             : filteredRoutes.at(0);

package/dist/esm/src/psychic-app/index.js

@@ -261,6 +261,35 @@ Try setting it to something valid, like:
         await this.inflections?.();
         this.booted = true;
     }
+    use(pathOrOnOrHandler, maybeHandler) {
+        if (maybeHandler) {
+            const eventType = pathOrOnOrHandler;
+            const handler = maybeHandler;
+            const wrappedHandler = (server) => {
+                server.expressApp.use(handler);
+            };
+            switch (eventType) {
+                case 'before-middleware':
+                    this.on('server:init:before-middleware', wrappedHandler);
+                    break;
+                case 'after-middleware':
+                    this.on('server:init:after-middleware', wrappedHandler);
+                    break;
+                case 'after-routes':
+                    this.on('server:init:after-routes', wrappedHandler);
+                    break;
+                default:
+                    throw new Error(`missing required case handler for PsychicApp#use: "${eventType}"`);
+            }
+            return;
+        }
+        else {
+            const wrappedHandler = (server) => {
+                server.expressApp.use(pathOrOnOrHandler);
+            };
+            this.on('server:init:after-middleware', wrappedHandler);
+        }
+    }
     plugin(cb) {
         this._plugins.push(cb);
     }

package/dist/esm/src/psychic-app/types.js

@@ -1 +1 @@
-export {};
+export const PsychicUseEventTypeValues = ['before-middleware', 'after-middleware', 'after-routes'];

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

@@ -30,9 +30,18 @@ export default class PsychicRouter {
     // this is called after all routes have been processed.
     commit() {
         this.routes.forEach(route => {
-            this.app[route.httpMethod](routePath(route.path), (req, res) => {
-                this.handle(route.controller, route.action, { req, res }).catch(() => { });
-            });
+            if (route.middleware) {
+                const routeConf = route;
+                this.app[routeConf.httpMethod](routePath(routeConf.path), (req, res, next) => {
+                    this.handleMiddleware(routeConf.middleware, { req, res, next }).catch(() => { });
+                });
+            }
+            else {
+                const routeConf = route;
+                this.app[routeConf.httpMethod](routePath(routeConf.path), (req, res) => {
+                    this.handle(routeConf.controller, routeConf.action, { req, res }).catch(() => { });
+                });
+            }
         });
     }
     get(path, controller, action) {
@@ -58,17 +67,30 @@ export default class PsychicRouter {
             return str;
         return '/' + this.currentNamespacePaths.join('/') + '/' + str;
     }
-    crud(httpMethod, path, controller, action) {
-        controller ||= lookupControllerOrFail(this, { path, httpMethod });
-        action ||= path.replace(/^\//, '');
-        if (action.match(/\//))
-            throw new Error('action cant have a slash in it - action was inferred from path');
-        this.routeManager.addRoute({
-            httpMethod,
-            path: this.prefixPathWithNamespaces(path),
-            controller,
-            action,
-        });
+    crud(httpMethod, path, controllerOrMiddleware, action) {
+        const isMiddleware = typeof controllerOrMiddleware === 'function' &&
+            !controllerOrMiddleware?.isPsychicController;
+        // devs can provide custom express middleware which bypasses
+        // the normal Controller#action paradigm.
+        if (isMiddleware) {
+            this.routeManager.addMiddleware({
+                httpMethod,
+                path: this.prefixPathWithNamespaces(path),
+                middleware: controllerOrMiddleware,
+            });
+        }
+        else {
+            controllerOrMiddleware ||= lookupControllerOrFail(this, { path, httpMethod });
+            action ||= path.replace(/^\//, '');
+            if (action.match(/\//))
+                throw new Error('action cant have a slash in it - action was inferred from path');
+            this.routeManager.addRoute({
+                httpMethod,
+                path: this.prefixPathWithNamespaces(path),
+                controller: controllerOrMiddleware,
+                action,
+            });
+        }
     }
     namespace(namespace, cb) {
         const nestedRouter = new PsychicNestedRouter(this.app, this.config, this.routeManager, {
@@ -181,6 +203,9 @@ export default class PsychicRouter {
         if (nestedRouter)
             nestedRouter.currentNamespaces = this.currentNamespaces;
     }
+    async handleMiddleware(middleware, { req, res, next, }) {
+        await middleware(req, res, next);
+    }
     async handle(controller, action, { req, res, }) {
         const controllerInstance = this._initializeController(controller, req, res, action);
         try {

package/dist/esm/src/router/route-manager.js

@@ -8,4 +8,11 @@ export default class RouteManager {
             action,
         });
     }
+    addMiddleware({ httpMethod, path, middleware, }) {
+        this.routes.push({
+            httpMethod,
+            path,
+            middleware,
+        });
+    }
 }

package/dist/types/src/psychic-app/index.d.ts

@@ -2,12 +2,12 @@ import { DreamApp, DreamAppInitOptions, DreamLogLevel, DreamLogger, EncryptOptio
 import * as bodyParser from 'body-parser';
 import { Command } from 'commander';
 import { CorsOptions } from 'cors';
-import { Request, Response } from 'express';
+import { Request, RequestHandler, Response } from 'express';
 import * as http from 'node:http';
 import { OpenapiContent, OpenapiHeaders, OpenapiResponses, OpenapiSecurity, OpenapiSecuritySchemes, OpenapiServer } from '../openapi-renderer/endpoint.js';
 import PsychicRouter from '../router/index.js';
 import PsychicServer from '../server/index.js';
-import { PsychicHookEventType } from './types.js';
+import { PsychicHookEventType, PsychicUseEventType } from './types.js';
 export default class PsychicApp {
     static init(cb: (app: PsychicApp) => void | Promise<void>, dreamCb: (app: DreamApp) => void | Promise<void>, opts?: PsychicAppInitOptions): Promise<PsychicApp>;
     static lookupClassByGlobalName(name: string): any;
@@ -89,6 +89,9 @@ export default class PsychicApp {
     load<RT extends 'controllers' | 'services' | 'initializers'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
     private booted;
     boot(force?: boolean): Promise<void>;
+    use(on: PsychicUseEventType, handler: RequestHandler): void;
+    use(handler: RequestHandler): void;
+    use(handler: () => void): void;
     plugin(cb: (app: PsychicApp) => void | Promise<void>): void;
     on<T extends PsychicHookEventType>(hookEventType: T, cb: T extends 'server:error' ? (err: Error, req: Request, res: Response) => void | Promise<void> : T extends 'server:init:before-middleware' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-middleware' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:start' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:shutdown' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-routes' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'cli:start' ? (program: Command) => void | Promise<void> : T extends 'cli:sync' ? () => any : (conf: PsychicApp) => void | Promise<void>): void;
     set(option: 'openapi', name: string, value: NamedPsychicOpenapiOptions): void;

package/dist/types/src/psychic-app/types.d.ts

@@ -2,6 +2,8 @@ import PsychicApp from './index.js';
 export type UUID = string;
 export type PsychicHookEventType = 'cli:sync' | 'server:init:before-middleware' | 'server:init:after-middleware' | 'server:init:after-routes' | 'server:start' | 'server:error' | 'server:shutdown';
 export type PsychicAppInitializerCb = (psychicApp: PsychicApp) => void | Promise<void>;
+export declare const PsychicUseEventTypeValues: readonly ["before-middleware", "after-middleware", "after-routes"];
+export type PsychicUseEventType = (typeof PsychicUseEventTypeValues)[number];
 type Only<T, U> = T & Partial<Record<Exclude<keyof U, keyof T>, never>>;
 export type Either<T, U> = Only<T, U> | Only<U, T>;
 export {};

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

@@ -1,4 +1,4 @@
-import { Express, Request, Response, Router } from 'express';
+import { Express, NextFunction, Request, RequestHandler, Response, Router } from 'express';
 import PsychicController from '../controller/index.js';
 import PsychicApp from '../psychic-app/index.js';
 import { NamespaceConfig, PsychicControllerActions } from '../router/helpers.js';
@@ -15,19 +15,26 @@ export default class PsychicRouter {
     private get currentNamespacePaths();
     commit(): void;
     get(path: string): void;
+    get(path: string, middleware: RequestHandler): void;
     get<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
     post(path: string): void;
+    post(path: string, middleware: RequestHandler): void;
     post<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
     put(path: string): void;
+    put(path: string, middleware: RequestHandler): void;
     put<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
     patch(path: string): void;
+    patch(path: string, middleware: RequestHandler): void;
     patch<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
     delete(path: string): void;
+    delete(path: string, middleware: RequestHandler): void;
     delete<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
     options(path: string): void;
+    options(path: string, middleware: RequestHandler): void;
     options<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
     private prefixPathWithNamespaces;
     crud(httpMethod: HttpMethod, path: string): void;
+    crud(httpMethod: HttpMethod, path: string, middleware: RequestHandler): void;
     crud(httpMethod: HttpMethod, path: string, controller: typeof PsychicController, action: string): void;
     namespace(namespace: string, cb: (router: PsychicNestedRouter) => void): void;
     scope(scope: string, cb: (router: PsychicNestedRouter) => void): void;
@@ -40,6 +47,11 @@ export default class PsychicRouter {
     private addNamespace;
     private removeLastNamespace;
     private makeRoomForNewIdParam;
+    handleMiddleware(middleware: RequestHandler, { req, res, next, }: {
+        req: Request;
+        res: Response;
+        next: NextFunction;
+    }): Promise<void>;
     handle(controller: typeof PsychicController, action: string, { req, res, }: {
         req: Request;
         res: Response;

package/dist/types/src/router/route-manager.d.ts

@@ -1,3 +1,4 @@
+import { RequestHandler } from 'express';
 import PsychicController from '../controller/index.js';
 import { HttpMethod } from './types.js';
 export default class RouteManager {
@@ -8,10 +9,22 @@ export default class RouteManager {
         controller: typeof PsychicController;
         action: string;
     }): void;
+    addMiddleware({ httpMethod, path, middleware, }: {
+        httpMethod: HttpMethod;
+        path: string;
+        middleware: RequestHandler;
+    }): void;
 }
-export interface RouteConfig {
-    controller: typeof PsychicController;
-    action: string;
-    path: string;
+export type RouteConfig = ControllerActionRouteConfig | MiddlewareRouteConfig;
+interface BaseRouteConfig {
     httpMethod: HttpMethod;
+    path: string;
 }
+export type ControllerActionRouteConfig = BaseRouteConfig & {
+    controller: typeof PsychicController;
+    action: string;
+};
+export type MiddlewareRouteConfig = BaseRouteConfig & {
+    middleware: RequestHandler;
+};
+export {};

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "author": "RVOHealth",
   "repository": {
     "type": "git",