algolia / algoliasearch-helper-js

Helper for implementing advanced search features with Algolia

algoliasearch-helper-js has a new home 👋

This project has moved and is now part of the InstantSearch monorepo! The library remains unchanged and is still available on npm and CDNs like jsDelivr.

You can browse the code, find existing issues and follow new releases over there.

algoliasearch-helper-js's Issues

If getRankingInfo is set, then the helper should aggregate timeoutCounts for disjunctive facets

getRankingInfo is a flag of the API that asks the engine to give informations about timeouts in queries. Such information is useful to know is the facets_stats are estimated or accurate.

All state mutation should trigger a search.

Handle numeric filters

add functions to handle numeric filters

Falsy comparison in removeNumericRefinement

In SearchParameters/index.js:removeNumericRefinement, the parameter value is never used, and the if ( value ) might evaluate to false if the numeric filter value is 0.

See _.isUndefined

Port to client v3.1

Replace batch to new search api.

What about numeric facettings ?

Right now, if we want a slider, we have an issue : a disjunctiveFacet doesn't ignore the numericRefinements on itself, which could make sense in some cases, but kills the whole idea of using facetting for this since the facet stats which come back take into account the newly created numericRefinements. How do we handle it ?
This question might also bring the same question with facetsExcludes, but I'm pretty sure that I we exclude a value from a disjunctive facet, we really don't want it at all.

Labels, values and i18n

