@jsonstudio/llms 0.4.2

package/dist/utils/error-utils.d.ts

@@ -0,0 +1,334 @@
+/**
+ * 错误处理工具函数
+ */
+/**
+ * LLMSwitch错误类型
+ */
+export declare enum LLMSwitchErrorType {
+    VALIDATION_ERROR = "validation_error",
+    INVALID_REQUEST_FORMAT = "invalid_request_format",
+    MISSING_REQUIRED_FIELD = "missing_required_field",
+    PROCESSING_ERROR = "processing_error",
+    HOOK_EXECUTION_ERROR = "hook_execution_error",
+    TRANSFORMATION_ERROR = "transformation_error",
+    NETWORK_ERROR = "network_error",
+    TIMEOUT_ERROR = "timeout_error",
+    CONNECTION_ERROR = "connection_error",
+    ENDPOINT_NOT_FOUND = "endpoint_not_found",
+    ENDPOINT_UNAVAILABLE = "endpoint_unavailable",
+    UNSUPPORTED_PROTOCOL = "unsupported_protocol",
+    MEMORY_ERROR = "memory_error",
+    CONFIGURATION_ERROR = "configuration_error",
+    INTERNAL_ERROR = "internal_error",
+    STREAM_ERROR = "stream_error",
+    SSE_ERROR = "sse_error"
+}
+/**
+ * 错误严重程度
+ */
+export declare enum ErrorSeverity {
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high",
+    CRITICAL = "critical"
+}
+/**
+ * 错误类型配置映射
+ */
+export declare const ERROR_TYPE_CONFIG: Map<LLMSwitchErrorType, {
+    severity: ErrorSeverity;
+    httpStatus: number;
+    isRetryable: boolean;
+    defaultMessage: string;
+}>;
+/**
+ * LLMSwitch自定义错误类
+ */
+export declare class LLMSwitchError extends Error {
+    readonly type: LLMSwitchErrorType;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly endpoint?: string;
+    readonly stage?: string;
+    readonly originalError?: Error;
+    readonly context?: Record<string, any>;
+    readonly timestamp: number;
+    readonly severity: ErrorSeverity;
+    readonly httpStatus: number;
+    readonly isRetryable: boolean;
+    constructor(type: LLMSwitchErrorType, message: string, options?: {
+        code?: string;
+        requestId?: string;
+        endpoint?: string;
+        stage?: string;
+        originalError?: Error;
+        context?: Record<string, any>;
+    });
+    /**
+     * 转换为JSON格式
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * 转换为标准HTTP错误响应格式
+     */
+    toErrorResponse(): {
+        success: false;
+        error: {
+            type: string;
+            code: string;
+            message: string;
+            severity: ErrorSeverity;
+            requestId?: string;
+            endpoint?: string;
+            stage?: string;
+            timestamp: number;
+            context?: Record<string, any>;
+        };
+    };
+    /**
+     * 转换为API错误响应格式（兼容旧版本）
+     */
+    toAPIResponse(): any;
+}
+/**
+ * 错误工厂类
+ */
+export declare class ErrorFactory {
+    /**
+     * 创建验证错误
+     */
+    static validationError(message: string, field?: string, context?: any): LLMSwitchError;
+    /**
+     * 创建请求格式错误
+     */
+    static invalidRequestFormat(message: string, context?: any): LLMSwitchError;
+    /**
+     * 创建缺失字段错误
+     */
+    static missingRequiredField(field: string, context?: any): LLMSwitchError;
+    /**
+     * 创建处理错误
+     */
+    static processingError(message: string, originalError?: Error, context?: any): LLMSwitchError;
+    /**
+     * 创建Hook执行错误
+     */
+    static hookExecutionError(stage: string, message: string, originalError?: Error, context?: any): LLMSwitchError;
+    /**
+     * 创建转换错误
+     */
+    static transformationError(message: string, fromProtocol?: string, toProtocol?: string, context?: any): LLMSwitchError;
+    /**
+     * 创建网络错误
+     */
+    static networkError(message: string, url?: string, statusCode?: number, context?: any): LLMSwitchError;
+    /**
+     * 创建超时错误
+     */
+    static timeoutError(operation: string, timeout: number, context?: any): LLMSwitchError;
+    /**
+     * 创建连接错误
+     */
+    static connectionError(message: string, endpoint?: string, context?: any): LLMSwitchError;
+    /**
+     * 创建端点未找到错误
+     */
+    static endpointNotFound(endpoint: string, context?: any): LLMSwitchError;
+    /**
+     * 创建端点不可用错误
+     */
+    static endpointUnavailable(endpoint: string, reason?: string, context?: any): LLMSwitchError;
+    /**
+     * 创建不支持的协议错误
+     */
+    static unsupportedProtocol(protocol: string, supportedProtocols?: string[], context?: any): LLMSwitchError;
+    /**
+     * 创建内存错误
+     */
+    static memoryError(message: string, usage?: NodeJS.MemoryUsage, context?: any): LLMSwitchError;
+    /**
+     * 创建配置错误
+     */
+    static configurationError(message: string, configPath?: string, context?: any): LLMSwitchError;
+    /**
+     * 创建内部错误
+     */
+    static internalError(message: string, originalError?: Error, context?: any): LLMSwitchError;
+    /**
+     * 创建流式错误
+     */
+    static streamError(message: string, context?: any): LLMSwitchError;
+    /**
+     * 创建SSE错误
+     */
+    static sseError(message: string, context?: any): LLMSwitchError;
+}
+/**
+ * 错误处理器
+ */
+export declare class ErrorHandler {
+    private static errorHandlers;
+    private static errorLog;
+    /**
+     * 注册错误处理器
+     */
+    static registerHandler(errorType: LLMSwitchErrorType, handler: (error: LLMSwitchError) => void): void;
+    /**
+     * 处理错误
+     */
+    static handle(error: Error | LLMSwitchError, context?: {
+        requestId?: string;
+        endpoint?: string;
+        stage?: string;
+    }): LLMSwitchError;
+    /**
+     * 记录错误
+     */
+    private static logError;
+    /**
+     * 获取错误日志
+     */
+    static getErrorLog(filter?: {
+        errorType?: LLMSwitchErrorType;
+        since?: number;
+        requestId?: string;
+        endpoint?: string;
+    }): Array<{
+        error: LLMSwitchError;
+        timestamp: number;
+    }>;
+    /**
+     * 获取错误统计
+     */
+    static getErrorStats(): {
+        total: number;
+        byType: Record<LLMSwitchErrorType, number>;
+        byEndpoint: Record<string, number>;
+        byStage: Record<string, number>;
+        recentErrors: Array<{
+            error: LLMSwitchError;
+            timestamp: number;
+        }>;
+    };
+    /**
+     * 清理错误日志
+     */
+    static clearErrorLog(): void;
+    /**
+     * 清理过期错误记录
+     */
+    static cleanup(maxAge?: number): void;
+}
+/**
+ * 错误恢复工具
+ */
+export declare class ErrorRecovery {
+    private static recoveryStrategies;
+    /**
+     * 注册恢复策略
+     */
+    static registerStrategy(errorType: LLMSwitchErrorType, strategy: RecoveryStrategy): void;
+    /**
+     * 尝试错误恢复
+     */
+    static attemptRecovery(error: LLMSwitchError, context?: any): Promise<RecoveryResult>;
+    /**
+     * 获取所有恢复策略
+     */
+    static getStrategies(): Map<LLMSwitchErrorType, RecoveryStrategy>;
+}
+/**
+ * 恢复策略接口
+ */
+export interface RecoveryStrategy {
+    recover(error: LLMSwitchError, context?: any): Promise<RecoveryResult>;
+    canRecover?(error: LLMSwitchError, context?: any): boolean;
+    maxAttempts?: number;
+}
+/**
+ * 恢复结果
+ */
+export interface RecoveryResult {
+    success: boolean;
+    action: string;
+    data?: any;
+    error?: Error;
+}
+/**
+ * 默认恢复策略
+ */
+export declare class DefaultRecoveryStrategies {
+    /**
+     * 网络错误恢复策略
+     */
+    static networkErrorStrategy: RecoveryStrategy;
+    /**
+     * 超时错误恢复策略
+     */
+    static timeoutErrorStrategy: RecoveryStrategy;
+    /**
+     * 内存错误恢复策略
+     */
+    static memoryErrorStrategy: RecoveryStrategy;
+    /**
+     * 注册所有默认策略
+     */
+    static registerAll(): void;
+}
+/**
+ * 全局错误响应助手类
+ */
+export declare class ErrorMapper {
+    /**
+     * 将错误转换为标准HTTP响应
+     */
+    static toHTTPResponse(error: Error | LLMSwitchError, requestId?: string): {
+        statusCode: number;
+        body: any;
+        headers: Record<string, string>;
+    };
+    /**
+     * 发送HTTP错误响应
+     */
+    static sendErrorResponse(res: any, error: Error | LLMSwitchError, requestId?: string): void;
+}
+/**
+ * 流式错误处理助手
+ */
+export declare class StreamErrorHandler {
+    /**
+     * 处理流式过程中的错误
+     */
+    static handleStreamError(error: Error, stream: any, context: {
+        requestId: string;
+        stage: string;
+    }): void;
+    /**
+     * 安全地包装流式操作
+     */
+    static wrapStreamOperation<T>(operation: () => Promise<T>, stream: any, context: {
+        requestId: string;
+        stage: string;
+    }): Promise<T>;
+}
+/**
+ * 安全JSON解析助手
+ */
+export declare class SafeJSONParser {
+    /**
+     * 安全解析JSON，失败时抛出结构化错误
+     */
+    static parse(jsonString: string, context: {
+        field?: string;
+        requestId?: string;
+        stage?: string;
+    }): any;
+    /**
+     * 安全字符串化JSON，失败时抛出结构化错误
+     */
+    static stringify(obj: any, context: {
+        field?: string;
+        requestId?: string;
+        stage?: string;
+    }): string;
+}