Research
Recent Trends in Malicious Packages Targeting Discord
The Socket research team breaks down a sampling of malicious packages that download and execute files, among other suspicious behaviors, targeting the popular Discord platform.
algoliasearch-helper
Advanced tools
Readme
Coming from V1 (or js client v2)? Read the migration guide to the new version of the Helper.
The JavaScript helper is an advanced library we provide to our users. If you are looking to build a complete search interface, we recommend you to use instantsearch.js. If you want to build an autocomplete menu, see autocomplete.js.
This module is the companion of the algolia/algoliasearch-client-js. It helps you keep track of the search parameters and provides a higher level API.
This is the library you will need to easily build a good search UX like our instant search demo.
A small example that uses Browserify to manage modules.
var algoliasearch = require('algoliasearch');
var algoliasearchHelper = require('algoliasearch-helper');
var client = algoliasearch('appId', 'apiKey');
var helper = algoliasearchHelper(client, 'indexName', {
facets: ['mainCharacterFirstName', 'year'],
disjunctiveFacets: ['director']
});
helper.on('result', function(data){
console.log(data.hits);
});
helper.addDisjunctiveFacetRefinement('director', 'Clint Eastwood');
helper.addDisjunctiveFacetRefinement('director', 'Sofia Coppola');
helper.addNumericRefinement('year', '=', 2003);
// Search for any movie filmed in 2003 and directed by either C. Eastwood or S. Coppola
helper.search();
See more examples in the examples folder
<script src="https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.angular.js"></script>
<script src="dist/algoliasearch.helper.min.js"></script>
<script type="text/javascript">
angular.module('searchApp', ['ngSanitize', 'algoliasearch'])
.controller('searchController', ['$scope', '$sce', 'algolia', function($scope, $sce, algolia) {
var algolia = algolia.Client('applicationId', 'apiKey');
$scope.q = '';
$scope.content = null;
$scope.helper = algoliasearchHelper(algolia, 'indexName', {
facets: ['type', 'shipping'],
disjunctiveFacets: ['category', 'manufacturer'],
hitsPerPage: 5,
});
$scope.helper.on('result', function(content) {
$scope.$apply(function() {
$scope.content = content;
});
});
$scope.toggleRefine = function($event, facet, value) {
$event.preventDefault();
$scope.helper.toggleRefine(facet, value).search();
};
$scope.$watch('q', function(q) {
$scope.helper.setQuery(q).search();
});
$scope.helper.search();
}]);
</script>
You can see the full Angular example here
There is also a complete JSDoc
<script>
tagUse our jsDelivr build:
<script src="https://cdn.jsdelivr.net/algoliasearch.helper/2/algoliasearch.helper.min.js"></script>
npm install algoliasearch-helper
bower install algoliasearch-helper
var helper = algoliasearchHelper(client, 'indexName'/*, parameters*/);
modify the parameters of the search (usually through user interactions)
helper.setQuery('iphone').addFacetRefinement('category', 'phone')
trigger the search (after all the modification have been applied)
helper.search()
read the results (with the event "result" handler) and update the UI with the results
helper.on('result', function(results) { updateUI(results); });
go back to 1
AlgoliasearchHelper: the helper. Keeps the state of the search, makes the queries and calls the handlers when an event happen.
SearchParameters: the object representing the state of the search. The current state is stored in helperInstance.state
.
SearchResults: the object in which the Algolia answers are transformed into. This object is passed to the result event handler. An example of SearchResults in JSON is available at the end of this readme
The search is triggered by the search()
method.
It takes all the previous modifications to the search and uses them to create the queries to Algolia. The search parameters are immutable.
Example:
var helper = algoliasearchHelper(client, indexName);
// Let's monitor the results with the console
helper.on('result', function(content) {
console.log(content);
});
// Let's make an empty search
// The results are all sorted using the dashboard configuration
helper.search();
// Let's search for "landscape"
helper.setQuery('landscape').search();
// Let's add a category "photo"
// Will make a search with "photo" tag and "landscape" as the query
helper.addTag('photo').search();
The helper is a Node.js EventEmitter instance.
result
: get notified when new results are received. The handler function will receive
two objects (SearchResults
and SearchParameters
).
error
: get notified when errors are received from the API.
change
: get notified when a property has changed in the helper
search
: get notified when a request is sent to Algolia
result
eventhelper.on('result', updateTheResults);
result
event oncehelper.once('result', updateTheResults);
result
listenerhelper.removeListener('result', updateTheResults);
result
listenershelper.removeAllListeners('result');
All the methods from Node.js EventEmitter class are available.
helper.setQuery('fruit').search();
Facets are filters to retrieve a subset of an index having a specific value for a given attribute. First you need to define which attribute will be used as a facet in the dashboard: https://www.algolia.com/explorer#?tab=display
Refinements are ANDed by default (Conjunctive selection).
var helper = algoliasearchHelper(client, indexName, {
facets: ['ANDFacet']
});
helper.addFacetRefinement('ANDFacet', 'valueOfANDFacet').search();
helper.removeFacetRefinement('ANDFacet', 'valueOfANDFacet').search();
Refinements are ORed by default (Disjunctive selection).
var helper = algoliasearchHelper(client, indexName, {
disjunctiveFacets: ['ORFacet']
});
helper.addDisjunctiveFacetRefinement('ORFacet', 'valueOfORFacet').search();
helper.removeDisjunctiveFacetRefinement('ORFacet', 'valueOfORFacet').search();
Filter so that we do NOT get a given facet
var helper = algoliasearchHelper(client, indexName, {
facets: ['ANDFacet']
}).search();
helper.addFacetExclusion('ANDFacet', 'valueOfANDFacetToExclude');
helper.removeFacetExclusion('ANDFacet', 'valueOfANDFacetToExclude');
Filter over numeric attributes with math operations like =
, >
, <
, >=
, <=
. Can be used for numbers and dates (if converted to timestamp)
var helper = algoliasearchHelper(client, indexName, {
disjunctiveFacets: ['numericAttribute']
});
helper.addNumericRefinement('numericAttribute', '=', '3').search();
// filter to only the results that match numericAttribute=3
helper.addNumericRefinement('numericAttribute', '=', '4').search();
// filter to only the results that match numericAttribute=3 AND numericAttribute=4
// On another numeric with no previous filter
helper.addNumericRefinement('numericAttribute2', '=', ['42', '56', '37'] ).search();
// filter to only the results that match numericAttribute=42 OR numericAttribute2=56 OR numericAttribute2=37
helper.removeNumericRefinement('numericAttribute', '=', '3').search();
// for the single operator = on numericAttribute
helper.removeNumericRefinement('numericAttribute', '=').search();
// for all the refinements on numericAttribute
helper.removeNumericRefinement('numericAttribute').search();
Hierarchical facets are useful to build such navigation menus:
| products
> fruits
> citrus
| strawberries
| peaches
| apples
Here, we refined the search this way:
To build such menu, you need to use hierarchical faceting:
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1']
}]
});
Requirements: All the specified attributes
must be defined in your Algolia settings
as attributes for faceting.
Given your objects looks like this:
{
"objectID": "123",
"name": "orange",
"categories": {
"lvl0": "fruits",
"lvl1": "fruits > citrus"
}
}
And you refine products
:
helper.toggleFacetRefinement('products', 'fruits > citrus');
You will get a hierarchical presentation of your facet values: a navigation menu of your facet values.
helper.on('result', function(data){
console.log(data.hierarchicalFacets[0]);
// {
// 'name': 'products',
// 'count': null,
// 'isRefined': true,
// 'path': null,
// 'data': [{
// 'name': 'fruits',
// 'path': 'fruits',
// 'count': 1,
// 'isRefined': true,
// 'data': [{
// 'name': 'citrus',
// 'path': 'fruits > citrus',
// 'count': 1,
// 'isRefined': true,
// 'data': null
// }]
// }]
// }
});
To ease navigation, we always:
fruits > citrus > *
: n + 1)fruits > citrus
=> fruits
: n -1) categoriesYour records can also share multiple categories between one another by using arrays inside your object:
{
"objectID": "123",
"name": "orange",
"categories": {
"lvl0": ["fruits", "color"],
"lvl1": ["fruits > citrus", "color > orange"]
}
},
{
"objectID": "456",
"name": "grapefruit",
"categories": {
"lvl0": ["fruits", "color", "new"],
"lvl1": ["fruits > citrus", "color > yellow", "new > citrus"]
}
}
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1'],
separator: '|'
}]
});
helper.toggleFacetRefinement('products', 'fruits|citrus');
Would mean that your objects look like so:
{
"objectID": "123",
"name": "orange",
"categories": {
"lvl0": "fruits",
"lvl1": "fruits|citrus"
}
}
The default sort for the hierarchical facet view is: isRefined:desc (first show refined), name:asc (then sort by name)
.
You can specify a different sort order by using:
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1'],
sortBy: ['count:desc', 'name:asc'] // first show the most common values, then sort by name
}]
});
The available sort tokens are:
Let's say you have a lot of levels:
- fruits
- yellow
- citrus
- spicy
But you only want to get the values starting at "citrus", you can use rootPath
You can specify an root path to filter the hierarchical values
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1', 'categories.lvl2', 'categories.lvl3'],
rootPath: 'fruits > yellow > citrus'
}]
});
Having a rootPath will refine the results on it automatically.
By default the hierarchical facet is going to return the child and parent facet values of the current refinement.
If you do not want to get the parent facet values you can set showParentLevel to false
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1'],
showParentLevel: false
}]
});
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1'],
separator: '|'
}]
});
helper.toggleFacetRefinement('products', 'fruits|citrus');
var breadcrumb = helper.getHierarchicalFacetBreadcrumb('products');
console.log(breadcrumb);
// ['fruits', 'citrus']
console.log(breadcrumb.join(' | '));
// 'fruits | citrus'
helper.clearRefinements().search();
helper.clearRefinements('ANDFacet').search();
helper.clearRefinements(function(value, attribute, type) {
return type === 'exclude' && attribute === 'ANDFacet';
}).search();
helper.on('result', function(result) {
// Get the facet values for the attribute age
result.getFacetValues('age');
// It will be ordered :
// - refined facets first
// - then ordered by number of occurence (bigger count -> higher in the list)
// - then ordered by name (alphabetically)
});
helper.on('result', function(result) {
// Get the facet values for the attribute age
result.getFacetValues('age', {sortBy: ['count:asc']});
// It will be ordered by number of occurence (lower number => higher position)
// Elements that can be sorted : count, name, isRefined
// Type of sort : 'asc' for ascending order, 'desc' for descending order
});
This only apply on numeric based facets/attributes.
helper.on('result', function(result) {
// Get the facet values for the attribute age
result.getFacetStats('age');
});
Tags are an easy way to do filtering. They are based on a special attribute in the records named _tags
, which can be a single string value or an array of strings.
helper.addTag('landscape').search();
helper.removeTag('landscape').search();
helper.clearTags().search();
helper.getPage();
helper.setPage(3).search();
During a search, changing the parameters will update the result set, which can then change the number of pages in the result set. Therefore, the behavior has been standardized so that any operation that may change the number of page will reset the pagination to page 0.
This may lead to some unexpected behavior. For example:
helper.setPage(4);
helper.getPage(); // 4
helper.setQuery('foo');
helper.getPage(); // 0
Non exhaustive list of operations that trigger a reset:
Index can be changed. The common use case is when you have several slaves with different sort order (sort by relevance, price or any other attribute).
helper.setIndex('index_orderByPrice').search();
var currentIndex = helper.getIndex();
Sometime it's convenient to reuse the current search parameters with small changes
without changing the state stored in the helper. That's why there is a function
called searchOnce
. This method does not trigger change
or error
events.
In the following, we are using searchOnce
to fetch only a single element using
all the other parameters already set in the search parameters.
var state = helper.searchOnce(
{hitsPerPage: 1},
function(error, content, state) {
// if an error occured it will be passed in error, otherwise its value is null
// content contains the results formatted as a SearchResults
// state is the instance of SearchParameters used for this search
});
var state1 = helper.searchOnce({hitsPerPage: 1})
.then(function(res) {
// res contains
// {
// content : SearchResults
// state : SearchParameters (the one used for this specific search)
// }
});
helper.setState(algoliasearchHelper.url.getStateFromQueryString(qs));
// to an object with the query and all the refinements
helper.getState(['query', 'attribute:*']);
var state = algoliasearchHelper.url.getStateFromQueryString(qs);
var otherConf = algoliasearchHelper.url.getUnrecognizedParametersInQueryString(qs);
var state = helper.getState();
var qs = algoliasearchHelper.url.getQueryStringFromState(state);
There are lots of other parameters you can set.
var helper = algoliasearchHelper(client, indexName, {
hitsPerPage: 50
});
helper.setQueryParameter('hitsPerPage', 20).search();
Name |
Type |
Description |
advancedSyntax |
boolean |
Enable the advanced syntax. |
allowTyposOnNumericTokens |
boolean |
Should the engine allow typos on numerics. |
analytics |
boolean |
Enable the analytics |
analyticsTags |
string |
Tag of the query in the analytics. |
aroundLatLng |
string |
Center of the geo search. |
aroundLatLngViaIP |
boolean |
Center of the search, retrieve from the user IP. |
aroundPrecision |
number |
Precision of the geo search. |
aroundRadius |
number |
Radius of the geo search. |
minimumAroundRadius |
number |
Minimum radius of the geo search. |
attributesToHighlight |
string |
List of attributes to highlight |
attributesToRetrieve |
string |
List of attributes to retrieve |
attributesToSnippet |
string |
List of attributes to snippet |
disjunctiveFacets |
Array.<string> |
All the declared disjunctive facets |
distinct |
boolean|number |
Remove duplicates based on the index setting attributeForDistinct |
facets |
Array.<string> |
All the facets that will be requested to the server |
getRankingInfo |
integer |
Enable the ranking informations in the response |
hitsPerPage |
number |
Number of hits to be returned by the search API |
ignorePlurals |
boolean |
Should the plurals be ignored |
insideBoundingBox |
string |
Geo search inside a box. |
insidePolygon |
string |
Geo search inside a polygon. |
maxValuesPerFacet |
number |
Number of values for each facetted attribute |
minWordSizefor1Typo |
number |
Number of characters to wait before doing one character replacement. |
minWordSizefor2Typos |
number |
Number of characters to wait before doing a second character replacement. |
optionalWords |
string |
Add some optional words to those defined in the dashboard |
page |
number |
The current page number |
query |
string |
Query string of the instant search. The empty string is a valid query. |
queryType |
string |
How the query should be treated by the search engine. Possible values: prefixAll, prefixLast, prefixNone |
removeWordsIfNoResults |
string |
Possible values are "lastWords" "firstWords" "allOptional" "none" (default) |
replaceSynonymsInHighlight |
boolean |
Should the engine replace the synonyms in the highlighted results. |
restrictSearchableAttributes |
string |
Restrict which attribute is searched. |
synonyms |
boolean |
Enable the synonyms |
tagFilters |
string |
Contains the tag filters in the raw format of the Algolia API. Setting this parameter is not compatible with the of the add/remove/toggle methods of the tag api. |
typoTolerance |
string |
How the typo tolerance behave in the search engine. Possible values: true, false, min, strict |
Here is an example of a result object you get with the result
event.
{
"hitsPerPage": 10,
"processingTimeMS": 2,
"facets": [
{
"name": "type",
"data": {
"HardGood": 6627,
"BlackTie": 550,
"Music": 665,
"Software": 131,
"Game": 456,
"Movie": 1571
},
"exhaustive": false
},
{
"exhaustive": false,
"data": {
"Free shipping": 5507
},
"name": "shipping"
}
],
"hits": [
{
"thumbnailImage": "http://img.bbystatic.com/BestBuy_US/images/products/1688/1688832_54x108_s.gif",
"_highlightResult": {
"shortDescription": {
"matchLevel": "none",
"value": "Safeguard your PC, Mac, Android and iOS devices with comprehensive Internet protection",
"matchedWords": []
},
"category": {
"matchLevel": "none",
"value": "Computer Security Software",
"matchedWords": []
},
"manufacturer": {
"matchedWords": [],
"value": "Webroot",
"matchLevel": "none"
},
"name": {
"value": "Webroot SecureAnywhere Internet Security (3-Device) (1-Year Subscription) - Mac/Windows",
"matchedWords": [],
"matchLevel": "none"
}
},
"image": "http://img.bbystatic.com/BestBuy_US/images/products/1688/1688832_105x210_sc.jpg",
"shipping": "Free shipping",
"bestSellingRank": 4,
"shortDescription": "Safeguard your PC, Mac, Android and iOS devices with comprehensive Internet protection",
"url": "http://www.bestbuy.com/site/webroot-secureanywhere-internet-security-3-devi…d=1219060687969&skuId=1688832&cmp=RMX&ky=2d3GfEmNIzjA0vkzveHdZEBgpPCyMnLTJ",
"name": "Webroot SecureAnywhere Internet Security (3-Device) (1-Year Subscription) - Mac/Windows",
"category": "Computer Security Software",
"salePrice_range": "1 - 50",
"objectID": "1688832",
"type": "Software",
"customerReviewCount": 5980,
"salePrice": 49.99,
"manufacturer": "Webroot"
},
....
],
"nbHits": 10000,
"disjunctiveFacets": [
{
"exhaustive": false,
"data": {
"5": 183,
"12": 112,
"7": 149,
...
},
"name": "customerReviewCount",
"stats": {
"max": 7461,
"avg": 157.939,
"min": 1
}
},
{
"data": {
"Printer Ink": 142,
"Wireless Speakers": 60,
"Point & Shoot Cameras": 48,
...
},
"name": "category",
"exhaustive": false
},
{
"exhaustive": false,
"data": {
"> 5000": 2,
"1 - 50": 6524,
"501 - 2000": 566,
"201 - 500": 1501,
"101 - 200": 1360,
"2001 - 5000": 47
},
"name": "salePrice_range"
},
{
"data": {
"Dynex™": 202,
"Insignia™": 230,
"PNY": 72,
...
},
"name": "manufacturer",
"exhaustive": false
}
],
"query": "",
"nbPages": 100,
"page": 0,
"index": "bestbuy"
}
This project works on any ES5 browser, basically >= IE9+.
FAQs
Helper for implementing advanced search features with algolia
We found that algoliasearch-helper demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
The Socket research team breaks down a sampling of malicious packages that download and execute files, among other suspicious behaviors, targeting the popular Discord platform.
Security News
Socket CEO Feross Aboukhadijeh joins a16z partners to discuss how modern, sophisticated supply chain attacks require AI-driven defenses and explore the challenges and solutions in leveraging AI for threat detection early in the development life cycle.
Security News
NIST's new AI Risk Management Framework aims to enhance the security and reliability of generative AI systems and address the unique challenges of malicious AI exploits.