te.js 2.2.0 → 2.2.1

package/rate-limit/base.js

@@ -1,7 +1,6 @@
 import TejError from '../server/error.js';
 import MemoryStorage from './storage/memory.js';
 import RedisStorage from './storage/redis.js';
-import dbManager from '../database/index.js';
 
 /**
  * Base rate limiter class implementing common functionality for rate limiting algorithms
@@ -15,11 +14,9 @@ import dbManager from '../database/index.js';
  * object is provided (tokenBucketConfig, slidingWindowConfig, or fixedWindowConfig).
  *
  * @example
- * // Using with Redis storage and token bucket algorithm
  * const limiter = new TokenBucketRateLimiter({
  *   maxRequests: 10,
  *   timeWindowSeconds: 60,
- *   store: 'redis',
  *   tokenBucketConfig: {
  *     refillRate: 0.5,
  *     burstSize: 15
@@ -40,7 +37,9 @@ class RateLimiter {
    *                                                 For token bucket, this affects the default refill rate calculation.
    * @param {string} [options.keyPrefix='rl:'] - Prefix for storage keys. Useful when implementing different rate limit
    *                                           rules with different prefixes (e.g., 'rl:api:', 'rl:web:').
-   * @param {string} [options.store='memory'] - Storage backend to use ('memory' or 'redis')
+   * @param {string|Object} [options.store='memory'] - Storage backend: 'memory' (default) or
+   *   { type: 'redis', url: 'redis://...', ...redisOptions }.
+   *   In-memory storage is not shared across processes; use Redis for distributed deployments.
    * @param {Object} [options.tokenBucketConfig] - Token bucket algorithm specific options
    * @param {Object} [options.slidingWindowConfig] - Sliding window algorithm specific options
    * @param {Object} [options.fixedWindowConfig] - Fixed window algorithm specific options
@@ -101,18 +100,16 @@ class RateLimiter {
         }
       : null;
 
-    // Initialize storage based on store type
-    if (this.options.store === 'redis') {
-      if (!dbManager.hasConnection('redis')) {
-        throw new TejError(
-          500,
-          'Redis store selected but no Redis connection available. Call withRedis() first.',
-        );
-      }
-      const redisClient = dbManager.getConnection('redis');
-      this.storage = new RedisStorage(redisClient);
-    } else {
+    const store = this.options.store;
+    if (!store || store === 'memory') {
       this.storage = new MemoryStorage();
+    } else if (typeof store === 'object' && store.type === 'redis') {
+      this.storage = new RedisStorage(store);
+    } else {
+      throw new TejError(
+        400,
+        `Invalid store config. Use 'memory' or { type: 'redis', url: '...' }.`,
+      );
     }
   }
 

package/rate-limit/index.js

@@ -2,7 +2,6 @@ import TejError from '../server/error.js';
 import FixedWindowRateLimiter from './algorithms/fixed-window.js';
 import SlidingWindowRateLimiter from './algorithms/sliding-window.js';
 import TokenBucketRateLimiter from './algorithms/token-bucket.js';
-import dbManager from '../database/index.js';
 
 /**
  * Creates a rate limiting middleware function with the specified algorithm and storage
@@ -14,9 +13,11 @@ import dbManager from '../database/index.js';
  *                                                     - 'token-bucket': Best for handling traffic bursts
  *                                                     - 'sliding-window': Best for smooth rate limiting
  *                                                     - 'fixed-window': Simplest approach
- * @param {string} [options.store='memory'] - Storage backend to use:
- *                                         - 'memory': In-memory storage (default)
- *                                         - 'redis': Redis-based storage (requires global Redis config)
+ * @param {string|Object} [options.store='memory'] - Storage backend to use:
+ *                                         - 'memory': In-memory storage (default, single-instance only)
+ *                                         - { type: 'redis', url: 'redis://...' }: Redis storage for distributed deployments.
+ *                                           The redis npm package is auto-installed on first use.
+ *                                           Any extra properties are forwarded to node-redis createClient.
  * @param {Object} [options.algorithmOptions] - Algorithm-specific options
  * @param {Function} [options.keyGenerator] - Optional function to generate unique identifiers
  * @param {Object} [options.headerFormat] - Rate limit header format configuration
@@ -39,14 +40,6 @@ function rateLimiter(options) {
     ...limiterOptions
   } = options;
 
-  // Check Redis connectivity if Redis store is selected
-  if (store === 'redis' && !dbManager.hasConnection('redis', {})) {
-    throw new TejError(
-      400,
-      'Redis store selected but no Redis connection found. Please use withRedis() before using withRateLimit()',
-    );
-  }
-
   const configMap = Object.create(null);
   configMap['token-bucket'] = 'tokenBucketConfig';
   configMap['sliding-window'] = 'slidingWindowConfig';
@@ -60,6 +53,13 @@ function rateLimiter(options) {
     );
   }
 
+  if (typeof store === 'object' && store.type === 'redis' && !store.url) {
+    throw new TejError(
+      400,
+      `Redis store requires a url. Provide store: { type: "redis", url: "redis://..." }`,
+    );
+  }
+
   const limiterConfig = Object.freeze({
     maxRequests: limiterOptions.maxRequests,
     timeWindowSeconds: limiterOptions.timeWindowSeconds,

package/rate-limit/index.test.js

@@ -4,16 +4,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import rateLimiter from './index.js';
 
-// Mock dbManager.hasConnection so we can test without a real DB
-vi.mock('../database/index.js', () => ({
-  default: {
-    hasConnection: vi.fn(() => false),
-    initializeConnection: vi.fn(),
-  },
-}));
-
 function makeAmmo(ip = '127.0.0.1') {
-  const headers = {};
   return {
     ip,
     res: {
@@ -24,13 +15,6 @@ function makeAmmo(ip = '127.0.0.1') {
 }
 
 describe('rateLimiter', () => {
-  it('should throw TejError when redis store selected but no connection', async () => {
-    const TejError = (await import('../server/error.js')).default;
-    expect(() =>
-      rateLimiter({ maxRequests: 10, timeWindowSeconds: 60, store: 'redis' }),
-    ).toThrow();
-  });
-
   it('should throw on invalid algorithm', () => {
     expect(() =>
       rateLimiter({
@@ -61,4 +45,49 @@ describe('rateLimiter', () => {
     await mw(ammo, next);
     expect(next).toHaveBeenCalled();
   });
+
+  it('should throw on invalid store config', () => {
+    expect(() =>
+      rateLimiter({
+        maxRequests: 10,
+        timeWindowSeconds: 60,
+        store: 'postgres',
+      }),
+    ).toThrow(/Invalid store config/);
+  });
+
+  it('should throw when redis store has no url', () => {
+    expect(() =>
+      rateLimiter({
+        maxRequests: 10,
+        timeWindowSeconds: 60,
+        store: { type: 'redis' },
+      }),
+    ).toThrow(/requires a url/);
+  });
+
+  it('should accept redis store config without throwing on creation', () => {
+    vi.mock('./storage/redis.js', () => ({
+      default: class MockRedisStorage {
+        async get() {
+          return null;
+        }
+        async set() {}
+        async increment() {
+          return null;
+        }
+        async delete() {}
+      },
+    }));
+
+    expect(() =>
+      rateLimiter({
+        maxRequests: 10,
+        timeWindowSeconds: 60,
+        store: { type: 'redis', url: 'redis://localhost:6379' },
+      }),
+    ).not.toThrow();
+
+    vi.restoreAllMocks();
+  });
 });

package/rate-limit/storage/memory.js

@@ -2,25 +2,25 @@ import RateLimitStorage from './base.js';
 
 /**
  * In-memory storage implementation for rate limiting
- * 
+ *
  * @extends RateLimitStorage
  * @description
  * This storage backend uses a JavaScript Map to store rate limit data in memory.
- * It's suitable for single-instance applications or testing environments, but not 
+ * It's suitable for single-instance applications or testing environments, but not
  * recommended for production use in distributed systems as data is not shared
  * between instances.
- * 
+ *
  * Key features:
  * - Fast access (all data in memory)
  * - Automatic cleanup of expired entries
  * - No external dependencies
  * - Data is lost on process restart
  * - Not suitable for distributed systems
- * 
+ *
  * @example
  * import { TokenBucketRateLimiter, MemoryStorage } from 'te.js/rate-limit';
- * 
- * // Memory storage is used by default if no redis config is provided
+ *
+ * // Memory storage is the default storage backend
  * const limiter = new TokenBucketRateLimiter({
  *   maxRequests: 60,
  *   timeWindowSeconds: 60,
@@ -29,7 +29,7 @@ import RateLimitStorage from './base.js';
  *     burstSize: 60
  *   }
  * });
- * 
+ *
  * // Or create storage instance explicitly
  * const storage = new MemoryStorage();
  * await storage.set('key', { counter: 5 }, 60); // Store for 60 seconds
@@ -45,7 +45,7 @@ class MemoryStorage extends RateLimitStorage {
 
   /**
    * Get stored data for a key, handling expiration
-   * 
+   *
    * @param {string} key - The storage key to retrieve data for
    * @returns {Promise<Object|null>} The stored data, or null if not found or expired
    */
