feat(server): add lifecycle hooks for custom logic execution in ExpressServer

Author: cyber-hari

README.md

@@ -65,7 +65,10 @@ const config = new ServerConfigBuilder()
 
 const server = new ExpressServer(config, {
   beforeInit: srv => console.log('Initializing server...'),
+  beforeRoutes: app => console.log('Setting up routes...'),
+  afterRoutes: app => console.log('Routes initialized.'),
   afterInit: srv => console.log('Server initialized'),
+  onServerCreated: srv => console.log('HTTP/HTTPS server instance created.'),
   beforeStart: app => console.log('Starting server...'),
   afterStart: srv => console.log('Server started!'),
   beforeStop: srv => console.log('Stopping server...'),

src/server/server.ts

@@ -205,6 +205,9 @@ export class ExpressServer {
     // Set up middleware stack (order is critical)
     await this.setupMiddleware();
 
+    // Allow users to run custom logic before routes are registered (e.g. for adding global middleware, modifying app instance, etc.)
+    await this.runHook('beforeRoutes', this.app);
+
     // Set up default routes and error handling
     await this.setupRoutes();
 
@@ -637,6 +640,9 @@ export class ExpressServer {
     const routerToUse = this.externalRouter || this.rootRouter;
     this.app.use(this.globalPrefix, routerToUse);
 
+    // Allow users to run custom logic after routes are registered but before error handling is set up
+    await this.runHook('afterRoutes', this.app);
+
     // 404 handler (must be after all other routes)
     this.app.use((req: Request, res: Response) => {
       const status = HttpStatusCodes.NOT_FOUND;
@@ -796,6 +802,7 @@ export class ExpressServer {
         };
 
         this.server = this.createServerInstance(onListening);
+        this.runHook('onServerCreated', this.server);
         this.setupConnectionTracking();
         this.setupServerErrorHandling(reject);
       } catch (error) {

src/types/server.ts

@@ -1,5 +1,6 @@
 import type { Express, json, NextFunction, urlencoded, Request, Response } from 'express';
 import type http from 'node:http';
+import type https from 'node:https';
 import type { ExpressServer } from '@catbee/utils/server';
 import type { HelmetOptions } from 'helmet';
 import type { CompressionOptions } from 'compression';
@@ -454,8 +455,14 @@ export interface CatbeeServerConfig {
 export interface CatbeeServerHooks {
   /** Called before middleware & routes initialize */
   beforeInit?: (server: ExpressServer) => Promise<void> | void;
+  /** Called before any routes are registered */
+  beforeRoutes?: (app: Express) => Promise<void> | void;
+  /** Called after all routes are registered, before error handling middleware */
+  afterRoutes?: (app: Express) => Promise<void> | void;
   /** Called after middleware & routes initialize */
   afterInit?: (server: ExpressServer) => Promise<void> | void;
+  /** Called when the underlying HTTP/HTTPS server instance is created */
+  onServerCreated?: (server: http.Server | https.Server) => Promise<void> | void;
   /** Called before server starts listening */
   beforeStart?: (app: Express) => Promise<void> | void;
   /** Called after server is ready */