@naman_deep_singh/server-utils 1.2.0 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @naman_deep_singh/server-utils
 
-**Version:** 1.2.0 (with integrated cache & session support)
+**Version:** 1.3.0 (with integrated cache & session support)
 
 Extensible server utilities for Express.js microservices with multi-protocol support, integrated caching, session management, and TypeScript.
 
@@ -19,13 +19,13 @@ npm install @naman_deep_singh/server-utils
 - ✅ **Graceful shutdown** handling with cache/session cleanup
 - ✅ **Health checks** with custom checks and cache health integration
 - ✅ **TypeScript support** with full type safety
-- ✅ **Hybrid exports** - use named imports or namespace imports
-- ✅ **Plugin architecture** for extensibility
+
 - ✅ **Built-in middleware** - logging, validation, rate limiting, auth, caching, sessions
 
+
 ## Quick Start
 
-### Named Imports
+### Basic Usage
 ```typescript
 import { createServer } from '@naman_deep_singh/server-utils';
 
@@ -44,13 +44,6 @@ server.app.get('/users', (req, res) => {
 await server.start();
 ```
 
-### Namespace Import
-```typescript
-import ServerUtils from '@naman_deep_singh/server-utils';
-
-const server = ServerUtils.createServer('My API', '1.0.0');
-```
-
 ## Multi-Protocol Support
 
 ### HTTP + Express Routes
