navis.js 3.0.1 → 3.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Syed Imran Ali
+Copyright (c) 2026 Syed Imran Ali
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -112,6 +112,14 @@ navis metrics
 - ✅ **Distributed tracing** - Trace and span management
 - ✅ **Enhanced CLI** - Test and metrics commands
 
+### v3.1 (Current)
+
+- ✅ **Lambda cold start optimization** - Connection pooling, lazy initialization
+- ✅ **ServiceClientPool** - Reuse HTTP connections across invocations
+- ✅ **LazyInit utility** - Defer heavy operations until needed
+- ✅ **LambdaHandler** - Optimized handler with warm-up support
+- ✅ **Cold start tracking** - Monitor and log cold start metrics
+
 ## API Reference
 
 ### NavisApp
@@ -248,12 +256,54 @@ await nats.connect();
 await nats.publish('user.created', { userId: 123 });
 ```
 
+### Lambda Optimization (v3.1)
+
+```javascript
+const {
+  NavisApp,
+  getPool,
+  LambdaHandler,
+  coldStartTracker,
+  LazyInit,
+} = require('navis.js');
+
+// Initialize app OUTSIDE handler (reused across invocations)
+const app = new NavisApp();
+app.use(coldStartTracker);
+
+// Connection pooling - reuse HTTP connections
+const client = getPool().get('http://api.example.com', {
+  timeout: 3000,
+  maxRetries: 2,
+});
+
+// Lazy initialization - defer heavy operations
+const dbConnection = new LazyInit();
+app.get('/users', async (req, res) => {
+  const db = await dbConnection.init(async () => {
+    return await connectToDatabase(); // Only runs once
+  });
+  res.body = await db.query('SELECT * FROM users');
+});
+
+// Optimized Lambda handler
+const handler = new LambdaHandler(app, {
+  enableMetrics: true,
+  warmupPath: '/warmup',
+});
+
+exports.handler = async (event, context) => {
+  return await handler.handle(event, context);
+};
+```
+
 ## Examples
 
 See the `examples/` directory:
 
 - `server.js` - Node.js HTTP server example
 - `lambda.js` - AWS Lambda handler example
+- `lambda-optimized.js` - Optimized Lambda handler with cold start optimizations (v3.1)
 - `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.)
@@ -273,6 +323,7 @@ Advanced features: async messaging (SQS/Kafka/NATS), observability, enhanced CLI
 
 - [V2 Features Guide](./V2_FEATURES.md) - Complete v2 features documentation
 - [V3 Features Guide](./V3_FEATURES.md) - Complete v3 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/lambda-optimized.js

@@ -0,0 +1,103 @@
+/**
+ * Optimized Lambda Handler Example
+ * v3.1: Best practices for reducing cold start time
+ */
+
+const { NavisApp, response, getPool } = require('../src/index');
+const LambdaHandler = require('../src/core/lambda-handler');
+const { coldStartTracker } = require('../src/middleware/cold-start-tracker');
+
+// ============================================
+// CRITICAL: Initialize app OUTSIDE handler
+// This ensures the app is reused across invocations
+// ============================================
+const app = new NavisApp();
+
+// Add cold start tracking middleware
+app.use(coldStartTracker);
+
+// ============================================
+// Register routes at MODULE LEVEL (not in handler)
+// This runs once per container, not per invocation
+// ============================================
+app.get('/', (req, res) => {
+  res.statusCode = 200;
+  res.body = { 
+    message: 'Welcome to Navis.js Lambda (Optimized)!',
+    optimized: true,
+  };
+});
+
+app.get('/health', (req, res) => {
+  res.statusCode = 200;
+  res.body = { status: 'ok' };
+});
+
+app.get('/warmup', (req, res) => {
+  res.statusCode = 200;
+  res.body = { status: 'warmed' };
+});
+
+// Example: Using ServiceClient with connection pooling
+app.get('/external', async (req, res) => {
+  try {
+    // Get client from pool (reuses connections)
+    const client = getPool().get('http://api.example.com', {
+      timeout: 3000,
+      maxRetries: 2,
+    });
+    
+    const result = await client.get('/data');
+    res.statusCode = 200;
+    res.body = { data: result.data };
+  } catch (error) {
+    res.statusCode = 500;
+    res.body = { error: error.message };
+  }
+});
+
+// ============================================
+// OPTIMIZED HANDLER
+// ============================================
+
+// Create handler instance (reused across invocations)
+const handler = new LambdaHandler(app, {
+  enableMetrics: true,
+  warmupPath: '/warmup',
+});
+
+// Cache the handler function (V8 optimization)
+let cachedHandler = null;
+
+/**
+ * Lambda handler - optimized for cold starts
+ * @param {Object} event - Lambda event
+ * @param {Object} context - Lambda context
+ */
+exports.handler = async (event, context) => {
+  // Reuse handler function (V8 JIT optimization)
+  if (!cachedHandler) {
+    cachedHandler = async (event, context) => {
+      return await handler.handle(event, context);
+    };
+  }
+  
+  return await cachedHandler(event, context);
+};
+
+/**
+ * Optional: Pre-warm function
+ * Can be called during container initialization
+ */
+exports.preWarm = async () => {
+  // Pre-initialize any heavy operations
+  // This runs once per container
+  console.log('Pre-warming Lambda container...');
+  
+  // Example: Pre-initialize service clients
+  const pool = getPool();
+  pool.get('http://api.example.com', { timeout: 3000 });
+  
+  console.log('Pre-warming complete');
+};
+

