Algolia InstantSearch

The AlgoliaSearchHelper is the primary interface of the Helper library. It manages search parameters and coordinates the search cycle using an event-driven architecture. Instead of just returning a promise, it emits events to ensure that the UI remains synchronized with the latest request, preventing race conditions where older search results might arrive after newer ones due to network latency.

Key Events:

• change: Triggered when a search parameter is set or updated.
• search: Triggered when a search request is sent to Algolia.
• result: Triggered when results are retrieved from Algolia.
• error: Triggered when Algolia returns an error.
• searchQueueEmpty: Triggered when there are no more pending searches.
• searchForFacetValues: Triggered when a search is sent via searchForFacetValues.
• searchOnce: Triggered when a search is sent via searchOnce.

The algoliasearch-helper is a companion library for the algoliasearch-client-javascript. It provides a higher-level API to manage search parameters, handle pagination, manage facet exclusions, and implement disjunctive faceting (searching across two or more values of the same facet).

Recommendation:

• For building a complete search interface, use InstantSearch.
• For building an autocomplete menu, use Autocomplete.
• Use the Helper when you need a programmatic way to track search parameters and manage the search state without a full UI framework.

Connectors allow you to decouple the search logic from the UI rendering. To create a custom widget:

1. Define a render function that receives renderOptions and isFirstRender.
2. Wrap this render function with the connector (e.g., connect{{ pascalCaseName }}).
3. Register the resulting custom widget using search.addWidgets().

import { connect{{ pascalCaseName }} } from '{{ packageName }}';

// 1. Create a render function
const render{{ pascalCaseName }} = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const custom{{ pascalCaseName }} = connect{{ pascalCaseName }}(
  render{{ pascalCaseName }}
);

// 3. Instantiate
search.addWidgets([
  custom{{ pascalCaseName }}(
    {
      // instance params
    },
  ),
]);

The helper follows a cyclical state-driven lifecycle:

1. Modify Parameters: Update search state via user interactions (e.g., helper.setQuery('iphone')).
2. Trigger Search: Execute the query after modifications are applied using helper.search().
3. Read Results: Use the result event handler to receive the transformed Algolia answers and update the UI.
4. Repeat: Return to step 1 based on further user interaction.