perplexity-mcp-server
Version:
A Perplexity API Model Context Protocol (MCP) server that unlocks Perplexity's search-augmented AI capabilities for LLM agents. Features robust error handling, secure input validation, and transparent reasoning with the showThinking parameter. Built with
177 lines (176 loc) • 7.7 kB
TypeScript
/**
* @fileoverview This module provides utilities for robust error handling.
* It defines structures for error context, options for handling errors,
* and mappings for classifying errors. The main `ErrorHandler` class
* offers static methods for consistent error processing, logging, and transformation.
* @module src/utils/internal/errorHandler
*/
import { BaseErrorCode } from "../../types-global/errors.js";
/**
* Defines a generic structure for providing context with errors.
* This context can include identifiers like `requestId` or any other relevant
* key-value pairs that aid in debugging or understanding the error's circumstances.
*/
export interface ErrorContext {
/**
* A unique identifier for the request or operation during which the error occurred.
* Useful for tracing errors through logs and distributed systems.
*/
requestId?: string;
/**
* Allows for arbitrary additional context information.
* Keys are strings, and values can be of any type.
*/
[key: string]: unknown;
}
/**
* Configuration options for the `ErrorHandler.handleError` method.
* These options control how an error is processed, logged, and whether it's rethrown.
*/
export interface ErrorHandlerOptions {
/**
* The context of the operation that caused the error.
* This can include `requestId` and other relevant debugging information.
*/
context?: ErrorContext;
/**
* A descriptive name of the operation being performed when the error occurred.
* This helps in identifying the source or nature of the error in logs.
* Example: "UserLogin", "ProcessPayment", "FetchUserProfile".
*/
operation: string;
/**
* The input data or parameters that were being processed when the error occurred.
* This input will be sanitized before logging to prevent sensitive data exposure.
*/
input?: unknown;
/**
* If true, the (potentially transformed) error will be rethrown after handling.
* Defaults to `false`.
*/
rethrow?: boolean;
/**
* A specific `BaseErrorCode` to assign to the error, overriding any
* automatically determined error code.
*/
errorCode?: BaseErrorCode;
/**
* A custom function to map or transform the original error into a new `Error` instance.
* If provided, this function is used instead of the default `McpError` creation.
* @param error - The original error that occurred.
* @returns The transformed error.
*/
errorMapper?: (error: unknown) => Error;
/**
* If true, stack traces will be included in the logs.
* Defaults to `true`.
*/
includeStack?: boolean;
/**
* If true, indicates that the error is critical and might require immediate attention
* or could lead to system instability. This is primarily for logging and alerting.
* Defaults to `false`.
*/
critical?: boolean;
}
/**
* Defines a basic rule for mapping errors based on patterns.
* Used internally by `COMMON_ERROR_PATTERNS` and as a base for `ErrorMapping`.
*/
export interface BaseErrorMapping {
/**
* A string or regular expression to match against the error message.
* If a string is provided, it's typically used for substring matching (case-insensitive).
*/
pattern: string | RegExp;
/**
* The `BaseErrorCode` to assign if the pattern matches.
*/
errorCode: BaseErrorCode;
/**
* An optional custom message template for the mapped error.
* (Note: This property is defined but not directly used by `ErrorHandler.determineErrorCode`
* which focuses on `errorCode`. It's more relevant for custom mapping logic.)
*/
messageTemplate?: string;
}
/**
* Extends `BaseErrorMapping` to include a factory function for creating
* specific error instances and additional context for the mapping.
* Used by `ErrorHandler.mapError`.
* @template T The type of `Error` this mapping will produce, defaults to `Error`.
*/
export interface ErrorMapping<T extends Error = Error> extends BaseErrorMapping {
/**
* A factory function that creates and returns an instance of the mapped error type `T`.
* @param error - The original error that occurred.
* @param context - Optional additional context provided in the mapping rule.
* @returns The newly created error instance.
*/
factory: (error: unknown, context?: Record<string, unknown>) => T;
/**
* Additional static context to be merged or passed to the `factory` function
* when this mapping rule is applied.
*/
additionalContext?: Record<string, unknown>;
}
/**
* A utility class providing static methods for comprehensive error handling.
*/
export declare class ErrorHandler {
/**
* Determines an appropriate `BaseErrorCode` for a given error.
* Checks `McpError` instances, `ERROR_TYPE_MAPPINGS`, and `COMMON_ERROR_PATTERNS`.
* Defaults to `BaseErrorCode.INTERNAL_ERROR`.
* @param error - The error instance or value to classify.
* @returns The determined error code.
*/
static determineErrorCode(error: unknown): BaseErrorCode;
/**
* Handles an error with consistent logging and optional transformation.
* Sanitizes input, determines error code, logs details, and can rethrow.
* @param error - The error instance or value that occurred.
* @param options - Configuration for handling the error.
* @returns The handled (and potentially transformed) error instance.
*/
static handleError(error: unknown, options: ErrorHandlerOptions): Error;
/**
* Maps an error to a specific error type `T` based on `ErrorMapping` rules.
* Returns original/default error if no mapping matches.
* @template T The target error type, extending `Error`.
* @param error - The error instance or value to map.
* @param mappings - An array of mapping rules to apply.
* @param defaultFactory - Optional factory for a default error if no mapping matches.
* @returns The mapped error of type `T`, or the original/defaulted error.
*/
static mapError<T extends Error>(error: unknown, mappings: ReadonlyArray<ErrorMapping<T>>, defaultFactory?: (error: unknown, context?: Record<string, unknown>) => T): T | Error;
/**
* Formats an error into a consistent object structure for API responses or structured logging.
* @param error - The error instance or value to format.
* @returns A structured representation of the error.
*/
static formatError(error: unknown): Record<string, unknown>;
/**
* Safely executes a function (sync or async) and handles errors using `ErrorHandler.handleError`.
* The error is always rethrown.
* @template T The expected return type of the function `fn`.
* @param fn - The function to execute.
* @param options - Error handling options (excluding `rethrow`).
* @returns A promise resolving with the result of `fn` if successful.
* @throws {McpError | Error} The error processed by `ErrorHandler.handleError`.
* @example
* ```typescript
* async function fetchData(userId: string, context: RequestContext) {
* return ErrorHandler.tryCatch(
* async () => {
* const response = await fetch(`/api/users/${userId}`);
* if (!response.ok) throw new Error(`Failed to fetch user: ${response.status}`);
* return response.json();
* },
* { operation: 'fetchUserData', context, input: { userId } }
* );
* }
* ```
*/
static tryCatch<T>(fn: () => Promise<T> | T, options: Omit<ErrorHandlerOptions, "rethrow">): Promise<T>;
}