navis.js 5.0.0 → 5.2.1

package/README.md

@@ -129,7 +129,7 @@ navis metrics
 - ✅ **Rate limiting** - In-memory rate limiting with configurable windows
 - ✅ **Enhanced error handling** - Custom error classes and error handler middleware
 
-### v5 (Current)
+### v5
 
 - ✅ **Caching layer** - In-memory cache with TTL and Redis adapter
 - ✅ **CORS support** - Cross-Origin Resource Sharing middleware
@@ -138,6 +138,19 @@ navis metrics
 - ✅ **Health checks** - Liveness and readiness probes
 - ✅ **Graceful shutdown** - Clean shutdown handling
 
+### v5.1 (Current)
+
+- ✅ **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)
+
+- ✅ **WebSocket support** - Real-time bidirectional communication
+- ✅ **Server-Sent Events** - One-way real-time streaming
+- ✅ **Database integration** - Connection pooling for PostgreSQL, MySQL, MongoDB
+
 ## API Reference
 
 ### NavisApp
@@ -342,15 +355,23 @@ Advanced features: async messaging (SQS/Kafka/NATS), observability, enhanced CLI
 ### v4 ✅
 Production-ready: advanced routing, validation, authentication, rate limiting, error handling
 
-### v5 ✅ (Current)
+### v5 ✅
 Enterprise-grade: caching, CORS, security headers, compression, health checks, graceful shutdown
 
+### v5.1 ✅ (Current)
+Developer experience: OpenAPI/Swagger, API versioning, file upload, testing utilities
+
+### v5.2 ✅ (Current)
+Real-time features: WebSocket, Server-Sent Events, database integration
+
 ## Documentation
 
 - [V2 Features Guide](./V2_FEATURES.md) - Complete v2 features documentation
 - [V3 Features Guide](./V3_FEATURES.md) - Complete v3 features documentation
 - [V4 Features Guide](./V4_FEATURES.md) - Complete v4 features documentation
 - [V5 Features Guide](./V5_FEATURES.md) - Complete v5 features documentation
+- [V5.1 Features Guide](./V5.1_FEATURES.md) - Complete v5.1 features documentation
+- [V5.2 Features Guide](./V5.2_FEATURES.md) - Complete v5.2 features documentation
 - [Lambda Optimization Guide](./LAMBDA_OPTIMIZATION.md) - Lambda cold start optimization guide (v3.1)
 - [Verification Guide v2](./VERIFY_V2.md) - How to verify v2 features
 - [Verification Guide v3](./VERIFY_V3.md) - How to verify v3 features

package/examples/v5.1-features-demo.js

