ts-packages 1.0.0

package/packages/server-utils/README.md

@@ -0,0 +1,281 @@
+# @naman_deep_singh/server-utils
+
+Extensible server utilities for Express.js microservices with multi-protocol support and TypeScript.
+
+## Installation
+
+```bash
+npm install @naman_deep_singh/server-utils
+```
+
+## Features
+
+- ✅ **Multi-protocol support** - HTTP, gRPC, JSON-RPC, WebSockets, Webhooks
+- ✅ **Express.js integration** with middleware collection
+- ✅ **Graceful shutdown** handling
+- ✅ **Health checks** with custom checks support
+- ✅ **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
+
+## Quick Start
+
+### Named Imports
+```typescript
+import { createServer } from '@naman_deep_singh/server-utils';
+
+const server = createServer('My API', '1.0.0', {
+  port: 3000,
+  cors: true,
+  helmet: true
+});
+
+// Add routes
+server.app.get('/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+// Start server
+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
+```typescript
+const server = createServer('Multi-Protocol Server', '1.0.0');
+
+server.app.get('/api/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+await server.start();
+```
+
+### gRPC Support
+```typescript
+// Add gRPC service (requires @grpc/grpc-js)
+server.addGrpcService(userProto.UserService.service, {
+  getUser: (call, callback) => {
+    callback(null, { id: call.request.id, name: 'John' });
+  }
+}, 50051); // Custom port
+```
+
+### JSON-RPC Support
+```typescript
+// Add JSON-RPC methods (requires jayson)
+server.addRpcMethods({
+  add: (params, callback) => {
+    callback(null, params[0] + params[1]);
+  },
+  getUser: (id, callback) => {
+    callback(null, { id, name: 'John' });
+  }
+}, '/rpc'); // Custom path
+```
+
+### WebSocket Support
+```typescript
+// Add Socket.IO (requires socket.io)
+const io = server.addSocketIO({
+  cors: true,
+  onConnection: (socket) => {
+    console.log('Client connected:', socket.id);
+    
+    socket.on('message', (data) => {
+      socket.broadcast.emit('message', data);
+    });
+  },
+  onDisconnection: (socket, reason) => {
+    console.log('Client disconnected:', socket.id, reason);
+  }
+});
+```
+
+### Webhook Support
+```typescript
+// Add secure webhooks
+server.addWebhook({
+  path: '/webhooks/github',
+  secret: process.env.GITHUB_WEBHOOK_SECRET,
+  handler: async (payload, headers) => {
+    if (payload.action === 'opened') {
+      console.log('New PR opened:', payload.pull_request.title);
+    }
+  }
+});
+
+server.addWebhook({
+  path: '/webhooks/stripe',
+  secret: process.env.STRIPE_WEBHOOK_SECRET,
+  handler: async (payload) => {
+    if (payload.type === 'payment_intent.succeeded') {
+      // Handle successful payment
+    }
+  }
+});
+```
+
+## Built-in Middleware
+
+### Logging Middleware
+```typescript
+import { createLoggingMiddleware, withLogging } 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
+```typescript
+import { validateFields } from '@naman_deep_singh/server-utils';
+
+server.app.post('/users', validateFields([
+  { field: 'email', required: true, type: 'email' },
+  { field: 'password', required: true, minLength: 8 },
+  { field: 'age', type: 'number', custom: (value) => value >= 18 || 'Must be 18+' }
+]), (req, res) => {
+  // Validation passed
+  res.json({ success: true });
+});
+```
+
+### Rate Limiting
+```typescript
+import { rateLimit } from '@naman_deep_singh/server-utils';
+
+server.app.use('/api', rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  maxRequests: 100,
+  message: 'Too many requests'
+}));
+```
+
+### Authentication Middleware
+```typescript
+import { requireAuth } from '@naman_deep_singh/server-utils';
+
+server.app.use('/protected', requireAuth({
+  tokenExtractor: (req) => req.headers.authorization?.substring(7),
+  tokenValidator: async (token) => {
+    // Verify JWT token
+    return jwt.verify(token, process.env.JWT_SECRET);
+  }
+}));
+```
+
+## Health Checks
+
+```typescript
+import { addHealthCheck } from '@naman_deep_singh/server-utils';
+
+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';
+      }
+    }
+  ]
+});
+```
+
+## Server Management
+
+### Server Information
+```typescript
+const info = server.getInfo();
+console.log(info);
+// {
+//   name: 'My API',
+//   version: '1.0.0',
+//   port: 3000,
+//   uptime: 12345,
+//   status: 'running',
+//   startTime: Date
+// }
+```
+
+### Graceful Shutdown
+```typescript
+const server = createServer('My API', '1.0.0', {
+  gracefulShutdown: true // Enabled by default
+});
+
+// Handles SIGINT and SIGTERM
+process.on('SIGINT', async () => {
+  await server.stop();
+  process.exit(0);
+});
+```
+
+## Configuration Options
+
+```typescript
+interface ServerConfig {
+  port?: number;                    // Default: 3000
+  cors?: boolean | CorsOptions;     // Default: true
+  helmet?: boolean;                 // Default: true
+  json?: boolean;                   // Default: true
+  customMiddleware?: RequestHandler[];
+  healthCheck?: boolean | string;   // Default: true
+  gracefulShutdown?: boolean;       // Default: true
+  socketIO?: SocketIOConfig;
+}
+```
+
+## API Reference
+
+### Core Functions
+- `createServer(name?, version?, config?)` - Create server instance
+- `ExpressServer` - Server class for advanced usage
+
+### Middleware Functions
+- `createLoggingMiddleware(format?)` - Request logging
+- `createErrorHandler()` - Error handling
+- `createValidationMiddleware(rules)` - Input validation
+- `createRateLimitMiddleware(config?)` - Rate limiting
+- `createAuthMiddleware(config)` - Authentication
+
+### Health & Monitoring
+- `createHealthCheck(config?)` - Health check endpoint
+- `addHealthCheck(app, path?, config?)` - Add health check to app
+
+### Graceful Shutdown
+- `createGracefulShutdown(server, config?)` - Setup graceful shutdown
+- `startServerWithShutdown(app, port, config?)` - Start with shutdown handling
+
+## Dependencies
+
+### Required
+- **express** - Web framework
+- **cors** - CORS middleware
+- **helmet** - Security middleware
+- **cookie-parser** - Cookie parsing
+
+### Optional (for specific features)
+- **@grpc/grpc-js** - For gRPC support
+- **jayson** - For JSON-RPC support
+- **socket.io** - For WebSocket support

package/packages/server-utils/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@naman_deep_singh/server-utils",
+  "version": "1.0.1",
+  "description": "Extensible server utilities for Express.js microservices with TypeScript",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "server",
+    "express",
+    "microservices",
+    "utils",
+    "typescript"
+  ],
+  "author": "Naman Deep Singh",
+  "license": "ISC",
+  "packageManager": "pnpm@10.20.0",
+  "dependencies": {
+    "express": "^4.21.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "typescript": "^5.9.3"
+  }
+}

