{"id":27942547,"url":"https://github.com/asuraking1n/nested-fuzzy-search","last_synced_at":"2025-06-10T15:04:49.283Z","repository":{"id":267946334,"uuid":"902843373","full_name":"Asuraking1n/nested-fuzzy-search","owner":"Asuraking1n","description":"A lightweight and customizable fuzzy search utility for nested objects and arrays, powered by Levenshtein distance.","archived":false,"fork":false,"pushed_at":"2024-12-22T03:10:57.000Z","size":128,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T11:57:00.152Z","etag":null,"topics":["fuzzy-logic","fuzzy-matching","fuzzy-search","search-algorithm","searching"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/nested-fuzzy-search","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Asuraking1n.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-13T11:36:26.000Z","updated_at":"2024-12-22T03:11:01.000Z","dependencies_parsed_at":"2024-12-13T12:45:18.883Z","dependency_job_id":null,"html_url":"https://github.com/Asuraking1n/nested-fuzzy-search","commit_stats":null,"previous_names":["asuraking1n/nested-fuzzy-search"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Asuraking1n%2Fnested-fuzzy-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Asuraking1n%2Fnested-fuzzy-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Asuraking1n%2Fnested-fuzzy-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Asuraking1n%2Fnested-fuzzy-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Asuraking1n","download_url":"https://codeload.github.com/Asuraking1n/nested-fuzzy-search/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252873986,"owners_count":21817711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fuzzy-logic","fuzzy-matching","fuzzy-search","search-algorithm","searching"],"created_at":"2025-05-07T11:57:02.450Z","updated_at":"2025-05-07T11:57:03.236Z","avatar_url":"https://github.com/Asuraking1n.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nested Fuzzy Search\n\n[![npm version](https://badge.fury.io/js/nested-fuzzy-search.svg)](https://www.npmjs.com/package/nested-fuzzy-search)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## Description\n\n**Nested Fuzzy Search** is a lightweight and customizable JavaScript library for performing fuzzy search operations on deeply nested objects and arrays. By leveraging the Levenshtein distance algorithm, this package efficiently handles complex data structures and provides accurate similarity-based results.\n\n## Features\n\n- Recursive search through nested objects and arrays.\n- Fuzzy matching using the Levenshtein distance algorithm.\n- Result streaming options for large dataset.\n- Customizable similarity threshold.\n- Easy integration with JavaScript and TypeScript projects.\n- Lightweight and dependency-free.\n\n## Installation\n\nInstall the package via npm:\n\n```bash\nnpm install nested-fuzzy-search\n```\n\n## Usage\n\n### Importing the Package\n\nUsing ES6 imports:\n\n```javascript\nimport { search } from \"nested-fuzzy-search\";\n```\n\n### Example with Object\n\nHere’s how you can use `nested-fuzzy-search` to perform a fuzzy search on a nested object:\n\n```javascript\nimport { search } from \"nested-fuzzy-search\";\n\nconst data = {\n  id: 1,\n  name: \"Root Level\",\n  details: {\n    created: \"2024-12-10\",\n    modified: \"2024-12-10\",\n    meta: {\n      tags: [\"root\", \"nested\", \"example\"],\n      author: {\n        name: \"John Doe\",\n        email: \"johndoe@example.com\",\n      },\n    },\n  },\n  children: [\n    {\n      id: 2,\n      name: \"Level 2 - A\",\n      type: \"Category\",\n      attributes: {\n        visibility: \"public\",\n        tags: [\"level2\", \"category\"],\n      },\n    },\n  ],\n};\n\nconst query = \"John\";\nconst threshold = 0.5; // Minimum similarity score\n\nconst results = search(data, query, {\n  threshold,\n});\n\nconsole.log(results);\n```\n\n### Output\n\n```javascript\n[{ path: \".details.meta.author.name\", value: \"John Doe\", score: 0.5 }];\n```\n\n### Example with Array\n\nHere’s an example using `nested-fuzzy-search` with a deeply nested array:\n\n```javascript\nimport { search } from \"nested-fuzzy-search\";\n\nconst deeplyNestedArray = [\n  {\n    id: 1,\n    name: \"Parent 1\",\n    children: [\n      {\n        id: 11,\n        name: \"Child 1.1\",\n        children: [\n          {\n            id: 111,\n            name: \"Sub-Child 1.1.1\",\n            value: \"Data at level 3\",\n          },\n        ],\n      },\n    ],\n  },\n];\n\nconst query = \"Leaf\";\nconst threshold = 0.3;\n\nconst results = search(deeplyNestedArray, query, {\n  threshold,\n  outputMode: \"tree\",\n});\n\nconsole.log(results);\n```\n\n### Output\n\n```javascript\n[\n  {\n    index: 0,\n    originalData: {\n      id: 1,\n      name: \"Parent 1\",\n      children: [\n        {\n          id: 11,\n          name: \"Child 1.1\",\n          children: [\n            {\n              id: 111,\n              name: \"Sub-Child 1.1.1\",\n              value: \"Data at level 3\",\n            },\n          ],\n        },\n      ],\n    },\n    matches: [\n      {\n        path: \"[0].children[0].children[0].value\",\n        value: \"Data at level 3\",\n        score: 0.4666666666666667,\n      },\n    ],\n  },\n];\n```\n\n### Nested Array with outputMode: `flat`\n\n```javascript\nconst query = \"Leaf\";\nconst threshold = 0.3;\n\nconst results = search(deeplyNestedArray, query, {\n  threshold,\n  outputMode: \"flat\",\n});\n\nconsole.log(results);\n```\n\n### Output\n\n```javascript\n[\n  {\n    path: \"[0].children[0].children[0].value\",\n    value: \"Data at level 3\",\n    score: 0.4666666666666667,\n  },\n];\n```\n\n### `searchStream` result output via streaming\n\n```javascript\nimport { searchStream } from \"nested-fuzzy-search\";\n\nasync function runSearch() {\n  console.time(\"Streaming Test\");\n\n  const simpleNestedArray = [\n    {\n      id: 1,\n      name: \"Parent 1\",\n      children: [\n        {\n          id: 11,\n          name: \"Child 1.1, level\",\n          children: [\n            {\n              id: 111,\n              name: \"Sub-Child 1.1.1 level 3\",\n              value: \"Data at level 3\",\n            },\n          ],\n        },\n      ],\n    },\n  ];\n\n  const query = \"level\";\n  const options = { threshold: 0.2, outputMode: \"flat\", exact: false };\n\n  console.log(\"Start streaming results...\");\n\n  for await (const result of searchStream(simpleNestedArray, query, options)) {\n    console.log(\"Received result:\", result);\n    await new Promise((r) =\u003e setTimeout(r, 500)); // Simulate processing delay\n  }\n\n  console.timeEnd(\"Streaming Test\");\n}\n\nrunSearch();\n```\n\n### Output\n\n```javascript\nStart streaming results...\nReceived result: {\n  path: '[0].children[0].name',\n  value: 'Child 1.1, level',\n  score: 0.3125\n}\nReceived result: {\n  path: '[0].children[0].children[0].name',\n  value: 'Sub-Child 1.1.1 level 3',\n  score: 0.21739130434782605\n}\nReceived result: {\n  path: '[0].children[0].children[0].value',\n  value: 'Data at level 3',\n  score: 0.33333333333333337\n}\nStreaming Test: 1.511s\n```\n\n- CodeSandbox: [Live](https://codesandbox.io/p/sandbox/sdrf7z?file=%2Fsrc%2FApp.js)\n\n## API\n\n### `search(data, query, options)`\n\nPerforms a fuzzy search on the provided nested data.\n\n### `searchStream(data, query, options)`\n\nPerforms a fuzzy search on the provided nested data and return result via streaming.\n\n#### Parameters:\n\n- **`data`**: The nested object or array to search.\n- **`query`**: The search string.\n- **`options`**: This is an object which support multiple options.\n\n`options`:\n\n- `options` can have four values:\n  - **`threshold`**: The minimum similarity score (default: `0.6`)\n  - **`outputMode`**: The type of output you want (default: `flat`)\n  - **`excludeKeys`**: The array of keys you want to exclude (default: `[]`)\n  - **`exact`**: Its a boolean value if its true, it will strict check the query instead of similarity score (default: `false`)\n\n#### Returns:\n\nAn array of results, each containing:\n\n- `path`: The path to the matched value.\n- `value`: The matched string.\n- `score`: The similarity score.\n\n### How it Works\n\n1. The library flattens the nested structure into a list of paths and string values.\n2. It calculates the similarity score between the query and each string value using the Levenshtein distance.\n3. Results with scores above the threshold are returned, sorted by relevance.\n\n## Testing\n\nRun unit tests using Jest:\n\n```bash\nnpm test\n```\n\n## Contributing\n\nContributions are welcome! If you’d like to improve this package, please:\n\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature-name`).\n3. Commit your changes (`git commit -m 'Add new feature'`).\n4. Push to the branch (`git push origin feature-name`).\n5. Open a pull request.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by the need for efficient and customizable fuzzy search in complex datasets.\n- Leverages the Levenshtein distance algorithm for similarity scoring.\n\n## Support\n\nIf you encounter any issues or have questions, feel free to open an [issue](https://github.com/Asuraking1n/nested-fuzzy-search/issues) on GitHub.\n\n## Connect\n\n- GitHub: [\u003cimg src=\"https://img.shields.io/badge/-GitHub-white?style=social\u0026logo=github\u0026logoColor=black\"  height=\"30\"/\u003e](https://github.com/Asuraking1n)\n- LinkedIn: [\u003cimg src=\"https://img.shields.io/badge/-LinkedIn-white?style=social\u0026logo=linkedin\u0026logoColor=blue\"  height=\"30\"/\u003e](https://www.linkedin.com/in/nishant-kumar-tiwari-253a46196/)\n\n---\n\nHappy Searching! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasuraking1n%2Fnested-fuzzy-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasuraking1n%2Fnested-fuzzy-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasuraking1n%2Fnested-fuzzy-search/lists"}