@@ -131,17 +124,13 @@ server.addWebhook({
 
 ## Built-in Middleware
 
+
 ### Logging Middleware
 ```typescript
-import { createLoggingMiddleware, withLogging } from '@naman_deep_singh/server-utils';
+import { createLoggingMiddleware } from '@naman_deep_singh/server-utils';
 
 // Direct usage
 server.app.use(createLoggingMiddleware('detailed'));
-
-// Plugin usage
-const server = createServerWithPlugins('My API', '1.0.0', [
-  withLogging('detailed')
-]);
 ```
 
 ### Validation Middleware
@@ -184,52 +173,16 @@ server.app.use('/protected', requireAuth({
 
 ## Health Checks
 
+
 ### Basic Health Check
 ```typescript
-import { addHealthCheck, createHealthCheck, withHealthCheck } from '@naman_deep_singh/server-utils';
+import { createHealthCheck } from '@naman_deep_singh/server-utils';
 
-// Method 1: Direct addition
-addHealthCheck(server.app, '/health');
+// The health check is automatically enabled when healthCheck is not false
+// Health endpoint is available at /health by default
 
-// Method 2: As middleware
+// If you need to customize or disable it:
 server.app.get('/health', createHealthCheck());
-
-// Method 3: As plugin
-const server = createServerWithPlugins('My API', '1.0.0', [
-  withHealthCheck('/health')
-]);
-```
-
-### Advanced Health Checks
-```typescript
-addHealthCheck(server.app, '/health', {
-  customChecks: [
-    {
-      name: 'database',
-      check: async () => {
-        // Check database connection
-        return await db.ping();
-      }
-    },
-    {
-      name: 'redis',
-      check: async () => {
-        return await redis.ping() === 'PONG';
-      }
-    }
-  ]
-});
-
-// Response format:
-// {
-//   "status": "healthy",
-//   "checks": {
-//     "server": true,
-//     "timestamp": 1640995200000,
-//     "database": true,
-//     "redis": false
-//   }
-// }
 ```
 
 ## Server Management
@@ -332,6 +285,12 @@ import { Request, Response, NextFunction, Router, Application } from '@naman_dee
 import type { RequestHandler, ErrorRequestHandler } from '@naman_deep_singh/server-utils';
 
 // No need to install Express separately in your services
+
+## TypeScript Notes
+
+- This package includes TypeScript augmentations for Express `Request` and `Application` that expose runtime helpers used by the middleware (for example `req.cache`, `req.sessionStore`, `req.getSession`, and `req.createSession`). Installing and importing `@naman_deep_singh/server-utils` in your project will surface these types automatically.
+- Middleware that attaches runtime props uses `unknown` internally and runtime guards — prefer the provided helpers rather than casting `req` to `any`.
+
 ```
 
 ## API Reference

package/dist/cjs/middleware.js

@@ -252,9 +252,9 @@ function cacheResponse(ttl) {
         try {
             if (req.method !== 'GET')
                 return next();
-            const cache = req.cache || req.app.locals.cache;
+            const cache = (req.cache ?? req.app.locals.cache);
             const defaultTTL = req.app.locals.cacheDefaultTTL;
-            if (!cache)
+            if (!cache || typeof cache.get !== 'function')
                 return next();
             const key = `${req.originalUrl}`;
             try {
@@ -272,15 +272,17 @@ function cacheResponse(ttl) {
             res.json = (body) => {
                 try {
                     const expiry = ttl ?? defaultTTL;
-                    if (expiry && cache) {
+                    if (expiry && cache && typeof cache.set === 'function') {
                         cache.set(key, body, expiry).catch((err) => {
                             console.error(`[Cache] Failed to set key "${key}" with TTL ${expiry}:`, err);
                         });
                     }
                     else if (cache) {
-                        cache.set(key, body).catch((err) => {
-                            console.error(`[Cache] Failed to set key "${key}":`, err);
-                        });
+                        if (typeof cache.set === 'function') {
+                            cache.set(key, body).catch((err) => {
+                                console.error(`[Cache] Failed to set key "${key}":`, err);
+                            });
+                        }
                     }
                 }
                 catch (e) {
@@ -305,7 +307,7 @@ function useSession(cookieName) {
             if (!store)
                 return next();
             const name = cookieName || req.app.locals.sessionCookieName || 'sid';
-            let sid = req.cookies?.[name] || req.cookies?.[name];
+            let sid = req.cookies?.[name];
             if (!sid) {
                 const cookieHeader = req.headers.cookie;
                 if (cookieHeader) {

package/dist/cjs/server.d.ts

@@ -49,6 +49,8 @@ export declare class ExpressServer implements ServerInstance {
     app: express.Application;
     server?: Server;
     config: ServerInstanceConfig;
+    cache?: import('@naman_deep_singh/cache').ICache<unknown>;
+    sessionStore?: import('@naman_deep_singh/cache').SessionStore | undefined;
     private status;
     private grpcServices;
     private grpcServer?;

package/dist/cjs/server.js

@@ -114,17 +114,15 @@ class ExpressServer {
             // Initialize cache if enabled
             if (config.cache && config.cache.enabled) {
                 try {
-                    const provided = config.cache.options;
+                    const provided = config.cache?.options;
                     let cacheConfig = provided && typeof provided === 'object' ? provided : undefined;
                     if (!cacheConfig) {
                         cacheConfig = { adapter: config.cache.adapter || 'memory' };
                     }
                     console.log(`🔄 [${serverName}] Initializing cache adapter: ${config.cache.adapter || 'memory'}...`);
                     // Use createWithFallback to prefer primary and fall back to memory when configured
-                    const cache = await cache_1.CacheFactory.createWithFallback({
-                        ...(cacheConfig || {}),
-                        ttl: cacheConfig?.ttl ?? config.cache?.defaultTTL
-                    });
+                    const cfg = { ...(cacheConfig || {}), ttl: cacheConfig?.ttl ?? config.cache?.defaultTTL };
+                    const cache = await cache_1.CacheFactory.createWithFallback(cfg);
                     this.app.locals.cache = cache;
                     this.cache = cache;
                     this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;

package/dist/cjs/shutdown.d.ts

@@ -2,4 +2,4 @@ import { Server } from 'http';
 import { GracefulShutdownConfig, ServerPlugin } from './types';
 export declare function createGracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
 export declare function withGracefulShutdown(config?: GracefulShutdownConfig): ServerPlugin;
-export declare function startServerWithShutdown(app: any, port: number, shutdownConfig?: GracefulShutdownConfig, serverName?: string, serverVersion?: string): Server;
+export declare function startServerWithShutdown(app: import('express').Application, port: number, shutdownConfig?: GracefulShutdownConfig, serverName?: string, serverVersion?: string): Server;

package/dist/esm/middleware.js

@@ -233,9 +233,9 @@ export function cacheResponse(ttl) {
         try {
             if (req.method !== 'GET')
                 return next();
-            const cache = req.cache || req.app.locals.cache;
+            const cache = (req.cache ?? req.app.locals.cache);
             const defaultTTL = req.app.locals.cacheDefaultTTL;
-            if (!cache)
+            if (!cache || typeof cache.get !== 'function')
                 return next();
             const key = `${req.originalUrl}`;
             try {
@@ -253,15 +253,17 @@ export function cacheResponse(ttl) {
             res.json = (body) => {
                 try {
                     const expiry = ttl ?? defaultTTL;
-                    if (expiry && cache) {
+                    if (expiry && cache && typeof cache.set === 'function') {
                         cache.set(key, body, expiry).catch((err) => {
                             console.error(`[Cache] Failed to set key "${key}" with TTL ${expiry}:`, err);
                         });
                     }
                     else if (cache) {
-                        cache.set(key, body).catch((err) => {
-                            console.error(`[Cache] Failed to set key "${key}":`, err);
-                        });
+                        if (typeof cache.set === 'function') {
+                            cache.set(key, body).catch((err) => {
+                                console.error(`[Cache] Failed to set key "${key}":`, err);
+                            });
+                        }
                     }
                 }
                 catch (e) {
@@ -286,7 +288,7 @@ export function useSession(cookieName) {
             if (!store)
                 return next();
             const name = cookieName || req.app.locals.sessionCookieName || 'sid';
-            let sid = req.cookies?.[name] || req.cookies?.[name];
+            let sid = req.cookies?.[name];
             if (!sid) {
                 const cookieHeader = req.headers.cookie;
                 if (cookieHeader) {

package/dist/esm/server.d.ts

@@ -49,6 +49,8 @@ export declare class ExpressServer implements ServerInstance {
     app: express.Application;
     server?: Server;
     config: ServerInstanceConfig;
+    cache?: import('@naman_deep_singh/cache').ICache<unknown>;
+    sessionStore?: import('@naman_deep_singh/cache').SessionStore | undefined;
     private status;
     private grpcServices;
     private grpcServer?;

package/dist/esm/server.js

@@ -107,17 +107,15 @@ export class ExpressServer {
             // Initialize cache if enabled
             if (config.cache && config.cache.enabled) {
                 try {
-                    const provided = config.cache.options;
+                    const provided = config.cache?.options;
                     let cacheConfig = provided && typeof provided === 'object' ? provided : undefined;
                     if (!cacheConfig) {
                         cacheConfig = { adapter: config.cache.adapter || 'memory' };
                     }
                     console.log(`🔄 [${serverName}] Initializing cache adapter: ${config.cache.adapter || 'memory'}...`);
                     // Use createWithFallback to prefer primary and fall back to memory when configured
-                    const cache = await CacheFactory.createWithFallback({
-                        ...(cacheConfig || {}),
-                        ttl: cacheConfig?.ttl ?? config.cache?.defaultTTL
-                    });
+                    const cfg = { ...(cacheConfig || {}), ttl: cacheConfig?.ttl ?? config.cache?.defaultTTL };
+                    const cache = await CacheFactory.createWithFallback(cfg);
                     this.app.locals.cache = cache;
                     this.cache = cache;
                     this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;

package/dist/esm/shutdown.d.ts

@@ -2,4 +2,4 @@ import { Server } from 'http';
 import { GracefulShutdownConfig, ServerPlugin } from './types';
 export declare function createGracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
 export declare function withGracefulShutdown(config?: GracefulShutdownConfig): ServerPlugin;
-export declare function startServerWithShutdown(app: any, port: number, shutdownConfig?: GracefulShutdownConfig, serverName?: string, serverVersion?: string): Server;
+export declare function startServerWithShutdown(app: import('express').Application, port: number, shutdownConfig?: GracefulShutdownConfig, serverName?: string, serverVersion?: string): Server;

package/dist/types/server.d.ts

@@ -49,6 +49,8 @@ export declare class ExpressServer implements ServerInstance {
     app: express.Application;
     server?: Server;
     config: ServerInstanceConfig;
+    cache?: import('@naman_deep_singh/cache').ICache<unknown>;
+    sessionStore?: import('@naman_deep_singh/cache').SessionStore | undefined;
     private status;
     private grpcServices;
     private grpcServer?;

package/dist/types/shutdown.d.ts

@@ -2,4 +2,4 @@ import { Server } from 'http';
 import { GracefulShutdownConfig, ServerPlugin } from './types';
 export declare function createGracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
 export declare function withGracefulShutdown(config?: GracefulShutdownConfig): ServerPlugin;
-export declare function startServerWithShutdown(app: any, port: number, shutdownConfig?: GracefulShutdownConfig, serverName?: string, serverVersion?: string): Server;
+export declare function startServerWithShutdown(app: import('express').Application, port: number, shutdownConfig?: GracefulShutdownConfig, serverName?: string, serverVersion?: string): Server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naman_deep_singh/server-utils",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Extensible server utilities for Express.js microservices with TypeScript",
   "type": "module",
   "main": "./dist/cjs/index.js",