navis.js 5.2.3 → 5.3.1

package/README.md

@@ -3,7 +3,7 @@
 A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js.
 
 **Author:** Syed Imran Ali  
-**Version:** 5.2.2  
+**Version:** 5.3.0  
 **License:** MIT
 
 ## Philosophy
@@ -72,6 +72,24 @@ exports.handler = async (event) => {
 };
 ```
 
+### TypeScript
+
+```typescript
+import { NavisApp, response } from 'navis.js';
+
+const app = new NavisApp();
+
+app.get('/', (req, res) => {
+  response.success(res, { 
+    message: 'Hello from Navis.js with TypeScript!'
+  });
+});
+
+app.listen(3000);
+```
+
+See `examples/server.ts` and `examples/typescript-features-demo.ts` for complete TypeScript examples.
+
 ## CLI
 
 ```bash
@@ -142,19 +160,25 @@ navis metrics
 - ✅ **Health checks** - Liveness and readiness probes
 - ✅ **Graceful shutdown** - Clean shutdown handling
 
-### v5.1 (Current)
+### v5.1
 
 - ✅ **OpenAPI/Swagger** - Auto-generate API documentation
 - ✅ **API versioning** - URL-based and header-based versioning
 - ✅ **File upload** - Multipart form data handling
 - ✅ **Testing utilities** - Test helpers for applications
 
-### v5.2 (Current)
+### v5.2
 
 - ✅ **WebSocket support** - Real-time bidirectional communication
 - ✅ **Server-Sent Events** - One-way real-time streaming
 - ✅ **Database integration** - Connection pooling for PostgreSQL, MySQL, MongoDB
 
+### v5.3 (Current)
+
+- ✅ **TypeScript support** - Full type definitions for all features
+- ✅ **Type-safe API** - Complete IntelliSense and type checking
+- ✅ **TypeScript examples** - Ready-to-use TypeScript examples
+
 ## API Reference
 
 ### NavisApp
@@ -337,13 +361,18 @@ exports.handler = async (event, context) => {
 See the `examples/` directory:
 
 - `server.js` - Node.js HTTP server example
+- `server.ts` - TypeScript HTTP server example (v5.3)
 - `lambda.js` - AWS Lambda handler example
+- `lambda.ts` - TypeScript Lambda handler example (v5.3)
 - `lambda-optimized.js` - Optimized Lambda handler with cold start optimizations (v3.1)
+- `typescript-features-demo.ts` - Complete TypeScript features demonstration (v5.3)
+- `v2-features-demo.js` - v2 features demonstration (retry, circuit breaker, etc.)
+- `v3-features-demo.js` - v3 features demonstration (messaging, observability, etc.)
 - `v4-features-demo.js` - v4 features demonstration (routing, validation, auth, rate limiting, etc.)
 - `v5-features-demo.js` - v5 features demonstration (caching, CORS, security, compression, health checks, etc.)
+- `v5.1-features-demo.js` - v5.1 features demonstration (Swagger, versioning, upload, testing)
+- `v5.2-features-demo.js` - v5.2 features demonstration (WebSocket, SSE, database)
 - `service-client-demo.js` - ServiceClient usage example
-- `v2-features-demo.js` - v2 features demonstration (retry, circuit breaker, etc.)
-- `v3-features-demo.js` - v3 features demonstration (messaging, observability, etc.)
 
 ## Roadmap
 
@@ -365,9 +394,12 @@ Enterprise-grade: caching, CORS, security headers, compression, health checks, g
 ### v5.1 ✅
 Developer experience: OpenAPI/Swagger, API versioning, file upload, testing utilities
 
-### v5.2 ✅ (Current)
+### v5.2 ✅
 Real-time features: WebSocket, Server-Sent Events, database integration
 
+### v5.3 ✅ (Current)
+TypeScript support: Full type definitions, type-safe API, IntelliSense
+
 ## What's Next?
 
 Future versions may include:
@@ -385,6 +417,7 @@ Future versions may include:
 - [V5 Features Guide](./docs/V5_FEATURES.md) - Complete v5 features documentation
 - [V5.1 Features Guide](./docs/V5.1_FEATURES.md) - Complete v5.1 features documentation
 - [V5.2 Features Guide](./docs/V5.2_FEATURES.md) - Complete v5.2 features documentation
+- [TypeScript Guide](./docs/TYPESCRIPT.md) - Complete TypeScript support documentation (v5.3)
 - [Lambda Optimization Guide](./docs/LAMBDA_OPTIMIZATION.md) - Lambda cold start optimization guide (v3.1)
 - [Verification Guide v2](./docs/VERIFY_V2.md) - How to verify v2 features
 - [Verification Guide v3](./docs/VERIFY_V3.md) - How to verify v3 features

package/examples/lambda.ts

@@ -0,0 +1,32 @@
+/**
+ * Navis.js TypeScript Example - AWS Lambda Handler
+ */
+
+import { NavisApp } from 'navis.js';
+
+const app = new NavisApp();
+
+// Lambda route handlers
+app.get('/hello', (req, res) => {
+  res.statusCode = 200;
+  res.body = {
+    message: 'Hello from Lambda with TypeScript!',
+    timestamp: new Date().toISOString()
+  };
+});
+
+app.get('/users/:id', (req, res) => {
+  const userId = req.params?.id;
+  res.statusCode = 200;
+  res.body = {
+    userId,
+    name: 'John Doe',
+    email: 'john@example.com'
+  };
+});
+
+// Export Lambda handler
+export const handler = async (event: any) => {
+  return await app.handleLambda(event);
+};
+

package/examples/server.ts

@@ -0,0 +1,47 @@
+/**
+ * Navis.js TypeScript Example - Node.js HTTP Server
+ */
+
+import { NavisApp, response } from 'navis.js';
+
+const app = new NavisApp();
+
+// Basic route with TypeScript types
+app.get('/', (req, res) => {
+  response.success(res, { 
+    message: 'Hello from Navis.js with TypeScript!',
+    version: '5.3.0'
+  });
+});
+
+// Route with parameters
+app.get('/users/:id', (req, res) => {
+  const userId = req.params?.id;
+  response.success(res, {
+    userId,
+    message: `User ${userId} found`
+  });
+});
+
+// POST route with body validation
+app.post('/users', (req, res) => {
+  const { name, email } = req.body || {};
+  
+  if (!name || !email) {
+    response.error(res, 'Name and email are required', 400);
+    return;
+  }
+  
+  response.success(res, {
+    id: Math.random().toString(36).substr(2, 9),
+    name,
+    email
+  }, 201);
+});
+
+// Start server
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`🚀 Navis.js TypeScript server running on http://localhost:${PORT}`);
+});
+