@@ -0,0 +1,192 @@
+/**
+ * Navis.js v5.1 Features Demo
+ * Demonstrates OpenAPI/Swagger, API versioning, file upload, and testing utilities
+ */
+
+const {
+  NavisApp,
+  response,
+  swagger,
+  createVersionManager,
+  headerVersioning,
+  upload,
+  testApp,
+} = require('../src/index');
+
+const app = new NavisApp();
+
+// ============================================
+// OpenAPI/Swagger Documentation
+// ============================================
+const swaggerMiddleware = swagger({
+  title: 'Navis.js API',
+  version: '5.1.0',
+  description: 'API documentation for Navis.js',
+  path: '/swagger.json',
+  uiPath: '/docs',
+  servers: [{ url: 'http://localhost:3000', description: 'Development server' }],
+  tags: [
+    { name: 'users', description: 'User operations' },
+    { name: 'posts', description: 'Post operations' },
+  ],
+});
+
+app.use(swaggerMiddleware.middleware);
+
+// Add routes to Swagger
+swaggerMiddleware.generator.addRoute('GET', '/users/:id', {
+  summary: 'Get user by ID',
+  description: 'Retrieve a user by their ID',
+  tags: ['users'],
+  parameters: [
+    {
+      name: 'id',
+      in: 'path',
+      required: true,
+      schema: { type: 'string' },
+    },
+  ],
+  responses: {
+    '200': {
+      description: 'User found',
+      content: {
+        'application/json': {
+          schema: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              name: { type: 'string' },
+            },
+          },
+        },
+      },
+    },
+    '404': { description: 'User not found' },
+  },
+});
+
+// ============================================
+// API Versioning
+// ============================================
+const versionManager = createVersionManager();
+
+// Version 1
+const v1 = versionManager.version('v1');
+v1.get('/users/:id', (req, res) => {
+  response.success(res, {
+    version: 'v1',
+    userId: req.params.id,
+    format: 'legacy',
+  });
+});
+
+// Version 2
+const v2 = versionManager.version('v2');
+v2.get('/users/:id', (req, res) => {
+  response.success(res, {
+    version: 'v2',
+    userId: req.params.id,
+    format: 'modern',
+    metadata: { source: 'v2-api' },
+  });
+});
+
+// Register versioned routes
+v1.get('/users/:id', (req, res) => {
+  response.success(res, { version: 'v1', userId: req.params.id });
+});
+v2.get('/users/:id', (req, res) => {
+  response.success(res, { version: 'v2', userId: req.params.id });
+});
+
+// Apply versioned routes to app
+for (const version of versionManager.getVersions()) {
+  const routes = versionManager.getRoutes(version);
+  for (const method in routes) {
+    for (const route of routes[method]) {
+      app[method.toLowerCase()](route.path, route.handler);
+    }
+  }
+}
+
+// Header-based versioning
+app.use(headerVersioning({
+  header: 'X-API-Version',
+  defaultVersion: 'v1',
+}));
+
+// ============================================
+// File Upload
+// ============================================
+app.post('/upload', upload({
+  dest: './uploads',
+  limits: {
+    fileSize: 5 * 1024 * 1024, // 5MB
+    files: 5,
+  },
+  fileFilter: (file) => {
+    // Allow images and PDFs
+    return file.mimetype.startsWith('image/') || file.mimetype === 'application/pdf';
+  },
+}), (req, res) => {
+  response.success(res, {
+    message: 'Files uploaded',
+    files: req.files || [],
+    fields: req.body,
+  });
+});
+
+// ============================================
+// Routes
+// ============================================
+app.get('/', (req, res) => {
+  response.success(res, {
+    message: 'Navis.js v5.1 Features Demo',
+    features: [
+      'OpenAPI/Swagger Documentation',
+      'API Versioning',
+      'File Upload',
+      'Testing Utilities',
+    ],
+    endpoints: {
+      swagger: '/swagger.json',
+      docs: '/docs',
+      v1: '/v1/users/:id',
+      v2: '/v2/users/:id',
+      upload: 'POST /upload',
+    },
+  });
+});
+
+app.get('/users/:id', (req, res) => {
+  response.success(res, {
+    userId: req.params.id,
+    version: req.apiVersion || 'default',
+  });
+});
+
+// ============================================
+// Start Server
+// ============================================
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`\n🚀 Navis.js v5.1 Features Demo Server`);
+  console.log(`📡 Listening on http://localhost:${PORT}\n`);
+  console.log('Available endpoints:');
+  console.log('  GET  /');
+  console.log('  GET  /swagger.json (OpenAPI spec)');
+  console.log('  GET  /docs (Swagger UI)');
+  console.log('  GET  /v1/users/:id (API v1)');
+  console.log('  GET  /v2/users/:id (API v2)');
+  console.log('  GET  /users/:id (with X-API-Version header)');
+  console.log('  POST /upload (file upload)');
+  console.log('\n💡 Test with:');
+  console.log('  curl http://localhost:3000/');
+  console.log('  curl http://localhost:3000/v1/users/123');
+  console.log('  curl http://localhost:3000/v2/users/123');
+  console.log('  curl -H "X-API-Version: v2" http://localhost:3000/users/123');
+  console.log('  curl http://localhost:3000/swagger.json');
+});
+
+module.exports = app;
+

package/examples/v5.2-features-demo.js