@@ -61,7 +61,7 @@ class MemoryStorage extends RateLimitStorage {
 
   /**
    * Store data with expiration time
-   * 
+   *
    * @param {string} key - The storage key
    * @param {Object} value - The data to store
    * @param {number} ttl - Time-to-live in seconds
@@ -70,13 +70,13 @@ class MemoryStorage extends RateLimitStorage {
   async set(key, value, ttl) {
     this.store.set(key, {
       value,
-      expireAt: Date.now() + ttl * 1000
+      expireAt: Date.now() + ttl * 1000,
     });
   }
 
   /**
    * Increment a numeric value in storage
-   * 
+   *
    * @param {string} key - The storage key to increment
    * @returns {Promise<number|null>} New value after increment, or null if key not found/expired
    */
@@ -90,7 +90,7 @@ class MemoryStorage extends RateLimitStorage {
 
   /**
    * Delete data for a key
-   * 
+   *
    * @param {string} key - The storage key to delete
    * @returns {Promise<void>}
    */
@@ -99,4 +99,4 @@ class MemoryStorage extends RateLimitStorage {
   }
 }
 
-export default MemoryStorage;
+export default MemoryStorage;

package/rate-limit/storage/redis-install.js

@@ -0,0 +1,70 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import TejLogger from 'tej-logger';
+
+const logger = new TejLogger('RedisAutoInstall');
+
+/**
+ * Checks whether the `redis` npm package is available in the consuming
+ * project's package.json and node_modules.
+ *
+ * @returns {{ needsInstall: boolean, reason: string }}
+ */
+export function checkRedisInstallation() {
+  const cwd = process.cwd();
+
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return {
+      needsInstall: true,
+      reason: 'No package.json found in project root',
+    };
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  } catch {
+    return { needsInstall: true, reason: 'Unable to read package.json' };
+  }
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const inPkgJson = 'redis' in deps;
+
+  const modulePath = join(cwd, 'node_modules', 'redis');
+  const inNodeModules = existsSync(modulePath);
+
+  if (inPkgJson && inNodeModules) {
+    return { needsInstall: false, reason: 'redis is already installed' };
+  }
+
+  if (inPkgJson && !inNodeModules) {
+    return {
+      needsInstall: true,
+      reason: 'redis is in package.json but not installed',
+    };
+  }
+
+  return { needsInstall: true, reason: 'redis is not in package.json' };
+}
+
+/**
+ * Synchronously installs the `redis` npm package into the consuming project.
+ * Throws if the installation fails.
+ */
+export function installRedisSync() {
+  logger.info('Installing redis package …');
+  try {
+    execSync('npm install redis', {
+      cwd: process.cwd(),
+      stdio: 'pipe',
+      timeout: 60_000,
+    });
+    logger.info('redis package installed successfully.');
+  } catch (err) {
+    throw new Error(
+      `Failed to auto-install redis package. Install it manually with: npm install redis\n${err.message}`,
+    );
+  }
+}

