@hackylabs/deep-redact

中文文档
4.1.0发布于 2026/08/28MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 34.5万

从对象,阵列和任意字符串(如XML或原始 cookie 数据)中深度编辑敏感数据,并具有可相容,函数先的API.

中文使用文档
文档目录22 节
  1. 特征
  2. 基线
  3. 安装
  4. 快速启动
  5. 基准
  6. TLDR 头条
  7. 结构化产出( serialise: false (中文(简体) )
  8. 序列化产出( E) serialise: true (中文(简体) )
  9. 配置
  10. 顶级选项
  11. KeySelector
  12. PathEntry
  13. StringTest
  14. TransformersOption
  15. DiagnosticsOptions
  16. 公共 API
  17. 文档
  18. 工作实例
  19. 移徙指南
  20. 建筑和设计
  21. 平台和安全小组
  22. 脚本

深度编辑

npm version GitHub license

@hackylabs/deep-redact是用于Node.js和Deno的由规则驱动的编辑库. 它使你能够表达要编辑什么——一个关键名称,一个路径,一个正格克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 政策一经初始化就汇编,并在每项请求中重新使用,使之适合高通量生产用途.

图书馆 fast-redact 需要为可能出现敏感字段的每个地点提供明确的路径(a.b.password, (中文(简体) ), a.c.password,....。深重置反转这个:一个单曲 keys: ['password'] 规则目标 password 字段在任意深度。 它还增加了路径编号库无法提供的能力,如部分字符串编辑(瞄准较大值内的敏感模式)和重复结构的通配符路径选择器.

ko-fi

特征

  • 深度不可知关键规则 ——在任何巢穴深度编辑任意字段的名称;不需要路径计数
  • 精确和结构化路径瞄准 ——当需要精确度时,将编辑指向特定地点
  • Regex 属性匹配 ——通过正则表达式匹配字段名称
  • 子字符串目标 ——编辑一个在较大值内出现的敏感字符串,而不只是全值替换
  • 通关卡和排除路径选择器 几乎在任何深度处理重复结构(['addresses.*', { ignore: 'country' }])而不列出每个索引
  • 结构化和序列化产出 ——返回活对象图或保证-JSON安全字符串(serialise: true(中文(简体) )
  • 内置和自定义变压器 ——超越特定运行时间类型在序列化输出中的表现方式
  • 内设安保 ——通过内存耗竭来防止原型污染和DoS
  • 控制台适配器 - 可选 console.* 通过明确的适配器编辑

基线

安装

npm install @hackylabs/deep-redact
pnpm add @hackylabs/deep-redact
yarn add @hackylabs/deep-redact
bun add @hackylabs/deep-redact

德诺 ——将软件包添加到导入地图中(deno.json:

{
  "imports": {
    "@hackylabs/deep-redact": "npm:@hackylabs/[email protected]"
  }
}

快速启动

import { deepRedact } from '@hackylabs/deep-redact'

const redact = deepRedact({ keys: ['password', 'token'] })

redact({ user: { password: 'secret', safe: 'keep this' }, token: 'abc123', id: 1 })
// { user: { password: '[REDACTED]', safe: 'keep this' }, token: '[REDACTED]', id: 1 }

基准

由承诺的手工艺品产生 test/artefacts/benchmarks/speed/. Node.js 24 LTS, Apple M系列. 1万个暖热后稳定状态.

TLDR 头条

如果原始吞吐量是您的主要制约因素, 您可以接受详尽的路径计数, 使用 fast-redact 换句话说. 它是专为JSON-string最大输出速度而专门建造的,在那种狭义的场景中,它将超越任何规则驱动的库. 当您需要深度不可知的目标、通配符路径、下行编辑或内置的安全保障时使用深重写.

如果你选择快速重写, 注意权衡:

  • 没有深度不可知的关键规则 ——必须明确列举每一个敏感路径
  • 无双通卡( N)**路径选择器 - 你不能瞄准目标 records.**.email 不列出每个深度
  • 没有子字符串目标 ——仅全值替换;不支持部分字符串编辑
  • 没有序列安全变压器管道 - 没有内置处理 BigInt, (中文(简体) ), Date, (中文(简体) ), Map, (中文(简体) ), Set, (中文(简体) ), Error, (中文(简体) ), RegExp,或 URL 数值
  • 没有污染保护原型 - 没有防守 __proto__ 财务报告和审定财务报表 constructor.prototype 注射
  • 没有可配置的深度或节点限制 ——没有通过深巢或过大的有效载荷进行防护

结构化产出(serialise: false(中文(简体) )

v4, v3, 并快速编辑全部返回一个平版 JavaScript 对象 .

Speed comparison — structured output

QQ快取是第三方图书馆,而不是深取的版本. 其被显示为吞吐量参考;其特征设置和保证与深红相异,因此它不是一种相类似比较.

v4 为 ~ 17× 更快 ~ 与基于路径的工作量和 ~ 10× 更快 ~ 关于通配符工作量.

序列化产出( E)serialise: true(中文(简体) )

所有四个解决方案都返回一个JSON字符串.

Speed comparison — serialised output

• 快速编辑是第三方图书馆;json-stringify-regex是一种天真的本土方法(JSON.stringify(value).replace(pattern, replacement)),不是图书馆. 既未进行深红字的结构编辑,也未提供其保证,因此两者都显示为吞吐量参考,而非类似比较.

v4在序列化模式下保持快于v3. 快速重写和json-stringify-regex具有吞吐量优势,因为它们的输出路径完全面向字符串生产.

相对于深红活性v2,序列相加不一:v4在基于路径的工作量上大致平分,而宽重(wildcard)的工作量则较慢. 这笔差额是安全v2的费用没有提供——根据 serialise: true,v4 运行生成 BigInt, (中文(简体) ), Date, (中文(简体) ), Map, (中文(简体) ), Set, (中文(简体) ), Error, (中文(简体) ), RegExp,以及 URL 它检测和校正了循环引用 而不是扔在它们身上 (通过 maxNodes编号 :maxDepth (b) 支票是反递增的,增加了可忽略不计的费用。 设定 onBudgetExceeded: 'truncate' 无法用 a 关闭 [TRUNCATED] 标记而不是投掷。 )

这些安全通行证是内在的 serialise: true 无法单独关闭。 如果您不需要这些保证, 想要匹配 v2 的吞吐量( 或者更好), 设置 serialise: false 自己开 JSON.stringify:结构化输出路径跳过变压器,圆通引用完全通过. 这会恢复V2的取舍 JSON.stringify 将弹出 BigInt 和通告参考, Map编号 :Set 序列为 {},以及 undefined 被删除.

全速和资源基准结果: docs/benchmarks/speed-results.md 财务报告和审定财务报表 docs/benchmarks/resource-results.md。 。 。 .

配置

deepRedact(options) 接受单个选项对象。 所有选项都是可选的.

顶级选项

选项类型默认需求说明
keysKeySelector[][]没有编辑任何匹配所列密钥的字段, 任何深度
pathsPathEntry[][]没有编辑特定路径的字段; 支持精确的字符串、结构化路径、通配符和排除选择器
stringTestsStringTest[][]没有调整字符串值内的匹配模式
censorstring | function'[REDACTED]'没有替换值或函数 (value, context) => replacement
serialiseboolean | functionfalse没有true 返回 JSON 安全字符串; 函数接收安全图表并可能返回任意字符串
removebooleanfalse没有从输出中删除匹配的密钥, 而不是替换其值
retainStructurebooleanfalse没有当父母相匹配时, 保留子孙节点可以用于低优先级规则
replaceStringByLengthbooleanfalse没有重复 censor 匹配已编辑值的字符长度的字符串
typesValueTypeName[]['string']没有typeof 符合编辑条件的类别; 其数值类型未列出的匹配密钥未受影响
fuzzyKeyMatchbooleanfalse没有当配置的密钥是字段名的子字符串时匹配(例如. 'pass' 匹配 'password'(中文(简体) )
caseSensitiveKeyMatchbooleantrue没有何时 false,在比较前将密钥名称(分解非单词字符,小写)正常化
maxDepthnumber500没有停止穿越这个筑巢深度; 警戒深筑巢载荷
maxNodesnumber50000没有在这么多节点后停止穿行; 防范过大的有效载荷 DoS
onBudgetExceeded'throw' | 'truncate''throw'没有在一个 maxDepth编号 :maxNodes 突破, 'throw' 引起内部预算错误; 'truncate' 将违法节点替换为 [TRUNCATED] 停止, 关闭
transformersTransformersOption内置默认值没有覆盖运行时间类型在序列化输出中的体现
diagnosticsDiagnosticsOptions—— 说没有结构化降解/预算事件 Opt-in sink; 默认沉默( 无控制台输出) 。 过 getNodeConsoleDiagnosticSink() 作为 sink 登录到控制台

ValueTypeName 这是: 'string', (中文(简体) ), 'number', (中文(简体) ), 'bigint', (中文(简体) ), 'boolean', (中文(简体) ), 'object', (中文(简体) ), 'function', (中文(简体) ), 'symbol', (中文(简体) ), 'undefined'。 。 。 .

KeySelector

每个条目 keys 可能是一个平地 string页:1 RegExp,或一个 KeyRule 每个密钥覆盖的对象.

keys 横穿平原对象、阵列、类例本身的可假设字段,以及 Map编号 :Set 目录. Map 条目密钥在结构输出中保留原始密钥对象的同时,与其成型的字符串形式相匹配; Set 成员按插入顺序穿行,但其数字位置是路径段而不是合成键.

外地类型默认需求说明
keystring | RegExp—— 说对要匹配的密钥
censorstring | function顶级 censor没有只覆盖此密钥的审查者
removeboolean顶级 remove没有仅为此密钥覆盖删除
retainStructureboolean顶级 retainStructure没有仅保留此密钥的构造
replaceStringByLengthboolean顶级 replaceStringByLength没有仅为此密钥取代 StringByLength
fuzzyKeyMatchboolean顶级 fuzzyKeyMatch没有仅覆盖此密钥的模糊密钥
caseSensitiveKeyMatchboolean顶级 caseSensitiveKeyMatch没有仅覆盖此密钥的敏感KeyMatch

PathEntry

每个条目 paths 可能是平面点注释字符串(如:. 'user.profile.ssn'),结构化路径数组,或 PathRule 用于 per-path 覆盖的对象.

结构化路径数组可能包含:

片段类型示例匹配
string 或者说 number'password'精确键或索引
RegExp/^pass/i匹配正则x 的密钥
{ any: true }—— 说任何单一的密钥( E)*(中文(简体) )
{ anyDepth: true }—— 说任意深度的零键或多键( N)**(中文(简体) )
{ ignore: string | number | RegExp }{ ignore: 'country' }从周边通配符中排除密钥
外地类型默认需求说明
pathstring | PathSegments[]—— 说对匹配的路径
censorstring | function顶级 censor没有仅覆盖此路径的审查者
removeboolean顶级 remove没有仅为此路径覆盖删除
retainStructureboolean顶级 retainStructure没有覆盖仅保留此路径的构造
replaceStringByLengthboolean顶级 replaceStringByLength没有仅为此路径取代 StringByLength

StringTest

每个条目 stringTests 也许是赤裸的 RegExp (全值替换为 censor或一个 SubstringRule 用于部分替换.

外地类型需求说明
patternRegExp对对照字符串值测试正则表达式
replacer(value: string, pattern: RegExp) => string对返回已编辑的字符串;仅在 pattern 匹配

TransformersOption

变形器控制非 JSON 运行时类型在何时被显示 serialise: true。每个变压器是一个函数 (value: unknown) => unknown ,或者返回已变换的值,或者返回未变换的值以传递给链条中的下一个变压器.

外地类型说明
byType.bigintTransformer[]适用于 BigInt 值( 不查阅) byType.object(中文(简体) )
byType.objectTransformer[]首先适用于内置构造器类型和未知对象类型
byConstructor.DateTransformer[]适用于 Date 实例
byConstructor.ErrorTransformer[]适用于 Error 实例
byConstructor.MapTransformer[]适用于 Map 实例
byConstructor.RegExpTransformer[]适用于 RegExp 实例
byConstructor.SetTransformer[]适用于 Set 实例
byConstructor.URLTransformer[]适用于 URL 实例
byConstructor.customCustomConstructorTransformerRegistration[]自定义类型匹配 instanceof 按声明顺序排列
fallbackTransformer[]当没有较早的变压器返回已更改的值时应用

内置变压器会产生决定性的标记对象(例如. { _transformer: 'date', datetime: '<ISO string>' }) (中文(简体) ). 见 docs/architecture/serialise-output.md 用于完整的调度命令和标记形状.

执行阶段. 用户 byConstructor.custom 财务报告和审定财务报表 byConstructor.Error 变压器运行 在正常转弯之前,在两种序列模式中:匹配的类实例转换为您返回的平面对象,然后由您擦除 keys编号 :paths 规则。 这就是PII在类中嵌入的方式——例如: Error编号 :AxiosError 携带 config.data 有效载荷——在没有预先正常步骤的情况下进行编辑(见 在错误实例中编辑 PII) (中文(简体) ). 其它水桶(byType, (中文(简体) ), fallback用户 byConstructor.{Date,Map,RegExp,Set,URL})仅在 serialise: true pass; 依赖这种仅序列化的行为——即变压器输出能从编辑中逃脱的行为——是 已贬值 支持上面的一等桶.

DiagnosticsOptions

外地类型说明
sink(event: DiagnosticEvent) => void当一个值退化为 '[UNSUPPORTED]' 序列化期间

公共 API

import { createRedactor, deepRedact } from '@hackylabs/deep-redact'

// deepRedact and createRedactor are the same factory under different names
const redact = deepRedact({ keys: ['secret'] })
const same = createRedactor({ keys: ['secret'] })

文档

工作实例

移徙指南

建筑和设计

平台和安全小组

  • 标准化指南 支助能力,针对语义、核查证据和通过决定的范围

脚本

  • pnpm run build
  • pnpm run lint
  • pnpm run test
  • pnpm run generate-exports
  • pnpm run generate-readme
  • pnpm run verify-generated-files
  • pnpm run bench
  • pnpm run bench:generate-charts

版本与发布记录

@hackylabs/deep-redact 共发布 19 个版本,首次发布于 2024/07/27;过去 12 个月发布了 6 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
4.1.0latest2026/08/282 个月前
4.0.22026/07/014 个月前
4.0.12026/06/204 个月前
2.2.2legacy-v22026/06/135 个月前
4.0.02026/06/075 个月前
3.0.5legacy-v32026/03/088 个月前

关于 @hackylabs/deep-redact 的常见问题

@hackylabs/deep-redact 是什么?

从对象,阵列和任意字符串(如XML或原始 cookie 数据)中深度编辑敏感数据,并具有可相容,函数先的API.

如何安装 @hackylabs/deep-redact?

在项目目录运行 npm install @hackylabs/deep-redact,或使用 pnpm add / yarn add / bun add。

@hackylabs/deep-redact 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hackylabs/deep-redact 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@hackylabs/deep-redact 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.18.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@hackylabs/deep-redact 可以商用吗?

@hackylabs/deep-redact 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hackylabs/deep-redact 的下载量有多少?

根据 npm 官方下载统计,@hackylabs/deep-redact 在 2026/10/17 – 2026/11/15 这 30 天内被下载 344,875 次,日均约 11,496 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hackylabs/deep-redact 还在维护吗?

最新版本 4.1.0 发布于 2026/08/28(2 个月前);至今共发布 19 个版本,其中过去 12 个月发布了 6 个;首次发布于 2024/07/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。