package/packages/server-utils/src/health.ts

@@ -0,0 +1,47 @@
+import express from 'express';
+import { HealthCheckConfig, HealthCheck, ServerPlugin } from './types';
+
+export function createHealthCheck(config: HealthCheckConfig = {}): express.RequestHandler {
+  const { customChecks = [] } = config;
+
+  return async (req: express.Request, res: express.Response) => {
+    try {
+      const checks: Record<string, boolean> = {
+        server: true,
+        timestamp: Date.now() as any
+      };
+
+      // Run custom health checks
+      for (const check of customChecks) {
+        try {
+          checks[check.name] = await check.check();
+        } catch (error) {
+          checks[check.name] = false;
+        }
+      }
+
+      const isHealthy = Object.values(checks).every(status => status === true || typeof status === 'number');
+      
+      res.status(isHealthy ? 200 : 503).json({
+        status: isHealthy ? 'healthy' : 'unhealthy',
+        checks
+      });
+    } catch (error) {
+      res.status(503).json({
+        status: 'unhealthy',
+        error: 'Health check failed'
+      });
+    }
+  };
+}
+
+export function withHealthCheck(path: string = '/health', config: HealthCheckConfig = {}): ServerPlugin {
+  return (app: express.Application) => {
+    app.get(path, createHealthCheck(config));
+  };
+}
+
+// Convenience function for direct use
+export function addHealthCheck(app: express.Application, path: string = '/health', config: HealthCheckConfig = {}): void {
+  app.get(path, createHealthCheck(config));
+}

package/packages/server-utils/src/index.ts

@@ -0,0 +1,113 @@
+// Core server utilities
+export { ExpressServer, createServer } from './server';
+export type { ServerInstance, ServerInfo, GrpcService, RpcMethod, WebhookConfig } from './server';
+
+// Health check utilities
+export { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
+
+// Graceful shutdown utilities
+export { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
+
+// Middleware utilities
+export { 
+  createLoggingMiddleware, 
+  createErrorHandler, 
+  createRequestIdMiddleware,
+  createValidationMiddleware,
+  createRateLimitMiddleware,
+  createAuthMiddleware,
+  withLogging, 
+  withErrorHandler, 
+  withRequestId,
+  withValidation,
+  withRateLimit,
+  withAuth,
+  validateFields,
+  rateLimit,
+  requireAuth,
+  type ValidationRule,
+  type RateLimitConfig,
+  type AuthConfig
+} from './middleware';
+
+// Utility functions
+export {
+  getEnv,
+  getEnvNumber,
+  getEnvBoolean
+} from './utils';
+
+// Types
+export type { 
+  ServerConfig, 
+  HealthCheckConfig, 
+  HealthCheck, 
+  GracefulShutdownConfig, 
+  ServerPlugin,
+  SocketIOConfig,
+  SocketInstance 
+} from './types';
+
+// Import all exports for default export
+import { ExpressServer, createServer } from './server';
+import { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
+import { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
+import { 
+  createLoggingMiddleware, 
+  createErrorHandler, 
+  createRequestIdMiddleware,
+  createValidationMiddleware,
+  createRateLimitMiddleware,
+  createAuthMiddleware,
+  withLogging, 
+  withErrorHandler, 
+  withRequestId,
+  withValidation,
+  withRateLimit,
+  withAuth,
+  validateFields,
+  rateLimit,
+  requireAuth
+} from './middleware';
+import { getEnv, getEnvNumber, getEnvBoolean } from './utils';
+
+// Default export for namespace usage
+const ServerUtils = {
+  // Server creation
+  createServer,
+  ExpressServer,
+  
+  // Health checks
+  createHealthCheck,
+  withHealthCheck,
+  addHealthCheck,
+  
+  // Graceful shutdown
+  createGracefulShutdown,
+  withGracefulShutdown,
+  startServerWithShutdown,
+  
+  // Middleware
+  createLoggingMiddleware,
+  createErrorHandler,
+  createRequestIdMiddleware,
+  createValidationMiddleware,
+  createRateLimitMiddleware,
+  createAuthMiddleware,
+  withLogging,
+  withErrorHandler,
+  withRequestId,
+  withValidation,
+  withRateLimit,
+  withAuth,
+  validateFields,
+  rateLimit,
+  requireAuth,
+  
+  // Utils
+  getEnv,
+  getEnvNumber,
+  getEnvBoolean
+};
+
+export default ServerUtils;