te.js 2.1.4 → 2.1.6

package/te.js

@@ -10,7 +10,10 @@ import dbManager from './database/index.js';
 import { loadConfigFile, standardizeObj } from './utils/configuration.js';
 
 import targetHandler from './server/handler.js';
-import { getErrorsLlmConfig, validateErrorsLlmAtTakeoff } from './utils/errors-llm-config.js';
+import {
+  getErrorsLlmConfig,
+  validateErrorsLlmAtTakeoff,
+} from './utils/errors-llm-config.js';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
@@ -133,10 +136,9 @@ class Tejas {
               ? path.join(parentPath, file.name)
               : path.join(baseDir, parentPath, file.name);
             const relativePath = path.relative(baseDir, fullPath);
-            const groupId = relativePath
-              .replace(/\.target\.js$/i, '')
-              .replace(/\\/g, '/')
-              || 'index';
+            const groupId =
+              relativePath.replace(/\.target\.js$/i, '').replace(/\\/g, '/') ||
+              'index';
             targetRegistry.setCurrentSourceGroup(groupId);
             try {
               await import(pathToFileURL(fullPath).href);
@@ -305,14 +307,21 @@ class Tejas {
 
   /**
    * Enables LLM-inferred error codes and messages for ammo.throw() and framework-caught errors.
-   * Call before takeoff(). Remaining options (baseURL, apiKey, model, messageType) can come from
-   * config, or from env/tejas.config.json (LLM_* / ERRORS_LLM_*). Validation runs at takeoff.
+   * Call before takeoff(). Remaining options can come from env/tejas.config.json (LLM_* / ERRORS_LLM_*).
+   * Validation runs at takeoff.
    *
    * @param {Object} [config] - Optional errors.llm overrides
    * @param {string} [config.baseURL] - LLM provider endpoint (e.g. https://api.openai.com/v1)
    * @param {string} [config.apiKey] - LLM provider API key
    * @param {string} [config.model] - Model name (e.g. gpt-4o-mini)
    * @param {'endUser'|'developer'} [config.messageType] - Default message tone
+   * @param {'sync'|'async'} [config.mode] - 'sync' blocks the response until LLM returns (default); 'async' responds immediately with 500 and dispatches LLM result to a channel
+   * @param {number} [config.timeout] - LLM fetch timeout in milliseconds (default 10000)
+   * @param {'console'|'log'|'both'} [config.channel] - Output channel for async mode results (default 'console')
+   * @param {string} [config.logFile] - Path to JSONL log file used by 'log' and 'both' channels (default './errors.llm.log')
+   * @param {number} [config.rateLimit] - Max LLM calls per minute across all requests (default 10)
+   * @param {boolean} [config.cache] - Cache LLM results by throw site + error message to avoid repeated calls (default true)
+   * @param {number} [config.cacheTTL] - How long cached results are reused in milliseconds (default 3600000 = 1 hour)
    * @returns {Tejas} The Tejas instance for chaining
    *
    * @example
@@ -322,6 +331,10 @@ class Tejas {
    * @example
    * app.withLLMErrors({ baseURL: 'https://api.openai.com/v1', apiKey: process.env.OPENAI_KEY, model: 'gpt-4o-mini' });
    * app.takeoff();
+   *
+   * @example
+   * app.withLLMErrors({ mode: 'async', channel: 'both', rateLimit: 20 });
+   * app.takeoff();
    */
   withLLMErrors(config) {
     setEnv('ERRORS_LLM_ENABLED', true);
@@ -329,7 +342,17 @@ class Tejas {
       if (config.baseURL != null) setEnv('ERRORS_LLM_BASE_URL', config.baseURL);
       if (config.apiKey != null) setEnv('ERRORS_LLM_API_KEY', config.apiKey);
       if (config.model != null) setEnv('ERRORS_LLM_MODEL', config.model);
-      if (config.messageType != null) setEnv('ERRORS_LLM_MESSAGE_TYPE', config.messageType);
+      if (config.messageType != null)
+        setEnv('ERRORS_LLM_MESSAGE_TYPE', config.messageType);
+      if (config.mode != null) setEnv('ERRORS_LLM_MODE', config.mode);
+      if (config.timeout != null) setEnv('ERRORS_LLM_TIMEOUT', config.timeout);
+      if (config.channel != null) setEnv('ERRORS_LLM_CHANNEL', config.channel);
+      if (config.logFile != null) setEnv('ERRORS_LLM_LOG_FILE', config.logFile);
+      if (config.rateLimit != null)
+        setEnv('ERRORS_LLM_RATE_LIMIT', config.rateLimit);
+      if (config.cache != null) setEnv('ERRORS_LLM_CACHE', config.cache);
+      if (config.cacheTTL != null)
+        setEnv('ERRORS_LLM_CACHE_TTL', config.cacheTTL);
     }
     return this;
   }
@@ -401,16 +424,21 @@ class Tejas {
    * app.takeoff();
    */
   serveDocs(config = {}) {
-    const specPath = path.resolve(process.cwd(), config.specPath || './openapi.json');
+    const specPath = path.resolve(
+      process.cwd(),
+      config.specPath || './openapi.json',
+    );
     const { scalarConfig } = config;
     const getSpec = async () => {
       const content = await readFile(specPath, 'utf8');
       return JSON.parse(content);
     };
-    registerDocRoutes({ getSpec, specUrl: '/docs/openapi.json', scalarConfig }, targetRegistry);
+    registerDocRoutes(
+      { getSpec, specUrl: '/docs/openapi.json', scalarConfig },
+      targetRegistry,
+    );
     return this;
   }
-
 }
 
 const listAllEndpoints = (grouped = false) => {

package/utils/errors-llm-config.js

@@ -7,6 +7,8 @@
 import { env } from 'tej-env';
 
 const MESSAGE_TYPES = /** @type {const} */ (['endUser', 'developer']);
+const LLM_MODES = /** @type {const} */ (['sync', 'async']);
+const LLM_CHANNELS = /** @type {const} */ (['console', 'log', 'both']);
 
 /**
  * Normalize messageType to 'endUser' | 'developer'.
@@ -14,14 +16,56 @@ const MESSAGE_TYPES = /** @type {const} */ (['endUser', 'developer']);
  * @returns {'endUser'|'developer'}
  */
 function normalizeMessageType(v) {
-  const s = String(v ?? '').trim().toLowerCase();
+  const s = String(v ?? '')
+    .trim()
+    .toLowerCase();
   if (s === 'developer' || s === 'dev') return 'developer';
   return 'endUser'; // endUser, end_user, default
 }
 
+/**
+ * Normalize mode to 'sync' | 'async'.
+ * @param {string} v
+ * @returns {'sync'|'async'}
+ */
+function normalizeMode(v) {
+  const s = String(v ?? '')
+    .trim()
+    .toLowerCase();
+  if (s === 'async') return 'async';
+  return 'sync';
+}
+
+/**
+ * Normalize channel to 'console' | 'log' | 'both'.
+ * @param {string} v
+ * @returns {'console'|'log'|'both'}
+ */
+function normalizeChannel(v) {
+  const s = String(v ?? '')
+    .trim()
+    .toLowerCase();
+  if (s === 'log') return 'log';
+  if (s === 'both') return 'both';
+  return 'console';
+}
+
 /**
  * Resolve errors.llm config from env (feature-specific then LLM_ fallback).
- * @returns {{ enabled: boolean, baseURL: string, apiKey: string, model: string, messageType: 'endUser'|'developer' }}
+ * @returns {{
+ *   enabled: boolean,
+ *   baseURL: string,
+ *   apiKey: string,
+ *   model: string,
+ *   messageType: 'endUser'|'developer',
+ *   mode: 'sync'|'async',
+ *   timeout: number,
+ *   channel: 'console'|'log'|'both',
+ *   logFile: string,
+ *   rateLimit: number,
+ *   cache: boolean,
+ *   cacheTTL: number,
+ * }}
  */
 export function getErrorsLlmConfig() {
   const enabledRaw = env('ERRORS_LLM_ENABLED') ?? '';
@@ -45,11 +89,50 @@ export function getErrorsLlmConfig() {
     env('LLM_APIKEY') ??
     '';
 
-  const model =
-    env('ERRORS_LLM_MODEL') ?? env('LLM_MODEL') ?? '';
+  const model = env('ERRORS_LLM_MODEL') ?? env('LLM_MODEL') ?? '';
 
   const messageTypeRaw =
-    env('ERRORS_LLM_MESSAGE_TYPE') ?? env('ERRORS_LLM_MESSAGETYPE') ?? env('LLM_MESSAGE_TYPE') ?? env('LLM_MESSAGETYPE') ?? '';
+    env('ERRORS_LLM_MESSAGE_TYPE') ??
+    env('ERRORS_LLM_MESSAGETYPE') ??
+    env('LLM_MESSAGE_TYPE') ??
+    env('LLM_MESSAGETYPE') ??
+    '';
+
+  const modeRaw = env('ERRORS_LLM_MODE') ?? env('LLM_MODE') ?? '';
+
+  const timeoutRaw = env('ERRORS_LLM_TIMEOUT') ?? env('LLM_TIMEOUT') ?? '';
+  const timeoutNum = Number(timeoutRaw);
+  const timeout =
+    !timeoutRaw || isNaN(timeoutNum) || timeoutNum <= 0 ? 10000 : timeoutNum;
+
+  const channelRaw = env('ERRORS_LLM_CHANNEL') ?? env('LLM_CHANNEL') ?? '';
+
+  const logFile =
+    String(env('ERRORS_LLM_LOG_FILE') ?? '').trim() || './errors.llm.log';
+
+  const rateLimitRaw =
+    env('ERRORS_LLM_RATE_LIMIT') ?? env('LLM_RATE_LIMIT') ?? '';
+  const rateLimitNum = Number(rateLimitRaw);
+  const rateLimit =
+    !rateLimitRaw || isNaN(rateLimitNum) || rateLimitNum <= 0
+      ? 10
+      : Math.floor(rateLimitNum);
+
+  const cacheRaw = env('ERRORS_LLM_CACHE') ?? '';
+  const cache =
+    cacheRaw === false ||
+    cacheRaw === 'false' ||
+    cacheRaw === '0' ||
+    cacheRaw === 0
+      ? false
+      : true;
+
+  const cacheTTLRaw = env('ERRORS_LLM_CACHE_TTL') ?? '';
+  const cacheTTLNum = Number(cacheTTLRaw);
+  const cacheTTL =
+    !cacheTTLRaw || isNaN(cacheTTLNum) || cacheTTLNum <= 0
+      ? 3600000
+      : cacheTTLNum;
 
   return {
     enabled: Boolean(enabled),
@@ -57,18 +140,35 @@ export function getErrorsLlmConfig() {
     apiKey: String(apiKey ?? '').trim(),
     model: String(model ?? '').trim(),
     messageType: normalizeMessageType(messageTypeRaw || 'endUser'),
+    mode: normalizeMode(modeRaw),
+    timeout,
+    channel: normalizeChannel(channelRaw),
+    logFile,
+    rateLimit,
+    cache,
+    cacheTTL,
   };
 }
 
-export { MESSAGE_TYPES };
+export { MESSAGE_TYPES, LLM_MODES, LLM_CHANNELS };
 
 /**
  * Validate errors.llm when enabled: require baseURL, apiKey, and model (after LLM_ fallback).
+ * Also warns about misconfigurations (e.g. channel set with sync mode).
  * Call at takeoff. Throws if enabled but config is invalid; no-op otherwise.
  * @throws {Error} If errors.llm.enabled is true but any of baseURL, apiKey, or model is missing
  */
 export function validateErrorsLlmAtTakeoff() {
-  const { enabled, baseURL, apiKey, model } = getErrorsLlmConfig();
+  const {
+    enabled,
+    baseURL,
+    apiKey,
+    model,
+    mode,
+    channel,
+    rateLimit,
+    cacheTTL,
+  } = getErrorsLlmConfig();
   if (!enabled) return;
 
   const missing = [];
@@ -81,4 +181,34 @@ export function validateErrorsLlmAtTakeoff() {
       `errors.llm is enabled but required config is missing: ${missing.join(', ')}. Set these env vars or disable errors.llm.enabled.`,
     );
   }
+
+  // Warn about channel set while mode is sync (channel only applies in async mode).
+  const channelRaw = String(
+    env('ERRORS_LLM_CHANNEL') ?? env('LLM_CHANNEL') ?? '',
+  ).trim();
+  if (mode === 'sync' && channelRaw) {
+    console.warn(
+      `[Tejas] errors.llm: channel="${channel}" is set but mode is "sync" — channel output only applies in async mode. Set ERRORS_LLM_MODE=async to use it.`,
+    );
+  }
+
+  // Warn about invalid numeric values that were silently reset to defaults.
+  const rateLimitRaw = String(
+    env('ERRORS_LLM_RATE_LIMIT') ?? env('LLM_RATE_LIMIT') ?? '',
+  ).trim();
+  if (
+    rateLimitRaw &&
+    (isNaN(Number(rateLimitRaw)) || Number(rateLimitRaw) <= 0)
+  ) {
+    console.warn(
+      `[Tejas] errors.llm: rateLimit value "${rateLimitRaw}" is invalid; defaulting to 10.`,
+    );
+  }
+
+  const cacheTTLRaw = String(env('ERRORS_LLM_CACHE_TTL') ?? '').trim();
+  if (cacheTTLRaw && (isNaN(Number(cacheTTLRaw)) || Number(cacheTTLRaw) <= 0)) {
+    console.warn(
+      `[Tejas] errors.llm: cacheTTL value "${cacheTTLRaw}" is invalid; defaulting to 3600000.`,
+    );
+  }
 }