package/examples/lambda.js

@@ -1,30 +1,31 @@
-const { NavisApp } = require('../src/index');
-
-const app = new NavisApp();
-
-// Middleware example
-app.use((req, res, next) => {
-  console.log(`Lambda: ${req.method} ${req.path}`);
-  next();
-});
-
-// Routes
-app.get('/', (req, res) => {
-  res.statusCode = 200;
-  res.body = { message: 'Welcome to Navis.js Lambda!' };
-});
-
-app.get('/health', (req, res) => {
-  res.statusCode = 200;
-  res.body = { status: 'ok' };
-});
-
-app.post('/echo', (req, res) => {
-  res.statusCode = 200;
-  res.body = { echo: req.body };
-});
-
-// Lambda handler
-exports.handler = async (event) => {
-  return await app.handleLambda(event);
+const { NavisApp } = require('../src/index');
+
+// Initialize app at module level (reused across invocations)
+const app = new NavisApp();
+
+// Middleware example
+app.use((req, res, next) => {
+  console.log(`Lambda: ${req.method} ${req.path}`);
+  next();
+});
+
+// Routes registered at module level (not in handler)
+app.get('/', (req, res) => {
+  res.statusCode = 200;
+  res.body = { message: 'Welcome to Navis.js Lambda!' };
+});
+
+app.get('/health', (req, res) => {
+  res.statusCode = 200;
+  res.body = { status: 'ok' };
+});
+
+app.post('/echo', (req, res) => {
+  res.statusCode = 200;
+  res.body = { echo: req.body };
+});
+
+// Lambda handler - optimized for reuse
+exports.handler = async (event) => {
+  return await app.handleLambda(event);
 };

package/package.json

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

package/src/core/lambda-handler.js

@@ -0,0 +1,130 @@
+/**
+ * Optimized Lambda Handler
+ * v3.1: Enhanced Lambda handler with cold start optimizations
+ */
+
+class LambdaHandler {
+  constructor(app, options = {}) {
+    this.app = app;
+    this.isWarm = false;
+    this.initTime = Date.now();
+    this.invocationCount = 0;
+    this.coldStartCount = 0;
+    this.enableMetrics = options.enableMetrics !== false;
+    this.warmupPath = options.warmupPath || '/warmup';
+  }
+
+  /**
+   * Handle Lambda invocation
+   * @param {Object} event - Lambda event
+   * @param {Object} context - Lambda context
+   * @returns {Promise<Object>} - Lambda response
+   */
+  async handle(event, context) {
+    this.invocationCount++;
+
+    // Detect warm-up events
+    if (this.isWarmupEvent(event)) {
+      return this.handleWarmup();
+    }
+
+    // Track cold start
+    const isColdStart = !this.isWarm;
+    if (isColdStart) {
+      this.isWarm = true;
+      this.coldStartCount++;
+      
+      if (this.enableMetrics) {
+        const coldStartDuration = Date.now() - this.initTime;
+        console.log(JSON.stringify({
+          type: 'cold-start',
+          duration: coldStartDuration,
+          memoryLimit: context.memoryLimitInMB,
+          requestId: context.requestId,
+        }));
+      }
+    }
+
+    // Add cold start headers to response
+    const response = await this.app.handleLambda(event);
+    
+    if (isColdStart && response.headers) {
+      response.headers['X-Cold-Start'] = 'true';
+      response.headers['X-Init-Time'] = (Date.now() - this.initTime).toString();
+    }
+
+    return response;
+  }
+
+  /**
+   * Check if event is a warm-up event
+   * @param {Object} event - Lambda event
+   * @returns {boolean} - True if warm-up event
+   */
+  isWarmupEvent(event) {
+    // Check various warm-up event formats
+    if (event.source === 'serverless-plugin-warmup') {
+      return true;
+    }
+    
+    if (event.warmup === true || event['serverless-plugin-warmup']) {
+      return true;
+    }
+    
+    // Check if it's a warm-up HTTP request
+    if (event.httpMethod === 'GET' && 
+        (event.path === this.warmupPath || event.rawPath === this.warmupPath)) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Handle warm-up event
+   * @returns {Object} - Warm-up response
+   */
+  handleWarmup() {
+    // Mark as warm
+    this.isWarm = true;
+    
+    return {
+      statusCode: 200,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        status: 'warmed',
+        invocationCount: this.invocationCount,
+        coldStartCount: this.coldStartCount,
+      }),
+    };
+  }
+
+  /**
+   * Get handler statistics
+   * @returns {Object} - Handler statistics
+   */
+  getStats() {
+    return {
+      isWarm: this.isWarm,
+      invocationCount: this.invocationCount,
+      coldStartCount: this.coldStartCount,
+      initTime: this.initTime,
+      uptime: Date.now() - this.initTime,
+    };
+  }
+
+  /**
+   * Reset handler state (useful for testing)
+   */
+  reset() {
+    this.isWarm = false;
+    this.invocationCount = 0;
+    this.coldStartCount = 0;
+    this.initTime = Date.now();
+  }
+}
+
+module.exports = LambdaHandler;
+