At some we want to be able to retrieve and sort the values of a facet (see #38). This is great but it doesn't to provide another layer of indirections that can happen if we do internationalisation. In this case the values stored in Algolia are ID's not human readable values. And of course, some sort should apply on those values and not on ID's.

So long story short, we need to provide a way (in a second step) to not only fetch the values sorted but provide an i18n mechanism so we can sort the translated values.

Count of facets not retrieved

Test case on the sample ( http://algolia.github.io/algoliasearch-helper-js/examples/instantsearch+helper.html ):

• the value "marshall" for the facet manufacturer is not displayed
• search for "marshall" in query input
• the value "marshall" is displayed with the count equals to 5
• check the "marshall" facet value in manufacturer
• value for this facet is still 5
• remove marshall from the query input
• value is 0 but should be 5

Update example with cdn version of algolia client.

Seems that attributesToRetrieve and attributesToHighlight are ignored completely

I tried with these options:

{
"hitsPerPage": 12,
"attributesToRetrieve":"nam1,field1,field2",
"attributesToHighlight":"name"
}

The response contains all the fields irrespective of the specified fields: name, field1 and field2.

The query param does not contain the attributesToRetrieve param as well.

Any other way to set these attributes?

AlgoliaSearchHelper: Simplify the hierarchical facets refinement

To be able to build such facet tree without messy code.

(originally by @redox on algolia/algoliasearch-client-javascript#35)

Remove holdSearch parameter!

See #36 for complete discussion.

Expected API :

helper.setDisjunctiveRefine( "facet1", "value" )
      .setQuery( "some input" )
      .search();

• Remove holdsearch parameter
• Remove autosearch magic
• Create a setQuery function and let search be the method that executes the search
• Make mutation API chainable
• Update tests
• Update samples

Clear refinements matching a specific criteria

Something like:

helper.clearRefinements(function(facet, value) {
  return facet === "foo" && value.indexOf("bar") === 0;
});

imported from algolia/algoliasearch-client-javascript#33

How to handle extraqueries in a event way...

V2 is event based, but what is an extra query in this context. Does it still make sense?

Conjunctive facets aren't stored in a array

It works fine except when facetting an array attribute.

Expose helper functions to know the selected disjunctive refinements

Same as isExclude or isRefine but for disjunctive facets.

add algoliasearchHelper.version

It's always very interesting to be able to see the module.version from the build.

We did it in the js client like that: https://github.com/algolia/algoliasearch-client-js/blob/f5068b73c23c1c812e16f702648593883b56de84/src/create-algoliasearch.js#L13.

It's using a browserify transform named packageify, that includes only the version, not the full package.

• add .version property on the helper, reading package.json.version
• use packageify transform to read and append version

Handle the whole scope of numeric filtering

The algolia API has the ability to set multiple values for a single parameter with or and and. https://www.algolia.com/doc#numericFilters

The helper api should be simple and not json based :P 🌴

setTypoTolerance

We cannot change the typoTolerance attribute. This is useful when we want to automatically search on ID

Remove extraQueries in v2

There are questions around the use of the extraQueries. So we might as well get rid of them for initial v2 and reintroduce later in a better form.

Every actions that may change the number of pages should reset the current page to the first

When we do a refinement right now, it doesn't reset the current, leading to inconsistencies.

Complete JSDoc

• events emitted by the component
• SearchParameters

Refresh method

Create a method to be able to refresh the results : execute the same query as in the current state of the helper.

Compose multiple search parameters into one big batch

Handle the URL Parameters

Have an optional way to:
Load the params of the state from URL hash
Set the URL hash when state changes

Shouldn't isRefined automatically detect the type of the facet ?

Like toggleRefine and others ?

Ability to dedup the hits retrieved from multiple nested queries

All search state parameters should be overridable once on search

Search should be usable for triggering search with existing parameters as well as for doing a one time override of the search parameters.

JS Doc not obviously available

Helper should emit an event when the state is updated

When the component is updated the component should emit an "state-changed" event.

Distinct : true with no filters nor query, automatic behavior?

We can't use the distinct flag set to true when the query is empty because the algolia engine returns an error. Why don't we change this parameter automatically when the query is empty or if we do not use filters?

Missing setter for search result page size

I did not find any documentation/sample on setting page size of search result. It will be great if someone creates a better documentation to make it more usable. For the time being I used the following workaround:

helper.search(query, function (err, content) {/* callback */}, {hitsPerPage:12});

Batch queries and helper

Hey,

Using the helper with batch queries doesn't feel very natural right now. You have a "main" query, which can use all methods like toggleRefine(), and "extra" queries which cannot.

Do you think it'd be possible to make the helper handle all queries the same way?

Thanks!

Avoid callback for outdated queries

Depending on the network, it may happen that a request sent before another is received after. This should not happen, and shouldn't be left to the responsibility of the user.

Setters/getters for misc parameters

Add functions to set and get the value for any parameters that will be used for the the search.

Fix the case where the distinct is applicable

@redox said :

Beware, you can use distinct=true if there are no facet filters, but some tag filters or some numeric filters or a query.

So probably something like:

if (!query && facetFilters.length === 0 && numericFilters.length === 0 && tagFilters.length === 0) {
  distinct = false;
}

Reimplement AlgoliaExplainResults

Previously in algoalisearch v2 we had AlgoliaExplainResults.

Would it be a good idea to reimplement it in the upcoming V2 helper?

The `processingTimeMS` should be summed

When we're dealing with disjunctive refinements, it generates multiple queries -> we need to sum the processingTimeMS of each answer to compute the final one.

The facet order should be consistent with the configuration

There is no guarantee on the order of the facets for the moment. The user has to manually sort its facets...

Removing of refinements

It be nice to be able to remove all refinements for a particular facet (conjunctive or disjunctive) without having to modify the helper refinements object from outside the helper.

The helper should provide a way to know how many queries it will execute

One problem with the helper is that it's a black box that does queries without letting the user know how many operations it'll actually do on Algolia.

Sort facets values

Copy of @redox suggestion :

Would be cool to be able to sort the values as well. I want my facet1 values sorted by count (default) and my facet2 values sorted by lexicographical order for instance.

{
  facets: [ "facet1", "facet2" ] // default sort order
}

or

{
  facets: [
    {attribute: "facet1", sortFunction: Helper.sortByCountDesc },
    {attribute: "facet2", sortFunction: Helper.sortByValueAsc },
    {attribute: "facet3", sortFunction: function custom(a, b) { /* */ } }
   ]
}

algoliasearch.helper is not on jsDelivr website/CDN

Can you have a look why @bobylito?

We need it for V3 release of course.

The response should treated with the same parameters used for the request

If you make programmatically make two request with the helper, the first response will use the state of the second request.

Example :

helper.clearDisjunctiveRefine( "facet", "value1" );
helper.addDisjunctiveRefine( "facet", "value2" );

This will end up in the clear response to be treated as if there was a refinement expecting a second request.

Workaround : use the 'holdSearch' flag to keep the helper from doing two requests

helper.clearDisjunctiveRefine( "facet", "value1", true );
helper.addDisjunctiveRefine( "facet", "value2" );

Possible fixes :

• bind the state to the callback. Because the state is immutable (in theory), each state is independent. here it might not work because of arrays. Have to dig a bit here.
• debounce over a few ms the internal search function. This will work but will add some complexity and magic.
• cancel first request if we are initiating a new search. Could have positive side effects on weird latency issues. I think it's feasible, must check.

is holdSearch parameter counter intuitive?

Add an optional parameter to hold the search when the state is mutated

Add a last parameter "holdSearch" to the state mutating methods of the helper.

helper.toggleRefine( "facet1", "value1", true);
helper.toggleRefine( "facet2", "valueA", true);
helper.search();

support promises

As the algoliasearch client support both promises and callbacks.

As the helper is a smart wrapper around our JavaScript client.

It would be great for the helper to support both promises and callbacks as the API it's wrapping.

So that we can write examples using both callbacks and promises and people never complain about one or another missing implementation ("I am using promises on the client, why can't I have promises in the helper?").

Persistent facets

In the case of menus, we want to be able to keep the reference to certain facets. But that's a pretty boring task that can be handled in the helper.

For this, it would be great that we can define some facets as persistent when we initialize the helper. It would need to trigger a blank search once, and cache the results. Those cached results will be then served through the search results object with some function or information to evaluate if the facet is available with the current search.

Cherry pick pre-v3 in js client master branch previous commits

Just in case, we need to ensure we cherry picked algolia/algoliasearch-client-javascript@b896bf3 and algolia/algoliasearch-client-javascript@11cecaa.

Commits were done on js client master branch after starting working on V3

Use an immutability library for arrays and objects in SearchParameters

Although the state is mostly immutable in SearchParameters, the inner structures based on array and objects are not due to their nature of native objects. It would be nice to use a library like Immutable to change the implementations of those structures. We could also benefits from data structures like Set or OrderedMap.

We should also make sure to leak the very minimal amount of abstractions to the users...