!npm
!npm bundle size
!build
!Coveralls github

s(imply)s(tupid)-search

$3

$3

- Ease of Use: Get appropriate results instantly without any configuration.
- Local Array Search: Effortlessly search through a local array of objects.
- Automatic Indexing: No manual indexing required.
- Precision: Always get exactly what you're looking for.
- Lightweight: Depends on just 5 lodash functions for a minimized size after tree shaking.

Demo


Still not convinced? Experience its power firsthand with this interactive demo.

$3

How does it compare to other search libraries? Test out for yourself with this interactive benchmark ;)

Install

ss-search is available on npm. Install it with:

npm install ss-search

Usage

$3

``javascript
import { search } from 'ss-search'

const data = [
{
number: 1,
text: 'A search function should be fast',
},
{
number: 2,
text: 'A search function should provide accurate results',
},
]
const searchKeys = ['text']
const searchText = 'fast search'

const results = search(data, searchKeys, searchText)
// results: [{ number: 1, text: "A search function should be fast" }]
`

It's that straightforward. No configurations, it just works.

$3

Almost all data types are supported [boolean, number, string, object, array].

`javascript
// This dataset will be used as a common starting point for our type examples
const data = [
{
boolean: true,
number: 1,
string: 'search',
object: { nestedProperty: 'nested value' },
array: ['value1', 'value2'],
arrayObjects: [{ arrayObjectProperty: 'array object value' }],
},
]
`

#### Boolean

`javascript
const results = search(data, ['boolean'], 'true')
// results: will return our original dataset
`

#### Number

`javascript
const results = search(data, ['number'], '1')
// results: will return our original dataset
`

#### String

`javascript
const results = search(data, ['string'], 'search')
// results: will return our original dataset
`

#### Object

Providing a key which refers to an object will stringify that object using JSON.stringify

`javascript
const results = search(data, ['object'], 'property')
// results: will return our original dataset as it matches the property key "nestedProperty" of our object
`

If you want to access a nested property of an object to extract only a single value

`javascript
const results = search(data, ['object.nestedProperty'], 'property')
// results: will return an empty array as we extracted the value of our nested object
// if we had searched for "nested value" we would of had the original dataset
`

#### Array

Providing a key which refers to an array will stringify that array using JSON.stringify

`javascript
const results = search(data, ['array'], 'value2')
// results: will return our original dataset
`

If you have an array of objects on which you want to search all properties

`javascript
const results = search(data, ['arrayObjects'], 'arrayObjectProperty')
// results: will return an our original dataset as it's treated just like a regular array
// thus the arrayObjectProperty is part of the searchable text
`

If you have an array of objects where you want only specific properties to be searchable

`javascript
const results = search(data, ['arrayObjects[arrayObjectProperty]'], 'arrayObjectProperty')
// results: will return an empty array as we extracted the value of our nested array of objects
// if we had searched for "value object" we would of had the original dataset
`

$3

Customize your search experience using the following options:

| Option parameter | Value | Description |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| withScore | true | When set to true, the search function will return an array of objects, each containing the matched element and its corresponding score. The score represents how closely the element matches the search text, with a higher score indicating a closer match. Even if the search doesn't match, it will return a score of 0. |
| withScore | false | When set to false or not provided, the function will return an array of matched elements without their scores. |
| cacheKey | unknown | The cacheKey is required if you dynamically update the searchableKeys as the memoization function will use the elements array by default to memoize the search tokens. |

$3

Without withScore option:

`javascript
const data = [{ name: 'John' }, { name: 'Jane' }, { name: 'Doe' }]
const result = search(data, ['name'], 'John')
console.log(result) // [{ name: 'John' }]
`

With withScore option:

`javascript
const data = [{ name: 'John' }, { name: 'Jane' }, { name: 'Doe' }]
const result = search(data, ['name'], 'John', { withScore: true })
console.log(result)
// [
// { element: { name: 'John' }, score: 1 },
// { element: { name: 'Jane' }, score: 0 },
// { element: { name: 'Doe' }, score: 0 }
// ]
`

When updating the searchableKeys dynamically, you need to provide a cacheKey:

`javascript
const data = [
{ name: 'John', age: 50 },
{ name: 'Jane', age: 40 },
]
const result1 = search(data, ['name'], 'John', { cacheKey: 'name' })
const result2 = search(data, ['age'], 40, { cacheKey: 'age' })
// result1: [{ name: 'John', age: 50 }]
// result2: [{ name: 'Jane', age: 40 }]

// If you do not manually update the cache-key, your second search would have used "name" as the searchKeys and returned an empty array
`

![](benchmark.gif)

$3

To better manage dependencies across the monorepo I'm using NX.

Install dependencies:
npm i

Start the web-app:
npm run web-app:serve

Test the library:
npm run test:all`