feat(core): introduce Requester API

[francoischalifour]

Description

Autocomplete relied on the getAlgoliaHits function coming from @algolia/autocomplete-preset-algolia to query Algolia indices. Since this function is used outside of any scoped container, we cannot control the requests sent to Algolia and to other backends.

The idea of this Requester API is to take control over these search calls to transform them and batch them. Batching Algolia calls significantly reduces the amount of requests sent to Algolia, and therefore reduces the cost customers pay to use federated search experiences with Autocomplete.

Imagine you have the following sources in Autocomplete:

• Recent Searches (doesn't target the network)
• Query Suggestions hits
• Category facet hits
• Brand facet hits

With the previous API, this would result in 3 network requests sent to Algolia at every key stroke. With this new Requester API, this results in a single network request because we're able to batch all queries (regular queries and facet queries too).

How

In terms of public API, only the requesters' names change:

• getAlgoliaHits → getAlgoliaResults
• getAlgoliaFacetHits → getAlgoliaFacets

The previous requesters were directly calling searchClient.search(), but they now just become descriptions (i.e., object that we're able to interpret internally).

type RequesterDescription<THit> = {
  searchClient: SearchClient;
  queries: MultipleQueriesQuery[];
  transformResponse: TransformResponse<THit>;
  execute: Execute<THit>;
};

These descriptions are now understood by our internal resolving mechanism, that groups descriptions based on their searchClient and their execute reference (execute is a reference to an internal fetchAlgoliaResults function which never changes user-land yet).

This means that if multiple sources use the same searchClient identity, we'll group them together to send a single network requests and redistribute the results to their respective callers (identified with their source ID). It is now required that sourceIds are unique, we throw an error if they're not.

Usage

autocomplete({
  container: '#autocomplete',
  getSources({ query }) {
    return [
      {
        sourceId: 'suggestions',
        getItems({ setContext }) {
          return getAlgoliaResults<QuerySuggestionsHit>({
            searchClient,
            queries: [
              { indexName: 'instant_search_demo_query_suggestions', query },
            ],
            transformResponse({ hits, results }) {
              const [suggestions] = results;

              setContext({
                suggestionsProcessingTime: suggestions.processingTimeMS,
              });

              return hits;
            },
          });
        },
        // ...
      },
      {
        sourceId: 'products',
        getItems() {
          return getAlgoliaResults<ProductHit>({
            searchClient,
            queries: [
              { indexName: 'instant_search', query },
              { indexName: 'instant_search_movies', query },
            ],
          });
        },
        // ...
      },
      {
        sourceId: 'categories',
        getItems() {
          return getAlgoliaFacets({
            searchClient,
            queries: [
              {
                indexName: 'instant_search',
                type: 'facet',
                facet: 'categories',
                params: {
                  facetQuery: query,
                },
              },
            ],
          });
        },
        // ...
      },
    ];
  },
});

Notice that we're not able to use getAlgoliaResults(/* ... *).then() anymore because it returns an object and not a promise. It's replaced by the transformResponse param.

Changes summary

• getAlgoliaHits → getAlgoliaResults
• getAlgoliaFacetHits → getAlgoliaFacets
• sourceIds must be unique

What's next

This is API is a drastic change to how our internal mechanism work, we plan to release this new API quite silently on a new alpha tag and ask current users to update their apps to report any wrong behavior.

This PR is just the foundation of powerful requesters in Autocomplete, but we would like to leverage more features in the future:

• Skip outdated requests to always reflect the latest state in the UI (because search-as-you-type triggers a lot of network requests that might get resolved in a order different than their caller order)
• Defer network calls (for Algolia Answers for instance)
• Sequence network calls (render-as-you-fetch, wait for all call to resolve, etc.)

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 81d9ff7:

Sandbox	Source
@algolia/autocomplete-example-github-repositories-custom-plugin	Configuration
@algolia/autocomplete-example-multiple-datasets-with-headers	Configuration
@algolia/autocomplete-example-playground	Configuration
@algolia/autocomplete-example-query-suggestion-with-categories	Configuration
@algolia/autocomplete-example-query-suggestions-with-hits	Configuration
@algolia/autocomplete-example-query-suggestions-with-inline-categories	Configuration
@algolia/autocomplete-example-query-suggestions-with-recent-searches-and-categories	Configuration
@algolia/autocomplete-example-query-suggestions-with-recent-searches	Configuration
@algolia/autocomplete-example-query-suggestions	Configuration
@algolia/autocomplete-example-react-renderer	Configuration

[Haroenv]

looks great!

[sarahdayan]

Two followup PRs:

• Documentation: docs: document Requester API #541
• Example and test fixes: fix: update examples and tests with Requester API #542

[Haroenv]

without testing the detailed behaviour, the code definitely looks good and much clearer!

[shortcuts]

Yet an other clean update 🎉

[shortcuts]

Suggested change

	return getAlgoliaResults<ProductRecord>({
	return getAlgoliaResults({

I think this should stay a ProductHit, otherwise the type returned by getSources isn't right

[sarahdayan]

Fixed in #542 (just the function).

[francoischalifour]

I think the problem is that client.search returns Hit<TRecord>, so if we provide ProductHit (and not ProductRecord) to getAlgoliaResults, it would return Hit<ProductHit> (i.e., Hit<Hit<ProductRecord>>). Perhaps that's not an issue since Hit is idempotent, but not too sure how TypeScript handles those.

So providing ProductHit indeed seems more correct, although then we're manipulating Hit<ProductHit> everywhere else.