feat(helper): remove getRefinements, hasRefinements (#6570)

These functions are an aggregate of multiple different functions that depend on the type of refinement you're using. It's better to use the getter for the right type of refinement.

BREAKING CHANGE: remove helper.hasRefinements (use helper.state.isXXXRefined instead)
BREAKING CHANGE: remove helper.getRefinements (read helper.state.XXXRefinement instead)
BREAKING CHANGE: remove helper.state.getRefinements (read helper.state.XXXRefinement instead)

Author: Haroenv

examples/js/e-commerce-umd/src/app.ts

@@ -3,3 +3,11 @@ import { attachEventListeners } from './ui';
 
 search.start();
 attachEventListeners();
+
+declare global {
+  interface Window {
+    search: typeof search;
+  }
+}
+
+window.search = search;

examples/js/e-commerce-umd/src/widgets/Products.ts

@@ -51,8 +51,9 @@ export const products = hits<Hit>({
         </article>
       `;
     },
-    empty(results, { html }) {
-      const hasRefinements = results.getRefinements().length > 0;
+    empty(_, { html }) {
+      const hasRefinements =
+        window.search.renderState.instant_search.clearRefinements?.canRefine;
       const description = hasRefinements
         ? 'Try to reset your applied filters.'
         : 'Please try another query.';

examples/js/e-commerce/src/app.ts

@@ -5,3 +5,11 @@ import 'instantsearch.css/themes/reset.css';
 
 search.start();
 attachEventListeners();
+
+declare global {
+  interface Window {
+    search: typeof search;
+  }
+}
+
+window.search = search;

examples/js/e-commerce/src/widgets/Products.ts

@@ -51,8 +51,9 @@ export const products = hits<Hit>({
         </article>
       `;
     },
-    empty(results, { html }) {
-      const hasRefinements = results.getRefinements().length > 0;
+    empty(_, { html }) {
+      const hasRefinements =
+        window.search.renderState.instant_search.clearRefinements?.canRefine;
       const description = hasRefinements
         ? 'Try to reset your applied filters.'
         : 'Please try another query.';

examples/js/media/src/widgets/Stats.ts

@@ -1,9 +1,10 @@
-import { connectHits } from 'instantsearch.js/es/connectors';
+import { connectCurrentRefinements } from 'instantsearch.js/es/connectors';
 
 import { formatNumber, getDateRangeFromTimestamp } from '../utils';
 
-const statsWidget = connectHits<{ container: string }>(
-  ({ results, widgetParams }) => {
+const statsWidget = connectCurrentRefinements<{ container: string }>(
+  ({ instantSearchInstance, items, widgetParams }) => {
+    const results = instantSearchInstance.mainIndex.getResults();
     if (!results) {
       return;
     }
@@ -12,25 +13,25 @@ const statsWidget = connectHits<{ container: string }>(
     if (!containerNode) {
       throw new Error('container not found');
     }
-    const { nbHits } = results;
+    const { nbHits } = results || {};
 
     const resultsStats = `${formatNumber(nbHits)} articles`;
 
-    const stringRefinements = results
-      .getRefinements()
-      .filter((refinement) => refinement.type !== 'numeric')
-      .filter((refinement) => refinement.attributeName !== 'categories')
-      .map((refinement) => refinement.name);
-    const dateRefinement = getDateRangeFromTimestamp(
-      results
-        .getRefinements()
-        .filter(
-          (refinement) => refinement.attributeName === 'created_at_timestamp'
-        )
-        .map((refinement) => refinement.numericValue)
-    );
-
-    const refinements = [...stringRefinements, dateRefinement]
+    const refinements = items
+      .flatMap((item) => item.refinements)
+      .map((refinement) => {
+        switch (refinement.type) {
+          case 'numeric': {
+            return getDateRangeFromTimestamp([refinement.value]);
+          }
+          default: {
+            if (refinement.attribute === 'categories') {
+              return undefined;
+            }
+            return refinement.label;
+          }
+        }
+      })
       .filter(Boolean)
       .map((refinement) => `<strong>${refinement}</strong>`);
 

examples/react/e-commerce/components/NoResults.tsx

@@ -1,13 +1,12 @@
 import React from 'react';
-import { useInstantSearch } from 'react-instantsearch';
+import { useClearRefinements } from 'react-instantsearch';
 
 import { ClearFilters } from './ClearFilters';
 
 export function NoResults() {
-  const { results } = useInstantSearch();
+  const { canRefine } = useClearRefinements();
 
-  const hasRefinements = results.getRefinements().length > 0;
-  const description = hasRefinements
+  const description = canRefine
     ? 'Try to reset your applied filters.'
     : 'Please try another query.';
 

examples/vue/e-commerce/src/widgets/NoResults.vue

@@ -81,11 +81,13 @@
         Sorry, we can't find any matches to your query!
       </p>
       <p class="hits-empty-state-description">
-        {{
-          state.results.getRefinements().length > 0
-            ? 'Try to reset your applied filters.'
-            : 'Please try another query.'
-        }}
+        <ais-clear-refinements v-slot="{ canRefine }">
+          {{
+            canRefine
+              ? 'Try to reset your applied filters.'
+              : 'Please try another query.'
+          }}
+        </ais-clear-refinements>
       </p>
 
       <ais-clear-refinements>

packages/algoliasearch-helper/documentation-src/content/reference.md

@@ -109,10 +109,6 @@ The values that can be used for filtering are retrieved with the answer from Alg
 
 {{> jsdoc jsdoc/helper/toggleFacetRefinement}}
 
-{{> jsdoc jsdoc/helper/hasRefinements}}
-
-{{> jsdoc jsdoc/helper/getRefinements}}
-
 ### Disjunctive facets
 
 Disjunctive facets are used to filter values from a facetted attribute. The filters set on an attribute are combined using an `or`, hence the disjunctive adjective.
@@ -149,8 +145,6 @@ The values that can be used for filtering are retrieved with the answer from Alg
 
 {{> jsdoc jsdoc/helper/removeDisjunctiveFacetRefinement}}
 
-{{> jsdoc jsdoc/helper/hasRefinements}}
-
 ### Hierarchical facets
 
 Hierarchical facets are useful to build such navigation menus:
@@ -379,8 +373,6 @@ The facet exclusions are not a type of facets by themselves, they are conjunctiv
 
 {{> jsdoc jsdoc/helper/toggleFacetExclusion}}
 
-{{> jsdoc jsdoc/helper/hasRefinements}}
-
 ### Numeric filters
 
 The numeric filters don't require any configuration. However they require that the attribute is stored as a number in Algolia.
@@ -447,8 +439,6 @@ The SearchResults is the interface to read the results received from Algolia sea
 
 {{> jsdoc jsdoc/results/getFacetStats}}
 
-{{> jsdoc jsdoc/results/getRefinements}}
-
 ### Geolocation data
 
 {{> jsdoc jsdoc/results/aroundLatLng}}

packages/algoliasearch-helper/index.d.ts

@@ -300,11 +300,9 @@ declare namespace algoliasearchHelper {
     setState(newState: PlainSearchParameters): this;
 
     overrideStateWithoutTriggeringChangeEvent: AlgoliaSearchHelper['setState'];
-    hasRefinements(facet: string): boolean;
     getIndex(): string;
     getPage(): number;
     getTags(): string[];
-    getRefinements(facetName: string): any[];
     getNumericRefinement: SearchParameters['getNumericRefinement'];
     getHierarchicalFacetBreadcrumb: SearchParameters['getHierarchicalFacetBreadcrumb'];
     clearCache(): this;
@@ -1395,17 +1393,6 @@ declare namespace algoliasearchHelper {
      * @return The stats of the facet
      */
     getFacetStats(attribute: string): any;
-
-    /**
-     * Returns all refinements for all filters + tags. It also provides
-     * additional information: count and exhaustiveness for each filter.
-     *
-     * See the [refinement type](#Refinement) for an exhaustive view of the available
-     * data.
-     *
-     * @return all the refinements
-     */
-    getRefinements(): SearchResults.Refinement[];
   }
 
   export type Banner = {

packages/algoliasearch-helper/src/SearchResults/index.js

@@ -744,10 +744,6 @@ function recSort(sortFn, node, names, level) {
 
 SearchResults.DEFAULT_SORT = ['isRefined:desc', 'count:desc', 'name:asc'];
 
-function vanillaSortFn(order, data) {
-  return data.sort(order);
-}
-
 /**
  * @typedef FacetOrdering
  * @type {Object}
@@ -907,7 +903,7 @@ SearchResults.prototype.getFacetValues = function (attribute, opts) {
         var order = formatSort(options.sortBy, SearchResults.DEFAULT_SORT);
         return orderBy(data, order[0], order[1]);
       } else if (typeof options.sortBy === 'function') {
-        return vanillaSortFn(options.sortBy, data);
+        return data.sort(options.sortBy);
       }
       throw new Error(
         'options.sortBy is optional but if defined it must be ' +
@@ -952,159 +948,4 @@ function getFacetStatsIfAvailable(facetList, facetName) {
   return data && data.stats;
 }
 
-/**
- * Returns all refinements for all filters + tags. It also provides
- * additional information: count and exhaustiveness for each filter.
- *
- * See the [refinement type](#Refinement) for an exhaustive view of the available
- * data.
- *
- * Note that for a numeric refinement, results are grouped per operator, this
- * means that it will return responses for operators which are empty.
- *
- * @return {Array.<Refinement>} all the refinements
- */
-SearchResults.prototype.getRefinements = function () {
-  var state = this._state;
-  // eslint-disable-next-line consistent-this
-  var results = this;
-  var res = [];
-
-  Object.keys(state.facetsRefinements).forEach(function (attributeName) {
-    state.facetsRefinements[attributeName].forEach(function (name) {
-      res.push(
-        getRefinement(state, 'facet', attributeName, name, results.facets)
-      );
-    });
-  });
-
-  Object.keys(state.facetsExcludes).forEach(function (attributeName) {
-    state.facetsExcludes[attributeName].forEach(function (name) {
-      res.push(
-        getRefinement(state, 'exclude', attributeName, name, results.facets)
-      );
-    });
-  });
-
-  Object.keys(state.disjunctiveFacetsRefinements).forEach(function (
-    attributeName
-  ) {
-    state.disjunctiveFacetsRefinements[attributeName].forEach(function (name) {
-      res.push(
-        getRefinement(
-          state,
-          'disjunctive',
-          attributeName,
-          name,
-          results.disjunctiveFacets
-        )
-      );
-    });
-  });
-
-  Object.keys(state.hierarchicalFacetsRefinements).forEach(function (
-    attributeName
-  ) {
-    state.hierarchicalFacetsRefinements[attributeName].forEach(function (name) {
-      res.push(
-        getHierarchicalRefinement(
-          state,
-          attributeName,
-          name,
-          results.hierarchicalFacets
-        )
-      );
-    });
-  });
-
-  Object.keys(state.numericRefinements).forEach(function (attributeName) {
-    var operators = state.numericRefinements[attributeName];
-    Object.keys(operators).forEach(function (operator) {
-      operators[operator].forEach(function (value) {
-        res.push({
-          type: 'numeric',
-          attributeName: attributeName,
-          name: value,
-          numericValue: value,
-          operator: operator,
-        });
-      });
-    });
-  });
-
-  state.tagRefinements.forEach(function (name) {
-    res.push({ type: 'tag', attributeName: '_tags', name: name });
-  });
-
-  return res;
-};
-
-/**
- * @typedef {Object} Facet
- * @property {string} name
- * @property {Object} data
- * @property {boolean} exhaustive
- */
-
-/**
- * @param {SearchParameters} state the current state
- * @param {string} type the type of the refinement
- * @param {string} attributeName The attribute of the facet
- * @param {*} name The name of the facet
- * @param {Facet[]} resultsFacets facets from the results
- * @return {Refinement} the refinement
- */
-function getRefinement(state, type, attributeName, name, resultsFacets) {
-  var facet = resultsFacets.find(function (f) {
-    return f.name === attributeName;
-  });
-  var count = facet && facet.data && facet.data[name] ? facet.data[name] : 0;
-  var exhaustive = (facet && facet.exhaustive) || false;
-
-  return {
-    type: type,
-    attributeName: attributeName,
-    name: name,
-    count: count,
-    exhaustive: exhaustive,
-  };
-}
-
-/**
- * @param {SearchParameters} state the current state
- * @param {string} attributeName the attribute of the hierarchical facet
- * @param {string} name the name of the facet
- * @param {Facet[]} resultsFacets facets from the results
- * @return {HierarchicalFacet} the hierarchical facet
- */
-function getHierarchicalRefinement(state, attributeName, name, resultsFacets) {
-  var facetDeclaration = state.getHierarchicalFacetByName(attributeName);
-  var separator = state._getHierarchicalFacetSeparator(facetDeclaration);
-  var split = name.split(separator);
-  var rootFacet = resultsFacets.find(function (facet) {
-    return facet.name === attributeName;
-  });
-
-  var facet = split.reduce(function (intermediateFacet, part) {
-    var newFacet =
-      intermediateFacet &&
-      intermediateFacet.data.find(function (f) {
-        return f.name === part;
-      });
-    return newFacet !== undefined ? newFacet : intermediateFacet;
-  }, rootFacet);
-
-  var count = (facet && facet.count) || 0;
-  var exhaustive = (facet && facet.exhaustive) || false;
-  var path = (facet && facet.path) || '';
-
-  return {
-    type: 'hierarchical',
-    attributeName: attributeName,
-    name: path,
-    count: count,
-    exhaustive: exhaustive,
-  };
-}
-
 module.exports = SearchResults;