package/examples/typescript-features-demo.ts

@@ -0,0 +1,264 @@
+/**
+ * Navis.js TypeScript Features Demo
+ * Demonstrates TypeScript usage with all v5.3 features
+ */
+
+import {
+  NavisApp,
+  response,
+  ServiceClient,
+  Cache,
+  cache,
+  cors,
+  security,
+  compress,
+  createHealthChecker,
+  gracefulShutdown,
+  swagger,
+  createVersionManager,
+  headerVersioning,
+  upload,
+  testApp,
+  WebSocketServer,
+  sse,
+  createPool,
+  Logger,
+  Metrics,
+  validate,
+  authenticateJWT,
+  rateLimit,
+  errorHandler,
+} from 'navis.js';
+
+const app = new NavisApp();
+
+// ============================================
+// TypeScript with CORS
+// ============================================
+app.use(cors({
+  origin: ['http://localhost:3000'],
+  credentials: true,
+}));
+
+// ============================================
+// TypeScript with Security Headers
+// ============================================
+app.use(security({
+  helmet: true,
+  hsts: true,
+  noSniff: true,
+}));
+
+// ============================================
+// TypeScript with Compression
+// ============================================
+app.use(compress({
+  level: 6,
+  threshold: 1024,
+}));
+
+// ============================================
+// TypeScript with Caching
+// ============================================
+const cacheStore = new Cache({
+  maxSize: 1000,
+  defaultTTL: 3600000,
+});
+
+app.get('/users/:id', cache({
+  cacheStore,
+  ttl: 1800,
+  keyGenerator: (req) => `user:${req.params?.id}`,
+}), (req, res) => {
+  const userId = req.params?.id;
+  response.success(res, {
+    id: userId,
+    name: 'John Doe',
+    email: 'john@example.com',
+  });
+});
+
+// ============================================
+// TypeScript with Validation
+// ============================================
+app.post('/users', validate({
+  body: {
+    name: { type: 'string', required: true, minLength: 2 },
+    email: { type: 'string', required: true, format: 'email' },
+  },
+}), (req, res) => {
+  const { name, email } = req.body || {};
+  response.success(res, {
+    id: Math.random().toString(36).substr(2, 9),
+    name,
+    email,
+  }, 201);
+});
+
+// ============================================
+// TypeScript with Authentication
+// ============================================
+app.get('/protected', authenticateJWT({
+  secret: process.env.JWT_SECRET || 'secret',
+}), (req, res) => {
+  response.success(res, {
+    message: 'This is a protected route',
+    user: (req as any).user,
+  });
+});
+
+// ============================================
+// TypeScript with Rate Limiting
+// ============================================
+app.post('/api/endpoint', rateLimit({
+  windowMs: 60000,
+  max: 10,
+}), (req, res) => {
+  response.success(res, { message: 'Rate limited endpoint' });
+});
+
+// ============================================
+// TypeScript with Observability
+// ============================================
+const logger = new Logger({ level: 'INFO' });
+const metrics = new Metrics();
+
+app.use((req, res, next) => {
+  logger.info('Request received', {
+    method: req.method,
+    path: req.path,
+  });
+  metrics.increment('http_requests', 1, {
+    method: req.method,
+    path: req.path || '/',
+  });
+  next();
+});
+
+// ============================================
+// TypeScript with Service Client
+// ============================================
+const client = new ServiceClient('http://api.example.com', {
+  timeout: 5000,
+  maxRetries: 3,
+});
+
+app.get('/external', async (req, res) => {
+  try {
+    const result = await client.get('/data');
+    response.success(res, result.body);
+  } catch (error) {
+    response.error(res, 'External service error', 502);
+  }
+});
+
+// ============================================
+// TypeScript with Health Checks
+// ============================================
+const healthChecker = createHealthChecker({
+  checks: {
+    cache: async () => cacheStore.size() >= 0,
+    database: async () => true, // Mock check
+  },
+});
+
+app.use(healthChecker.middleware());
+
+// ============================================
+// TypeScript with Swagger
+// ============================================
+const swaggerMiddleware = swagger({
+  title: 'Navis.js TypeScript API',
+  version: '5.3.0',
+  description: 'API with full TypeScript support',
+});
+
+app.use(swaggerMiddleware.middleware);
+
+// ============================================
+// TypeScript with API Versioning
+// ============================================
+app.use(headerVersioning({
+  header: 'X-API-Version',
+  defaultVersion: 'v1',
+}));
+
+const versionManager = createVersionManager();
+const v1 = versionManager.version('v1');
+v1.get('/users/:id', (req, res) => {
+  response.success(res, { version: 'v1', userId: req.params?.id });
+});
+
+// ============================================
+// TypeScript with SSE
+// ============================================
+app.get('/events', sse(), (req, res) => {
+  res.sse?.send({ message: 'Connected' }, 'connection');
+  
+  let count = 0;
+  const interval = setInterval(() => {
+    count++;
+    res.sse?.send({ count, timestamp: new Date().toISOString() }, 'update');
+    
+    if (count >= 10) {
+      clearInterval(interval);
+      res.sse?.close();
+    }
+  }, 1000);
+  
+  (req as any).on('close', () => {
+    clearInterval(interval);
+  });
+});
+
+// ============================================
+// TypeScript with Error Handling
+// ============================================
+app.use(errorHandler());
+
+// ============================================
+// Routes
+// ============================================
+app.get('/', (req, res) => {
+  response.success(res, {
+    message: 'Navis.js TypeScript Features Demo',
+    version: '5.3.0',
+    features: [
+      'Full TypeScript support',
+      'Type-safe API',
+      'IntelliSense',
+      'Type checking',
+    ],
+  });
+});
+
+// ============================================
+// Start Server
+// ============================================
+const PORT = 3000;
+const server = app.listen(PORT, () => {
+  console.log(`\n🚀 Navis.js TypeScript Demo Server`);
+  console.log(`📡 Listening on http://localhost:${PORT}\n`);
+  console.log('Available endpoints:');
+  console.log('  GET  /');
+  console.log('  GET  /users/:id (cached)');
+  console.log('  POST /users (validated)');
+  console.log('  GET  /protected (authenticated)');
+  console.log('  GET  /events (SSE)');
+  console.log('  GET  /swagger.json (OpenAPI)');
+  console.log('  GET  /docs (Swagger UI)');
+  console.log('  GET  /health/ready (health check)');
+});
+
+// ============================================
+// Graceful Shutdown
+// ============================================
+gracefulShutdown(server, {
+  timeout: 10000,
+  onShutdown: async () => {
+    console.log('Cleaning up...');
+    cacheStore.destroy();
+    console.log('Cleanup complete');
+  },
+});
+

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "navis.js",
-  "version": "5.2.3",
+  "version": "5.3.1",
   "description": "A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js",
   "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "typings": "types/index.d.ts",
   "bin": {
     "navis": "bin/navis.js"
   },
   "files": [
     "src/",
+    "types/",
     "bin/",
     "examples/",
     "README.md",

package/types/index.d.ts

@@ -0,0 +1,711 @@
+/**
+ * Navis.js TypeScript Definitions
+ * v5.3: Full TypeScript support
+ */
+
+// ============================================
+// Core Types
+// ============================================
+
+export interface NavisRequest {
+  method: string;
+  path: string;
+  url?: string;
+  headers: Record<string, string>;
+  body?: any;
+  query?: Record<string, string>;
+  params?: Record<string, string>;
+  event?: any;
+  apiVersion?: string;
+  files?: FileUpload[];
+}
+
+export interface NavisResponse {
+  statusCode: number;
+  headers?: Record<string, string>;
+  body?: any;
+  writeHead?: (statusCode: number, headers?: Record<string, string>) => void;
+  setHeader?: (name: string, value: string) => void;
+  end?: (body?: any) => void;
+  finish?: (...args: any[]) => void;
+  sse?: {
+    send: (data: any, event?: string, id?: string) => boolean;
+    close: () => void;
+  };
+}
+
+export type Middleware = (req: NavisRequest, res: NavisResponse, next: () => Promise<void>) => Promise<void> | void;
+export type RouteHandler = (req: NavisRequest, res: NavisResponse) => Promise<void> | void | Promise<any> | any;
+
+export interface NavisAppOptions {
+  useAdvancedRouter?: boolean;
+}
+
+export interface NavisApp {
+  use(fn: Middleware): void;
+  get(path: string, ...handlers: (Middleware | RouteHandler)[]): void;
+  post(path: string, ...handlers: (Middleware | RouteHandler)[]): void;
+  put(path: string, ...handlers: (Middleware | RouteHandler)[]): void;
+  delete(path: string, ...handlers: (Middleware | RouteHandler)[]): void;
+  patch(path: string, ...handlers: (Middleware | RouteHandler)[]): void;
+  listen(port?: number, callback?: () => void): any;
+  handleLambda(event: any): Promise<any>;
+  getServer(): any;
+}
+
+// ============================================
+// Service Client Types
+// ============================================
+
+export interface ServiceClientOptions {
+  timeout?: number;
+  maxRetries?: number;
+  retryBaseDelay?: number;
+  retryMaxDelay?: number;
+  retryStatusCodes?: number[];
+  circuitBreaker?: CircuitBreakerOptions;
+}
+
+export interface CircuitBreakerOptions {
+  failureThreshold?: number;
+  resetTimeout?: number;
+  halfOpenMaxAttempts?: number;
+}
+
+export interface ServiceClientResponse {
+  statusCode: number;
+  body: any;
+  headers: Record<string, string>;
+}
+
+export interface ServiceClient {
+  get(path: string, options?: ServiceClientOptions): Promise<ServiceClientResponse>;
+  post(path: string, data?: any, options?: ServiceClientOptions): Promise<ServiceClientResponse>;
+  put(path: string, data?: any, options?: ServiceClientOptions): Promise<ServiceClientResponse>;
+  delete(path: string, options?: ServiceClientOptions): Promise<ServiceClientResponse>;
+  patch(path: string, data?: any, options?: ServiceClientOptions): Promise<ServiceClientResponse>;
+  getCircuitBreakerState(): string;
+  resetCircuitBreaker(): void;
+}
+
+// ============================================
+// Response Types
+// ============================================
+
+export interface ResponseHelpers {
+  success(context: NavisResponse, data: any, statusCode?: number, isLambda?: boolean): void;
+  error(context: NavisResponse, message: string, statusCode?: number, isLambda?: boolean): void;
+}
+
+// ============================================
+// Retry Types
+// ============================================
+
+export interface RetryOptions {
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  retryCondition?: (error: any, response?: any) => boolean;
+}
+
+export interface RetryHelpers {
+  retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+  shouldRetryHttpStatus(statusCode: number): boolean;
+}
+
+// ============================================
+// Circuit Breaker Types
+// ============================================
+
+export interface CircuitBreaker {
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+  getState(): 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+  isOpen(): boolean;
+  reset(): void;
+}
+
+// ============================================
+// Service Config Types
+// ============================================
+
+export interface ServiceConfigOptions {
+  defaultOptions?: ServiceClientOptions;
+}
+
+export interface ServiceConfig {
+  register(name: string, baseUrl: string, options?: ServiceClientOptions): void;
+  get(name: string): { baseUrl: string; options?: ServiceClientOptions } | null;
+  getAll(): Record<string, { baseUrl: string; options?: ServiceClientOptions }>;
+  unregister(name: string): void;
+}
+
+// ============================================
+// Service Discovery Types
+// ============================================
+
+export interface ServiceDiscoveryOptions {
+  healthCheckInterval?: number;
+  healthCheckTimeout?: number;
+  healthCheckPath?: string;
+}
+
+export interface ServiceDiscovery {
+  register(name: string, urls: string[], options?: ServiceDiscoveryOptions): void;
+  getNext(name: string): string | null;
+  getAll(name: string): string[];
+  unregister(name: string): void;
+  getHealthyUrls(name: string): string[];
+}
+
+// ============================================
+// Observability Types
+// ============================================
+
+export interface LoggerOptions {
+  level?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+  context?: Record<string, any>;
+}
+
+export interface Logger {
+  debug(message: string, meta?: Record<string, any>): void;
+  info(message: string, meta?: Record<string, any>): void;
+  warn(message: string, meta?: Record<string, any>): void;
+  error(message: string, meta?: Record<string, any>): void;
+  setLevel(level: string): void;
+  getLevel(): string;
+}
+
+export interface Metrics {
+  increment(name: string, value?: number, labels?: Record<string, string>): void;
+  decrement(name: string, value?: number, labels?: Record<string, string>): void;
+  gauge(name: string, value: number, labels?: Record<string, string>): void;
+  histogram(name: string, value: number, labels?: Record<string, string>): void;
+  recordRequest(method: string, path: string, duration: number, statusCode: number): void;
+  toPrometheus(): string;
+  reset(): void;
+}
+
+export interface TracerOptions {
+  serviceName?: string;
+}
+
+export interface Tracer {
+  startTrace(name: string, meta?: Record<string, any>): string;
+  startSpan(name: string, options?: { traceId?: string; meta?: Record<string, any> }): string;
+  finishSpan(spanId: string, meta?: Record<string, any>): void;
+  getTrace(traceId: string): { traceId: string; spans: any[] } | null;
+}
+
+// ============================================
+// Messaging Types
+// ============================================
+
+export interface SQSMessagingOptions {
+  region?: string;
+  queueUrl?: string;
+}
+
+export interface SQSMessaging {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  publish(queueUrl: string, message: any, options?: any): Promise<void>;
+  subscribe(queueUrl: string, handler: (message: any, metadata: any) => Promise<void>): Promise<void>;
+}
+
+export interface KafkaMessagingOptions {
+  brokers: string[];
+  clientId?: string;
+  consumerGroupId?: string;
+}
+
+export interface KafkaMessaging {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  publish(topic: string, message: any, options?: any): Promise<void>;
+  subscribe(topic: string, handler: (message: any, metadata: any) => Promise<void>): Promise<void>;
+}
+
+export interface NATSMessagingOptions {
+  servers: string[];
+}
+
+export interface NATSMessaging {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  publish(subject: string, message: any): Promise<void>;
+  subscribe(subject: string, handler: (message: any) => Promise<void>): Promise<void>;
+}
+
+// ============================================
+// Lambda Optimization Types
+// ============================================
+
+export interface ServiceClientPool {
+  get(baseUrl: string, options?: ServiceClientOptions): ServiceClient;
+  clear(): void;
+  size(): number;
+}
+
+export interface LazyInitOptions {
+  timeout?: number;
+}
+
+export interface LazyInit {
+  init<T>(initFn: () => Promise<T>): Promise<T>;
+  reset(): void;
+  isInitialized(): boolean;
+}
+
+export interface LambdaHandlerOptions {
+  enableMetrics?: boolean;
+  warmupPath?: string;
+}
+
+export interface LambdaHandler {
+  handle(event: any, context?: any): Promise<any>;
+  getStats(): any;
+  isWarm(): boolean;
+}
+
+// ============================================
+// Advanced Features Types (v4)
+// ============================================
+
+export interface ValidationSchema {
+  body?: Record<string, ValidationRule>;
+  query?: Record<string, ValidationRule>;
+  params?: Record<string, ValidationRule>;
+  headers?: Record<string, ValidationRule>;
+}
+
+export interface ValidationRule {
+  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  required?: boolean;
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string | RegExp;
+  format?: 'email' | 'uuid' | 'url';
+  enum?: any[];
+  items?: ValidationRule;
+  properties?: Record<string, ValidationRule>;
+  custom?: (value: any) => boolean | string;
+}
+
+export interface ValidationError extends Error {
+  field: string;
+  message: string;
+  code: string;
+}
+
+export interface AuthOptions {
+  secret?: string;
+  algorithm?: string;
+  issuer?: string;
+  audience?: string;
+}
+
+export interface RateLimitOptions {
+  windowMs?: number;
+  max?: number;
+  message?: string;
+  skipSuccessfulRequests?: boolean;
+  skipFailedRequests?: boolean;
+}
+
+export interface RateLimiter {
+  check(key: string): { allowed: boolean; remaining: number; resetTime: number };
+  reset(key: string): void;
+  clear(): void;
+}
+
+// ============================================
+// Enterprise Features Types (v5)
+// ============================================
+
+export interface CacheOptions {
+  maxSize?: number;
+  defaultTTL?: number;
+  cleanupInterval?: number;
+}
+
+export interface Cache {
+  set(key: string, value: any, ttl?: number): void;
+  get(key: string): any;
+  has(key: string): boolean;
+  delete(key: string): boolean;
+  clear(): void;
+  size(): number;
+  keys(): string[];
+  destroy(): void;
+}
+
+export interface RedisCacheOptions {
+  url?: string;
+  defaultTTL?: number;
+  prefix?: string;
+}
+
+export interface RedisCache {
+  connect(options?: any): Promise<void>;
+  disconnect(): Promise<void>;
+  set(key: string, value: any, ttl?: number): Promise<void>;
+  get(key: string): Promise<any>;
+  has(key: string): Promise<boolean>;
+  delete(key: string): Promise<boolean>;
+  clear(): Promise<void>;
+  size(): Promise<number>;
+}
+
+export interface CacheMiddlewareOptions {
+  cacheStore: Cache | RedisCache;
+  ttl?: number;
+  keyGenerator?: (req: NavisRequest) => string;
+  skipCache?: (req: NavisRequest, res: NavisResponse) => boolean;
+  vary?: string[];
+}
+
+export interface CORSOptions {
+  origin?: string | string[];
+  methods?: string[];
+  allowedHeaders?: string[];
+  exposedHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+  preflightContinue?: boolean;
+}
+
+export interface SecurityOptions {
+  helmet?: boolean;
+  hsts?: boolean;
+  hstsMaxAge?: number;
+  hstsIncludeSubDomains?: boolean;
+  hstsPreload?: boolean;
+  noSniff?: boolean;
+  xssFilter?: boolean;
+  frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+  contentSecurityPolicy?: boolean | Record<string, string[]>;
+  referrerPolicy?: string;
+  permissionsPolicy?: Record<string, string>;
+}
+
+export interface CompressionOptions {
+  level?: number;
+  threshold?: number;
+  algorithm?: 'gzip' | 'brotli';
+  filter?: (req: NavisRequest, res: NavisResponse) => boolean;
+}
+
+export interface HealthCheckOptions {
+  livenessPath?: string;
+  readinessPath?: string;
+  checks?: Record<string, () => Promise<boolean>>;
+  enabled?: boolean;
+}
+
+export interface HealthChecker {
+  addCheck(name: string, checkFn: () => Promise<boolean>): void;
+  removeCheck(name: string): void;
+  runChecks(includeReadiness?: boolean): Promise<any>;
+  middleware(): Middleware;
+}
+
+export interface GracefulShutdownOptions {
+  timeout?: number;
+  onShutdown?: () => Promise<void>;
+  signals?: string[];
+  log?: (message: string) => void;
+}
+
+// ============================================
+// Developer Experience Types (v5.1)
+// ============================================
+
+export interface SwaggerOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+  path?: string;
+  uiPath?: string;
+  servers?: Array<{ url: string; description?: string }>;
+  tags?: Array<{ name: string; description?: string }>;
+}
+
+export interface SwaggerGenerator {
+  addRoute(method: string, path: string, spec?: any): void;
+  addSchema(name: string, schema: any): void;
+  addSecurityScheme(name: string, scheme: any): void;
+  generate(): any;
+  toJSON(): string;
+}
+
+export interface SwaggerMiddleware {
+  generator: SwaggerGenerator;
+  middleware: Middleware;
+}
+
+export interface VersionManager {
+  version(version: string): {
+    get: (path: string, handler: RouteHandler) => void;
+    post: (path: string, handler: RouteHandler) => void;
+    put: (path: string, handler: RouteHandler) => void;
+    delete: (path: string, handler: RouteHandler) => void;
+    patch: (path: string, handler: RouteHandler) => void;
+    use: (middleware: Middleware) => void;
+  };
+  setDefaultVersion(version: string): void;
+  getRoutes(version: string): any;
+  getVersions(): string[];
+}
+
+export interface HeaderVersioningOptions {
+  header?: string;
+  defaultVersion?: string;
+}
+
+export interface FileUploadOptions {
+  dest?: string;
+  limits?: {
+    fileSize?: number;
+    files?: number;
+  };
+  fileFilter?: (file: FileUpload) => boolean;
+  preserveExtension?: boolean;
+  generateFilename?: (file: FileUpload) => string;
+}
+
+export interface FileUpload {
+  fieldname: string;
+  originalname: string;
+  encoding: string;
+  mimetype: string;
+  size: number;
+  destination: string;
+  filename: string;
+  path: string;
+  buffer?: Buffer;
+  stream?: any;
+}
+
+export interface TestApp {
+  get(path: string, options?: any): Promise<TestResponse>;
+  post(path: string, data?: any, options?: any): Promise<TestResponse>;
+  put(path: string, data?: any, options?: any): Promise<TestResponse>;
+  delete(path: string, options?: any): Promise<TestResponse>;
+  patch(path: string, data?: any, options?: any): Promise<TestResponse>;
+}
+
+export interface TestResponse {
+  statusCode: number;
+  headers: Record<string, string>;
+  body: any;
+  json(): any;
+  text(): string;
+}
+
+// ============================================
+// Real-time Features Types (v5.2)
+// ============================================
+
+export interface WebSocketServerOptions {
+  server?: any;
+  path?: string;
+}
+
+export interface WebSocketClient {
+  id: string;
+  socket: any;
+  request: any;
+  send(data: any): boolean;
+  close(): void;
+}
+
+export interface WebSocketServer {
+  attach(server: any): void;
+  on(path: string, handler: (message: any, client: WebSocketClient) => void): void;
+  onConnection(handler: (client: WebSocketClient) => void): void;
+  onDisconnection(handler: (client: WebSocketClient) => void): void;
+  broadcast(data: any): void;
+  getClients(): WebSocketClient[];
+}
+
+export interface SSEServer {
+  middleware(): Middleware;
+  broadcast(data: any, event?: string): void;
+  getClients(): any[];
+}
+
+export interface DatabasePoolOptions {
+  type?: 'postgres' | 'postgresql' | 'mysql' | 'mariadb' | 'mongodb';
+  connectionString?: string;
+  maxConnections?: number;
+  minConnections?: number;
+  idleTimeout?: number;
+}
+
+export interface DatabasePool {
+  connect(): Promise<void>;
+  query(query: string, params?: any[]): Promise<any>;
+  getConnection(): Promise<any>;
+  close(): Promise<void>;
+  ping(): Promise<boolean>;
+}
+
+// ============================================
+// Main Exports
+// ============================================
+
+export const NavisApp: {
+  new (options?: NavisAppOptions): NavisApp;
+};
+
+export const ServiceClient: {
+  new (baseUrl: string, options?: ServiceClientOptions): ServiceClient;
+};
+
+export const ServiceConfig: {
+  new (options?: ServiceConfigOptions): ServiceConfig;
+};
+
+export const ServiceDiscovery: {
+  new (): ServiceDiscovery;
+};
+
+export const CircuitBreaker: {
+  new (options?: CircuitBreakerOptions): CircuitBreaker;
+};
+
+export const Logger: {
+  new (options?: LoggerOptions): Logger;
+};
+
+export const Metrics: {
+  new (): Metrics;
+};
+
+export const Tracer: {
+  new (options?: TracerOptions): Tracer;
+};
+
+export const SQSMessaging: {
+  new (options?: SQSMessagingOptions): SQSMessaging;
+};
+
+export const KafkaMessaging: {
+  new (options?: KafkaMessagingOptions): KafkaMessaging;
+};
+
+export const NATSMessaging: {
+  new (options?: NATSMessagingOptions): NATSMessaging;
+};
+
+export const ServiceClientPool: {
+  new (): ServiceClientPool;
+};
+
+export const LazyInit: {
+  new (options?: LazyInitOptions): LazyInit;
+};
+
+export const LambdaHandler: {
+  new (app: NavisApp, options?: LambdaHandlerOptions): LambdaHandler;
+};
+
+export const AdvancedRouter: {
+  new (): any;
+};
+
+export const RateLimiter: {
+  new (options?: RateLimitOptions): RateLimiter;
+};
+
+export const Cache: {
+  new (options?: CacheOptions): Cache;
+};
+
+export const RedisCache: {
+  new (options?: RedisCacheOptions): RedisCache;
+};
+
+export const HealthChecker: {
+  new (options?: HealthCheckOptions): HealthChecker;
+};
+
+export const SwaggerGenerator: {
+  new (options?: SwaggerOptions): SwaggerGenerator;
+};
+
+export const VersionManager: {
+  new (): VersionManager;
+};
+
+export const TestApp: {
+  new (app: NavisApp): TestApp;
+};
+
+export const WebSocketServer: {
+  new (options?: WebSocketServerOptions): WebSocketServer;
+};
+
+export const SSEServer: {
+  new (): SSEServer;
+};
+
+export const DatabasePool: {
+  new (options?: DatabasePoolOptions): DatabasePool;
+};
+
+// Functions
+export function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+export function shouldRetryHttpStatus(statusCode: number): boolean;
+export function validate(schema: ValidationSchema): Middleware;
+export function authenticateJWT(options?: AuthOptions): Middleware;
+export function authenticateAPIKey(options?: AuthOptions): Middleware;
+export function authorize(roles: string[]): Middleware;
+export function optionalAuth(options?: AuthOptions): Middleware;
+export function rateLimit(options?: RateLimitOptions): Middleware;
+export function errorHandler(): Middleware;
+export function asyncHandler(fn: RouteHandler): RouteHandler;
+export function notFoundHandler(): RouteHandler;
+export function cache(options: CacheMiddlewareOptions): Middleware;
+export function cors(options?: CORSOptions): Middleware;
+export function security(options?: SecurityOptions): Middleware;
+export function compress(options?: CompressionOptions): Middleware;
+export function swagger(options?: SwaggerOptions): SwaggerMiddleware;
+export function createVersionManager(): VersionManager;
+export function headerVersioning(options?: HeaderVersioningOptions): Middleware;
+export function upload(options?: FileUploadOptions): Middleware;
+export function saveFile(file: FileUpload, dest: string, generateFilename?: (file: FileUpload) => string): Promise<string>;
+export function testApp(app: NavisApp): TestApp;
+export function sse(): Middleware;
+export function createSSEServer(): SSEServer;
+export function createPool(options?: DatabasePoolOptions): DatabasePool;
+export function createHealthChecker(options?: HealthCheckOptions): HealthChecker;
+export function gracefulShutdown(server: any, options?: GracefulShutdownOptions): any;
+export function getPool(): ServiceClientPool;
+export function createLazyInit(initFn: () => Promise<any>, options?: LazyInitOptions): LazyInit;
+export function coldStartTracker(): Middleware;
+
+// Error Classes
+export class ValidationError extends Error {
+  field: string;
+  code: string;
+}
+
+export class AuthenticationError extends Error {}
+export class AuthorizationError extends Error {}
+export class AppError extends Error {
+  statusCode: number;
+}
+export class NotFoundError extends AppError {}
+export class BadRequestError extends AppError {}
+export class UnauthorizedError extends AppError {}
+export class ForbiddenError extends AppError {}
+export class ConflictError extends AppError {}
+export class InternalServerError extends AppError {}
+
+// Response and Retry helpers
+export const response: ResponseHelpers;
+export const retry: RetryHelpers;
+