@ecromaneli/search-engine NPM

Search-Engine

A lightweight, powerful object search engine for JavaScript with advanced query syntax.

Installation

npm install @ecromaneli/search-engine

Features

Powerful query language with boolean operators (AND/OR)
Field-specific searches
Support for wildcards and regex pattern matching
Numeric range searches
Logical negation of search terms
Nested property searching
Logical grouping with parentheses
Customizable search options
Zero dependencies

Basic Usage

const SearchEngine = require('@ecromaneli/search-engine')

const users = [
  { id: 1, name: 'John Doe', age: 28, tags: ['developer', 'javascript'] },
  { id: 2, name: 'Jane Smith', age: 34, tags: ['designer', 'ui/ux'] },
  { id: 3, name: 'Bob Johnson', age: 45, tags: ['manager', 'finance'] }
]

const result = SearchEngine.search(users, 'name: john')
console.log(result)

Using the SearchEngine Constructor

You can create a SearchEngine instance with specific options that will be used for all searches:

const engine = new SearchEngine({
  excludeKeys: ['password', 'private.info'],
  allowNumericString: false,
  allowKeyValueMatching: true,
  matchChildKeysAsValues: false
})

const results = engine.search(users, 'age~: 25-35')
console.log(results)

Search Options

The SearchOptions object allows you to customize the behavior of the search engine. Below is a table explaining each option:

Option	Type	Default	Description
`excludeKeys`	`string[]`	`[]`	Array of keys to exclude from search. Useful for excluding sensitive data.
`allowNumericString`	`boolean`	`true`	Controls whether string values that can be parsed as numbers are used in range searches.
`allowKeyValueMatching`	`boolean`	`true`	When enabled, unquoted terms without a field/value separator match both field names and values.
`matchChildKeysAsValues`	`boolean`	`false`	When enabled, after finding a matching key, also looks for the value in child object keys.

Differences Between Options

allowNumericString:
- When true, strings like "123" will be treated as numbers in range searches.
- When false, only actual numbers will be considered for range searches.
allowKeyValueMatching:
- When true, a query like admin will match both { admin: "value" } and { key: "admin" }.
- When false, it will only match field names or values explicitly.
matchChildKeysAsValues:
- When true, a query like foo:bar will match both { foo: "bar" } and {foo: { bar: "value" }}.
- When false, it will only match { foo: "bar" }.

Query Syntax Reference

Basic Queries

foo - Search for objects having a field or value foo.
"value" - Search for "value" in any field.
field: value - Search for value in the specific field.

Specialized Searches

field*: pattern - Regex pattern match on field.
field~: min-max - Numeric range search.
field~: 10- - Numbers greater than or equal to 10.
field~: -20 - Numbers less than or equal to 20.

Negative values are also supported.

Boolean Operators

term1 and term2 - Both terms must match.
term1 or term2 - Either term must match.

Negation and Grouping

not term - Term must not match.
not (term1 or term2) - Group negation (neither term1 nor term2 should match).
(term1 or term2) and term3 - Logical grouping with parentheses.

API Reference

Static Methods

`SearchEngine.search(objList, queryStr, options)`

objList (Array): Array of objects to search through.
queryStr (String): Query string following the syntax described above.
options (Object, optional): Search options object.
Returns (Array): Array of matching objects.

Instance Methods

To store the options, use the constructor below:

`new SearchEngine(options)`

options (Object, optional): Search options object (see Options table).
Returns (SearchEngine): A new SearchEngine instance with the specified options.

`searchInstance.search(objList, queryStr)`

objList (Array): Array of objects to search through.
queryStr (String): Query string following the syntax described above.
Returns (Array): Array of matching objects with the instance's options applied.

Performance Tips

For large datasets, consider disabling allowNumericString if you don't need string-to-number conversion.
Set matchChildKeysAsValues: false (default) unless you specifically need to match object keys as values.
Use excludeKeys to skip searching in fields that are never relevant to your searches.
For repeated searches with the same options, create a SearchEngine instance instead of using the static method.