@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/internal/error-handler/helpers.js

@@ -0,0 +1,214 @@
+/**
+ * @fileoverview Helper utilities for error inspection and normalization.
+ * Enhanced with cause chain extraction and circular reference detection.
+ * @module src/utils/internal/error-handler/helpers
+ */
+import { McpError } from '../../../types-global/errors.js';
+import { isAggregateError } from '../../../utils/types/guards.js';
+/**
+ * Retrieves a descriptive name for an error object or value.
+ *
+ * - `Error` instances → `error.name` (e.g. `'TypeError'`), falling back to `'Error'`.
+ * - `null` → `'NullValueEncountered'`
+ * - `undefined` → `'UndefinedValueEncountered'`
+ * - Non-plain objects with a named constructor → `'<ConstructorName>Encountered'`
+ * - Everything else → `'<typeof value>Encountered'` (e.g. `'stringEncountered'`)
+ *
+ * @param error - The error object or value.
+ * @returns A stable, human-readable string identifying the error's type.
+ *
+ * @example
+ * ```ts
+ * getErrorName(new TypeError('bad'));   // → 'TypeError'
+ * getErrorName('oops');                 // → 'stringEncountered'
+ * getErrorName(null);                   // → 'NullValueEncountered'
+ * ```
+ */
+export function getErrorName(error) {
+    if (error instanceof Error) {
+        return error.name || 'Error';
+    }
+    if (error === null) {
+        return 'NullValueEncountered';
+    }
+    if (error === undefined) {
+        return 'UndefinedValueEncountered';
+    }
+    if (typeof error === 'object' &&
+        error !== null &&
+        error.constructor &&
+        typeof error.constructor.name === 'string' &&
+        error.constructor.name !== 'Object') {
+        return `${error.constructor.name}Encountered`;
+    }
+    return `${typeof error}Encountered`;
+}
+/**
+ * Extracts a human-readable message string from any thrown value.
+ *
+ * Handles every JavaScript type so that `catch (e)` blocks never produce `[object Object]`:
+ * - `AggregateError` → combines up to 3 inner error messages after the outer message.
+ * - `Error` → `error.message`
+ * - `null` / `undefined` → descriptive literal strings.
+ * - Primitives (`string`, `number`, `boolean`, `bigint`, `symbol`) → string-coerced value.
+ * - Functions → `[function <name>]`
+ * - Objects → JSON-serialized if possible; otherwise constructor name fallback.
+ * - If conversion itself throws, returns a safe fallback describing the conversion error.
+ *
+ * @param error - The thrown value to extract a message from.
+ * @returns A non-empty string describing the error.
+ *
+ * @example
+ * ```ts
+ * getErrorMessage(new Error('oops'));              // → 'oops'
+ * getErrorMessage('string thrown');               // → 'string thrown'
+ * getErrorMessage(42);                            // → '42'
+ * getErrorMessage(null);                          // → 'Null value encountered as error'
+ * getErrorMessage(new AggregateError([new Error('a'), new Error('b')], 'multi'));
+ * // → 'multi: a; b'
+ * ```
+ */
+export function getErrorMessage(error) {
+    try {
+        if (error instanceof Error) {
+            // AggregateError should surface combined messages succinctly
+            if (isAggregateError(error)) {
+                const inner = error.errors
+                    .map((e) => (e instanceof Error ? e.message : String(e)))
+                    .filter(Boolean)
+                    .slice(0, 3)
+                    .join('; ');
+                return inner ? `${error.message}: ${inner}` : error.message;
+            }
+            return error.message;
+        }
+        if (error === null) {
+            return 'Null value encountered as error';
+        }
+        if (error === undefined) {
+            return 'Undefined value encountered as error';
+        }
+        if (typeof error === 'string') {
+            return error;
+        }
+        if (typeof error === 'number' || typeof error === 'boolean') {
+            return String(error);
+        }
+        if (typeof error === 'bigint') {
+            return error.toString();
+        }
+        if (typeof error === 'function') {
+            return `[function ${error.name || 'anonymous'}]`;
+        }
+        if (typeof error === 'object') {
+            try {
+                const json = JSON.stringify(error);
+                if (json && json !== '{}')
+                    return json;
+            }
+            catch {
+                // fall through
+            }
+            const ctor = error.constructor?.name;
+            return `Non-Error object encountered (constructor: ${ctor || 'Object'})`;
+        }
+        if (typeof error === 'symbol') {
+            return error.toString();
+        }
+        // c8 ignore next
+        return '[unrepresentable error]';
+    }
+    catch (conversionError) {
+        return `Error converting error to string: ${conversionError instanceof Error ? conversionError.message : 'Unknown conversion error'}`;
+    }
+}
+/**
+ * Extracts the complete error cause chain into a flat array of `ErrorCauseNode` objects.
+ *
+ * Starts at `error` (depth 0) and follows `error.cause` links until:
+ * - a non-Error value is encountered (appended as the terminal node, then stops),
+ * - a circular reference is detected (sentinel node appended, then stops),
+ * - or `maxDepth` is reached (sentinel node appended, then stops).
+ *
+ * String causes are treated as terminal `StringError` nodes.
+ * `McpError` nodes include the `data` property when present.
+ * Circular references are detected via `WeakSet` identity tracking.
+ *
+ * @param error - The outermost error to start traversal from.
+ * @param maxDepth - Maximum number of nodes to traverse before stopping. Defaults to `20`.
+ * @returns An array of `ErrorCauseNode` objects ordered from outermost (depth 0) to deepest cause.
+ *          An empty array is returned if `error` itself is falsy.
+ *
+ * @example
+ * ```ts
+ * const inner = new Error('db connection failed');
+ * const outer = new Error('user lookup failed', { cause: inner });
+ * const chain = extractErrorCauseChain(outer);
+ * // → [
+ * //   { name: 'Error', message: 'user lookup failed', depth: 0, stack: '...' },
+ * //   { name: 'Error', message: 'db connection failed', depth: 1, stack: '...' },
+ * // ]
+ * ```
+ */
+export function extractErrorCauseChain(error, maxDepth = 20) {
+    const chain = [];
+    const seen = new WeakSet();
+    let current = error;
+    let depth = 0;
+    while (current && depth < maxDepth) {
+        // Circular reference detection
+        if (typeof current === 'object' && current !== null) {
+            if (seen.has(current)) {
+                chain.push({
+                    name: 'CircularReference',
+                    message: 'Circular reference detected in error cause chain',
+                    depth,
+                });
+                break;
+            }
+            seen.add(current);
+        }
+        if (current instanceof Error) {
+            const node = {
+                name: current.name,
+                message: current.message,
+                depth,
+                // Only include stack if it exists (exact optional property types)
+                ...(current.stack !== undefined ? { stack: current.stack } : {}),
+            };
+            // Extract data from McpError instances
+            if (current instanceof McpError && current.data) {
+                node.data = current.data;
+            }
+            chain.push(node);
+            // Continue traversing cause chain
+            current = current.cause;
+        }
+        else if (typeof current === 'string') {
+            chain.push({
+                name: 'StringError',
+                message: current,
+                depth,
+            });
+            break;
+        }
+        else {
+            chain.push({
+                name: getErrorName(current),
+                message: getErrorMessage(current),
+                depth,
+            });
+            break;
+        }
+        depth++;
+    }
+    if (depth >= maxDepth) {
+        chain.push({
+            name: 'MaxDepthExceeded',
+            message: `Error cause chain exceeded maximum depth of ${maxDepth}`,
+            depth,
+        });
+    }
+    return chain;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/utils/internal/error-handler/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,sBAAsB,CAAC;IAChC,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,KAAK,CAAC,WAAW;QACjB,OAAO,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ;QAC1C,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ,EACnC,CAAC;QACD,OAAO,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,aAAa,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,OAAO,KAAK,aAAa,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC;QACH,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,6DAA6D;YAC7D,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM;qBACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;qBACxD,MAAM,CAAC,OAAO,CAAC;qBACf,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;qBACX,IAAI,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;YAC9D,CAAC;YACD,OAAO,KAAK,CAAC,OAAO,CAAC;QACvB,CAAC;QACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,iCAAiC,CAAC;QAC3C,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,sCAAsC,CAAC;QAChD,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;YAChC,OAAO,aAAa,KAAK,CAAC,IAAI,IAAI,WAAW,GAAG,CAAC;QACnD,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI;oBAAE,OAAO,IAAI,CAAC;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,eAAe;YACjB,CAAC;YACD,MAAM,IAAI,GAAI,KAA6C,CAAC,WAAW,EAAE,IAAI,CAAC;YAC9E,OAAO,8CAA8C,IAAI,IAAI,QAAQ,GAAG,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;QACD,iBAAiB;QACjB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAAC,OAAO,eAAe,EAAE,CAAC;QACzB,OAAO,qCAAqC,eAAe,YAAY,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B,EAAE,CAAC;IACxI,CAAC;AACH,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,QAAQ,GAAG,EAAE;IAClE,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,OAAO,OAAO,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;QACnC,+BAA+B;QAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACpD,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtB,KAAK,CAAC,IAAI,CAAC;oBACT,IAAI,EAAE,mBAAmB;oBACzB,OAAO,EAAE,kDAAkD;oBAC3D,KAAK;iBACN,CAAC,CAAC;gBACH,MAAM;YACR,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpB,CAAC;QAED,IAAI,OAAO,YAAY,KAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAmB;gBAC3B,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,KAAK;gBACL,kEAAkE;gBAClE,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACjE,CAAC;YAEF,uCAAuC;YACvC,IAAI,OAAO,YAAY,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBAChD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAC3B,CAAC;YAED,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEjB,kCAAkC;YAClC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;QAC1B,CAAC;aAAM,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,OAAO;gBAChB,KAAK;aACN,CAAC,CAAC;YACH,MAAM;QACR,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC;gBAC3B,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC;gBACjC,KAAK;aACN,CAAC,CAAC;YACH,MAAM;QACR,CAAC;QAED,KAAK,EAAE,CAAC;IACV,CAAC;IAED,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,+CAA+C,QAAQ,EAAE;YAClE,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/internal/error-handler/mappings.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Shared error classification constants used by the error handler.
+ * Enhanced with regex caching for performance and provider-specific error patterns.
+ * @module src/utils/internal/error-handler/mappings
+ */
+import { JsonRpcErrorCode } from '../../../types-global/errors.js';
+import type { BaseErrorMapping } from './types.js';
+/**
+ * Compiles and caches a regex pattern for repeated use without re-compilation overhead.
+ *
+ * - String patterns are compiled with the `i` (case-insensitive) flag.
+ * - `RegExp` patterns are re-compiled without the `g` flag (global flag is removed to prevent
+ *   stateful `lastIndex` bugs when the same pattern is reused across multiple `.test()` calls)
+ *   and with `i` added if absent.
+ * - Cache key for `RegExp` inputs is `source + flags`; for strings it is the string itself.
+ *
+ * @param pattern - A string or `RegExp` to compile and cache.
+ * @returns The compiled, cached `RegExp` instance.
+ *
+ * @example
+ * ```ts
+ * const re = getCompiledPattern('not found');
+ * re.test('Resource not found'); // → true
+ *
+ * const re2 = getCompiledPattern(/ThrottlingException/i);
+ * re2.test('ThrottlingException: rate exceeded'); // → true
+ * ```
+ */
+export declare function getCompiledPattern(pattern: string | RegExp): RegExp;
+/**
+ * Extended error mapping interface that includes pre-compiled regex pattern.
+ * @private
+ */
+interface CompiledErrorMapping extends BaseErrorMapping {
+    /** Pre-compiled regex pattern for efficient matching */
+    compiledPattern: RegExp;
+}
+/**
+ * Maps standard JavaScript error constructor names to `JsonRpcErrorCode` values.
+ *
+ * Consulted by `ErrorHandler.determineErrorCode` as the first pattern-match step after
+ * checking for `McpError` instances. Constructor names are matched via `getErrorName()`.
+ *
+ * | Constructor | Mapped Code |
+ * |-------------|-------------|
+ * | `SyntaxError` | `ValidationError` |
+ * | `TypeError` | `ValidationError` |
+ * | `RangeError` | `ValidationError` |
+ * | `URIError` | `ValidationError` |
+ * | `ReferenceError` | `InternalError` |
+ * | `EvalError` | `InternalError` |
+ * | `AggregateError` | `InternalError` |
+ *
+ * @example
+ * ```ts
+ * ERROR_TYPE_MAPPINGS['TypeError']; // → JsonRpcErrorCode.ValidationError
+ * ```
+ */
+export declare const ERROR_TYPE_MAPPINGS: Readonly<Record<string, JsonRpcErrorCode>>;
+/**
+ * Pre-compiled common error patterns used by `ErrorHandler.determineErrorCode`.
+ *
+ * Derived from `COMMON_ERROR_PATTERNS` — each entry has its `pattern` compiled via
+ * `getCompiledPattern` at module initialization. Checked after `COMPILED_PROVIDER_PATTERNS`
+ * (provider patterns are more specific and take priority).
+ *
+ * Patterns cover: auth/unauthorized, forbidden, not-found, validation, conflict,
+ * rate-limit, timeout/abort, service-unavailable, and Zod schema errors.
+ */
+export declare const COMPILED_ERROR_PATTERNS: ReadonlyArray<Readonly<CompiledErrorMapping>>;
+/**
+ * Pre-compiled provider-specific error patterns used by `ErrorHandler.determineErrorCode`.
+ *
+ * Derived from `PROVIDER_ERROR_PATTERNS` — each entry has its `pattern` compiled via
+ * `getCompiledPattern` at module initialization. Checked before `COMPILED_ERROR_PATTERNS`
+ * because provider patterns are more specific (e.g. `status code 429` is more precise than
+ * the generic `rate limit` common pattern).
+ *
+ * Covers: AWS service errors, HTTP status codes (401/403/404/409/429/5xx),
+ * database connection/constraint errors, Supabase JWT/RLS, OpenRouter/LLM quota errors,
+ * and low-level network errors (ECONNREFUSED, ECONNRESET, ENOTFOUND, ETIMEDOUT).
+ */
+export declare const COMPILED_PROVIDER_PATTERNS: ReadonlyArray<Readonly<CompiledErrorMapping>>;
+export {};
+//# sourceMappingURL=mappings.d.ts.map

package/dist/utils/internal/error-handler/mappings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappings.d.ts","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/mappings.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AASnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAyBnE;AAED;;;GAGG;AACH,UAAU,oBAAqB,SAAQ,gBAAgB;IACrD,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAQ1E,CAAC;AAkDF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAI7E,CAAC;AA6EN;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAIhF,CAAC"}

package/dist/utils/internal/error-handler/mappings.js

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Shared error classification constants used by the error handler.
+ * Enhanced with regex caching for performance and provider-specific error patterns.
+ * @module src/utils/internal/error-handler/mappings
+ */
+import { JsonRpcErrorCode } from '../../../types-global/errors.js';
+/**
+ * Compiled regex cache for performance optimization.
+ * Prevents repeated regex compilation on every error classification.
+ * @private
+ */
+const COMPILED_PATTERN_CACHE = new Map();
+/**
+ * Compiles and caches a regex pattern for repeated use without re-compilation overhead.
+ *
+ * - String patterns are compiled with the `i` (case-insensitive) flag.
+ * - `RegExp` patterns are re-compiled without the `g` flag (global flag is removed to prevent
+ *   stateful `lastIndex` bugs when the same pattern is reused across multiple `.test()` calls)
+ *   and with `i` added if absent.
+ * - Cache key for `RegExp` inputs is `source + flags`; for strings it is the string itself.
+ *
+ * @param pattern - A string or `RegExp` to compile and cache.
+ * @returns The compiled, cached `RegExp` instance.
+ *
+ * @example
+ * ```ts
+ * const re = getCompiledPattern('not found');
+ * re.test('Resource not found'); // → true
+ *
+ * const re2 = getCompiledPattern(/ThrottlingException/i);
+ * re2.test('ThrottlingException: rate exceeded'); // → true
+ * ```
+ */
+export function getCompiledPattern(pattern) {
+    // Create a stable cache key
+    const cacheKey = pattern instanceof RegExp ? pattern.source + pattern.flags : pattern;
+    // Return cached pattern if available
+    if (COMPILED_PATTERN_CACHE.has(cacheKey)) {
+        return COMPILED_PATTERN_CACHE.get(cacheKey);
+    }
+    // Compile new pattern
+    let compiled;
+    if (pattern instanceof RegExp) {
+        // Remove global flag, ensure case-insensitive
+        let flags = pattern.flags.replace('g', '');
+        if (!flags.includes('i')) {
+            flags += 'i';
+        }
+        compiled = new RegExp(pattern.source, flags);
+    }
+    else {
+        compiled = new RegExp(pattern, 'i');
+    }
+    // Cache for future use
+    COMPILED_PATTERN_CACHE.set(cacheKey, compiled);
+    return compiled;
+}
+/**
+ * Maps standard JavaScript error constructor names to `JsonRpcErrorCode` values.
+ *
+ * Consulted by `ErrorHandler.determineErrorCode` as the first pattern-match step after
+ * checking for `McpError` instances. Constructor names are matched via `getErrorName()`.
+ *
+ * | Constructor | Mapped Code |
+ * |-------------|-------------|
+ * | `SyntaxError` | `ValidationError` |
+ * | `TypeError` | `ValidationError` |
+ * | `RangeError` | `ValidationError` |
+ * | `URIError` | `ValidationError` |
+ * | `ReferenceError` | `InternalError` |
+ * | `EvalError` | `InternalError` |
+ * | `AggregateError` | `InternalError` |
+ *
+ * @example
+ * ```ts
+ * ERROR_TYPE_MAPPINGS['TypeError']; // → JsonRpcErrorCode.ValidationError
+ * ```
+ */
+export const ERROR_TYPE_MAPPINGS = {
+    SyntaxError: JsonRpcErrorCode.ValidationError,
+    TypeError: JsonRpcErrorCode.ValidationError,
+    ReferenceError: JsonRpcErrorCode.InternalError,
+    RangeError: JsonRpcErrorCode.ValidationError,
+    URIError: JsonRpcErrorCode.ValidationError,
+    EvalError: JsonRpcErrorCode.InternalError,
+    AggregateError: JsonRpcErrorCode.InternalError,
+};
+/**
+ * Common error patterns for classifying errors by message/name.
+ * Order matters: more specific patterns should precede generic ones.
+ * @private — only consumed via COMPILED_ERROR_PATTERNS
+ */
+const COMMON_ERROR_PATTERNS = [
+    {
+        pattern: /auth|unauthorized|unauthenticated|not.*logged.*in|invalid.*token|expired.*token/i,
+        errorCode: JsonRpcErrorCode.Unauthorized,
+    },
+    {
+        pattern: /permission|forbidden|access.*denied|not.*allowed/i,
+        errorCode: JsonRpcErrorCode.Forbidden,
+    },
+    {
+        pattern: /not found|missing|no such|doesn't exist|couldn't find/i,
+        errorCode: JsonRpcErrorCode.NotFound,
+    },
+    {
+        pattern: /invalid|validation|malformed|bad request|wrong format|missing required/i,
+        errorCode: JsonRpcErrorCode.ValidationError,
+    },
+    {
+        pattern: /conflict|already exists|duplicate|unique constraint/i,
+        errorCode: JsonRpcErrorCode.Conflict,
+    },
+    {
+        pattern: /rate limit|too many requests|throttled/i,
+        errorCode: JsonRpcErrorCode.RateLimited,
+    },
+    {
+        pattern: /timeout|timed out|deadline exceeded/i,
+        errorCode: JsonRpcErrorCode.Timeout,
+    },
+    {
+        pattern: /abort(ed)?|cancell?ed/i,
+        errorCode: JsonRpcErrorCode.Timeout,
+    },
+    {
+        pattern: /service unavailable|bad gateway|gateway timeout|upstream error/i,
+        errorCode: JsonRpcErrorCode.ServiceUnavailable,
+    },
+    {
+        pattern: /zod|zoderror|schema validation/i,
+        errorCode: JsonRpcErrorCode.ValidationError,
+    },
+];
+/**
+ * Pre-compiled common error patterns used by `ErrorHandler.determineErrorCode`.
+ *
+ * Derived from `COMMON_ERROR_PATTERNS` — each entry has its `pattern` compiled via
+ * `getCompiledPattern` at module initialization. Checked after `COMPILED_PROVIDER_PATTERNS`
+ * (provider patterns are more specific and take priority).
+ *
+ * Patterns cover: auth/unauthorized, forbidden, not-found, validation, conflict,
+ * rate-limit, timeout/abort, service-unavailable, and Zod schema errors.
+ */
+export const COMPILED_ERROR_PATTERNS = COMMON_ERROR_PATTERNS.map((mapping) => ({
+    ...mapping,
+    compiledPattern: getCompiledPattern(mapping.pattern),
+}));
+/**
+ * Provider-specific error patterns for external service integration.
+ * Covers common error formats from AWS, HTTP status codes, databases, and LLM providers.
+ * @private — only consumed via COMPILED_PROVIDER_PATTERNS
+ */
+const PROVIDER_ERROR_PATTERNS = [
+    // AWS Service Errors
+    {
+        pattern: /ThrottlingException|TooManyRequestsException/i,
+        errorCode: JsonRpcErrorCode.RateLimited,
+    },
+    {
+        pattern: /AccessDenied|UnauthorizedOperation/i,
+        errorCode: JsonRpcErrorCode.Forbidden,
+    },
+    {
+        pattern: /ResourceNotFoundException/i,
+        errorCode: JsonRpcErrorCode.NotFound,
+    },
+    // HTTP Status-based errors
+    { pattern: /status code 401/i, errorCode: JsonRpcErrorCode.Unauthorized },
+    { pattern: /status code 403/i, errorCode: JsonRpcErrorCode.Forbidden },
+    { pattern: /status code 404/i, errorCode: JsonRpcErrorCode.NotFound },
+    { pattern: /status code 409/i, errorCode: JsonRpcErrorCode.Conflict },
+    { pattern: /status code 429/i, errorCode: JsonRpcErrorCode.RateLimited },
+    {
+        pattern: /status code 5\d\d/i,
+        errorCode: JsonRpcErrorCode.ServiceUnavailable,
+    },
+    // Database connection and constraint errors
+    {
+        pattern: /ECONNREFUSED|connection refused/i,
+        errorCode: JsonRpcErrorCode.ServiceUnavailable,
+    },
+    {
+        pattern: /ETIMEDOUT|connection timeout/i,
+        errorCode: JsonRpcErrorCode.Timeout,
+    },
+    {
+        pattern: /unique constraint|duplicate key/i,
+        errorCode: JsonRpcErrorCode.Conflict,
+    },
+    {
+        pattern: /foreign key constraint/i,
+        errorCode: JsonRpcErrorCode.ValidationError,
+    },
+    // Supabase-specific errors
+    { pattern: /JWT expired/i, errorCode: JsonRpcErrorCode.Unauthorized },
+    {
+        pattern: /row level security/i,
+        errorCode: JsonRpcErrorCode.Forbidden,
+    },
+    // OpenRouter/LLM provider errors
+    {
+        pattern: /insufficient_quota|quota exceeded/i,
+        errorCode: JsonRpcErrorCode.RateLimited,
+    },
+    { pattern: /model_not_found/i, errorCode: JsonRpcErrorCode.NotFound },
+    {
+        pattern: /context_length_exceeded/i,
+        errorCode: JsonRpcErrorCode.ValidationError,
+    },
+    // Network errors
+    { pattern: /ENOTFOUND|DNS/i, errorCode: JsonRpcErrorCode.ServiceUnavailable },
+    {
+        pattern: /ECONNRESET|connection reset/i,
+        errorCode: JsonRpcErrorCode.ServiceUnavailable,
+    },
+];
+/**
+ * Pre-compiled provider-specific error patterns used by `ErrorHandler.determineErrorCode`.
+ *
+ * Derived from `PROVIDER_ERROR_PATTERNS` — each entry has its `pattern` compiled via
+ * `getCompiledPattern` at module initialization. Checked before `COMPILED_ERROR_PATTERNS`
+ * because provider patterns are more specific (e.g. `status code 429` is more precise than
+ * the generic `rate limit` common pattern).
+ *
+ * Covers: AWS service errors, HTTP status codes (401/403/404/409/429/5xx),
+ * database connection/constraint errors, Supabase JWT/RLS, OpenRouter/LLM quota errors,
+ * and low-level network errors (ECONNREFUSED, ECONNRESET, ENOTFOUND, ETIMEDOUT).
+ */
+export const COMPILED_PROVIDER_PATTERNS = PROVIDER_ERROR_PATTERNS.map((mapping) => ({
+    ...mapping,
+    compiledPattern: getCompiledPattern(mapping.pattern),
+}));
+//# sourceMappingURL=mappings.js.map

package/dist/utils/internal/error-handler/mappings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappings.js","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/mappings.ts"],"names":[],"mappings":"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"}