navis.js 4.0.0 → 5.2.0

package/src/cache/cache.js

@@ -0,0 +1,157 @@
+/**
+ * In-Memory Cache
+ * v5: Simple in-memory caching with TTL support
+ */
+
+class Cache {
+  constructor(options = {}) {
+    this.store = new Map();
+    this.maxSize = options.maxSize || 1000;
+    this.defaultTTL = options.defaultTTL || 3600000; // 1 hour in ms
+    this.cleanupInterval = options.cleanupInterval || 60000; // 1 minute
+    
+    // Start cleanup interval
+    this.intervalId = setInterval(() => {
+      this._cleanup();
+    }, this.cleanupInterval);
+  }
+
+  /**
+   * Set a value in cache
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   * @param {number} ttl - Time to live in milliseconds
+   */
+  set(key, value, ttl = null) {
+    const expiration = Date.now() + (ttl || this.defaultTTL);
+    
+    // Remove oldest entries if at max size
+    if (this.store.size >= this.maxSize && !this.store.has(key)) {
+      this._evictOldest();
+    }
+    
+    this.store.set(key, {
+      value,
+      expiration,
+    });
+  }
+
+  /**
+   * Get a value from cache
+   * @param {string} key - Cache key
+   * @returns {*} - Cached value or null
+   */
+  get(key) {
+    const entry = this.store.get(key);
+    
+    if (!entry) {
+      return null;
+    }
+    
+    // Check if expired
+    if (Date.now() > entry.expiration) {
+      this.store.delete(key);
+      return null;
+    }
+    
+    return entry.value;
+  }
+
+  /**
+   * Check if key exists in cache
+   * @param {string} key - Cache key
+   * @returns {boolean} - True if key exists and not expired
+   */
+  has(key) {
+    const entry = this.store.get(key);
+    
+    if (!entry) {
+      return false;
+    }
+    
+    if (Date.now() > entry.expiration) {
+      this.store.delete(key);
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Delete a key from cache
+   * @param {string} key - Cache key
+   * @returns {boolean} - True if key was deleted
+   */
+  delete(key) {
+    return this.store.delete(key);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear() {
+    this.store.clear();
+  }
+
+  /**
+   * Get cache size
+   * @returns {number} - Number of entries
+   */
+  size() {
+    return this.store.size;
+  }
+
+  /**
+   * Get all keys
+   * @returns {Array} - Array of cache keys
+   */
+  keys() {
+    return Array.from(this.store.keys());
+  }
+
+  /**
+   * Cleanup expired entries
+   * @private
+   */
+  _cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (now > entry.expiration) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Evict oldest entry (LRU-like)
+   * @private
+   */
+  _evictOldest() {
+    let oldestKey = null;
+    let oldestExpiration = Infinity;
+    
+    for (const [key, entry] of this.store.entries()) {
+      if (entry.expiration < oldestExpiration) {
+        oldestExpiration = entry.expiration;
+        oldestKey = key;
+      }
+    }
+    
+    if (oldestKey) {
+      this.store.delete(oldestKey);
+    }
+  }
+
+  /**
+   * Destroy cache (cleanup)
+   */
+  destroy() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+    }
+    this.clear();
+  }
+}
+
+module.exports = Cache;
+

package/src/cache/redis-cache.js

@@ -0,0 +1,174 @@
+/**
+ * Redis Cache Adapter
+ * v5: Redis-based caching (requires redis package)
+ */
+
+class RedisCache {
+  constructor(options = {}) {
+    this.client = null;
+    this.defaultTTL = options.defaultTTL || 3600; // 1 hour in seconds
+    this.prefix = options.prefix || 'navis:';
+    this.connected = false;
+    
+    // Try to require redis (optional dependency)
+    try {
+      const redis = require('redis');
+      this.redis = redis;
+    } catch (error) {
+      throw new Error('Redis package not installed. Install with: npm install redis');
+    }
+  }
+
+  /**
+   * Connect to Redis
+   * @param {Object} options - Redis connection options
+   */
+  async connect(options = {}) {
+    if (this.connected && this.client) {
+      return;
+    }
+
+    const {
+      url = process.env.REDIS_URL || 'redis://localhost:6379',
+      socket = {},
+      ...otherOptions
+    } = options;
+
+    this.client = this.redis.createClient({
+      url,
+      socket: {
+        reconnectStrategy: (retries) => {
+          if (retries > 10) {
+            return new Error('Too many reconnection attempts');
+          }
+          return Math.min(retries * 100, 3000);
+        },
+        ...socket,
+      },
+      ...otherOptions,
+    });
+
+    this.client.on('error', (err) => {
+      console.error('Redis Client Error:', err);
+    });
+
+    await this.client.connect();
+    this.connected = true;
+  }
+
+  /**
+   * Disconnect from Redis
+   */
+  async disconnect() {
+    if (this.client && this.connected) {
+      await this.client.quit();
+      this.connected = false;
+    }
+  }
+
+  /**
+   * Set a value in cache
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   * @param {number} ttl - Time to live in seconds
+   */
+  async set(key, value, ttl = null) {
+    if (!this.connected) {
+      throw new Error('Redis not connected. Call connect() first.');
+    }
+
+    const fullKey = this.prefix + key;
+    const serialized = JSON.stringify(value);
+    const expiration = ttl || this.defaultTTL;
+
+    if (expiration > 0) {
+      await this.client.setEx(fullKey, expiration, serialized);
+    } else {
+      await this.client.set(fullKey, serialized);
+    }
+  }
+
+  /**
+   * Get a value from cache
+   * @param {string} key - Cache key
+   * @returns {*} - Cached value or null
+   */
+  async get(key) {
+    if (!this.connected) {
+      throw new Error('Redis not connected. Call connect() first.');
+    }
+
+    const fullKey = this.prefix + key;
+    const serialized = await this.client.get(fullKey);
+
+    if (!serialized) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(serialized);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Check if key exists in cache
+   * @param {string} key - Cache key
+   * @returns {boolean} - True if key exists
+   */
+  async has(key) {
+    if (!this.connected) {
+      return false;
+    }
+
+    const fullKey = this.prefix + key;
+    const exists = await this.client.exists(fullKey);
+    return exists === 1;
+  }
+
+  /**
+   * Delete a key from cache
+   * @param {string} key - Cache key
+   * @returns {boolean} - True if key was deleted
+   */
+  async delete(key) {
+    if (!this.connected) {
+      return false;
+    }
+
+    const fullKey = this.prefix + key;
+    const result = await this.client.del(fullKey);
+    return result > 0;
+  }
+
+  /**
+   * Clear all cache entries with prefix
+   */
+  async clear() {
+    if (!this.connected) {
+      return;
+    }
+
+    const keys = await this.client.keys(this.prefix + '*');
+    if (keys.length > 0) {
+      await this.client.del(keys);
+    }
+  }
+
+  /**
+   * Get cache size (approximate)
+   * @returns {number} - Number of keys with prefix
+   */
+  async size() {
+    if (!this.connected) {
+      return 0;
+    }
+
+    const keys = await this.client.keys(this.prefix + '*');
+    return keys.length;
+  }
+}
+
+module.exports = RedisCache;
+

package/src/core/app.js

@@ -238,6 +238,7 @@ class NavisApp {
    * Start HTTP server (Node.js)
    * @param {number} port - Port number
    * @param {Function} callback - Optional callback
+   * @returns {Object} - HTTP server instance
    */
   listen(port = 3000, callback) {
     this.server = http.createServer((req, res) => {
@@ -251,6 +252,14 @@ class NavisApp {
 
     return this.server;
   }
+
+  /**
+   * Get server instance
+   * @returns {Object|null} - HTTP server instance
+   */
+  getServer() {
+    return this.server;
+  }
 }
 
 module.exports = NavisApp;

package/src/core/graceful-shutdown.js

@@ -0,0 +1,77 @@
+/**
+ * Graceful Shutdown Handler
+ * v5: Clean shutdown handling for Node.js servers
+ */
+
+/**
+ * Graceful shutdown handler
+ * @param {Object} server - HTTP server instance
+ * @param {Object} options - Shutdown options
+ */
+function gracefulShutdown(server, options = {}) {
+  const {
+    timeout = 10000, // 10 seconds default
+    onShutdown = async () => {}, // Cleanup function
+    signals = ['SIGTERM', 'SIGINT'],
+    log = console.log,
+  } = options;
+
+  let isShuttingDown = false;
+
+  const shutdown = async (signal) => {
+    if (isShuttingDown) {
+      return;
+    }
+
+    isShuttingDown = true;
+    log(`Received ${signal}, starting graceful shutdown...`);
+
+    // Stop accepting new connections
+    server.close(() => {
+      log('HTTP server closed');
+    });
+
+    // Set timeout for forced shutdown
+    const shutdownTimer = setTimeout(() => {
+      log('Forced shutdown after timeout');
+      process.exit(1);
+    }, timeout);
+
+    try {
+      // Run cleanup
+      await onShutdown();
+      clearTimeout(shutdownTimer);
+      log('Graceful shutdown completed');
+      process.exit(0);
+    } catch (error) {
+      clearTimeout(shutdownTimer);
+      log('Error during shutdown:', error);
+      process.exit(1);
+    }
+  };
+
+  // Register signal handlers
+  for (const signal of signals) {
+    process.on(signal, () => shutdown(signal));
+  }
+
+  // Handle uncaught exceptions
+  process.on('uncaughtException', async (error) => {
+    log('Uncaught exception:', error);
+    await shutdown('uncaughtException');
+  });
+
+  // Handle unhandled promise rejections
+  process.on('unhandledRejection', async (reason, promise) => {
+    log('Unhandled rejection:', reason);
+    await shutdown('unhandledRejection');
+  });
+
+  return {
+    shutdown: () => shutdown('manual'),
+    isShuttingDown: () => isShuttingDown,
+  };
+}
+
+module.exports = gracefulShutdown;
+

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,
+};
+