tsmx/json-tools
GitHub: tsmx/json-tools
一个用于 JSON 数据分析、敏感信息混淆以及 LLM 友好格式转换的 Node.js 工具库。
Stars: 0 | Forks: 0
[](https://opensource.org/licenses/MIT)
[](https://img.shields.io/github/actions/workflow/status/tsmx/json-tools/git-build.yml?branch=master)
[](https://coveralls.io/github/tsmx/json-tools?branch=master)
# json-tools
🔍 用于 JSON 对象基础分析的[实用函数](#utility-functions)
- 检查复杂度
- 确定嵌套深度
- 分析类型统计
🔒 用于保护敏感数据的[混淆函数](#obfuscation-functions-obfuscate)
- 信用卡号（支持 Visa、Mastercard 和 Amex 号码）
- IP 地址
- 按键名匹配的值
- 数字
- 字符串
- 按 RegEx 匹配的值/键
⚡ 用于从 JSON 对象生成替代格式的[转换函数](#transformation-functions-transform)
- 数组
- Map
- 属性字符串
- Token 优化的 LLM 表示
有关完整的规范和示例，请参阅下方的 [API 参考](#api-reference)。
👉 实际用例：假设您在 AI 应用中使用以下 JSON 对象作为输入：
```
{
"accounts": [
{ "id": 1, "name": "Joe", "creditCard": "4111-1111-1111-1111" },
{ "id": 2, "name": "Sue", "creditCard": "5555-5555-5555-4444" }
],
"visits": [
{ "visitorId": 1, "timestamp": "2025-01-01T12:00:00Z", "ip": "192.168.1.1", "site": "index.html"},
{ "visitorId": 1, "timestamp": "2025-01-01T13:05:00Z", "ip": "192.168.1.2", "site": "shop.html"},
{ "visitorId": 2, "timestamp": "2025-01-01T14:00:00Z", "ip": "192.168.1.2", "site": "login.html"},
{ "visitorId": 2, "timestamp": "2025-01-01T14:10:00Z", "ip": "192.168.1.1", "site": "index.html"}
]
}
```
在将数据输入任何 LLM 之前，您需要...
- 混淆敏感数据：IP 地址、信用卡号
- 优化数据表示以节省 Token
为此，只需执行：
```
const jt = require('@tsmx/json-tools');
jt.obfuscate.ipAddresses(obj);
jt.obfuscate.creditCards(obj);
const result = jt.transform.toLLM(obj, true);
```
这将为您提供以下结果。
```
accounts[2](id,name,creditCard)
-1
Joe
***
-2
Sue
***
visits[4](visitorId,timestamp,ip,site)
-1
2025-01-01T12:00:00Z
***
index.html
-1
2025-01-01T13:05:00Z
***
shop.html
-2
2025-01-01T14:00:00Z
***
login.html
-2
2025-01-01T14:10:00Z
***
index.html
```
💰 对于此示例，根据用于 GPT-4o 的 [OpenAI Tokenizer](https://platform.openai.com/tokenizer)，Token 数量从 265 减少到 139，为您节省了 48% 的费用，同时还增加了不向 LLM 暴露敏感数据的安全性。
## API 参考
### 混淆函数 (`obfuscate`)
#### `obfuscate.strings(obj, replacement, retain, minreplace)`
通过用替换字符替换字符来混淆 JSON 对象中的所有字符串值，同时保留指定数量的最左侧字符。
**参数：**
- `obj` (Object)：要混淆的对象
- `replacement` (string, optional)：替换字符（默认值：`*`）
- `retain` (number, optional)：要保留的最左侧字符数（默认值：`3`）
- `minreplace` (number, optional)：使用的替换字符的最小数量（默认值：`3`）
**示例：**
```
const { obfuscate } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
lastName: 'Smith',
city: 'New York'
};
obfuscate.strings(input);
// Result: { firstName: 'Joh***', lastName: 'Smi***', city: 'New***' }
```
#### `obfuscate.numbers(obj, replacement)`
通过将 JSON 对象中的所有数字值替换为给定字符串来对其进行混淆。
**参数：**
- `obj` (Object)：要混淆的对象
- `replacement` (string, optional)：替换字符串（默认值：`***`）
**示例：**
```
const { obfuscate } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
age: 30,
salary: 50000
};
obfuscate.numbers(input);
// Result: { firstName: 'John', age: '***', salary: '***' }
```
#### `obfuscate.ipAddresses(obj, replacement)`
通过将 JSON 对象中的 IP 地址值（IPv4 和 IPv6）替换为给定字符串来对其进行混淆。
**参数：**
- `obj` (Object)：要混淆的对象
- `replacement` (string, optional)：替换字符串（默认值：`***`）
**示例：**
```
const { obfuscate } = require('@tsmx/json-tools');
const input = {
serverIp: '192.168.1.1',
clientIp: '10.0.0.5'
};
obfuscate.ipAddresses(input);
// Result: { serverIp: '***', clientIp: '***' }
```
#### `obfuscate.creditCards(obj, replacement)`
通过将 JSON 对象中的信用卡值替换为给定字符串来对其进行混淆。支持由破折号、点、空格分隔或不带分隔符的 Visa、MasterCard 和 Amex 卡号。
**参数：**
- `obj` (Object)：要混淆的对象
- `replacement` (string, optional)：替换字符串（默认值：`***`）
**示例：**
```
const { obfuscate } = require('@tsmx/json-tools');
const input = {
cardNumber: '4012-8888-8888-1881',
cardType: 'Visa'
};
obfuscate.creditCards(input);
// Result: { cardNumber: '***', cardType: 'Visa' }
```
#### `obfuscate.keyRegex(obj, pattern, replacement)`
混淆 JSON 对象中键匹配给定 RegEx 模式（不区分大小写）的所有值。
**参数：**
- `obj` (Object)：要混淆的对象
- `pattern` (string)：用于匹配键的 RegEx 模式
- `replacement` (string, optional)：替换字符串（默认值：`***`）
**示例：**
```
const { obfuscate } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
lastName: 'Smith',
email: 'john@example.com'
};
obfuscate.keyRegex(input, 'name');
// Result: { firstName: '***', lastName: '***', email: 'john@example.com' }
```
#### `obfuscate.valueRegex(obj, pattern, replacement)`
混淆 JSON 对象中值匹配给定 RegEx 模式（不区分大小写）的所有值。
**参数：**
- `obj` (Object)：要混淆的对象
- `pattern` (string)：用于匹配值的 RegEx 模式
- `replacement` (string, optional)：替换字符串（默认值：`***`）
**示例：**
```
const { obfuscate } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
city: 'New York',
country: 'United States'
};
obfuscate.valueRegex(input, 'ork');
// Result: { firstName: 'John', city: '***', country: 'United States' }
```
### 转换函数 (`transform`)
#### `transform.toMap(obj)`
将 JSON 对象转换为 JavaScript Map，其中包含所有根级对象属性作为条目，其属性名称作为键。
**参数：**
- `obj` (Object)：要转换的对象
**返回值：** Map - 包含所有根级属性的 Map
**示例：**
```
const { transform } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
lastName: 'Smith',
age: 30
};
const result = transform.toMap(input);
// Result: Map { 'firstName' => 'John', 'lastName' => 'Smith', 'age' => 30 }
```
#### `transform.toArray(obj)`
将 JSON 对象转换为包含所有根级属性的 {key, value} 对象的数组。
**参数：**
- `obj` (Object)：要转换的对象
**返回值：** Array - {key, value} 对象的数组
**示例：**
```
const { transform } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
lastName: 'Smith',
age: 30
};
const result = transform.toArray(input);
// Result:
// [
// { key: 'firstName', value: 'John' },
// { key: 'lastName', value: 'Smith' },
// { key: 'age', value: 30 }
// ]
```
#### `transform.toProperties(obj, expandArrays)`
将 JSON 对象转换为属性文件字符串。嵌套的子对象及其值被解析为具有完整点分隔路径的属性（例如，`country.name=USA`）。行尾为 `\r\n`。
**参数：**
- `obj` (Object)：要转换的对象
- `expandArrays` (boolean, optional)：如果为 true，则为每个数组元素创建一个带有从零开始的索引的条目（默认值：`false`）
**返回值：** String - 属性文件格式的字符串
**示例：**
```
const { transform } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
lastName: 'Smith',
country: {
name: 'USA',
code: 'US'
}
};
const result = transform.toProperties(input);
// Result:
// firstName=John
// lastName=Smith
// country.name=USA
// country.code=US
```
#### `transform.toPropertiesFlat(obj, expandArrays)`
将 JSON 对象转换为仅考虑根级别的属性文件字符串。嵌套的子对象和数组打印为字符串化的 JSON。
**参数：**
- `obj` (Object)：要转换的对象
- `expandArrays` (boolean, optional)：如果为 true，则为每个数组元素创建一个带有从零开始的索引的条目（默认值：`false`）
**返回值：** String - 扁平化的属性文件格式字符串
**示例：**
```
const { transform } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
lastName: 'Smith',
country: {
name: 'USA',
code: 'US'
}
};
const result = transform.toPropertiesFlat(input);
// Result:
// firstName=John
// lastName=Smith
// country={"name":"USA","code":"US"}
```
#### `transform.toLLM(obj, compactArrays)`
将 JSON 对象转换为 LLM 友好、节省 Token 的表示法，专为 AI 应用中的进一步处理而优化。
**参数：**
- `obj` (any)：要转换的对象
- `compactArrays` (boolean, optional)：如果为 true，包含完全相同对象（相同的键和顺序）的数组将被进一步压缩（默认值：`false`）
**返回值：** String - Token 优化的 LLM 表示法字符串
**示例 1 - 简单对象：**
```
const { transform } = require('@tsmx/json-tools');
const input = {
firstName: 'John',
lastName: 'Smith',
age: 30
};
const result = transform.toLLM(input);
// Result:
// firstName=John
// lastName=Smith
// age=30
```
**示例 2 - 具有不同对象（键顺序不同）的数组：**
```
const { transform } = require('@tsmx/json-tools');
const input = {
accounts: [
{ id: 1, name: 'Joe' },
{ name: 'Sue', id: 2 }
]
};
const result = transform.toLLM(input);
// Result:
// accounts[2]
// -id=1
// name=Joe
// -name=Sue
// id=2
```
**示例 3 - 具有相同对象（已压缩）的数组：**
```
const { transform } = require('@tsmx/json-tools');
const input = {
accounts: [
{ id: 1, name: 'Joe' },
{ id: 2, name: 'Sue' },
{ id: 3, name: 'Alice' }
]
};
const result = transform.toLLM(input, true);
// Result:
// accounts[3](id, name)
// -1
// Joe
// -2
// Sue
// -3
// Alice
```
### 实用函数
#### `getDepth(obj, includeArrays)`
获取 JSON 对象的嵌套级别（深度）。根级别被视为零。
**参数：**
- `obj` (Object)：要检查的对象
- `includeArrays` (boolean, optional)：计算深度时是否考虑数组内的对象（默认值：`true`）
**返回值：** Number - JSON 结构的从零开始的深度
**示例：**
```
const jt = require('@tsmx/json-tools');
const simple = { firstName: 'John', age: 30 };
const nested = { user: { firstName: 'John', address: { city: 'NYC' } } };
jt.getDepth(simple); // Result: 0
jt.getDepth(nested); // Result: 2
```
#### `isSimple(obj, includeArrays)`
检查 JSON 对象是否简单，即它没有嵌套对象（深度 == 0）。
**参数：**
- `obj` (Object)：要检查的对象
- `includeArrays` (boolean, optional)：是否考虑数组内的对象（默认值：`true`）
**返回值：** Boolean - 如果对象简单则为 True
**示例：**
```
const jt = require('@tsmx/json-tools');
const simple = { firstName: 'John', age: 30 };
const nested = { user: { firstName: 'John' } };
jt.isSimple(simple); // Result: true
jt.isSimple(nested); // Result: false
```
#### `isComplex(obj, includeArrays)`
检查 JSON 对象是否复杂，即它具有嵌套对象（深度 > 0）。
**参数：**
- `obj` (Object)：要检查的对象
- `includeArrays` (boolean, optional)：是否考虑数组内的对象（默认值：`true`）
**返回值：** Boolean - 如果对象复杂则为 True
**示例：**
```
const jt = require('@tsmx/json-tools');
const simple = { firstName: 'John', age: 30 };
const nested = { user: { firstName: 'John' } };
jt.isComplex(simple); // Result: false
jt.isComplex(nested); // Result: true
```
#### `typeStats(obj)`
分析对象的所有值，并返回 Map 中每种类型的出现次数。执行深度解析，包括子对象和数组元素。
**参数：**
- `obj` (Object)：要分析的对象
**返回值：** Map - 包含发现的每种类型的计数的 Map（例如，`{ 'string' => 5, 'number' => 2, 'object' => 1 }`）
**示例：**
```
const jt = require('@tsmx/json-tools');
const input = {
firstName: 'John',
lastName: 'Smith',
age: 30,
active: true,
country: { name: 'USA' }
};
const result = jt.typeStats(input);
// Result: Map {
// 'string' => 3,
// 'number' => 1,
// 'boolean' => 1,
// 'object' => 1
// }
```
标签：AI开发工具, DLL 劫持, DNS 反向解析, GNU通用公共许可证, IP地址隐藏, JavaScript工具库, JSON压缩, JSON处理, LLM, MITM代理, Node.js, npm包, StruQ, Token优化, TypeScript, Unmanaged PE, 信用卡掩码, 复杂度分析, 大语言模型, 安全插件, 提示词工程, 敏感信息保护, 数据可视化, 数据混淆, 数据脱敏, 数据转换, 正则表达式替换, 策略决策点, 结构化数据, 自定义脚本, 自定义脚本, 隐私合规