[!TIP] 本文档由 AI 阅读代码后生成。中文版本已经过本人初步审校。英文版本基于中文版本由 AI 翻译生成。如有问题或更好的文档，欢迎提交 Issue。
This document is generated by AI after reading the code. The Chinese version has been preliminarily reviewed by the author. The English version is AI-translated based on the Chinese version. If you have any issues or a better version of the documentation, please feel free to submit an Issue.

简体中文 | English

@danor-lib/error

一个轻量级的错误增强与类型标识工具，适用于 Node.js 与浏览器环境。
A lightweight error enhancement and type identification utility, suitable for both Node.js and browser environments.

RichError 扩展了原生 Error 对象，支持附加错误码、上下文数据、发生位置、内部标记以及错误链，同时提供更干净的堆栈追踪。
vof 是一个小巧的辅助函数，用于生成可读性更高的值类型描述字符串。

基础示例

import { RichError, vof } from '@danor-lib/error';

// --- 创建增强错误 ---
try {
  throw new RichError('解析二进制数据失败', {
    code: 'error-parse-data',
    at: 'Biffer.unpack',
    data: { offset: 0x10, expected: '4s' },
    cause: new Error('Buffer 长度不足'),
    internal: false
  });
} catch (err) {
  console.error(err.message);        // '解析二进制数据失败'
  console.error(err.code);           // 'error-parse-data'
  console.error(err.at);             // 'Biffer.unpack'
  console.error(err.data);           // { offset: 0x10, expected: '4s' }
  console.error(err.cause);          // Error: Buffer 长度不足
  console.error(err.stack);          // 堆栈已自动清理 RichError 构造器行
  console.error(err.root);           // 返回错误链最底层的原始错误
}

// --- 类型标识 (vof) ---
console.log(vof(null));              // '<is:null>'
console.log(vof([1, 2, 3]));         // '1,2,3 <is:Array(3)>'
console.log(vof(NaN));               // '<is:NaN>'
console.log(vof(() => {}));          // 'function (anonymous) <is:function>'
console.log(vof(''));                // '<is:empty-string>'

核心概念

@danor-lib/error 提供两个核心导出：

| 导出 | 类型 | 说明 | | :---------- | :------------------- | :------------------------------------------- | | RichError | class / function | 增强的错误类，支持附加元数据与错误链管理。 | | vof | function | 返回值的类型标识字符串，便于调试与日志记录。 |

RichError 选项

创建 RichError 时，可以传入第二个参数 options 对象来附加额外信息：

| 属性 | 类型 | 说明 | | :--------- | :-------- | :-------------------------------------------------- | | code | string | 错误码，用于分类或程序识别。推荐slug风格 | | at | string | 标识错误发生的大概位置或方法名。 | | data | any | 任意上下文数据，用于调试。 | | internal | boolean | 是否为内部错误，用于区分暴露给用户的信息。 | | cause | Error | 引发当前错误的原始错误（符合 Error.cause 规范）。 |

静态方法

vof(value)

返回一个描述值类型与内容的字符串，对于调试和日志记录非常有用。

• 参数:
  • value {unknown} - 需要标识的任意值。
• 返回值: {string} - 类型描述字符串。

import { vof } from '@danor-lib/error';

console.log(vof(undefined));              // '<is:undefined>'
console.log(vof(null));                   // '<is:null>'
console.log(vof(''));                     // '<is:empty-string>'
console.log(vof('hello'));                // 'hello <is:string(5)>'
console.log(vof(42));                     // '42 <is:number>'
console.log(vof(-0));                     // '-0 <is:number>'
console.log(vof(NaN));                    // '<is:NaN>'
console.log(vof(Infinity));               // '<is:Infinity>'
console.log(vof({ a: 1 }));               // '{"a":1} <is:object>'
console.log(vof([1, 2]));                 // '1,2 <is:Array(2)>'
console.log(vof(() => {}));               // 'function (anonymous) <is:function>'
console.log(vof(function test() {}));     // 'function test <is:function>'

RichError 构造函数与实例属性

new RichError(message?, options?)

创建一个新的 RichError 实例。支持直接 new 调用或作为普通函数调用（如 RichError(...)），内部自动处理原型链，确保 instanceof 行为正确。

• 参数:
  • message {string} 可选 - 人类可读的错误描述。
  • options {Object} 可选 - 配置选项（见上表）。

const err = new RichError('操作超时', {
  code: 'ETIMEOUT',
  at: 'fetchData',
  data: { url: '/api/data' }
});

实例属性

| 属性 | 类型 | 描述 | | :--------- | :------------------------------ | :------------------------------------------------------- | | name | string | 错误名称，固定为 'RichError'（若被继承则为子类名称）。 | | message | string | 错误描述信息。 | | stack | string \| undefined | 堆栈追踪字符串（自动移除了 RichError 自身构造器行）。 | | code | number \| string \| undefined | 传入的错误码。 | | at | string \| undefined | 传入的发生位置标识。 | | data | any \| undefined | 传入的上下文数据。 | | internal | boolean \| undefined | 是否为内部错误标记。 | | cause | Error \| undefined | 原始错误（通过 options.cause 设置）。 |

root (getter)

获取错误链最底层的原始错误。沿着 cause 属性递归查找，直到找到一个没有 cause 或 cause 不是 Error 实例的错误对象。

• 返回值: {Error} - 错误链的根错误。

const rootCause = new Error('原始问题');
const midError = new RichError('中间层错误', { cause: rootCause });
const topError = new RichError('顶层错误', { cause: midError });

console.log(topError.root === rootCause); // true

高级特性说明

1. 堆栈清理

RichError 在构造时会自动从堆栈字符串中移除自身的构造器行，使得堆栈输出更加清晰，直接指向业务调用代码。

2. 支持继承

RichError 可以作为一个普通函数使用，并且能够配合 class extends 语法进行子类化。内部会正确处理原型链与堆栈中的名称替换。

class MyCustomError extends RichError {
  constructor(message, options) {
    super(message, options);
    // 自定义初始化
  }
}

const err = new MyCustomError('自定义错误', { code: 1001 });
console.log(err.name); // 'MyCustomError'
console.log(err instanceof MyCustomError); // true
console.log(err instanceof RichError);     // true
console.log(err instanceof Error);         // true

3. vof 的特殊处理

• 空字符串 ('') 被标识为 <is:empty-string>，便于区分空字符串与未定义值。
• NaN、Infinity、-Infinity 和 -0 都有特定的标识输出，避免被误认为是普通数字。
• 对于无法被 JSON.stringify 序列化的对象（如包含循环引用），vof 会返回 <bad-stringify object>，防止抛出异常。