@@ -0,0 +1,153 @@
+/**
+ * Navis.js v5.2 Features Demo
+ * Demonstrates WebSocket, Server-Sent Events, and database integration
+ */
+
+const {
+  NavisApp,
+  response,
+  WebSocketServer,
+  sse,
+  createPool,
+} = require('../src/index');
+
+const app = new NavisApp();
+
+// ============================================
+// Server-Sent Events (SSE)
+// ============================================
+app.get('/events', sse(), (req, res) => {
+  // Send initial event
+  res.sse.send({ message: 'Connected to SSE stream' }, 'connection');
+
+  // Send periodic updates
+  let count = 0;
+  const interval = setInterval(() => {
+    count++;
+    res.sse.send({
+      timestamp: new Date().toISOString(),
+      count,
+      data: `Event ${count}`,
+    }, 'update');
+
+    // Close after 10 events
+    if (count >= 10) {
+      clearInterval(interval);
+      res.sse.send({ message: 'Stream ended' }, 'close');
+      setTimeout(() => res.sse.close(), 1000);
+    }
+  }, 1000);
+
+  // Cleanup on disconnect
+  req.on('close', () => {
+    clearInterval(interval);
+  });
+});
+
+// ============================================
+// Database Integration (Example)
+// ============================================
+// Note: Requires database packages (pg, mysql2, or mongodb)
+let dbPool = null;
+
+// Initialize database pool (commented out - requires actual DB)
+// dbPool = createPool({
+//   type: 'postgres',
+//   connectionString: process.env.DATABASE_URL,
+// });
+
+// Example route using database
+app.get('/db-example', async (req, res) => {
+  if (!dbPool) {
+    response.success(res, {
+      message: 'Database not configured',
+      note: 'Set DATABASE_URL and install database package (pg, mysql2, or mongodb)',
+    });
+    return;
+  }
+
+  try {
+    // Example query
+    const result = await dbPool.query('SELECT NOW() as current_time');
+    response.success(res, result);
+  } catch (error) {
+    response.error(res, error.message, 500);
+  }
+});
+
+// ============================================
+// Routes
+// ============================================
+app.get('/', (req, res) => {
+  response.success(res, {
+    message: 'Navis.js v5.2 Features Demo',
+    features: [
+      'WebSocket Support',
+      'Server-Sent Events (SSE)',
+      'Database Integration',
+    ],
+    endpoints: {
+      sse: 'GET /events (SSE stream)',
+      websocket: 'WS /ws (WebSocket)',
+      db: 'GET /db-example',
+    },
+  });
+});
+
+// ============================================
+// Start Server
+// ============================================
+const PORT = 3000;
+const server = app.listen(PORT, () => {
+  console.log(`\n🚀 Navis.js v5.2 Features Demo Server`);
+  console.log(`📡 Listening on http://localhost:${PORT}\n`);
+  console.log('Available endpoints:');
+  console.log('  GET  /');
+  console.log('  GET  /events (SSE stream)');
+  console.log('  WS   /ws (WebSocket)');
+  console.log('  GET  /db-example');
+  console.log('\n💡 Test with:');
+  console.log('  curl http://localhost:3000/');
+  console.log('  curl -N http://localhost:3000/events');
+  console.log('  wscat -c ws://localhost:3000/ws');
+});
+
+// ============================================
+// WebSocket Server
+// ============================================
+const wsServer = new WebSocketServer({
+  path: '/ws',
+});
+
+wsServer.attach(server);
+
+wsServer.onConnection((client) => {
+  console.log(`WebSocket client connected: ${client.id}`);
+  client.send({ type: 'welcome', message: 'Connected to WebSocket server' });
+});
+
+wsServer.on('*', (message, client) => {
+  console.log(`Message from ${client.id}:`, message);
+  
+  // Echo message back
+  client.send({
+    type: 'echo',
+    original: message,
+    timestamp: new Date().toISOString(),
+  });
+});
+
+wsServer.onDisconnection((client) => {
+  console.log(`WebSocket client disconnected: ${client.id}`);
+});
+
+// Cleanup on shutdown
+process.on('SIGTERM', async () => {
+  if (dbPool) {
+    await dbPool.close();
+  }
+  process.exit(0);
+});
+
+module.exports = app;
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navis.js",
-  "version": "5.0.0",
+  "version": "5.2.1",
   "description": "A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js",
   "main": "src/index.js",
   "bin": {

package/src/core/versioning.js

@@ -0,0 +1,124 @@
+/**
+ * API Versioning
+ * v5.1: URL-based and header-based API versioning
+ */
+
+class VersionManager {
+  constructor() {
+    this.versions = new Map();
+    this.defaultVersion = null;
+  }
+
+  /**
+   * Create a version router
+   * @param {string} version - Version identifier (e.g., 'v1', 'v2')
+   * @returns {Object} - Version router with route methods
+   */
+  version(version) {
+    if (!this.versions.has(version)) {
+      const router = {
+        version,
+        routes: {
+          GET: [],
+          POST: [],
+          PUT: [],
+          DELETE: [],
+          PATCH: [],
+        },
+      };
+      this.versions.set(version, router);
+    }
+
+    const router = this.versions.get(version);
+
+    return {
+      get: (path, handler) => this._register(router, 'GET', path, handler),
+      post: (path, handler) => this._register(router, 'POST', path, handler),
+      put: (path, handler) => this._register(router, 'PUT', path, handler),
+      delete: (path, handler) => this._register(router, 'DELETE', path, handler),
+      patch: (path, handler) => this._register(router, 'PATCH', path, handler),
+      use: (middleware) => {
+        if (!router.middlewares) {
+          router.middlewares = [];
+        }
+        router.middlewares.push(middleware);
+      },
+    };
+  }
+
+  /**
+   * Register a route for a version
+   * @private
+   */
+  _register(router, method, path, handler) {
+    const versionedPath = `/${router.version}${path}`;
+    router.routes[method].push({
+      path: versionedPath,
+      originalPath: path,
+      handler,
+    });
+  }
+
+  /**
+   * Set default version
+   * @param {string} version - Default version
+   */
+  setDefaultVersion(version) {
+    this.defaultVersion = version;
+  }
+
+  /**
+   * Get routes for a version
+   * @param {string} version - Version identifier
+   * @returns {Object} - Routes for the version
+   */
+  getRoutes(version) {
+    const router = this.versions.get(version);
+    return router ? router.routes : null;
+  }
+
+  /**
+   * Get all versions
+   * @returns {Array} - Array of version identifiers
+   */
+  getVersions() {
+    return Array.from(this.versions.keys());
+  }
+}
+
+/**
+ * Create version manager
+ * @returns {VersionManager} - Version manager instance
+ */
+function createVersionManager() {
+  return new VersionManager();
+}
+
+/**
+ * Header-based versioning middleware
+ * @param {Object} options - Versioning options
+ * @returns {Function} - Middleware function
+ */
+function headerVersioning(options = {}) {
+  const {
+    header = 'X-API-Version',
+    defaultVersion = null,
+  } = options;
+
+  return async (req, res, next) => {
+    const version = req.headers[header] || req.headers[header.toLowerCase()] || defaultVersion;
+    
+    if (version) {
+      req.apiVersion = version;
+    }
+
+    next();
+  };
+}
+
+module.exports = {
+  VersionManager,
+  createVersionManager,
+  headerVersioning,
+};
+