{"_id":"x-arraysearch","_rev":"3-f4234db63366166c9982ef9a4b703968","name":"x-arraysearch","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"x-arraysearch","version":"1.0.0","keywords":["search","array","object","typescript","nested","filter","deep","match","advanced"],"author":{"name":"onewayx"},"license":"MIT","_id":"x-arraysearch@1.0.0","maintainers":[{"name":"onewayx","email":"2089046083@qq.com"}],"homepage":"https://github.com/onewayx/x-arraysearch#readme","bugs":{"url":"https://github.com/onewayx/x-arraysearch/issues"},"dist":{"shasum":"1d13e2852779dcdca1075b1a04df376953d7a53c","tarball":"https://registry.npmjs.org/x-arraysearch/-/x-arraysearch-1.0.0.tgz","fileCount":7,"integrity":"sha512-OGwNXmE3EBFcnPxn21WfgQKWKOIUernlnF81Z6Oe78wUTeKi4qNasYaEpoy7iikWhFmC4X0AJim3zPoRVm/q4Q==","signatures":[{"sig":"MEQCIGsfRhC6A6SP9+r03syJwNRVe/YGOVPtiI0rwXnWVObKAiAOiEDSjgmoPWAU+hxawcm3CiM5busC8O9NEm8d3RDWqg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25814},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=14.0.0"},"scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts","format":"prettier --write \"src/**/*.ts\"","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"onewayx","email":"2089046083@qq.com"},"repository":{"url":"git+https://github.com/onewayx/x-arraysearch.git","type":"git"},"_npmVersion":"11.1.0","description":"高级对象搜索工具库，支持多层级嵌套对象、数组自动展开、自定义匹配逻辑和安全深度控制","directories":{},"_nodeVersion":"22.13.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^8.0.0","vitest":"^1.0.0","prettier":"^3.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/x-arraysearch_1.0.0_1742056664807_0.060385721207578014","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"x-arraysearch","version":"1.0.1","keywords":["search","array","object","typescript","nested","filter","deep","match","advanced"],"author":{"name":"onewayx"},"license":"MIT","_id":"x-arraysearch@1.0.1","maintainers":[{"name":"onewayx","email":"2089046083@qq.com"}],"homepage":"https://github.com/YIfangweb/x-arraysearch#readme","bugs":{"url":"https://github.com/YIfangweb/x-arraysearch/issues"},"dist":{"shasum":"0dbd61ac1e2a05d26813a05e4c00f091f7fc8502","tarball":"https://registry.npmjs.org/x-arraysearch/-/x-arraysearch-1.0.1.tgz","fileCount":7,"integrity":"sha512-EjmBverXFyO9oEOeO7fF4quk9SOCHzq7t/QDwcbe5Nythd09oKg6WhIEQYLgGRRdmBFe32a6wn07Yh4TYntCiw==","signatures":[{"sig":"MEQCICrkM5W5XrFVE8mQz5cS0yYZAWH765PyqaV68lHnL/CZAiAQXAfAg7SG9nTuriyfEJGLSeDUlpnA9scHzgyaYziofg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25935},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=14.0.0"},"gitHead":"cacaa2899c331eb143f2364adae69fe2a2de9bce","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts","format":"prettier --write \"src/**/*.ts\"","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"onewayx","email":"2089046083@qq.com"},"repository":{"url":"git+https://github.com/YIfangweb/x-arraysearch.git","type":"git"},"_npmVersion":"11.1.0","description":"高级对象搜索工具库，支持多层级嵌套对象、数组自动展开、自定义匹配逻辑和安全深度控制","directories":{},"_nodeVersion":"22.13.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^8.0.0","vitest":"^1.0.0","prettier":"^3.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/x-arraysearch_1.0.1_1742058756341_0.9708077448983552","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"x-arraysearch","version":"1.0.2","description":"高级对象搜索工具库，支持多层级嵌套对象、数组自动展开、自定义匹配逻辑和安全深度控制","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","scripts":{"build":"tsup src/index.ts --format cjs,esm --dts","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"eslint src --ext .ts","format":"prettier --write \"src/**/*.ts\"","prepublishOnly":"npm run build"},"keywords":["search","array","object","typescript","nested","filter","deep","match","advanced"],"author":{"name":"onewayx"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/YIfangweb/x-arraysearch.git"},"bugs":{"url":"https://github.com/YIfangweb/x-arraysearch/issues"},"homepage":"https://github.com/YIfangweb/x-arraysearch#readme","devDependencies":{"@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","prettier":"^3.0.0","tsup":"^8.0.0","typescript":"^5.0.0","vitest":"^1.0.0"},"engines":{"node":">=14.0.0"},"_id":"x-arraysearch@1.0.2","gitHead":"aa82a7d875af3a3772d560fd5ea9f5e8d2ea7c65","_nodeVersion":"22.13.1","_npmVersion":"11.1.0","dist":{"integrity":"sha512-Nc0mn7NGMhFOgNZ5rSfQitIyy6VzOnlxPNhWDaUOZAn1JUAltbJeeuB/Y8Xy+F/INl85tYGV8vV/8Ike31df8g==","shasum":"45c1a59528b292959370b06a3b6afe876def8714","tarball":"https://registry.npmjs.org/x-arraysearch/-/x-arraysearch-1.0.2.tgz","fileCount":7,"unpackedSize":29470,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEUMPHxF35gItjG4M2G+/OzCK2ArDHI0MSPs6W72Xen3AiEApS+P6y/dmgfHNA6TJWRgKHQNa7X8Zh0mY0RhexUdGg0="}]},"_npmUser":{"name":"onewayx","email":"2089046083@qq.com"},"directories":{},"maintainers":[{"name":"onewayx","email":"2089046083@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/x-arraysearch_1.0.2_1742097475710_0.9082510011464235"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-15T16:37:44.806Z","modified":"2025-03-16T03:57:56.077Z","1.0.0":"2025-03-15T16:37:44.986Z","1.0.1":"2025-03-15T17:12:36.533Z","1.0.2":"2025-03-16T03:57:55.899Z"},"bugs":{"url":"https://github.com/YIfangweb/x-arraysearch/issues"},"author":{"name":"onewayx"},"license":"MIT","homepage":"https://github.com/YIfangweb/x-arraysearch#readme","keywords":["search","array","object","typescript","nested","filter","deep","match","advanced"],"repository":{"type":"git","url":"git+https://github.com/YIfangweb/x-arraysearch.git"},"description":"高级对象搜索工具库，支持多层级嵌套对象、数组自动展开、自定义匹配逻辑和安全深度控制","maintainers":[{"name":"onewayx","email":"2089046083@qq.com"}],"readme":"# X-ArraySearch\r\n\r\n[![测试覆盖率](https://img.shields.io/badge/coverage-100%25-success)](https://github.com/YIfangweb/x-arraysearch)\r\n![TypeScript](https://img.shields.io/badge/lang-typescript-blue)\r\n[![Issues](https://img.shields.io/badge/x-arraysearch-issues)](https://github.com/YIfangweb/x-arraysearch/issues)\r\n\r\n用于复杂对象搜索的TypeScript工具库，支持：\r\n- 多层级嵌套对象\r\n- 数组自动展开\r\n- 自定义匹配逻辑\r\n- 安全深度控制\r\n\r\n## 安装\r\n\r\n```bash\r\nnpm i x-arraysearch@latest\r\n# 或\r\nyarn add x-arraysearch\r\n```\r\n\r\n## 核心特性\r\n\r\n### 路径语法\r\n- 点标记法：`'user.address.city'`\r\n- 自动数组展开：`'orders[].product'`\r\n- 混合路径：`'departments[].employees[].name'`\r\n\r\n### 匹配模式\r\n| 匹配器             | 描述                     | 示例                     |\r\n|--------------------|--------------------------|--------------------------|\r\n| `defaultMatcher`   | 不区分大小写包含匹配     | `'apple' → 'Apple Pie'`  |\r\n| `exactMatcher`     | 严格类型相等匹配         | `100 不匹配 '100'`       |\r\n| `createRegExpMatcher()` | 正则表达式匹配         | `'^d+' 匹配 '123abc'`    |\r\n\r\n### 性能优化\r\n- 短路匹配：发现匹配后立即停止搜索\r\n- 深度控制：默认最大递归深度10层\r\n- 路径缓存：优化重复路径的查询性能\r\n- 并行处理：自动处理大数据集\r\n\r\n### 安全特性\r\n- 类型安全：完整的 TypeScript 类型支持\r\n- 循环检测：自动处理循环引用\r\n- 错误处理：优雅处理无效输入\r\n- 深度限制：防止栈溢出\r\n\r\n## API 文档\r\n\r\n### `searchData<T>`\r\n```typescript\r\nfunction searchData<T extends Record<string, any>>(\r\n  data: T[],\r\n  term: unknown,\r\n  options?: SearchOptions\r\n): T[] | Promise<T[]>\r\n```\r\n\r\n**参数**\r\n- `data`: 对象数组\r\n- `term`: 搜索关键词\r\n- `options`: 配置选项\r\n  - `keys`: 搜索路径数组\r\n  - `customMatch`: 自定义匹配函数\r\n  - `maxDepth`: 最大递归深度（默认10）\r\n  - `enablePathCache`: 是否启用路径缓存（默认true）\r\n  - `parallel`: 是否并行处理大数据集（默认false）\r\n\r\n### 内置匹配器\r\n\r\n#### `defaultMatcher`\r\n默认的包含匹配函数，不区分大小写\r\n\r\n#### `exactMatcher`\r\n严格类型检查的精确匹配\r\n\r\n#### `createRegExpMatcher(flags?)`\r\n创建正则表达式匹配器工厂函数\r\n\r\n## 使用指南\r\n\r\n### 快速开始\r\n\r\n```typescript\r\nimport { searchData, createRegExpMatcher } from 'x-arraysearch';\r\n\r\nconst products = [\r\n  {\r\n    id: 1,\r\n    name: 'iPhone 13',\r\n    details: {\r\n      tags: ['手机', '苹果'],\r\n      specs: {\r\n        storage: '128GB',\r\n        color: '暗夜绿'\r\n      }\r\n    }\r\n  }\r\n];\r\n\r\n// 简单搜索\r\nconst results = await searchData(products, 'iPhone');\r\n\r\n// 高级搜索\r\nconst filtered = await searchData(products, '^128', {\r\n  keys: ['details.specs.storage'],\r\n  customMatch: createRegExpMatcher('i')\r\n});\r\n```\r\n\r\n### 基本搜索功能\r\n\r\n#### 简单文本搜索\r\n默认情况下，`searchData` 会在整个对象树中搜索匹配项，不区分大小写：\r\n\r\n```typescript\r\n// 搜索包含 \"iphone\" 的数据（不区分大小写）\r\nconst results = await searchData(products, 'iphone');\r\n```\r\n\r\n#### 搜索特定属性\r\n通过指定 `keys` 选项限制搜索范围：\r\n\r\n```typescript\r\n// 只在产品名称中搜索\r\nconst results = await searchData(products, '苹果', {\r\n  keys: ['name']\r\n});\r\n```\r\n\r\n#### 递归深度控制\r\n设置 `maxDepth` 以限制递归深度，防止过深的对象导致性能问题：\r\n\r\n```typescript\r\n// 限制搜索深度为3层\r\nconst results = await searchData(complexData, 'target', {\r\n  maxDepth: 3\r\n});\r\n```\r\n\r\n### 高级路径搜索\r\n\r\n#### 点表示法搜索\r\n可以使用点表示法精确定位嵌套属性：\r\n\r\n```typescript\r\n// 搜索特定嵌套属性\r\nconst results = await searchData(products, '手机', {\r\n  keys: ['category.sub']\r\n});\r\n```\r\n\r\n#### 多路径搜索\r\n同时在多个路径中进行搜索：\r\n\r\n```typescript\r\n// 同时搜索颜色和标签\r\nconst results = await searchData(products, '白色', {\r\n  keys: ['specs.color', 'tags']\r\n});\r\n```\r\n\r\n#### 数组路径遍历\r\n自动展开和搜索数组内的元素：\r\n\r\n```typescript\r\n// 搜索产品功能列表\r\nconst results = await searchData(products, 'Face ID', {\r\n  keys: ['specs.features']\r\n});\r\n```\r\n\r\n### 匹配器使用\r\n\r\n#### 默认匹配器\r\n不区分大小写的部分匹配，适用于大多数场景：\r\n\r\n```typescript\r\n// 默认使用 defaultMatcher\r\nconst results = await searchData(products, 'pro');\r\n\r\n// defaultMatcher 的行为：\r\n// - 'Hello World' 匹配 'world'\r\n// - 123 匹配 '23'\r\n// - true 匹配 'true'\r\n```\r\n\r\n#### 精确匹配器\r\n使用严格相等比较，特别适合比较数值和布尔值：\r\n\r\n```typescript\r\nimport { searchData, exactMatcher } from 'x-arraysearch';\r\n\r\n// 只匹配库存数量恰好为 100 的产品\r\nconst results = await searchData(products, 100, {\r\n  keys: ['stock.count'],\r\n  customMatch: exactMatcher\r\n});\r\n\r\n// exactMatcher 的行为：\r\n// - 123 只匹配 123 (不匹配 '123')\r\n// - true 只匹配 true (不匹配 'true')\r\n```\r\n\r\n#### 正则表达式匹配器\r\n支持使用正则表达式进行复杂模式匹配：\r\n\r\n```typescript\r\nimport { searchData, createRegExpMatcher } from 'x-arraysearch';\r\n\r\n// 使用正则表达式匹配所有以数字开头的型号\r\nconst regexMatcher = createRegExpMatcher('i'); // 'i' 表示不区分大小写\r\nconst results = await searchData(products, '^\\\\d+', {\r\n  keys: ['model'],\r\n  customMatch: regexMatcher\r\n});\r\n```\r\n\r\n### 性能优化技术\r\n\r\n#### 路径缓存\r\n对于重复查询，启用路径缓存可显著提高性能：\r\n\r\n```typescript\r\n// 创建共享搜索配置\r\nconst searchOptions = {\r\n  keys: ['category.sub', 'specs.features'],\r\n  enablePathCache: true  // 默认就是 true\r\n};\r\n\r\n// 首次查询会缓存解析后的路径\r\nconst phoneResults = await searchData(products, '手机', searchOptions);\r\n// 后续查询复用缓存，提高性能\r\nconst iosResults = await searchData(products, 'iOS', searchOptions);\r\n```\r\n\r\n#### 并行处理大数据集\r\n处理大量数据时，启用并行处理能加快搜索速度：\r\n\r\n```typescript\r\n// 处理超过1000条的数据集\r\nconst results = await searchData(largeData, 'target', {\r\n  keys: ['importantField', 'nested.targetField'],\r\n  parallel: true  // 自动分片并行处理\r\n});\r\n```\r\n\r\n### 自定义搜索逻辑\r\n\r\n创建自定义匹配函数来实现特定的比较逻辑：\r\n\r\n```typescript\r\nconst customMatcher = (value: unknown, term: unknown) => {\r\n  if (typeof value === 'number') {\r\n    return value > (term as number);\r\n  }\r\n  return defaultMatcher(value, term);\r\n};\r\n\r\n// 查找价格高于5000的所有产品\r\nconst results = await searchData(products, 5000, {\r\n  keys: ['price'],\r\n  customMatch: customMatcher\r\n});\r\n```\r\n\r\n### 边界情况处理\r\n\r\n#### 空数据集处理\r\n正确处理空数组：\r\n\r\n```typescript\r\n// 返回空数组，不会抛出错误\r\nconst results = await searchData([], 'test');\r\n```\r\n\r\n#### 循环引用安全处理\r\n自动检测并处理循环引用：\r\n\r\n```typescript\r\n// 创建循环引用的数据\r\nconst circularData = { name: 'test' };\r\ncircularData.self = circularData;\r\n\r\n// 安全处理循环引用，不会导致栈溢出\r\nconst results = await searchData([circularData], 'test');\r\n```\r\n\r\n## 注意事项\r\n1. 循环引用对象会自动终止遍历\r\n2. Symbol 键名会被忽略\r\n3. 不可枚举属性不会被搜索\r\n4. 建议对超大数据集启用并行处理\r\n\r\n## 贡献指南\r\n欢迎提交 Pull Request，请确保：\r\n1. 通过所有单元测试\r\n2. 更新类型定义文件\r\n3. 添加对应的文档说明\r\n\r\n## 许可证\r\nMIT © 2025 onewayx\r\n","readmeFilename":"README.md"}