te.js 2.1.6 → 2.2.1

package/docs/rate-limiting.md

@@ -10,10 +10,9 @@ import Tejas from 'te.js';
 const app = new Tejas();
 
 app
-  .withRedis({ url: 'redis://localhost:6379' })
   .withRateLimit({
     maxRequests: 100,
-    timeWindowSeconds: 60
+    timeWindowSeconds: 60,
   })
   .takeoff();
 ```
@@ -25,35 +24,35 @@ This limits all endpoints to 100 requests per minute per IP address.
 ```javascript
 app.withRateLimit({
   // Core settings
-  maxRequests: 100,           // Maximum requests in time window
-  timeWindowSeconds: 60,      // Time window in seconds
-  
+  maxRequests: 100, // Maximum requests in time window
+  timeWindowSeconds: 60, // Time window in seconds
+
   // Algorithm selection
   algorithm: 'sliding-window', // 'sliding-window' | 'token-bucket' | 'fixed-window'
-  
+
   // Storage backend
-  store: 'redis',             // 'redis' | 'memory'
-  
+  store: 'memory', // 'memory' or { type: 'redis', url: '...' }
+
   // Custom key generator (defaults to IP-based)
   keyGenerator: (ammo) => ammo.ip,
-  
+
   // Algorithm-specific options
   algorithmOptions: {},
-  
+
   // Key prefix for storage keys (useful for namespacing)
   keyPrefix: 'rl:',
-  
+
   // Header format
   headerFormat: {
-    type: 'standard',         // 'standard' | 'legacy' | 'both'
-    draft7: false,            // Include RateLimit-Policy header (e.g. "100;w=60")
-    draft8: false             // Use delta-seconds for RateLimit-Reset instead of Unix timestamp
+    type: 'standard', // 'standard' | 'legacy' | 'both'
+    draft7: false, // Include RateLimit-Policy header (e.g. "100;w=60")
+    draft8: false, // Use delta-seconds for RateLimit-Reset instead of Unix timestamp
   },
-  
+
   // Custom handler when rate limited
   onRateLimited: (ammo) => {
     ammo.fire(429, { error: 'Slow down!' });
-  }
+  },
 });
 ```
 
@@ -67,7 +66,7 @@ Best for smooth, accurate rate limiting. Prevents the "burst at window boundary"
 app.withRateLimit({
   maxRequests: 100,
   timeWindowSeconds: 60,
-  algorithm: 'sliding-window'
+  algorithm: 'sliding-window',
 });
 ```
 
@@ -83,9 +82,9 @@ app.withRateLimit({
   timeWindowSeconds: 60,
   algorithm: 'token-bucket',
   algorithmOptions: {
-    refillRate: 1.67,    // Tokens per second (100/60)
-    burstSize: 150       // Maximum tokens (allows 50% burst)
-  }
+    refillRate: 1.67, // Tokens per second (100/60)
+    burstSize: 150, // Maximum tokens (allows 50% burst)
+  },
 });
 ```
 
@@ -101,8 +100,8 @@ app.withRateLimit({
   timeWindowSeconds: 60,
   algorithm: 'fixed-window',
   algorithmOptions: {
-    strictWindow: true   // Align to clock boundaries
-  }
+    strictWindow: true, // Align to clock boundaries
+  },
 });
 ```
 
@@ -118,31 +117,34 @@ Good for single-server deployments:
 app.withRateLimit({
   maxRequests: 100,
   timeWindowSeconds: 60,
-  store: 'memory'
+  store: 'memory',
 });
 ```
 
 **Pros:** No external dependencies, fast  
-**Cons:** Not shared between server instances
+**Cons:** Not shared between server instances — may be inaccurate in distributed deployments
+
+> **Warning:** If you run multiple server instances (e.g. behind a load balancer), each instance tracks its own counters independently. Use Redis storage below for accurate distributed rate limiting.
 
 ### Redis
 
-Required for distributed/multi-server deployments:
+For distributed / multi-instance deployments where counters must be shared:
 
 ```javascript
