isabella232 / queries

Module that offers a variety of queries around npms data.

@npms/queries

Module that offers a variety of queries around npms data.

Installation

$ npm install @npms/queries

Usage

For now, only queries related to search are available. Though, the goal of this module is to provide other interesting queries in the near future, such as top ranked modules, top authors, etc.

.search(q, esClient, [options]) -> Promise

Performs a search query.

Besides normal text, q supports qualifiers to express filters and other modifiers. The esClient accepts a elasticsearch instance or a config to instantiate it.

You may read the API docs to know which qualifiers are available.

const queries = require('@npms/queries');

// ...
queries.search('test framework', esClient)
.then((res) => {
    console.log('total', res.total);
    console.log('results', res.results);
});

Available options:

• from: The offset in which to start searching from, defaults to 0
• size: The total number of results to return, defaults to 25
• throwOnInvalid: Whether to reject the promise if the query has invalid qualifiers or not, defaults to false (if false, invalid qualifiers will be removed from q)

.search.suggestions(q, esClient, [options]) -> Promise

Fetch search suggestions to be typically displayed when doing autocomplete.

Only normal text is supported in q but any qualifiers will be automatically discarded. The esClient accepts a elasticsearch instance or a config to instantiate it.

const queries = require('@npms/queries');

// ...
queries.search.suggestions('gulp', esClient)
.then((suggestions) => console.log('suggestions', suggestions));

Available options:

• boostExact: How much should the score of exact matches be boosted? defaults to 100000.
• size: The total number of results to return, defaults to 25
• analyzerWeight: How much should we weight the analyzer's score.final by? defaults to 1.0.
• scoreWeight: How much should we weight the search _score? defaults to 0.3.

.search.similar(q, esClient, [options]) -> Promise

Perform a fuzzy search for similarly named packages.

Results are ranked based on a combination of analyzer weightings (quality, popularity, maintenance) and the _score returned by the fuzzy match.

const queries = require('@npms/queries');

// ...
queries.search.similar('chaik', esClient)
.then(results => {
  // perhaps we were instead looking for chalk?
});

Available options:

• size: The total number of results to return, defaults to 10.
• analyzerWeight: How much should we weight the analyzer's score.final by? defaults to 2.2.
• scoreWeight: How much should we weight the search _score? defaults to 1.5.
• minScore: defaults to 4.5.

the above default values were based on trial and error examining the top npm modules, they will likely change over time.

Tests

$ npm test
$ npm test-cov to get coverage report

License

Released under the MIT License.