All files / src/lib error-utils.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
/**
 * 错误处理工具函数
 * 提供统一的错误消息提取和静默错误处理
 */
 
/**
 * 从未知错误中提取错误消息
 * @param err - 捕获的错误
 * @returns 格式化的错误消息字符串
 */
export function getErrorMessage(err: unknown): string {
  if (err instanceof Error) return err.message;
  if (typeof err === 'string') return err;
  if (err && typeof err === 'object' && 'message' in err) {
    return String((err as { message: unknown }).message);
  }
  return 'Unknown error';
}
 
/**
 * 类型守卫：检查是否为 Error 实例
 */
export function isError(err: unknown): err is Error {
  return err instanceof Error;
}
 
/**
 * 获取错误的堆栈跟踪（仅开发环境）
 */
export function getErrorStack(err: unknown): string | undefined {
  if (import.meta.env.DEV && err instanceof Error) {
    return err.stack;
  }
  return undefined;
}
 
/**
 * 创建静默错误处理器
 * 用于 UI 事件处理器中预期的、不需要用户通知的错误
 * 在开发环境中会记录警告，生产环境中静默处理
 *
 * @param context - 上下文名称，用于日志标识
 * @returns 错误处理函数
 *
 * @example
 * // 在事件处理器中使用
 * onClick={() => { handleSubmit().catch(silentErrorHandler('FeedbackModal')); }}
 */
export function silentErrorHandler(context: string): (err: unknown) => void {
  return (err: unknown) => {
    if (import.meta.env.DEV) {
      console.warn(`[${context}] Operation failed silently:`, getErrorMessage(err));
    }
  };
}
 
/**
 * 安全执行异步操作，捕获错误并可选地记录
 * 用于不阻塞主流程的副作用操作
 *
 * @param context - 上下文名称
 * @param fn - 要执行的异步函数
 * @param options - 配置选项
 *
 * @example
 * // 安全执行连接操作
 * safeAsync('App', () => connect());
 */
export async function safeAsync<T>(
  context: string,
  fn: () => Promise<T>,
  options: { logInDev?: boolean } = { logInDev: true }
): Promise<T | undefined> {
  try {
    return await fn();
  } catch (err: unknown) {
    if (options.logInDev !== false && import.meta.env.DEV) {
      console.warn(`[${context}] Async operation failed:`, getErrorMessage(err));
    }
    return undefined;
  }
}