migration-guide.md

Migrate from v2 to v3

We are preparing to integrate the Helper directly inside InstantSearch, and for this are making some breaking changes. If you are happy using the current version of the Helper, there's no pressing need for you to upgrade to the next version.

Lodash

We have fully migrated away from lodash in v3. This means that there are some cases which used to accept incorrect shapes (objects where it should be arrays) will throw errors now.

URL sync

Synchronizing to the URL is no longer a responsibility of the Helper, but instead now it's a responsibility of the routing functionality of InstantSearch. This means the following methods no longer exist:

• algoliasearchHelper.url
• /url
• getStateAsQueryString
• getConfigurationFromQueryString
• getForeignConfigurationInQueryString
• setStateFromQueryString

Events

The event payload now always is an object, instead of multiple arguments:

on(
  "search",
  ({ state: SearchParameters, results: SearchResults }) => {/**/}
);
on(
  "change",
  ({ state: SearchParameters, results: SearchResults, isPageReset: boolean }) =>
    {/**/}
);
on(
  "searchForFacetValues",
  ({ state: SearchParameters, facet: string, query: string }) => {/**/}
);
on(
  "searchOnce",
  ({ state: SearchParameters }) => {/**/}
);
on(
  "result",
  ({ results: SearchResults, state: SearchParameters }) => {/**/}
);
on(
  "error",
  ({ error: Error }) => {/**/}
);
on(
  "searchQueueEmpty",
  () => {/**/}
);

Default values

SearchParameters no longer contains a default value for the parameters, from the previous undefined, "" or 0, we now have no more values on the object by default, this means an empty SearchParameters now looks like this:

{
  "facets": [],
  "disjunctiveFacets": [],
  "hierarchicalFacets": [],
  "facetsRefinements": {},
  "facetsExcludes": {},
  "disjunctiveFacetsRefinements": {},
  "numericRefinements": {},
  "tagRefinements": [],
  "hierarchicalFacetsRefinements": {}
}

Removed methods

• getQueryParameter

// With getQueryParameter
helper.getQueryParameter('hitsPerPage');

// Without getQueryParameter
helper.state.hitsPerPage;

• SearchParameters.filter

You need to filter the returned object yourself using e.g. Object.fromEntries(Object.entries().filter())

• SearchParameters.mutateMe