feat: implement dedicated reset page method (#673)

* feat(SearchParameters): implement resetPage

* refactor: use resetPage rather than setPage

* feat: emit change event with reset page information

* refactor(change): use object vs list of arguments

src/SearchParameters/index.js

@@ -1334,6 +1334,20 @@ SearchParameters.prototype = {
     });
   },
 
+  /**
+   * Returns a new instance with the page reset. Two scenarios possible:
+   * the page is omitted -> return the given instance
+   * the page is set -> return a new instance with a page of 0
+   * @return {SearchParameters} a new updated instance
+   */
+  resetPage: function() {
+    if (this.page === undefined) {
+      return this;
+    }
+
+    return this.setPage(0);
+  },
+
   /**
    * Returns an object with only the selected attributes.
    * @param {string[]} filters filters to retrieve only a subset of the state. It

src/algoliasearch.helper.js

@@ -328,7 +328,11 @@ AlgoliaSearchHelper.prototype.searchForFacetValues = function(facet, query, maxF
  * @chainable
  */
 AlgoliaSearchHelper.prototype.setQuery = function(q) {
-  this._change(this.state.setPage(0).setQuery(q));
+  this._change({
+    state: this.state.resetPage().setQuery(q),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -356,7 +360,11 @@ AlgoliaSearchHelper.prototype.setQuery = function(q) {
  * }).search();
  */
 AlgoliaSearchHelper.prototype.clearRefinements = function(name) {
-  this._change(this.state.setPage(0).clearRefinements(name));
+  this._change({
+    state: this.state.resetPage().clearRefinements(name),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -369,7 +377,11 @@ AlgoliaSearchHelper.prototype.clearRefinements = function(name) {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.clearTags = function() {
-  this._change(this.state.setPage(0).clearTags());
+  this._change({
+    state: this.state.resetPage().clearTags(),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -385,7 +397,11 @@ AlgoliaSearchHelper.prototype.clearTags = function() {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.addDisjunctiveFacetRefinement = function(facet, value) {
-  this._change(this.state.setPage(0).addDisjunctiveFacetRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().addDisjunctiveFacetRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -410,7 +426,11 @@ AlgoliaSearchHelper.prototype.addDisjunctiveRefine = function() {
  * @fires change
  */
 AlgoliaSearchHelper.prototype.addHierarchicalFacetRefinement = function(facet, value) {
-  this._change(this.state.setPage(0).addHierarchicalFacetRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().addHierarchicalFacetRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -427,7 +447,11 @@ AlgoliaSearchHelper.prototype.addHierarchicalFacetRefinement = function(facet, v
  * @chainable
  */
 AlgoliaSearchHelper.prototype.addNumericRefinement = function(attribute, operator, value) {
-  this._change(this.state.setPage(0).addNumericRefinement(attribute, operator, value));
+  this._change({
+    state: this.state.resetPage().addNumericRefinement(attribute, operator, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -443,7 +467,11 @@ AlgoliaSearchHelper.prototype.addNumericRefinement = function(attribute, operato
  * @chainable
  */
 AlgoliaSearchHelper.prototype.addFacetRefinement = function(facet, value) {
-  this._change(this.state.setPage(0).addFacetRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().addFacetRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -467,7 +495,11 @@ AlgoliaSearchHelper.prototype.addRefine = function() {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.addFacetExclusion = function(facet, value) {
-  this._change(this.state.setPage(0).addExcludeRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().addExcludeRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -489,7 +521,11 @@ AlgoliaSearchHelper.prototype.addExclude = function() {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.addTag = function(tag) {
-  this._change(this.state.setPage(0).addTagRefinement(tag));
+  this._change({
+    state: this.state.resetPage().addTagRefinement(tag),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -512,7 +548,11 @@ AlgoliaSearchHelper.prototype.addTag = function(tag) {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.removeNumericRefinement = function(attribute, operator, value) {
-  this._change(this.state.setPage(0).removeNumericRefinement(attribute, operator, value));
+  this._change({
+    state: this.state.resetPage().removeNumericRefinement(attribute, operator, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -531,7 +571,11 @@ AlgoliaSearchHelper.prototype.removeNumericRefinement = function(attribute, oper
  * @chainable
  */
 AlgoliaSearchHelper.prototype.removeDisjunctiveFacetRefinement = function(facet, value) {
-  this._change(this.state.setPage(0).removeDisjunctiveFacetRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().removeDisjunctiveFacetRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -551,7 +595,10 @@ AlgoliaSearchHelper.prototype.removeDisjunctiveRefine = function() {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.removeHierarchicalFacetRefinement = function(facet) {
-  this._change(this.state.setPage(0).removeHierarchicalFacetRefinement(facet));
+  this._change({
+    state: this.state.resetPage().removeHierarchicalFacetRefinement(facet),
+    isPageReset: true
+  });
 
   return this;
 };
@@ -571,7 +618,11 @@ AlgoliaSearchHelper.prototype.removeHierarchicalFacetRefinement = function(facet
  * @chainable
  */
 AlgoliaSearchHelper.prototype.removeFacetRefinement = function(facet, value) {
-  this._change(this.state.setPage(0).removeFacetRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().removeFacetRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -597,7 +648,11 @@ AlgoliaSearchHelper.prototype.removeRefine = function() {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.removeFacetExclusion = function(facet, value) {
-  this._change(this.state.setPage(0).removeExcludeRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().removeExcludeRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -619,7 +674,11 @@ AlgoliaSearchHelper.prototype.removeExclude = function() {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.removeTag = function(tag) {
-  this._change(this.state.setPage(0).removeTagRefinement(tag));
+  this._change({
+    state: this.state.resetPage().removeTagRefinement(tag),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -635,7 +694,11 @@ AlgoliaSearchHelper.prototype.removeTag = function(tag) {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.toggleFacetExclusion = function(facet, value) {
-  this._change(this.state.setPage(0).toggleExcludeFacetRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().toggleExcludeFacetRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -680,7 +743,11 @@ AlgoliaSearchHelper.prototype.toggleRefinement = function(facet, value) {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.toggleFacetRefinement = function(facet, value) {
-  this._change(this.state.setPage(0).toggleFacetRefinement(facet, value));
+  this._change({
+    state: this.state.resetPage().toggleFacetRefinement(facet, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -702,7 +769,11 @@ AlgoliaSearchHelper.prototype.toggleRefine = function() {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.toggleTag = function(tag) {
-  this._change(this.state.setPage(0).toggleTagRefinement(tag));
+  this._change({
+    state: this.state.resetPage().toggleTagRefinement(tag),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -740,7 +811,10 @@ AlgoliaSearchHelper.prototype.previousPage = function() {
 function setCurrentPage(page) {
   if (page < 0) throw new Error('Page requested below 0.');
 
-  this._change(this.state.setPage(page));
+  this._change({
+    state: this.state.setPage(page),
+    isPageReset: false
+  });
 
   return this;
 }
@@ -775,7 +849,11 @@ AlgoliaSearchHelper.prototype.setPage = setCurrentPage;
  * @chainable
  */
 AlgoliaSearchHelper.prototype.setIndex = function(name) {
-  this._change(this.state.setPage(0).setIndex(name));
+  this._change({
+    state: this.state.resetPage().setIndex(name),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -797,7 +875,11 @@ AlgoliaSearchHelper.prototype.setIndex = function(name) {
  * helper.setQueryParameter('hitsPerPage', 20).search();
  */
 AlgoliaSearchHelper.prototype.setQueryParameter = function(parameter, value) {
-  this._change(this.state.setPage(0).setQueryParameter(parameter, value));
+  this._change({
+    state: this.state.resetPage().setQueryParameter(parameter, value),
+    isPageReset: true
+  });
+
   return this;
 };
 
@@ -809,7 +891,11 @@ AlgoliaSearchHelper.prototype.setQueryParameter = function(parameter, value) {
  * @chainable
  */
 AlgoliaSearchHelper.prototype.setState = function(newState) {
-  this._change(SearchParameters.make(newState));
+  this._change({
+    state: SearchParameters.make(newState),
+    isPageReset: false
+  });
+
   return this;
 };
 
@@ -1240,10 +1326,18 @@ AlgoliaSearchHelper.prototype._hasDisjunctiveRefinements = function(facet) {
     this.state.disjunctiveRefinements[facet].length > 0;
 };
 
-AlgoliaSearchHelper.prototype._change = function(newState) {
-  if (newState !== this.state) {
-    this.state = newState;
-    this.emit('change', this.state, this.lastResults);
+AlgoliaSearchHelper.prototype._change = function(event) {
+  var state = event.state;
+  var isPageReset = event.isPageReset;
+
+  if (state !== this.state) {
+    this.state = state;
+
+    this.emit('change', {
+      state: this.state,
+      results: this.lastResults,
+      isPageReset: isPageReset
+    });
   }
 };
 

test/datasets/SearchParameters/search.dataset.js

@@ -193,11 +193,6 @@ function getData() {
   };
 
   var searchParams = new SearchParameters({
-    // @TODO: at the moment we have to provide a default value for the page, otherwise
-    // some methods reset the page to 0 (because of the reset behavior). This is what
-    // happens: page omit -> page defined with 0. We'll fix those issues with a next PR
-    // that implements a proper reset with the updated structure of the `SearchParameters`.
-    page: 0,
     index: 'test_hotels-node',
     disjunctiveFacets: ['city'],
     disjunctiveFacetsRefinements: {

test/spec/SearchParameters/resetPage.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const SearchParameters = require('../../../src/SearchParameters');
+
+test('without a previous page it should return the given SearchParameters', () => {
+  const parameters = new SearchParameters();
+  const parametersWithPageReseted = parameters.resetPage();
+
+  expect(parameters).toBe(parametersWithPageReseted);
+  expect(parametersWithPageReseted.page).toBeUndefined();
+});
+
+test('with a previous page of 0 it should return the given SearchParameters', () => {
+  const parameters = new SearchParameters({
+    page: 0
+  });
+
+  const parametersWithPageReseted = parameters.resetPage();
+
+  expect(parameters).toBe(parametersWithPageReseted);
+  expect(parametersWithPageReseted.page).toBe(0);
+});
+
+
+test('with a previous page it should set the page to 0', () => {
+  const parameters = new SearchParameters({
+    page: 5
+  });
+
+  const parametersWithPageReseted = parameters.resetPage();
+
+  expect(parameters).not.toBe(parametersWithPageReseted);
+  expect(parametersWithPageReseted.page).toBe(0);
+});