-app
-  .withRedis({ url: 'redis://localhost:6379' })
-  .withRateLimit({
-    maxRequests: 100,
-    timeWindowSeconds: 60,
-    store: 'redis'
-  });
+app.withRateLimit({
+  maxRequests: 100,
+  timeWindowSeconds: 60,
+  store: {
+    type: 'redis',
+    url: 'redis://localhost:6379',
+  },
+});
 ```
 
-**Pros:** Shared across all servers, persistent  
-**Cons:** Requires Redis server, slightly higher latency
+The `redis` npm package is auto-installed on first use if not already present. Any additional properties in the `store` object are forwarded to the node-redis `createClient` call.
 
-> **Important:** Initialize Redis with `withRedis()` before using `store: 'redis'`
+**Pros:** Shared across all server instances, persistent  
+**Cons:** Requires a Redis server, slightly higher latency
 
 ## Custom Key Generation
 
@@ -154,7 +156,7 @@ By default, rate limiting is based on client IP. Customize this:
 app.withRateLimit({
   maxRequests: 100,
   timeWindowSeconds: 60,
-  keyGenerator: (ammo) => ammo.user?.id || ammo.ip
+  keyGenerator: (ammo) => ammo.user?.id || ammo.ip,
 });
 ```
 
@@ -164,7 +166,7 @@ app.withRateLimit({
 app.withRateLimit({
   maxRequests: 1000,
   timeWindowSeconds: 60,
-  keyGenerator: (ammo) => ammo.headers['x-api-key'] || ammo.ip
+  keyGenerator: (ammo) => ammo.headers['x-api-key'] || ammo.ip,
 });
 ```
 
@@ -174,7 +176,7 @@ app.withRateLimit({
 app.withRateLimit({
   maxRequests: 100,
   timeWindowSeconds: 60,
-  keyGenerator: (ammo) => `${ammo.ip}:${ammo.endpoint}`
+  keyGenerator: (ammo) => `${ammo.ip}:${ammo.endpoint}`,
 });
 ```
 
@@ -194,7 +196,7 @@ RateLimit-Reset: 1706540400
 
 ```javascript
 app.withRateLimit({
-  headerFormat: { type: 'legacy' }
+  headerFormat: { type: 'legacy' },
 });
 ```
 
@@ -208,7 +210,7 @@ X-RateLimit-Reset: 1706540400
 
 ```javascript
 app.withRateLimit({
-  headerFormat: { type: 'both' }
+  headerFormat: { type: 'both' },
 });
 ```
 
@@ -216,7 +218,7 @@ app.withRateLimit({
 
 ```javascript
 app.withRateLimit({
-  headerFormat: { type: 'standard', draft7: true }
+  headerFormat: { type: 'standard', draft7: true },
 });
 ```
 
@@ -238,9 +240,9 @@ app.withRateLimit({
     ammo.fire(429, {
       error: 'Rate limit exceeded',
       message: 'Please slow down and try again later',
-      retryAfter: ammo.res.getHeader('Retry-After')
+      retryAfter: ammo.res.getHeader('Retry-After'),
     });
-  }
+  },
 });
 ```
 
@@ -259,14 +261,14 @@ const api = new Target('/api');
 const authLimiter = rateLimiter({
   maxRequests: 5,
   timeWindowSeconds: 60,
-  algorithm: 'fixed-window'
+  algorithm: 'fixed-window',
 });
 
 // Relaxed limit for read operations
 const readLimiter = rateLimiter({
   maxRequests: 1000,
   timeWindowSeconds: 60,
-  algorithm: 'sliding-window'
+  algorithm: 'sliding-window',
 });
 
 // Apply to specific routes
@@ -281,11 +283,11 @@ api.register('/data', readLimiter, (ammo) => {
 
 ## Algorithm Comparison
 
-| Algorithm | Best For | Burst Handling | Accuracy | Memory |
-|-----------|----------|----------------|----------|--------|
-| **Sliding Window** | Most APIs | Smooth | High | Medium |
-| **Token Bucket** | Burst-tolerant APIs | Allows bursts | Medium | Low |
-| **Fixed Window** | Simple cases | Poor at boundaries | Low | Low |
+| Algorithm          | Best For            | Burst Handling     | Accuracy | Memory |
+| ------------------ | ------------------- | ------------------ | -------- | ------ |
+| **Sliding Window** | Most APIs           | Smooth             | High     | Medium |
+| **Token Bucket**   | Burst-tolerant APIs | Allows bursts      | Medium   | Low    |
+| **Fixed Window**   | Simple cases        | Poor at boundaries | Low      | Low    |
 
 ## Examples
 
@@ -295,7 +297,7 @@ api.register('/data', readLimiter, (ammo) => {
 const tierLimits = {
   free: { maxRequests: 100, timeWindowSeconds: 3600 },
   pro: { maxRequests: 1000, timeWindowSeconds: 3600 },
-  enterprise: { maxRequests: 10000, timeWindowSeconds: 3600 }
+  enterprise: { maxRequests: 10000, timeWindowSeconds: 3600 },
 };
 
 app.withRateLimit({
@@ -309,8 +311,8 @@ app.withRateLimit({
     getLimits: (key) => {
       const tier = key.split(':')[0];
       return tierLimits[tier] || tierLimits.free;
-    }
-  }
+    },
+  },
 });
 ```
 
@@ -320,14 +322,13 @@ app.withRateLimit({
 // Global rate limit
 app.withRateLimit({
   maxRequests: 1000,
-  timeWindowSeconds: 60
+  timeWindowSeconds: 60,
 });
 
 // Stricter limit for expensive endpoints
 const expensiveLimiter = rateLimiter({
   maxRequests: 10,
   timeWindowSeconds: 60,
-  store: 'redis'
 });
 
 api.register('/search', expensiveLimiter, (ammo) => {
@@ -348,7 +349,7 @@ target.register('/status', (ammo) => {
   ammo.fire({
     limit: ammo.res.getHeader('RateLimit-Limit'),
     remaining: ammo.res.getHeader('RateLimit-Remaining'),
-    reset: ammo.res.getHeader('RateLimit-Reset')
+    reset: ammo.res.getHeader('RateLimit-Reset'),
   });
 });
 ```
@@ -380,11 +381,11 @@ class PostgresStorage extends RateLimitStorage {
 }
 ```
 
-The built-in backends (`MemoryStorage` and `RedisStorage`) both extend this base class.
+The built-in `MemoryStorage` and `RedisStorage` backends both extend this base class.
 
 ## Best Practices
 
-1. **Use Redis in production** — Memory store doesn't scale across instances
+1. **Use Redis in production** — Memory store doesn't share counters across instances; use `store: { type: 'redis', url: '...' }` for distributed deployments
 2. **Set appropriate limits** — Too strict frustrates users, too lenient invites abuse
 3. **Different limits for different endpoints** — Auth endpoints need stricter limits
 4. **Include headers** — Help clients self-regulate

package/lib/llm/client.js

@@ -6,7 +6,7 @@
 
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
 const DEFAULT_MODEL = 'gpt-4o-mini';
-const DEFAULT_TIMEOUT = 10000;
+const DEFAULT_TIMEOUT = 20000;
 
 /**
  * OpenAI-compatible LLM provider. Exposes only constructor and analyze(prompt).
@@ -20,7 +20,7 @@ class LLMProvider {
       typeof options.timeout === 'number' && options.timeout > 0
         ? options.timeout
         : DEFAULT_TIMEOUT;
-    this.options = options;
+    this.options = Object.freeze({ ...options });
   }
 
   /**
@@ -30,6 +30,11 @@ class LLMProvider {
    * @returns {Promise<{ content: string, usage: { prompt_tokens: number, completion_tokens: number, total_tokens: number } }>}
    */
   async analyze(prompt) {
+    if (!prompt || typeof prompt !== 'string') {
+      throw new TypeError(
+        'LLMProvider.analyze: prompt must be a non-empty string',
+      );
+    }
     const url = `${this.baseURL}/chat/completions`;
     const headers = {
       'Content-Type': 'application/json',

package/lib/llm/index.js

@@ -3,5 +3,18 @@
  * Used by auto-docs, error-inference, and future LLM features.
  */
 
+/**
+ * OpenAI-compatible LLM client.
+ * @see {@link ./client.js}
+ */
 export { LLMProvider, createProvider } from './client.js';
-export { extractJSON, extractJSONArray, reconcileOrderedTags } from './parse.js';
+
+/**
+ * JSON parsing utilities for LLM responses.
+ * @see {@link ./parse.js}
+ */
+export {
+  extractJSON,
+  extractJSONArray,
+  reconcileOrderedTags,
+} from './parse.js';

package/lib/llm/parse.test.js

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for lib/llm parse utilities (extractJSON, extractJSONArray, reconcileOrderedTags).
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  extractJSON,
+  extractJSONArray,
+  reconcileOrderedTags,
+} from './index.js';
+
+describe('llm/parse', () => {
+  describe('extractJSON', () => {
+    it('extracts object from plain JSON string', () => {
+      const str = '{"name":"Users","description":"CRUD"}';
+      expect(extractJSON(str)).toEqual({ name: 'Users', description: 'CRUD' });
+    });
+    it('extracts first object from text with markdown', () => {
+      const str = 'Here is the result:\n```json\n{"summary":"Get item"}\n```';
+      expect(extractJSON(str)).toEqual({ summary: 'Get item' });
+    });
+    it('returns null for empty or no object', () => {
+      expect(extractJSON('')).toBeNull();
+      expect(extractJSON('no brace here')).toBeNull();
+    });
+  });
+
+  describe('extractJSONArray', () => {
+    it('extracts array from string', () => {
+      const str = '["Users", "Auth", "Health"]';
+      expect(extractJSONArray(str)).toEqual(['Users', 'Auth', 'Health']);
+    });
+    it('returns null when no array', () => {
+      expect(extractJSONArray('')).toBeNull();
+      expect(extractJSONArray('nothing')).toBeNull();
+    });
+  });
+
+  describe('reconcileOrderedTags', () => {
+    it('reorders tags by orderedTagNames', () => {
+      const tags = [
+        { name: 'Health', description: '...' },
+        { name: 'Users', description: '...' },
+        { name: 'Auth', description: '...' },
+      ];
+      const ordered = reconcileOrderedTags(['Users', 'Auth', 'Health'], tags);
+      expect(ordered.map((t) => t.name)).toEqual(['Users', 'Auth', 'Health']);
+    });
+    it('appends tags not in orderedTagNames', () => {
+      const tags = [{ name: 'Users' }, { name: 'Other' }];
+      const ordered = reconcileOrderedTags(['Users'], tags);
+      expect(ordered.map((t) => t.name)).toEqual(['Users', 'Other']);
+    });
+    it('returns copy of tags when orderedTagNames empty', () => {
+      const tags = [{ name: 'A' }];
+      const ordered = reconcileOrderedTags([], tags);
+      expect(ordered).toEqual([{ name: 'A' }]);
+      expect(ordered).not.toBe(tags);
+    });
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "te.js",
-  "version": "2.1.6",
+  "version": "2.2.1",
   "description": "AI Native Node.js Framework",
   "type": "module",
   "main": "te.js",
@@ -18,6 +18,7 @@
   "license": "ISC",
   "devDependencies": {
     "@types/node": "^20.12.5",
+    "@vitest/coverage-v8": "^4.0.18",
     "husky": "^9.0.11",
     "lint-staged": "^15.2.2",
     "prettier": "3.2.5",
@@ -31,6 +32,7 @@
     "te.js",
     "cli",
     "cors",
+    "radar",
     "server",
     "database",
     "rate-limit",