package/src/index.js

@@ -16,6 +16,12 @@ const Logger = require('./observability/logger');
 const Metrics = require('./observability/metrics');
 const Tracer = require('./observability/tracer');
 
+// v3.1: Lambda Optimizations
+const { getPool, ServiceClientPool } = require('./utils/service-client-pool');
+const { LazyInit, createLazyInit } = require('./utils/lazy-init');
+const LambdaHandler = require('./core/lambda-handler');
+const { coldStartTracker } = require('./middleware/cold-start-tracker');
+
 module.exports = {
   // Core
   NavisApp,
@@ -38,6 +44,14 @@ module.exports = {
   Metrics,
   Tracer,
   
+  // v3.1: Lambda Optimizations
+  ServiceClientPool,
+  getPool,
+  LazyInit,
+  createLazyInit,
+  LambdaHandler,
+  coldStartTracker,
+  
   // Utilities
   response: {
     success,

package/src/middleware/cold-start-tracker.js

@@ -0,0 +1,56 @@
+/**
+ * Cold Start Tracker Middleware
+ * v3.1: Track and log cold start metrics
+ */
+
+let isFirstInvocation = true;
+let initTime = Date.now();
+
+/**
+ * Cold start tracking middleware
+ * Tracks cold starts and adds headers to response
+ * @param {Object} req - Request object
+ * @param {Object} res - Response object
+ * @param {Function} next - Next middleware
+ */
+function coldStartTracker(req, res, next) {
+  if (isFirstInvocation) {
+    const coldStartDuration = Date.now() - initTime;
+    
+    // Add cold start info to response headers
+    if (res.headers) {
+      res.headers['X-Cold-Start'] = 'true';
+      res.headers['X-Cold-Start-Duration'] = coldStartDuration.toString();
+    }
+    
+    // Log cold start (structured logging)
+    console.log(JSON.stringify({
+      type: 'cold-start',
+      duration: coldStartDuration,
+      path: req.path || req.url,
+      method: req.method,
+    }));
+    
+    isFirstInvocation = false;
+  } else {
+    if (res.headers) {
+      res.headers['X-Cold-Start'] = 'false';
+    }
+  }
+  
+  next();
+}
+
+/**
+ * Reset cold start tracker (useful for testing)
+ */
+function resetColdStartTracker() {
+  isFirstInvocation = true;
+  initTime = Date.now();
+}
+
+module.exports = {
+  coldStartTracker,
+  resetColdStartTracker,
+};
+

package/src/utils/lazy-init.js

@@ -0,0 +1,100 @@
+/**
+ * Lazy Initialization Utility
+ * v3.1: Defer heavy initialization until needed (reduces cold start time)
+ */
+
+class LazyInit {
+  constructor(options = {}) {
+    this.initialized = false;
+    this.initPromise = null;
+    this.initFn = null;
+    this.autoInit = options.autoInit !== false; // Auto-init on first access
+    this.cacheResult = options.cacheResult !== false; // Cache initialization result
+    this.cachedResult = null;
+  }
+
+  /**
+   * Initialize with a function
+   * @param {Function} initFn - Initialization function (can be async)
+   * @returns {Promise} - Initialization promise
+   */
+  async init(initFn) {
+    if (this.initialized && this.cacheResult) {
+      return this.cachedResult;
+    }
+
+    if (!this.initPromise) {
+      this.initFn = initFn;
+      this.initPromise = Promise.resolve(initFn()).then(result => {
+        this.initialized = true;
+        if (this.cacheResult) {
+          this.cachedResult = result;
+        }
+        return result;
+      }).catch(error => {
+        // Reset on error so it can be retried
+        this.initPromise = null;
+        throw error;
+      });
+    }
+
+    return this.initPromise;
+  }
+
+  /**
+   * Check if initialized
+   * @returns {boolean} - True if initialized
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+
+  /**
+   * Get cached result (if available)
+   * @returns {*} - Cached initialization result
+   */
+  getCached() {
+    return this.cachedResult;
+  }
+
+  /**
+   * Reset initialization state
+   */
+  reset() {
+    this.initialized = false;
+    this.initPromise = null;
+    this.cachedResult = null;
+  }
+
+  /**
+   * Execute function with lazy initialization
+   * @param {Function} fn - Function to execute after initialization
+   * @returns {Promise} - Result of function execution
+   */
+  async withInit(fn) {
+    if (!this.initialized && this.initFn) {
+      await this.init(this.initFn);
+    }
+    return await fn(this.cachedResult);
+  }
+}
+
+/**
+ * Create a lazy initializer
+ * @param {Function} initFn - Initialization function
+ * @param {Object} options - Options
+ * @returns {LazyInit} - LazyInit instance
+ */
+function createLazyInit(initFn, options = {}) {
+  const lazy = new LazyInit(options);
+  if (initFn) {
+    lazy.initFn = initFn;
+  }
+  return lazy;
+}
+
+module.exports = {
+  LazyInit,
+  createLazyInit,
+};
+

package/src/utils/service-client-pool.js

@@ -0,0 +1,131 @@
+/**
+ * ServiceClient Pool - Connection reuse for Lambda
+ * v3.1: Connection pooling to reduce cold start overhead
+ */
+
+const ServiceClient = require('./service-client');
+
+class ServiceClientPool {
+  constructor() {
+    this.clients = new Map();
+    this.maxSize = 10; // Maximum cached clients
+  }
+
+  /**
+   * Get or create a ServiceClient instance
+   * Reuses existing clients to avoid re-initialization
+   * @param {string} baseUrl - Service base URL
+   * @param {Object} options - ServiceClient options
+   * @returns {ServiceClient} - Cached or new ServiceClient
+   */
+  get(baseUrl, options = {}) {
+    // Create a unique key for this client configuration
+    const key = this._createKey(baseUrl, options);
+    
+    if (!this.clients.has(key)) {
+      // Create new client if not in pool
+      const client = new ServiceClient(baseUrl, options);
+      this.clients.set(key, client);
+      
+      // Limit pool size (remove oldest if needed)
+      if (this.clients.size > this.maxSize) {
+        const firstKey = this.clients.keys().next().value;
+        this.clients.delete(firstKey);
+      }
+    }
+    
+    return this.clients.get(key);
+  }
+
+  /**
+   * Check if a client exists in pool
+   * @param {string} baseUrl - Service base URL
+   * @param {Object} options - ServiceClient options
+   * @returns {boolean} - True if client exists in pool
+   */
+  has(baseUrl, options = {}) {
+    const key = this._createKey(baseUrl, options);
+    return this.clients.has(key);
+  }
+
+  /**
+   * Remove a client from pool
+   * @param {string} baseUrl - Service base URL
+   * @param {Object} options - ServiceClient options
+   */
+  delete(baseUrl, options = {}) {
+    const key = this._createKey(baseUrl, options);
+    this.clients.delete(key);
+  }
+
+  /**
+   * Clear all clients from pool
+   */
+  clear() {
+    this.clients.clear();
+  }
+
+  /**
+   * Get pool size
+   * @returns {number} - Number of cached clients
+   */
+  size() {
+    return this.clients.size;
+  }
+
+  /**
+   * Get all cached client URLs
+   * @returns {Array} - Array of base URLs
+   */
+  getCachedUrls() {
+    return Array.from(this.clients.keys()).map(key => {
+      const [url] = key.split('::');
+      return url;
+    });
+  }
+
+  /**
+   * Create unique key for client
+   * @private
+   */
+  _createKey(baseUrl, options) {
+    // Normalize options to create consistent key
+    const normalizedOptions = {
+      timeout: options.timeout || 5000,
+      maxRetries: options.maxRetries,
+      retryBaseDelay: options.retryBaseDelay,
+      circuitBreaker: options.circuitBreaker ? JSON.stringify(options.circuitBreaker) : undefined,
+    };
+    
+    return `${baseUrl}::${JSON.stringify(normalizedOptions)}`;
+  }
+}
+
+// Singleton instance for Lambda (reused across invocations)
+let poolInstance = null;
+
+/**
+ * Get singleton ServiceClientPool instance
+ * In Lambda, this instance persists across invocations
+ * @returns {ServiceClientPool} - Singleton pool instance
+ */
+function getPool() {
+  if (!poolInstance) {
+    poolInstance = new ServiceClientPool();
+  }
+  return poolInstance;
+}
+
+/**
+ * Reset pool (useful for testing)
+ */
+function resetPool() {
+  poolInstance = null;
+}
+
+module.exports = {
+  ServiceClientPool,
+  getPool,
+  resetPool,
+};
+