te.js 2.1.6 → 2.2.0

package/server/ammo.js

@@ -15,6 +15,9 @@ import {
   buildPayload,
   dispatchToChannels,
 } from './errors/channels/index.js';
+import TejLogger from 'tej-logger';
+
+const logger = new TejLogger('Tejas.Ammo');
 
 /**
  * Detect if the value is a throw() options object (per-call overrides).
@@ -85,6 +88,13 @@ class Ammo {
 
     // Response related data
     this.dispatchedData = undefined;
+
+    /**
+     * Resolved error info stashed after ammo.throw() completes.
+     * Read by the radar middleware on res.finish to populate error tracking.
+     * @type {{ message: string, type: string|null, devInsight: string|null, stack: string|null, codeContext: object|null } | null}
+     */
+    this._errorInfo = null;
   }
 
   /**
@@ -371,7 +381,11 @@ class Ammo {
     // Per-call options: last arg can be { useLlm?, messageType? } when call is LLM-eligible (no explicit code).
     const llmEligible =
       args.length === 0 ||
-      (!isStatusCode(args[0]) && !(args[0] instanceof TejError));
+      (!isStatusCode(args[0]) &&
+        !(
+          typeof args[0]?.statusCode === 'number' &&
+          typeof args[0]?.code === 'string'
+        ));
     let throwOpts =
       /** @type {{ useLlm?: boolean, messageType?: 'endUser'|'developer' } | null} */ (
         null
@@ -393,7 +407,7 @@ class Ammo {
       // Capture the stack string SYNCHRONOUSLY before any async work or fire() call,
       // because the call stack unwinds as soon as we await or respond.
       const stack =
-        args[0] instanceof Error && args[0].stack
+        args[0] != null && typeof args[0].stack === 'string'
           ? args[0].stack
           : new Error().stack;
       const originalError =
@@ -405,11 +419,31 @@ class Ammo {
         // Respond immediately with a generic 500, then run LLM in the background.
         this.fire(500, 'Internal Server Error');
 
+        // Stash basic error info synchronously so radar can read it on res.finish
+        // even before LLM completes. LLM result will update _errorInfo when ready.
+        const errorType =
+          originalError != null &&
+          typeof originalError.constructor?.name === 'string'
+            ? originalError.constructor.name
+            : originalError !== undefined
+              ? typeof originalError
+              : null;
+        this._errorInfo = {
+          message: 'Internal Server Error',
+          type: errorType,
+          devInsight: null,
+          stack: stack ?? null,
+          codeContext: null,
+        };
+
         // Fire-and-forget: capture context, call LLM, dispatch to channel.
         const method = this.method;
         const path = this.path;
+        const self = this;
         captureCodeContext(stack)
           .then((codeContext) => {
+            // Update _errorInfo with captured code context
+            if (self._errorInfo) self._errorInfo.codeContext = codeContext;
             const context = {
               codeContext,
               method,
@@ -428,6 +462,11 @@ class Ammo {
             }));
           })
           .then(({ result, codeContext }) => {
+            // Update _errorInfo with full LLM result
+            if (self._errorInfo) {
+              self._errorInfo.message = result.message;
+              self._errorInfo.devInsight = result.devInsight ?? null;
+            }
             const channels = getChannels(channel, logFile);
             const payload = buildPayload({
               method,
@@ -442,8 +481,12 @@ class Ammo {
             });
             return dispatchToChannels(channels, payload);
           })
-          .catch(() => {
-            // Swallow background errors — the HTTP response has already been sent.
+          .catch((err) => {
+            // Background LLM failed after HTTP response already sent — log the failure
+            // but do not attempt to respond again.
+            logger.warn(
+              `Background LLM dispatch failed: ${err?.message ?? err}`,
+            );
           });
 
         return;
@@ -462,9 +505,27 @@ class Ammo {
             }),
           };
           if (originalError !== undefined) context.error = originalError;
-          return inferErrorFromContext(context);
+          return inferErrorFromContext(context).then((result) => ({
+            result,
+            codeContext,
+          }));
         })
-        .then(({ statusCode, message, devInsight }) => {
+        .then(({ result, codeContext }) => {
+          const { statusCode, message, devInsight } = result;
+          const errorType =
+            originalError != null &&
+            typeof originalError.constructor?.name === 'string'
+              ? originalError.constructor.name
+              : originalError !== undefined
+                ? typeof originalError
+                : null;
+          this._errorInfo = {
+            message,
+            type: errorType,
+            devInsight: devInsight ?? null,
+            stack: stack ?? null,
+            codeContext: codeContext ?? null,
+          };
           const isProduction = process.env.NODE_ENV === 'production';
           const data =
             !isProduction && devInsight
@@ -472,15 +533,23 @@ class Ammo {
               : message;
           this.fire(statusCode, data);
         })
-        .catch(() => {
+        .catch((err) => {
           // LLM call failed (network error, timeout, etc.) — fall back to generic 500
           // so the client always gets a response and we don't trigger an infinite retry loop.
+          logger.warn(`LLM error inference failed: ${err?.message ?? err}`);
           this.fire(500, 'Internal Server Error');
         });
     }
 
     // Sync path: explicit code/message or useLlm: false
     if (args.length === 0) {
+      this._errorInfo = {
+        message: 'Internal Server Error',
+        type: null,
+        devInsight: null,
+        stack: null,
+        codeContext: null,
+      };
       this.fire(500, 'Internal Server Error');
       return;
     }
@@ -488,29 +557,71 @@ class Ammo {
     if (isStatusCode(args[0])) {
       const statusCode = args[0];
       const message = args[1] || toStatusMessage(statusCode);
+      this._errorInfo = {
+        message,
+        type: null,
+        devInsight: null,
+        stack: null,
+        codeContext: null,
+      };
       this.fire(statusCode, message);
       return;
     }
 
-    if (args[0] instanceof TejError) {
+    if (
+      typeof args[0]?.statusCode === 'number' &&
+      typeof args[0]?.code === 'string'
+    ) {
       const error = args[0];
-      this.fire(error.code, error.message);
+      this._errorInfo = {
+        message: error.message,
+        type: error.constructor?.name ?? 'TejError',
+        devInsight: null,
+        stack: error.stack ?? null,
+        codeContext: null,
+      };
+      this.fire(error.statusCode, error.message);
       return;
     }
 
-    if (args[0] instanceof Error) {
+    if (
+      args[0] != null &&
+      typeof args[0].message === 'string' &&
+      typeof args[0].stack === 'string'
+    ) {
       const error = args[0];
       if (!isNaN(parseInt(error.message))) {
         const statusCode = parseInt(error.message);
         const message = toStatusMessage(statusCode) || toStatusMessage(500);
+        this._errorInfo = {
+          message,
+          type: error.constructor.name,
+          devInsight: null,
+          stack: error.stack ?? null,
+          codeContext: null,
+        };
         this.fire(statusCode, message);
         return;
       }
       const statusCode = toStatusCode(error.message);
       if (statusCode) {
+        this._errorInfo = {
+          message: error.message,
+          type: error.constructor.name,
+          devInsight: null,
+          stack: error.stack ?? null,
+          codeContext: null,
+        };
         this.fire(statusCode, error.message);
         return;
       }
+      this._errorInfo = {
+        message: error.message,
+        type: error.constructor.name,
+        devInsight: null,
+        stack: error.stack ?? null,
+        codeContext: null,
+      };
       this.fire(500, error.message);
       return;
     }
@@ -518,9 +629,23 @@ class Ammo {
     const errorValue = args[0];
     const statusCode = toStatusCode(errorValue);
     if (statusCode) {
+      this._errorInfo = {
+        message: toStatusMessage(statusCode),
+        type: null,
+        devInsight: null,
+        stack: null,
+        codeContext: null,
+      };
       this.fire(statusCode, toStatusMessage(statusCode));
       return;
     }
+    this._errorInfo = {
+      message: errorValue.toString(),
+      type: null,
+      devInsight: null,
+      stack: null,
+      codeContext: null,
+    };
     this.fire(500, errorValue.toString());
   }
 }

package/server/context/request-context.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Request-scoped context using AsyncLocalStorage.
+ *
+ * Provides a safe, mutation-resistant store for per-request data.
+ * The store is initialized by the handler and is accessible from any
+ * code running within the same async execution context (middleware, handlers,
+ * service functions, etc.) without needing to thread parameters through.
+ *
+ * @example
+ * // In a middleware or handler:
+ * import { getRequestId, getRequestStore } from '../server/context/request-context.js';
+ * const requestId = getRequestId(); // 'abc-123...' or 'no-context'
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+
+/** @type {AsyncLocalStorage<{ requestId: string, startTime: number }>} */
+export const requestContext = new AsyncLocalStorage();
+
+/**
+ * Returns the current request ID from async context, or 'no-context' if called
+ * outside of an active request (e.g., during startup).
+ * @returns {string}
+ */
+export function getRequestId() {
+  return requestContext.getStore()?.requestId ?? 'no-context';
+}
+
+/**
+ * Returns the full request store, or null if not in a request context.
+ * @returns {{ requestId: string, startTime: number } | undefined}
+ */
+export function getRequestStore() {
+  return requestContext.getStore();
+}
+
+/**
+ * Middleware that initializes the per-request AsyncLocalStorage store.
+ * Must be the first global middleware registered via app.midair().
+ *
+ * @param {import('../ammo.js').default} ammo
+ * @param {function(): Promise<void>} next
+ */
+export function contextMiddleware(ammo, next) {
+  const store = {
+    requestId: randomUUID(),
+    startTime: Date.now(),
+  };
+  return requestContext.run(store, next);
+}

package/server/context/request-context.test.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Tests for request-context (AsyncLocalStorage).
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  requestContext,
+  getRequestId,
+  getRequestStore,
+  contextMiddleware,
+} from './request-context.js';
+
+describe('requestContext', () => {
+  it('should return "no-context" when called outside a request', () => {
+    expect(getRequestId()).toBe('no-context');
+  });
+
+  it('should return undefined store outside a request', () => {
+    expect(getRequestStore()).toBeUndefined();
+  });
+
+  it('should provide requestId within contextMiddleware', async () => {
+    const results = [];
+    const next = async () => {
+      results.push(getRequestId());
+    };
+    await contextMiddleware({}, next);
+    expect(results).toHaveLength(1);
+    expect(typeof results[0]).toBe('string');
+    expect(results[0]).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it('should provide startTime within contextMiddleware', async () => {
+    const before = Date.now();
+    let store;
+    await contextMiddleware({}, async () => {
+      store = getRequestStore();
+    });
+    expect(store.startTime).toBeGreaterThanOrEqual(before);
+  });
+
+  it('each request should have unique requestId', async () => {
+    const ids = [];
+    for (let i = 0; i < 5; i++) {
+      await contextMiddleware({}, async () => {
+        ids.push(getRequestId());
+      });
+    }
+    const unique = new Set(ids);
+    expect(unique.size).toBe(5);
+  });
+});

package/server/endpoint.js

@@ -2,7 +2,16 @@ import isMiddlewareValid from './targets/middleware-validator.js';
 import { isPathValid, standardizePath } from './targets/path-validator.js';
 import isShootValid from './targets/shoot-validator.js';
 
+/**
+ * Represents a single route endpoint: a path, handler, optional middlewares,
+ * allowed HTTP methods, and documentation metadata.
+ *
+ * Use the fluent builder methods to configure before registering with a Target.
+ */
 class Endpoint {
+  /**
+   * Create a new Endpoint with empty defaults.
+   */
   constructor() {
     this.path = '';
     this.middlewares = [];
@@ -14,6 +23,12 @@ class Endpoint {
     this.group = null;
   }
 
+  /**
+   * Set the full path by combining a base path and a path segment.
+   * @param {string} base - Base path (e.g. '/api')
+   * @param {string} path - Route path segment (e.g. '/users')
+   * @returns {Endpoint}
+   */
   setPath(base, path) {
     const standardizedBase = standardizePath(base);
     const standardizedPath = standardizePath(path);

package/server/error.js

@@ -1,9 +1,62 @@
+/**
+ * @fileoverview Base error class for the Tejas framework.
+ *
+ * All errors thrown by the framework extend TejError. The constructor
+ * accepts the HTTP status code as the first argument (matching the existing
+ * call signature `new TejError(statusCode, message)`) and derives a
+ * machine-readable `code` string of the form `ERR_HTTP_<statusCode>`.
+ *
+ * Well-known codes are available as named constants on `TejError` for
+ * callers that want expressive error codes without hardcoding numbers.
+ */
+
+/**
+ * Base framework error class.
+ *
+ * @extends {Error}
+ *
+ * @example
+ * throw new TejError(404, 'Not Found');
+ * // error.statusCode === 404
+ * // error.code      === 'ERR_HTTP_404'
+ *
+ * @example
+ * // With cause chaining
+ * throw new TejError(500, 'Database failure', { cause: originalError });
+ */
 class TejError extends Error {
-  constructor(code, message) {
-    super(message);
+  /**
+   * @param {number} statusCode   - HTTP status code (e.g. 404, 500)
+   * @param {string} message      - Human-readable description
+   * @param {{ cause?: Error }} [options] - Optional native cause for chaining
+   */
+  constructor(statusCode, message, options) {
+    super(message, options);
     this.name = this.constructor.name;
-    this.code = code;
+    /** @type {number} HTTP status code */
+    this.statusCode = statusCode;
+    /** @type {string} Machine-readable error code derived from status */
+    this.code = `ERR_HTTP_${statusCode}`;
+    Error.captureStackTrace(this, this.constructor);
   }
 }
 
+/**
+ * Named error codes for common framework scenarios.
+ * Use these instead of hardcoding numeric status codes at call sites.
+ */
+TejError.CODES = Object.freeze({
+  ERR_ROUTING_FAILED: 'ERR_ROUTING_FAILED',
+  ERR_INVALID_DEPENDENCY: 'ERR_INVALID_DEPENDENCY',
+  ERR_PLUGIN_LOAD_FAILED: 'ERR_PLUGIN_LOAD_FAILED',
+  ERR_CONFIG_INVALID: 'ERR_CONFIG_INVALID',
+  ERR_STREAM_OVERFLOW: 'ERR_STREAM_OVERFLOW',
+  ERR_AUTH_FAILED: 'ERR_AUTH_FAILED',
+  ERR_NOT_FOUND: 'ERR_HTTP_404',
+  ERR_METHOD_NOT_ALLOWED: 'ERR_HTTP_405',
+  ERR_UNAUTHORIZED: 'ERR_HTTP_401',
+  ERR_BAD_REQUEST: 'ERR_HTTP_400',
+  ERR_INTERNAL: 'ERR_HTTP_500',
+});
+
 export default TejError;

package/server/error.test.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Tests for TejError base class.
+ */
+import { describe, it, expect } from 'vitest';
+import TejError from './error.js';
+
+describe('TejError', () => {
+  it('should set statusCode and derive ERR_HTTP_* code', () => {
+    const err = new TejError(404, 'Not Found');
+    expect(err.statusCode).toBe(404);
+    expect(err.code).toBe('ERR_HTTP_404');
+    expect(err.message).toBe('Not Found');
+    expect(err.name).toBe('TejError');
+  });
+
+  it('should capture a stack trace', () => {
+    const err = new TejError(500, 'Internal Server Error');
+    expect(typeof err.stack).toBe('string');
+    expect(err.stack).toContain('TejError');
+  });
+
+  it('should support native cause chaining', () => {
+    const cause = new Error('original');
+    const err = new TejError(500, 'Wrapped', { cause });
+    expect(err.cause).toBe(cause);
+  });
+
+  it('should extend Error', () => {
+    const err = new TejError(400, 'Bad Request');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('should have frozen CODES constant', () => {
+    expect(Object.isFrozen(TejError.CODES)).toBe(true);
+    expect(TejError.CODES.ERR_ROUTING_FAILED).toBe('ERR_ROUTING_FAILED');
+    expect(TejError.CODES.ERR_NOT_FOUND).toBe('ERR_HTTP_404');
+  });
+
+  it('should derive correct codes for common statuses', () => {
+    expect(new TejError(400, '').code).toBe('ERR_HTTP_400');
+    expect(new TejError(401, '').code).toBe('ERR_HTTP_401');
+    expect(new TejError(403, '').code).toBe('ERR_HTTP_403');
+    expect(new TejError(500, '').code).toBe('ERR_HTTP_500');
+  });
+});

package/server/errors/channels/channels.test.js

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getChannels, buildPayload } from './index.js';
+import { ConsoleChannel } from './console.js';
+import { LogChannel } from './log.js';
+
+describe('getChannels()', () => {
+  it('returns a ConsoleChannel for "console"', () => {
+    const channels = getChannels('console', './test.log');
+    expect(channels).toHaveLength(1);
+    expect(channels[0]).toBeInstanceOf(ConsoleChannel);
+  });
+
+  it('returns a LogChannel for "log"', () => {
+    const channels = getChannels('log', './test.log');
+    expect(channels).toHaveLength(1);
+    expect(channels[0]).toBeInstanceOf(LogChannel);
+  });
+
+  it('returns both channels for "both"', () => {
+    const channels = getChannels('both', './test.log');
+    expect(channels).toHaveLength(2);
+    const types = channels.map((c) => c.constructor.name);
+    expect(types).toContain('ConsoleChannel');
+    expect(types).toContain('LogChannel');
+  });
+
+  it('defaults to ConsoleChannel for unknown values', () => {
+    const channels = getChannels('unknown', './test.log');
+    expect(channels).toHaveLength(1);
+    expect(channels[0]).toBeInstanceOf(ConsoleChannel);
+  });
+
+  it('returns same ConsoleChannel singleton across calls', () => {
+    const a = getChannels('console', './test.log')[0];
+    const b = getChannels('console', './test.log')[0];
+    expect(a).toBe(b);
+  });
+
+  it('LogChannel uses the provided logFile path', () => {
+    const channels = getChannels('log', './my-errors.log');
+    expect(channels[0].logFile).toBe('./my-errors.log');
+  });
+});
+
+describe('buildPayload()', () => {
+  const codeContext = {
+    snippets: [
+      { file: '/app/handler.js', line: 10, snippet: '→ ammo.throw()' },
+    ],
+  };
+
+  it('builds a complete payload', () => {
+    const payload = buildPayload({
+      method: 'POST',
+      path: '/users',
+      originalError: new Error('DB error'),
+      codeContext,
+      statusCode: 500,
+      message: 'Internal Server Error',
+      devInsight: 'DB connection may be down.',
+    });
+
+    expect(payload.method).toBe('POST');
+    expect(payload.path).toBe('/users');
+    expect(payload.statusCode).toBe(500);
+    expect(payload.message).toBe('Internal Server Error');
+    expect(payload.devInsight).toBe('DB connection may be down.');
+    expect(payload.error).toEqual({ type: 'Error', message: 'DB error' });
+    expect(payload.codeContext).toBe(codeContext);
+    expect(typeof payload.timestamp).toBe('string');
+    expect(() => new Date(payload.timestamp)).not.toThrow();
+  });
+
+  it('handles string error', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/items',
+      originalError: 'Not found',
+      codeContext,
+      statusCode: 404,
+      message: 'Not found',
+    });
+    expect(payload.error).toEqual({ type: 'string', message: 'Not found' });
+  });
+
+  it('sets error to null when no originalError', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 500,
+      message: 'Error',
+    });
+    expect(payload.error).toBeNull();
+  });
+
+  it('includes cached flag when provided', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 404,
+      message: 'Not found',
+      cached: true,
+    });
+    expect(payload.cached).toBe(true);
+  });
+
+  it('includes rateLimited flag when provided', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 500,
+      message: 'Error',
+      rateLimited: true,
+    });
+    expect(payload.rateLimited).toBe(true);
+  });
+
+  it('omits cached and rateLimited when not provided', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 200,
+      message: 'OK',
+    });
+    expect(payload).not.toHaveProperty('cached');
+    expect(payload).not.toHaveProperty('rateLimited');
+  });
+
+  it('omits devInsight when not provided', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 500,
+      message: 'Error',
+    });
+    expect(payload).not.toHaveProperty('devInsight');
+  });
+});

package/server/errors/channels/index.js

@@ -77,7 +77,7 @@ export function buildPayload({
   rateLimited,
 }) {
   let errorSummary = null;
-  if (originalError instanceof Error) {
+  if (originalError != null && typeof originalError.message === 'string') {
     errorSummary = {
       type: originalError.constructor?.name ?? 'Error',
       message: originalError.message ?? '',

package/server/errors/llm-cache.js

@@ -29,7 +29,7 @@ class LLMErrorCache {
     const snippet = codeContext?.snippets?.[0];
     const location = snippet ? `${snippet.file}:${snippet.line}` : 'unknown';
     let errText = '';
-    if (error instanceof Error) {
+    if (error != null && typeof error.message === 'string') {
       errText = error.message ?? '';
     } else if (error != null) {
       errText = String(error);