OUSSearch

Installation

Install using NPM:

npm install OUSSearch

Typical Usage

To use the library you create an instance of OUSSearch and provide options using the built in functions. You need to provide:

• A traversal strategy that describes how the engine should traverse the structure, when to stop as well as what to return
• An array of comparison strategies to define how terms and contexts should be compared
• A dataset
• Optionally you can provide an array of sorting algorithms for the resultset. They will be evaluated in index order.
• Optionally you can provide a limit for how many results you are interested in

Here is an example:

import { OUSSearch, TraversalStrategy, ComparisonStrategy, SortingStrategy } from "OUSSearch"
const data = [
    {
        name: "tom"
    },
    {
        name: "tim"
    }
]
const se = new OUSSearch()
    .setTraversalStrategy(TraversalStrategy.RETURN_ROOT_ON_FIRST_MATCH_ORDERED)
    .setComparisonStrategy([ComparisonStrategy.STARTS_WITH, ComparisonStrategy.FUZZY_SEQUENTIAL])
    .setSortingStrategy([sortingStrategy.SORT_BY_RELEVANCE])
    .setLimit(2)
    .setDataset(data)
const results = se.search("tm")
//[{name: "tom"}, {name, "tim"}]

Included / Ignored Attributes Customizability

By default OUSSearch looks through all attributes for the supplied criteria, but the engine can be configured to either only look for certain attributes, or ignore certain attributes. You can set this up by providing an array of regexps (as strings or regex instances), that will be evaluated against the path. The path string will be formatted with a "." separator between hierarchical steps. You can use it like so:

import OUSSearch from "OUSSearch"
const attributeArray = [/name$/]
const data = [
    {
        name: "tom"
    },
    {
        otherNameAttribute: "tim"
    }
]
const seInc = new OUSSearch()
    .setTraversalStrategy(TraversalStrategy.RETURN_ROOT_ON_FIRST_MATCH)
    .setComparisonStrategy([ComparisonStrategy.FUZZY_SEQUENTIAL])
    .setDataset(data)
    .setIncludedAttributes(attributeArray)
const seIgn = new OUSSearch()
    .setTraversalStrategy(TraversalStrategy.RETURN_ROOT_ON_FIRST_MATCH)
    .setComparisonStrategy([ComparisonStrategy.FUZZY_SEQUENTIAL])
    .setDataset(data)
    .setIgnoredAttributes(attributeArray)
const resultsIncluded = seInc.search("tm")
//[{name: "tom"}]
const resultsIgnored = seIgn.search("tm")
//[{otherNameAttribute: "tom"}]

Traversal Strategy

The traversal strategy describes how OUSSearch should traverse the JSON tree, when to stop, as well as what to return as a result when a match is found. There are a few strategies that come included in the library:

Strategy	Description
RETURN_ROOT_ON_FIRST_MATCH	Traversal stops as soon as a match is found. The entire root object is returned as a result.
RETURN_ROOT_ON_FIRST_MATCH_ORDERED	Similar to the above strategy, but guarantees the order of the supplied comparison strategies. It has the same time complexity as the above strategy, but is in most cases slower. It does, however, give more accurate results.
EXTRACT_ALL_NESTED	Traversal will continue until every branch has been evaluated, and the result will be the actual branch where the result was found rather than the root node.

Comparison Strategy

The comparison strategy is how OUSSearch determines if there is a match or not. OUSSearch comes with a few built in options for this:

Strategy	Description
BITAP	Will check if term exists inside context within a Levenshtein distance of 2.
FUZZY_SEQUENCE	Will check if all letters of the term exist - in given order, but not necessarily one after the other - somwhere inside the context. (not case sensitive!)
STARTS_WITH	Will check if the context starts with the term
STARTS_WITH_CASE_INSENSITIVE	Will check if the context starts with the term (not case sensitive!)
STARTS_WITH_INSIDE_CONTAINS	Will check if the context starts with the term somwhere inside of it (not case sensitive!)
STARTS_WITH_INSIDE_CONTAINS_CASE_INSENSITIVE	Will check if the context starts with the term somewhere inside of it (not case sensitive!)
ENDS_WITH	Will check if the context ends with the term
ENDS_WITH_CASE_INSENSITIVE	Will check if the context ends with the term (not case sensitive!)
CONTAINS	Will check if the context contains the term
CONTAINS_CASE_INSENSITIVE	Will check if the context contains the term (not case sensitive!)
EQUALS	Will check if the context equals the term
EQUALS_CASE_INSENSITIVE	Will check if the context equals the term (not case sensitive!)
CONTAINS_ALL_WORDS	This strategy will determine if all the words in the term are contained inside of the context (not case sensitive!)

You can also create a custom comparison strategy. This is done by providing a function that returns a boolean based on if the evaluation was a match or not. A comparison strategy function will be provided the following arguments: Argument | Description --- | --- term* | The value to be searched for context* | The value to be searched

Sorting Strategy

The sorting strategy defines how OUSSearch sorts the resultset. If a sorting strategy is not provided the resultset will be returned in the order of items found. These sorting algorithms ship in the library:

Strategy	Description
VALUE	Sort by value, descending.
ATTRIBUTE	Sort by attribute, descending.
DEPTH	Sort by depth, ascending.
RELEVANCE	Sort by relevance, descending.