x-arraysearch
TypeScript icon, indicating that this package has built-in type declarations

1.0.2 • Public • Published

X-ArraySearch

测试覆盖率 TypeScript Issues

用于复杂对象搜索的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 类型支持
  • 循环检测:自动处理循环引用
  • 错误处理:优雅处理无效输入
  • 深度限制:防止栈溢出

API 文档

searchData<T>

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)

内置匹配器

defaultMatcher

默认的包含匹配函数,不区分大小写

exactMatcher

严格类型检查的精确匹配

createRegExpMatcher(flags?)

创建正则表达式匹配器工厂函数

使用指南

快速开始

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');

注意事项

  1. 循环引用对象会自动终止遍历
  2. Symbol 键名会被忽略
  3. 不可枚举属性不会被搜索
  4. 建议对超大数据集启用并行处理

贡献指南

欢迎提交 Pull Request,请确保:

  1. 通过所有单元测试
  2. 更新类型定义文件
  3. 添加对应的文档说明

许可证

MIT © 2025 onewayx

Package Sidebar

Install

npm i x-arraysearch

Weekly Downloads

9

Version

1.0.2

License

MIT

Unpacked Size

29.5 kB

Total Files

7

Last publish

Collaborators

  • onewayx