用于复杂对象搜索的TypeScript工具库,支持:
- 多层级嵌套对象
- 数组自动展开
- 自定义匹配逻辑
- 安全深度控制
npm i x-arraysearch@latest
# 或
yarn add x-arraysearch
- 点标记法:
'user.address.city'
- 自动数组展开:
'orders[].product'
- 混合路径:
'departments[].employees[].name'
匹配器 | 描述 | 示例 |
---|---|---|
defaultMatcher |
不区分大小写包含匹配 | 'apple' → 'Apple Pie' |
exactMatcher |
严格类型相等匹配 | 100 不匹配 '100' |
createRegExpMatcher() |
正则表达式匹配 | '^d+' 匹配 '123abc' |
- 短路匹配:发现匹配后立即停止搜索
- 深度控制:默认最大递归深度10层
- 路径缓存:优化重复路径的查询性能
- 并行处理:自动处理大数据集
- 类型安全:完整的 TypeScript 类型支持
- 循环检测:自动处理循环引用
- 错误处理:优雅处理无效输入
- 深度限制:防止栈溢出
function searchData<T extends Record<string, any>>(
data: T[],
term: unknown,
options?: SearchOptions
): T[] | Promise<T[]>
参数
-
data
: 对象数组 -
term
: 搜索关键词 -
options
: 配置选项-
keys
: 搜索路径数组 -
customMatch
: 自定义匹配函数 -
maxDepth
: 最大递归深度(默认10) -
enablePathCache
: 是否启用路径缓存(默认true) -
parallel
: 是否并行处理大数据集(默认false)
-
默认的包含匹配函数,不区分大小写
严格类型检查的精确匹配
创建正则表达式匹配器工厂函数
import { searchData, createRegExpMatcher } from 'x-arraysearch';
const products = [
{
id: 1,
name: 'iPhone 13',
details: {
tags: ['手机', '苹果'],
specs: {
storage: '128GB',
color: '暗夜绿'
}
}
}
];
// 简单搜索
const results = await searchData(products, 'iPhone');
// 高级搜索
const filtered = await searchData(products, '^128', {
keys: ['details.specs.storage'],
customMatch: createRegExpMatcher('i')
});
默认情况下,searchData
会在整个对象树中搜索匹配项,不区分大小写:
// 搜索包含 "iphone" 的数据(不区分大小写)
const results = await searchData(products, 'iphone');
通过指定 keys
选项限制搜索范围:
// 只在产品名称中搜索
const results = await searchData(products, '苹果', {
keys: ['name']
});
设置 maxDepth
以限制递归深度,防止过深的对象导致性能问题:
// 限制搜索深度为3层
const results = await searchData(complexData, 'target', {
maxDepth: 3
});
可以使用点表示法精确定位嵌套属性:
// 搜索特定嵌套属性
const results = await searchData(products, '手机', {
keys: ['category.sub']
});
同时在多个路径中进行搜索:
// 同时搜索颜色和标签
const results = await searchData(products, '白色', {
keys: ['specs.color', 'tags']
});
自动展开和搜索数组内的元素:
// 搜索产品功能列表
const results = await searchData(products, 'Face ID', {
keys: ['specs.features']
});
不区分大小写的部分匹配,适用于大多数场景:
// 默认使用 defaultMatcher
const results = await searchData(products, 'pro');
// defaultMatcher 的行为:
// - 'Hello World' 匹配 'world'
// - 123 匹配 '23'
// - true 匹配 'true'
使用严格相等比较,特别适合比较数值和布尔值:
import { searchData, exactMatcher } from 'x-arraysearch';
// 只匹配库存数量恰好为 100 的产品
const results = await searchData(products, 100, {
keys: ['stock.count'],
customMatch: exactMatcher
});
// exactMatcher 的行为:
// - 123 只匹配 123 (不匹配 '123')
// - true 只匹配 true (不匹配 'true')
支持使用正则表达式进行复杂模式匹配:
import { searchData, createRegExpMatcher } from 'x-arraysearch';
// 使用正则表达式匹配所有以数字开头的型号
const regexMatcher = createRegExpMatcher('i'); // 'i' 表示不区分大小写
const results = await searchData(products, '^\\d+', {
keys: ['model'],
customMatch: regexMatcher
});
对于重复查询,启用路径缓存可显著提高性能:
// 创建共享搜索配置
const searchOptions = {
keys: ['category.sub', 'specs.features'],
enablePathCache: true // 默认就是 true
};
// 首次查询会缓存解析后的路径
const phoneResults = await searchData(products, '手机', searchOptions);
// 后续查询复用缓存,提高性能
const iosResults = await searchData(products, 'iOS', searchOptions);
处理大量数据时,启用并行处理能加快搜索速度:
// 处理超过1000条的数据集
const results = await searchData(largeData, 'target', {
keys: ['importantField', 'nested.targetField'],
parallel: true // 自动分片并行处理
});
创建自定义匹配函数来实现特定的比较逻辑:
const customMatcher = (value: unknown, term: unknown) => {
if (typeof value === 'number') {
return value > (term as number);
}
return defaultMatcher(value, term);
};
// 查找价格高于5000的所有产品
const results = await searchData(products, 5000, {
keys: ['price'],
customMatch: customMatcher
});
正确处理空数组:
// 返回空数组,不会抛出错误
const results = await searchData([], 'test');
自动检测并处理循环引用:
// 创建循环引用的数据
const circularData = { name: 'test' };
circularData.self = circularData;
// 安全处理循环引用,不会导致栈溢出
const results = await searchData([circularData], 'test');
- 循环引用对象会自动终止遍历
- Symbol 键名会被忽略
- 不可枚举属性不会被搜索
- 建议对超大数据集启用并行处理
欢迎提交 Pull Request,请确保:
- 通过所有单元测试
- 更新类型定义文件
- 添加对应的文档说明
MIT © 2025 onewayx