Getting Started

To use in your application

In order to use this package in your project, you'll need to:

Install the package as a dependency:

yarn add @darylcecile/nsearch

Once you have it set up as a dependency, you can import the library. This library comes with two main features, Search and Semantics. Both are very early stages and should be considered POC only.

Search

The Search feature can be used to rank a collection based on a given search query:

import {Search} from "@darylcecile/nsearch";

const collectionExample = [
    {title:'Creating a new react 3.1 application'},
    {title:"Testing application on version 3.1"},
    {title:"Onboarding app onto turbo"},
    {title:"Setting up webhooks on github"},
    {title:"setting up a new github application"},
    {title:"Running your application on react 2.12.1"}
]

// will return the collection sorted by match probability
Search.rank({
    query: "cape crap treat", 
    collection: collectionExample,  // list of string or objects to sort through
    expander: (item) => item.title  // (optional) expand objects to specify which property to use
    topN: 0                         // (optional) number of results to return. Zero returns all
    ignoreTypos: false              // (optional) when false will attempt to sort through typos
    dropNonMatches: false           // (optional) when true, items that dont match wont be included
});

If you need to know the estimates of the matches, weighMatches() can be used instead:

import {Search} from "@darylcecile/nsearch";

// collection must be a list of object containing at least one key or label property
const collectionExample = [...];

// will return an object containing: 'weight', 'atomicProduct', and 'item'
// weight is the match estimation (percentage)
// atomicProduct is the match estimation in terms of characters (percentage)
// item is each induvidual item
Search.weighMatches(collectionExample, "cape crap treat");

Semantic and Search Tokenization

The semantic feature can be used to tokenize search queries (inspired by Google WebSearch - Refine Searches).

import {Semantics} from "@darylcecile/nsearch";

// returns an object which may contain: query, exclude, categories, limits, ranges, and exact
// query - the user query (excluding other filters; e.g. migration to gcp cli)
// exclude - a list of terms to exclude (e.g. ["azure"])
// categories - a dictionary of categories (e.g. {source:"notion.so", type:"meeting-notes"})
// limits - a dictionary of terms with 'over'/'under'/'within' limits
// ranges - a dictionary of terms with upper/lower values
// exact - any user queries within double quotes
Semantics.getFormattedSemantics(`source:notion.so type:meeting-notes migration to gcp -azure cli`);

For more examples of usages, check out the tests. More usage details Coming soon!

Local development

To get you started locally, pull down the repo and run one of the followin:

• Install: yarn - To install the dependencies
• Build: yarn build - To transpile the typescript files to javascript
• Test: yarn test - To run the tests (You may need to build before running)

Explaination and Disclaimer

This project allows for an easy way to filter and rank a collection of string/objects by its similary to a given query. For example, ordering a collection of results by a search query.

This POC was created to investigate and alternative way to filter/rank a list of strings, without checking that the query exists in each possible match. This solution is by no way the fastest or most efficient; plus it requires being able to loop through the collection multiple times - so avoid using this with large datasets if you can. My use-case for this was on a SSG search page.

Disclaimer: This project is a PoC and not fully developed. If you decide to use the contents of this work, do so at your own risk; with all its faults and quirks - PRs and feedback are both welcome. Again, this is obviously not battle-tested - so if you need to use it as-is, proceed with caution.