feat(routing): add a "single index" compatibility mode (#4087)

* feat(routing): enable "compatibility" mode by default

This mode has as goal to

For Vue InstantSearch, which doesn't provide a default value for routing, users import this `compat` state mapping, and need to give the static index name as a property.

This required some maybe less than ideal changes to the `Routing` type, because it assumed you could only pass the generic once, maybe someone has a better idea than what i did here?

https://algolia.atlassian.net/browse/IFW-941

* do not enable by default

* chore: add default values

* rename

src/lib/InstantSearch.ts

@@ -3,7 +3,7 @@ import { Client as AlgoliaSearchClient } from 'algoliasearch';
 import EventEmitter from 'events';
 import index, { Index } from '../widgets/index/index';
 import RoutingManager from './RoutingManager';
-import simpleMapping from './stateMappings/simple';
+import simpleStateMapping from './stateMappings/simple';
 import historyRouter from './routers/history';
 import version from './version';
 import createHelpers from './createHelpers';
@@ -28,11 +28,6 @@ const withUsage = createDocumentationMessageGenerator({
   name: 'instantsearch',
 });
 
-const ROUTING_DEFAULT_OPTIONS = {
-  stateMapping: simpleMapping(),
-  router: historyRouter(),
-};
-
 function defaultCreateURL() {
   return '#';
 }
@@ -237,11 +232,16 @@ See ${createDocumentationLink({
       this._searchFunction = searchFunction;
     }
 
+    const defaultRoutingOptions = {
+      stateMapping: simpleStateMapping(),
+      router: historyRouter(),
+    };
+
     if (routing === true) {
-      this.routing = ROUTING_DEFAULT_OPTIONS;
+      this.routing = defaultRoutingOptions;
     } else if (isPlainObject(routing)) {
       this.routing = {
-        ...ROUTING_DEFAULT_OPTIONS,
+        ...defaultRoutingOptions,
         ...routing,
       };
     }

src/lib/stateMappings/__tests__/singleIndex-test.ts

@@ -0,0 +1,215 @@
+import singleIndexStateMapping from '../singleIndex';
+
+describe('singleIndexStateMapping', () => {
+  describe('stateToRoute', () => {
+    it('passes normal state through', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.stateToRoute({
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+        },
+      });
+
+      expect(actual).toEqual({
+        query: 'zamboni',
+        refinementList: {
+          color: ['red'],
+        },
+      });
+    });
+
+    it('removes configure', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.stateToRoute({
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+          configure: {
+            advancedSyntax: false,
+          },
+        },
+      });
+
+      expect(actual).toEqual({
+        query: 'zamboni',
+        refinementList: {
+          color: ['red'],
+        },
+      });
+    });
+
+    it('passes non-UiState through', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.stateToRoute({
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+          // @ts-ignore
+          spy: ['stealing', 'all', 'your', 'searches'],
+        },
+      });
+
+      expect(actual).toEqual({
+        query: 'zamboni',
+        refinementList: {
+          color: ['red'],
+        },
+        spy: ['stealing', 'all', 'your', 'searches'],
+      });
+    });
+
+    it('picks the correct index', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.stateToRoute({
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+        },
+        anotherIndex: {
+          // @ts-ignore
+          totally: 'ignored',
+          refinementList: {
+            color: ['blue'],
+          },
+        },
+      });
+
+      expect(actual).toEqual({
+        query: 'zamboni',
+        refinementList: {
+          color: ['red'],
+        },
+      });
+    });
+
+    it('empty object if there is no matching index', () => {
+      const stateMapping = singleIndexStateMapping('magicIndex');
+      const actual = stateMapping.stateToRoute({
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+        },
+        anotherIndex: {
+          // @ts-ignore
+          totally: 'ignored',
+          refinementList: {
+            color: ['blue'],
+          },
+        },
+      });
+
+      expect(actual).toEqual({});
+    });
+  });
+
+  describe('routeToState', () => {
+    it('passes normal state through', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.routeToState({
+        query: 'zamboni',
+        refinementList: {
+          color: ['red'],
+        },
+      });
+
+      expect(actual).toEqual({
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+        },
+      });
+    });
+
+    it('removes configure', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.routeToState({
+        query: 'zamboni',
+        refinementList: {
+          color: ['red'],
+        },
+        configure: {
+          advancedSyntax: false,
+        },
+      });
+
+      expect(actual).toEqual({
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+        },
+      });
+    });
+
+    it('passes non-UiState through', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.routeToState({
+        query: 'zamboni',
+        refinementList: {
+          color: ['red'],
+        },
+        // @ts-ignore
+        spy: ['stealing', 'all', 'your', 'searches'],
+      });
+
+      expect(actual).toEqual({
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+          spy: ['stealing', 'all', 'your', 'searches'],
+        },
+      });
+    });
+
+    it('returns wrong data if used with nested state', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.routeToState({
+        // @ts-ignore (we are passing wrong data)
+        indexName: {
+          query: 'zamboni',
+          refinementList: {
+            color: ['red'],
+          },
+        },
+        anotherIndex: {},
+      });
+
+      expect(actual).toEqual({
+        indexName: {
+          indexName: {
+            query: 'zamboni',
+            refinementList: {
+              color: ['red'],
+            },
+          },
+          anotherIndex: {},
+        },
+      });
+    });
+
+    it('keeps empty index empty', () => {
+      const stateMapping = singleIndexStateMapping('indexName');
+      const actual = stateMapping.routeToState({});
+
+      expect(actual).toEqual({
+        indexName: {},
+      });
+    });
+  });
+});

src/lib/stateMappings/index.ts

@@ -1 +1,2 @@
 export { default as simple } from './simple';
+export { default as singleIndex } from './singleIndex';

src/lib/stateMappings/simple.ts

@@ -20,7 +20,7 @@ export default function simpleStateMapping(): StateMapping<UiState> {
       );
     },
 
-    routeToState(routeState) {
+    routeToState(routeState = {}) {
       return Object.keys(routeState).reduce<UiState>(
         (state, indexId) => ({
           ...state,

src/lib/stateMappings/singleIndex.ts

@@ -0,0 +1,21 @@
+import { StateMapping, IndexUiState } from '../../types';
+
+function getIndexStateWithoutConfigure(uiState: IndexUiState): IndexUiState {
+  const { configure, ...trackedUiState } = uiState;
+  return trackedUiState;
+}
+
+export default function singleIndexStateMapping(
+  indexName: string
+): StateMapping<IndexUiState> {
+  return {
+    stateToRoute(uiState) {
+      return getIndexStateWithoutConfigure(uiState[indexName] || {});
+    },
+    routeToState(routeState = {}) {
+      return {
+        [indexName]: getIndexStateWithoutConfigure(routeState),
+      };
+    },
+  };
+}