API: function based initial config on the Helper

[bobylito]

One thing that we've noticed is that modifying a SearchParameter object is much simpler that working with the raw data structure. Also implementations based on the data structure is likely to break at some point if it ever evolves, whereas with the functions of the SearchParameters we can maintain the same API while modifying the underlying structure.

Proposal

var helper = algoliasearchHelper(client, index, function(params) {
  return params.addDisjunctiveFacet('categories')
           .addDisjunctiveFacetRefinement('categories', 'shirts');
});

This won't remove the possibility to pass an object, it's just a more friendly alternative to set the configuration and the default parameters.

[vvo]

I am trying to see if it provides a nicer API than what we have today.

With the new API:

var helper = algoliasearchHelper(client, index, function(params) {
  return params
    .addDisjunctiveFacet('categories')
    .addHierarchicalFacet('products', {separator: '<'})
    .addDisjunctiveFacetRefinement('categories', 'shirts');
});

VS the current API:

var helper = algoliasearchHelper(client, index, {
  facets: ['categories'],
  hierarchicalFacets: [{
    products: {separator: '<'}
  }]
});
helper.addDisjunctiveFacetRefinement('categories', 'shirts');

I feel what we could ask ourselves here is: "What does this API brings today that cannot be done easily with the current API?" and I am not sure to find a lot of differences.

Still for sure your example feels less complex to understand: only function calls and no need to iterate on the helper multiple times.

[bobylito]

I feel what we could ask ourselves here is: "What does this API brings today that cannot be done easily with the current API?" and I am not sure to find a lot of differences.

You are right, for today, the benefits are thin. User wise it make only a slight difference.

However the programmatic API is more future proof (does not rely on structure that can change) and I would like to propose this alternative in order to deprecate the object one. Also proposing this would be also a win for instantsearch.js, for which this paradigm is closer.

Also providing a function means that it can be replay. Which could also be interesting for default parameters implementation.

[bobylito]

If the state is provided from somewhere else (like the URL or any cold storage like the local-storage) we would still need to have a way to provide a plain JS Object. In the case of this proposal we can still instanciate a new SearchParameters with just the JS object but this makes the implementation less straightforward.

var coldState = getStateFromSomewhere();
var h = algoliasearchHelper(client, index, () => new SearchParameters(coldState));