npm package: @projectfunction/nsearch
Author: Daryl Cecile
Latest version: 1.2.15


# 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:
```bash
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:
```ts
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:
```ts
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](https://support.google.com/websearch/answer/2466433?hl=en)).

```ts
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.