https://github.com/asuraking1n/nested-fuzzy-search
A lightweight and customizable fuzzy search utility for nested objects and arrays, powered by Levenshtein distance.
https://github.com/asuraking1n/nested-fuzzy-search
fuzzy-logic fuzzy-matching fuzzy-search search-algorithm searching
Last synced: 11 days ago
JSON representation
A lightweight and customizable fuzzy search utility for nested objects and arrays, powered by Levenshtein distance.
- Host: GitHub
- URL: https://github.com/asuraking1n/nested-fuzzy-search
- Owner: Asuraking1n
- Created: 2024-12-13T11:36:26.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-12-22T03:10:57.000Z (6 months ago)
- Last Synced: 2025-05-07T11:57:00.152Z (about 2 months ago)
- Topics: fuzzy-logic, fuzzy-matching, fuzzy-search, search-algorithm, searching
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/nested-fuzzy-search
- Size: 125 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Nested Fuzzy Search
[](https://www.npmjs.com/package/nested-fuzzy-search)
[](https://opensource.org/licenses/MIT)
## Description
**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.
## Features
- Recursive search through nested objects and arrays.
- Fuzzy matching using the Levenshtein distance algorithm.
- Result streaming options for large dataset.
- Customizable similarity threshold.
- Easy integration with JavaScript and TypeScript projects.
- Lightweight and dependency-free.
## Installation
Install the package via npm:
```bash
npm install nested-fuzzy-search
```
## Usage
### Importing the Package
Using ES6 imports:
```javascript
import { search } from "nested-fuzzy-search";
```
### Example with Object
Here’s how you can use `nested-fuzzy-search` to perform a fuzzy search on a nested object:
```javascript
import { search } from "nested-fuzzy-search";
const data = {
id: 1,
name: "Root Level",
details: {
created: "2024-12-10",
modified: "2024-12-10",
meta: {
tags: ["root", "nested", "example"],
author: {
name: "John Doe",
email: "[email protected]",
},
},
},
children: [
{
id: 2,
name: "Level 2 - A",
type: "Category",
attributes: {
visibility: "public",
tags: ["level2", "category"],
},
},
],
};
const query = "John";
const threshold = 0.5; // Minimum similarity score
const results = search(data, query, {
threshold,
});
console.log(results);
```
### Output
```javascript
[{ path: ".details.meta.author.name", value: "John Doe", score: 0.5 }];
```
### Example with Array
Here’s an example using `nested-fuzzy-search` with a deeply nested array:
```javascript
import { search } from "nested-fuzzy-search";
const deeplyNestedArray = [
{
id: 1,
name: "Parent 1",
children: [
{
id: 11,
name: "Child 1.1",
children: [
{
id: 111,
name: "Sub-Child 1.1.1",
value: "Data at level 3",
},
],
},
],
},
];
const query = "Leaf";
const threshold = 0.3;
const results = search(deeplyNestedArray, query, {
threshold,
outputMode: "tree",
});
console.log(results);
```
### Output
```javascript
[
{
index: 0,
originalData: {
id: 1,
name: "Parent 1",
children: [
{
id: 11,
name: "Child 1.1",
children: [
{
id: 111,
name: "Sub-Child 1.1.1",
value: "Data at level 3",
},
],
},
],
},
matches: [
{
path: "[0].children[0].children[0].value",
value: "Data at level 3",
score: 0.4666666666666667,
},
],
},
];
```
### Nested Array with outputMode: `flat`
```javascript
const query = "Leaf";
const threshold = 0.3;
const results = search(deeplyNestedArray, query, {
threshold,
outputMode: "flat",
});
console.log(results);
```
### Output
```javascript
[
{
path: "[0].children[0].children[0].value",
value: "Data at level 3",
score: 0.4666666666666667,
},
];
```
### `searchStream` result output via streaming
```javascript
import { searchStream } from "nested-fuzzy-search";
async function runSearch() {
console.time("Streaming Test");
const simpleNestedArray = [
{
id: 1,
name: "Parent 1",
children: [
{
id: 11,
name: "Child 1.1, level",
children: [
{
id: 111,
name: "Sub-Child 1.1.1 level 3",
value: "Data at level 3",
},
],
},
],
},
];
const query = "level";
const options = { threshold: 0.2, outputMode: "flat", exact: false };
console.log("Start streaming results...");
for await (const result of searchStream(simpleNestedArray, query, options)) {
console.log("Received result:", result);
await new Promise((r) => setTimeout(r, 500)); // Simulate processing delay
}
console.timeEnd("Streaming Test");
}
runSearch();
```
### Output
```javascript
Start streaming results...
Received result: {
path: '[0].children[0].name',
value: 'Child 1.1, level',
score: 0.3125
}
Received result: {
path: '[0].children[0].children[0].name',
value: 'Sub-Child 1.1.1 level 3',
score: 0.21739130434782605
}
Received result: {
path: '[0].children[0].children[0].value',
value: 'Data at level 3',
score: 0.33333333333333337
}
Streaming Test: 1.511s
```
- CodeSandbox: [Live](https://codesandbox.io/p/sandbox/sdrf7z?file=%2Fsrc%2FApp.js)
## API
### `search(data, query, options)`
Performs a fuzzy search on the provided nested data.
### `searchStream(data, query, options)`
Performs a fuzzy search on the provided nested data and return result via streaming.
#### Parameters:
- **`data`**: The nested object or array to search.
- **`query`**: The search string.
- **`options`**: This is an object which support multiple options.
`options`:
- `options` can have four values:
- **`threshold`**: The minimum similarity score (default: `0.6`)
- **`outputMode`**: The type of output you want (default: `flat`)
- **`excludeKeys`**: The array of keys you want to exclude (default: `[]`)
- **`exact`**: Its a boolean value if its true, it will strict check the query instead of similarity score (default: `false`)
#### Returns:
An array of results, each containing:
- `path`: The path to the matched value.
- `value`: The matched string.
- `score`: The similarity score.
### How it Works
1. The library flattens the nested structure into a list of paths and string values.
2. It calculates the similarity score between the query and each string value using the Levenshtein distance.
3. Results with scores above the threshold are returned, sorted by relevance.
## Testing
Run unit tests using Jest:
```bash
npm test
```
## Contributing
Contributions are welcome! If you’d like to improve this package, please:
1. Fork the repository.
2. Create a new branch (`git checkout -b feature-name`).
3. Commit your changes (`git commit -m 'Add new feature'`).
4. Push to the branch (`git push origin feature-name`).
5. Open a pull request.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Inspired by the need for efficient and customizable fuzzy search in complex datasets.
- Leverages the Levenshtein distance algorithm for similarity scoring.
## Support
If you encounter any issues or have questions, feel free to open an [issue](https://github.com/Asuraking1n/nested-fuzzy-search/issues) on GitHub.
## Connect
- GitHub: [
](https://github.com/Asuraking1n)
- LinkedIn: [
](https://www.linkedin.com/in/nishant-kumar-tiwari-253a46196/)
---
Happy Searching! 🚀