package/rate-limit/storage/redis.js

@@ -1,87 +1,129 @@
 import RateLimitStorage from './base.js';
+import { checkRedisInstallation, installRedisSync } from './redis-install.js';
+import TejLogger from 'tej-logger';
+
+const logger = new TejLogger('RedisStorage');
 
 /**
- * Redis storage implementation for rate limiting
- *
- * @extends RateLimitStorage
- * @description
- * This storage backend uses Redis for distributed rate limiting across multiple application instances.
- * It's the recommended storage backend for production use in distributed systems as it provides
- * reliable rate limiting across all application instances.
+ * Redis-backed storage implementation for rate limiting.
  *
- * Key features:
- * - Distributed rate limiting (works across multiple app instances)
- * - Atomic operations for race condition prevention
- * - Automatic key expiration using Redis TTL
- * - Persistence options available through Redis configuration
- * - Clustering support for high availability
+ * Suitable for distributed / multi-instance deployments where rate-limit
+ * counters must be shared across processes.
  *
- * @example
- * import { TokenBucketRateLimiter } from 'te.js/rate-limit';
+ * The `redis` npm package is auto-installed into the consuming project
+ * on first use if it is not already present.
  *
- * // Use Redis storage for distributed rate limiting
- * const limiter = new TokenBucketRateLimiter({
- *   maxRequests: 100,
- *   timeWindowSeconds: 60,
- *   store: 'redis', // Use Redis storage
- *   tokenBucketConfig: {
- *     refillRate: 2,
- *     burstSize: 100
- *   }
- * });
+ * @extends RateLimitStorage
  */
 class RedisStorage extends RateLimitStorage {
   /**
-   * Initialize Redis storage with client
-   *
-   * @param {RedisClient} client - Connected Redis client instance
+   * @param {Object} config - Redis connection configuration
+   * @param {string} config.url - Redis connection URL (required)
+   *   Remaining properties are forwarded to the node-redis `createClient` call.
    */
-  constructor(client) {
+  constructor(config) {
     super();
-    this.client = client;
+
+    if (!config?.url) {
+      throw new Error(
+        'RedisStorage requires a url. Provide store: { type: "redis", url: "redis://..." }',
+      );
+    }
+
+    const { type: _type, url, ...redisOptions } = config;
+    this._url = url;
+    this._redisOptions = redisOptions;
+
+    this._client = null;
+    this._connectPromise = this._init();
+  }
+
+  /** Bootstrap: ensure redis is installed, create client, connect. */
+  async _init() {
+    const { needsInstall } = checkRedisInstallation();
+    if (needsInstall) {
+      installRedisSync();
+    }
+
+    // Dynamic import so the module is only resolved after auto-install
+    const { createClient } = await import('redis');
+
+    this._client = createClient({ url: this._url, ...this._redisOptions });
+
+    this._client.on('error', (err) => {
+      logger.error(`Redis client error: ${err.message}`);
+    });
+
+    await this._client.connect();
+    logger.info(`Connected to Redis at ${this._url}`);
+  }
+
+  /** Wait until the client is ready before any operation. */
+  async _ready() {
+    await this._connectPromise;
+    return this._client;
   }
 
   /**
-   * Get stored data for a key
-   *
-   * @param {string} key - The storage key to retrieve
-   * @returns {Promise<Object|null>} Stored value if found, null otherwise
+   * @param {string} key
+   * @returns {Promise<Object|null>}
    */
   async get(key) {
-    const value = await this.client.get(key);
-    return value ? JSON.parse(value) : null;
+    const client = await this._ready();
+    const raw = await client.get(key);
+    if (raw === null) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
   }
 
   /**
-   * Store data with expiration time
-   *
-   * @param {string} key - The storage key
-   * @param {Object} value - The data to store
-   * @param {number} ttl - Time-to-live in seconds
-   * @returns {Promise<void>}
+   * @param {string} key
+   * @param {Object} value
+   * @param {number} ttl - seconds
    */
   async set(key, value, ttl) {
-    await this.client.set(key, JSON.stringify(value), { EX: ttl });
+    const client = await this._ready();
+    const seconds = Math.max(1, Math.ceil(ttl));
+    await client.setEx(key, seconds, JSON.stringify(value));
   }
 
   /**
-   * Increment a counter value atomically
+   * Atomically increments the `counter` field inside the stored JSON value.
+   * Uses a Lua script to read-modify-write in a single round-trip.
    *
-   * @param {string} key - The storage key to increment
-   * @returns {Promise<number>} New value after increment
+   * @param {string} key
+   * @returns {Promise<number|null>}
    */
   async increment(key) {
-    return await this.client.incr(key);
+    const client = await this._ready();
+
+    const script = `
+      local raw = redis.call('GET', KEYS[1])
+      if not raw then return nil end
+      local data = cjson.decode(raw)
+      data.counter = (data.counter or 0) + 1
+      local ttl = redis.call('TTL', KEYS[1])
+      if ttl > 0 then
+        redis.call('SETEX', KEYS[1], ttl, cjson.encode(data))
+      else
+        redis.call('SET', KEYS[1], cjson.encode(data))
+      end
+      return data.counter
+    `;
+
+    const result = await client.eval(script, { keys: [key] });
+    return result === null ? null : Number(result);
   }
 
   /**
-   * Delete data for a key
-   *
-   * @param {string} key - The storage key to delete
-   * @returns {Promise<void>}
+   * @param {string} key
    */
   async delete(key) {
-    await this.client.del(key);
+    const client = await this._ready();
+    await client.del(key);
   }
 }
 

package/server/ammo.js

@@ -436,11 +436,12 @@ class Ammo {
           codeContext: null,
         };
 
-        // Fire-and-forget: capture context, call LLM, dispatch to channel.
+        // Run LLM in the background; expose the promise so the Radar middleware
+        // can await it before flushing events (ensures LLM data is captured).
         const method = this.method;
         const path = this.path;
         const self = this;
-        captureCodeContext(stack)
+        this._llmPromise = captureCodeContext(stack)
           .then((codeContext) => {
             // Update _errorInfo with captured code context
             if (self._errorInfo) self._errorInfo.codeContext = codeContext;