[!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({
    message: '解析二进制数据失败',
    code: 'error-parse-data',
    at: 'Biffer.unpack',
    data: { offset: 0x10, expected: '4s' },
    pruner: (data) => `{${data.expected}} at ${data.offset}`
    cause: new Error('Buffer 长度不足'),
    internal: false,
  });
}
catch (error) {
  console.error(error.message);        // '解析二进制数据失败'
  console.error(error.code);           // 'error-parse-data'
  console.error(error.at);             // 'Biffer.unpack'
  console.error(error.data);           // { offset: 0x10, expected: '4s' }
  console.error(error.datasPruned);    // undefined
  console.error(error.pruner);         // Function
  console.error(error.cause);          // Error: Buffer 长度不足
  console.error(error.stack);          // 堆栈已自动清理 RichError 构造器行
  console.error(error.root);           // 返回错误链最底层的原始错误

  await error.prune();
  console.error(error.datasPruned);    // '{4s} at 16'
}

// --- 类型标识 (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 | 增强的错误类，支持附加元数据与错误链管理。 | | vof | function | 返回值的类型标识字符串，便于调试与日志记录。 |

RichError 选项

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

| 属性 | 类型 | 说明 | | :------------ | :--------- | :-------------------------------------------------- | | code | string | 错误码，用于分类或程序识别。推荐slug风格。 | | at | string | 标识错误发生的大概位置或方法名。 | | data | any | 任意上下文数据，用于调试。 | | datasPruned | string[] | 修剪过的上下文数据。 | | pruner | Function | 修剪器。在有需要时修剪上下文数据，防止内存过大。 | | 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(options?)

创建一个新的 RichError 实例。

• 参数:
  • options {RichError} 可选 - 配置选项（见上表）。

const err = new RichError({
  code: 'timeout',
  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 | 传入的上下文数据。 | | datasPruned | string[] \| undefined | 修剪过的上下文数据文本。 | | pruner | Function \| undefined | 上下文数据修剪器。 | | internal | boolean \| undefined | 是否为内部错误标记。 | | cause | Error \| undefined | 原始错误（通过 options.cause 设置）。 |

实例方法

| 方法 | 描述 | | :------ | :-------------------------------------------------------------- | | prune | 异步调用.pruner()（如果存在），并将结果保存到.datasPruned。 |

.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的堆栈清理

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

2. RichError支持继承

RichError 能够配合 class extends 语法进行子类化。

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

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. RichError的上下文数据修剪

多数情况下，datas是推荐保存最完整的数据以便调试。但实际应用，datas可能存在数据体积太大，或顶层代码需要渲染数据为文本等情况。 因此引入datasPruned/pruner/prune的属性。
pruner与prune可以让使用者自行控制修剪时机。而将datasPruned定义为数组，有利用顶层代码组织文本。

4. vof 的特殊处理

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