@tracer-kit/domain

npm install @tracer-kit/domain

模块角色

Tracer Domain 是业务调用与基础设施之间的领域编排层。业务只调用 log()；Domain 捕获时间和顺序、合并公共上下文、规范化任意值、加密并串行写入 Core Storage。

flowchart LR
  Business[业务代码] -->|log message, data| Domain[Tracer Domain]
  Domain --> Context[静态和动态公参]
  Domain --> Normalize[值规范化]
  Context --> Normalize
  Normalize --> Codec[Encryption Codec]
  Codec --> Storage[Core Storage]
  Storage --> IndexedDB[(IndexedDB 密文)]

公共导出

• createTracerDomain(config)：创建 Tracer Domain 实例。
• normalizeValue(value, options?)：把任意 JavaScript 值转换为可序列化、安全遍历且字符串有界的值。
• TracerPayloadLimitError：明文载荷超过预算时交给 reportError 的稳定错误类型，code 为 PAYLOAD_TOO_LARGE。
• 类型：TracerDomain、TracerDomainConfig、LogPayload、CommonConfig。

import { createTracerDomain } from '@tracer-kit/domain';

const tracer = createTracerDomain({ storage, encoder, common });

// ready 表示底层存储已初始化；初始化期间调用 log 也会进入有界队列。
await tracer.ready;

// log 为同步、永不抛错的业务接口；实际规范化、加密和写入在队列中执行。
tracer.log('操作完成', { resourceId: 123n });

// 应用销毁时停止新写入并关闭底层存储。
tracer.destroy();

内部实现

创建实例后立即初始化存储。初始化期间的业务日志进入有界等待队列；初始化成功后先写入启动记录，再按调用顺序排空队列。之后所有编码和写入通过 Promise 链串行执行，确保日志顺序稳定。

buildPayload 合并静态 common 快照和动态 commonGetters。动态 getter 在每次 log() 调用时立即求值，即使日志正在等待初始化或前序写入，也能保留该次调用对应的路由等上下文。每个 getter 单独隔离错误，随后通过 normalizeValue 处理 BigInt、Error、Date、循环引用、Proxy/getter 异常以及深度和条目上限。

单个字符串默认最多保留 64 KiB 字符，单条日志全部字符串默认最多保留 256 KiB 字符；截断位置追加 [Truncated]。规范化后的完整 JSON 在加密前按 UTF-8 计量，默认上限 1 MiB。超限日志被丢弃并通过 reportError 上报，不进入 Encoder，也不从 log() 抛出。三个上限可通过 maxStringLength、maxTotalStringLength、maxPayloadBytes 覆盖。

Domain 在加密前生成记录 ID，并把 ID 与发生时间作为 v2 信封的 AES-GCM AAD。加密后只把记录 ID、发生时间和密文交给 Core Storage。字节计量、容量拒绝和淘汰完全由存储层负责；Domain 只消费结构化写入结果并上报拒绝或失败。

sequenceDiagram
  participant B as 业务方
  participant D as Domain
  participant S as Core Storage
  participant E as Encoder
  B->>D: createTracerDomain
  D->>S: initialize
  B->>D: log A
  B->>D: log B
  Note over D: 初始化期间进入有界等待队列
  S-->>D: ready
  D->>E: 启动记录 -> 加密
  D->>S: 写入启动记录
  D->>E: A -> 规范化并加密
  D->>S: 写入 A
  D->>E: B -> 规范化并加密
  D->>S: 写入 B

失败与生命周期

• 配置缺少 storage/encoder 或队列上限非法时同步抛出。
• ready 在存储初始化失败时拒绝。
• log() 永远不把内部错误抛给业务调用方；错误交给 reportError。
• destroy() 幂等，清空等待队列、阻止新写入并关闭存储。

测试与维护

• test/domain.test.ts：初始化顺序、串行写入、错误隔离、队列和销毁。
• test/normalize.test.ts：特殊值、循环、危险对象和资源上限。

修改 log() 可观察行为、队列、payload 或错误边界时，必须同步本 README、相关测试以及 docs/modules/tracer-domain.md。