navigation-stack 0.1.0

package/src/middleware/normalizeInputLocationMiddleware.js

@@ -0,0 +1,21 @@
+import ActionTypes from '../ActionTypes';
+import normalizeInputLocation from '../normalizeInputLocation';
+
+// This "middleware" transforms input location argument into a proper `NormalizedInputLocation`.
+export default function normalizeInputLocationMiddleware() {
+  return (next) => (action) => {
+    const { type, payload } = action;
+
+    switch (type) {
+      case ActionTypes.PUSH:
+      case ActionTypes.REPLACE:
+        return next({
+          type,
+          payload: normalizeInputLocation(payload),
+        });
+
+      default:
+        return next(action);
+    }
+  };
+}

package/src/navigationBlockers.js

@@ -0,0 +1,158 @@
+import isPromise from './isPromise';
+import onlyAllowedOnClientSide from './onlyAllowedOnClientSide';
+
+let navigationBlockersList = [];
+
+let removeBeforeDestroyListener;
+
+export function getNavigationBlockers() {
+  return navigationBlockersList;
+}
+
+function addNavigationBlockerToTheList(blocker) {
+  onlyAllowedOnClientSide();
+  navigationBlockersList.push(blocker);
+}
+
+function removeNavigationBlockerFromTheList(blocker) {
+  onlyAllowedOnClientSide();
+  navigationBlockersList = navigationBlockersList.filter((_) => _ !== blocker);
+}
+
+export function removeAllNavigationBlockers() {
+  onlyAllowedOnClientSide();
+  if (getNavigationBlockers().some((blocker) => blocker.beforeDestroy)) {
+    removeBeforeDestroyListener();
+    removeBeforeDestroyListener = undefined;
+  }
+  navigationBlockersList = [];
+}
+
+// Runs the `listener` while ignoring any errors that might be thrown by it.
+function runNavigationBlocker({ listener }, location) {
+  let result;
+  try {
+    result = listener(location);
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `Ignoring navigation blocker \`${listener.name}\` that failed with \`${error}\`.`,
+    );
+    // eslint-disable-next-line no-console
+    console.error(error);
+  }
+
+  // If the listener returned a `Promise`, await for that `Promise`
+  // and then return the result.
+  if (isPromise(result)) {
+    return result.catch((error) => {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `Ignoring navigation blocker \`${listener.name}\` that failed with \`${error}\`.`,
+      );
+      // eslint-disable-next-line no-console
+      console.error(error);
+    });
+  }
+  // The listener didn't return a `Promise`.
+  // Return the "synchronous" result.
+  return result;
+}
+
+// Runs all listeners in order.
+// If any listener returns a non-`null` result, it stops and returns the result.
+// If there's no such listener, returns `true`.
+export function runNavigationBlockers(navigationBlockers, toLocation) {
+  if (navigationBlockers.length === 0) {
+    return undefined;
+  }
+
+  // Call the first blocker in the list.
+  const result = runNavigationBlocker(navigationBlockers[0], toLocation);
+
+  const next = () => {
+    // Proceed to the next blocker.
+    return runNavigationBlockers(navigationBlockers.slice(1), toLocation);
+  };
+
+  if (isPromise(result)) {
+    return result.then((resultValue) => {
+      if (resultValue) {
+        return resultValue;
+      }
+      return next();
+    });
+  }
+
+  if (result) {
+    return result;
+  }
+  return next();
+}
+
+/* istanbul ignore next: not testable with Karma */
+function onBeforeDestroy() {
+  const result = runNavigationBlockers(getNavigationBlockers(), null);
+
+  // If no listener returned anything, don't prevent the "unload" event.
+  if (!result) {
+    return undefined;
+  }
+
+  // Web browsers don't allow displaying a custom modal in "beforeunload" phase.
+  // They only allow displaying a standard one, with the default text.
+  // Hence, "asynchronous" listeners should be ignored.
+  // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
+  if (isPromise(result)) {
+    return undefined;
+  }
+
+  // Prevent the "unload" event.
+  return true;
+}
+
+export function addNavigationBlocker(environment, listener) {
+  onlyAllowedOnClientSide();
+
+  // All navigation blockers also run on `beforeDestroy` event.
+  // If required, this could be a parameter of this function.
+  // The rationale could be that adding `beforeunload` a listener
+  // disables web page caching in some browsers like Firefox.
+  const beforeDestroy = true;
+
+  // If it's the first "beforeDestroy" listener, add the global `onBeforeDestroy` listener.
+  //
+  // Sidenote: Add the "beforeunload" event listener only as needed, as its presence
+  // prevents the page from being added to the page navigation cache:
+  //
+  // "In Firefox, beforeunload is not compatible with the back/forward cache (bfcache):
+  //  that is, Firefox will not place pages in the bfcache if they have beforeunload listeners,
+  //  and this is bad for performance."
+  //
+  // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
+  if (
+    beforeDestroy &&
+    !getNavigationBlockers().some((blocker) => blocker.beforeDestroy)
+  ) {
+    removeBeforeDestroyListener =
+      environment.addBeforeDestroyListener(onBeforeDestroy);
+  }
+
+  const blocker = { listener, beforeDestroy };
+  addNavigationBlockerToTheList(blocker);
+
+  return () => {
+    removeNavigationBlockerFromTheList(blocker);
+
+    // If it was the last "beforeDestroy" listener, remove the global `onBeforeDestroy` listener.
+    if (
+      beforeDestroy &&
+      !getNavigationBlockers().some(
+        (navigationBlocker) => navigationBlocker.beforeDestroy,
+      )
+    ) {
+      removeBeforeDestroyListener();
+      removeBeforeDestroyListener = undefined;
+    }
+  };
+}

package/src/normalizeInputLocation.js

@@ -0,0 +1,44 @@
+import createSearchFromQuery from './createSearchFromQuery';
+import parseLocationUrl from './parseLocationUrl';
+import parseQueryFromSearch from './parseQueryFromSearch';
+
+// * If `location` is a string, it parses it into a `NormalizedInputLocation`.
+// * If `location` is an object, it ensures that `search` and `hash` properties aren't `undefined`,
+//   i.e. it "ensures" that the `location` object can be used as a `NormalizedInputLocation`.
+export default function normalizeInputLocation(location) {
+  if (typeof location === 'string') {
+    return parseLocationUrl(location);
+  }
+
+  // Convert `query` property values to strings.
+  if (location.query) {
+    for (const key of Object.keys(location.query)) {
+      location.query[key] = String(location.query[key]);
+    }
+  }
+
+  // Create `query` from `search`.
+  if (location.search && !location.query) {
+    location = {
+      ...location,
+      query: parseQueryFromSearch(location.search),
+    };
+  }
+
+  // Convert `query` object into a `search` string
+  // if `query` is present but `search` is not.
+  if (location.query && !location.search) {
+    location = {
+      ...location,
+      search: createSearchFromQuery(location.query),
+    };
+  }
+
+  // Set default values on `search` and `hash`
+  // if those properties are not present.
+  return {
+    ...location,
+    search: location.search || '',
+    hash: location.hash || '',
+  };
+}

package/src/onlyAllowedOnClientSide.js

@@ -0,0 +1,5 @@
+export default function onlyAllowedOnClientSide() {
+  if (typeof window === 'undefined') {
+    throw new Error('This function can only be called on client side');
+  }
+}

package/src/parseLocationUrl.js

@@ -0,0 +1,40 @@
+import parseQueryFromSearch from './parseQueryFromSearch';
+
+export default function parseLocationUrl(url) {
+  if (url[0] !== '/') {
+    throw new Error('Expected URL to start with a slash');
+  }
+
+  let remainingPath = url;
+
+  const hashIndex = remainingPath.indexOf('#');
+  let hash;
+  if (hashIndex !== -1) {
+    hash = remainingPath.slice(hashIndex);
+    remainingPath = remainingPath.slice(0, hashIndex);
+  } else {
+    hash = '';
+  }
+
+  const searchIndex = remainingPath.indexOf('?');
+  let search;
+  if (searchIndex !== -1) {
+    search = remainingPath.slice(searchIndex);
+    remainingPath = remainingPath.slice(0, searchIndex);
+  } else {
+    search = '';
+  }
+
+  const location = {
+    pathname: remainingPath,
+    search,
+    hash,
+  };
+
+  const query = parseQueryFromSearch(search);
+  if (query) {
+    location.query = query;
+  }
+
+  return location;
+}

package/src/parseQueryFromSearch.js

@@ -0,0 +1,12 @@
+import { parse as parseQuery } from 'query-string';
+
+export default function parseQueryFromSearch(search) {
+  if (search.length > '?'.length) {
+    try {
+      return parseQuery(search.slice(1));
+    } catch (error) {
+      // Ignore any query parsing errors.
+    }
+  }
+  return undefined;
+}

package/test/.eslintrc.cjs

@@ -0,0 +1,17 @@
+module.exports = {
+  env: {
+    mocha: true,
+  },
+  globals: {
+    expect: false,
+    sinon: false,
+  },
+  rules: {
+    'import/no-extraneous-dependencies': [
+      'error',
+      {
+        devDependencies: true,
+      },
+    ],
+  },
+};

package/test/Action.test.js

@@ -0,0 +1,72 @@
+import ActionTypes from '../src/ActionTypes';
+import Actions from '../src/Actions';
+
+describe('Actions', () => {
+  it('#init should create an INIT action', () => {
+    expect(Actions.init()).to.eql({
+      type: ActionTypes.INIT,
+    });
+  });
+
+  it('#push should create a PUSH action with location', () => {
+    expect(Actions.push('/foo?bar=baz#qux')).to.eql({
+      type: ActionTypes.PUSH,
+      payload: '/foo?bar=baz#qux',
+    });
+
+    expect(
+      Actions.push({
+        pathname: '/foo',
+        search: '?bar=baz',
+        hash: '#qux',
+      }),
+    ).to.eql({
+      type: ActionTypes.PUSH,
+      payload: {
+        pathname: '/foo',
+        search: '?bar=baz',
+        hash: '#qux',
+      },
+    });
+  });
+
+  it('#replace should create a REPLACE action with location', () => {
+    expect(Actions.replace('/foo?bar=baz#qux')).to.eql({
+      type: ActionTypes.REPLACE,
+      payload: '/foo?bar=baz#qux',
+    });
+
+    expect(
+      Actions.replace({
+        pathname: '/foo',
+        search: '?bar=baz',
+        hash: '#qux',
+      }),
+    ).to.eql({
+      type: ActionTypes.REPLACE,
+      payload: {
+        pathname: '/foo',
+        search: '?bar=baz',
+        hash: '#qux',
+      },
+    });
+  });
+
+  it('#go should create a SHIFT action with delta', () => {
+    expect(Actions.shift(1)).to.eql({
+      type: ActionTypes.SHIFT,
+      payload: 1,
+    });
+
+    expect(Actions.shift(-1)).to.eql({
+      type: ActionTypes.SHIFT,
+      payload: -1,
+    });
+  });
+
+  it('#dispose should create a DISPOSE action', () => {
+    expect(Actions.dispose()).to.eql({
+      type: ActionTypes.DISPOSE,
+    });
+  });
+});

package/test/ActionTypes.test.js

@@ -0,0 +1,13 @@
+import ActionTypes from '../src/ActionTypes';
+
+describe('ActionTypes', () => {
+  it('should have the correct exports', () => {
+    expect(ActionTypes.INIT).to.exist();
+    expect(ActionTypes.PUSH).to.exist();
+    expect(ActionTypes.REPLACE).to.exist();
+    expect(ActionTypes.NAVIGATE).to.exist();
+    expect(ActionTypes.SHIFT).to.exist();
+    expect(ActionTypes.UPDATE).to.exist();
+    expect(ActionTypes.DISPOSE).to.exist();
+  });
+});

package/test/LocationStateStorage.test.js

@@ -0,0 +1,75 @@
+import LocationStateStorage from '../src/LocationStateStorage';
+import MemoryEnvironment from '../src/environment/MemoryEnvironment';
+
+describe('LocationStateStorage', () => {
+  let environment;
+  let stateStorage;
+
+  const location = {
+    key: 'location:0',
+  };
+
+  beforeEach(() => {
+    window.sessionStorage.clear();
+
+    environment = new MemoryEnvironment('/initial-location');
+    stateStorage = new LocationStateStorage(environment, {
+      namespace: 'test',
+    });
+  });
+
+  it('should read saved value for default key', () => {
+    stateStorage.set(location, '', 1);
+
+    expect(stateStorage.get(location, '')).to.equal(1);
+    expect(stateStorage.get(location, 'foo')).to.be.undefined();
+  });
+
+  it('should read saved value for explicit key', () => {
+    stateStorage.set(location, 'foo', [2, 3]);
+
+    expect(stateStorage.get(location, 'foo')).to.eql([2, 3]);
+    expect(stateStorage.get(location, '')).to.be.undefined();
+  });
+
+  it('should read undefined when value is missing', () => {
+    expect(stateStorage.get(location, '')).to.be.undefined();
+    expect(stateStorage.get(location, 'foo')).to.be.undefined();
+  });
+
+  it('should work with arbitrary types', () => {
+    stateStorage.set(location, 'number', 1);
+    stateStorage.set(location, 'boolean', true);
+    stateStorage.set(location, 'string', 'state');
+    stateStorage.set(location, 'array', [2, 3]);
+    stateStorage.set(location, 'object', { a: 1 });
+    stateStorage.set(location, 'null', null);
+
+    expect(stateStorage.get(location, 'number')).to.equal(1);
+    expect(stateStorage.get(location, 'boolean')).to.equal(true);
+    expect(stateStorage.get(location, 'string')).to.equal('state');
+    expect(stateStorage.get(location, 'array')).to.eql([2, 3]);
+    expect(stateStorage.get(location, 'object')).to.eql({ a: 1 });
+    expect(stateStorage.get(location, 'null')).to.be.null();
+  });
+
+  it('should support deleting values', () => {
+    stateStorage.set(location, '', 1);
+    expect(stateStorage.get(location, '')).to.equal(1);
+
+    stateStorage.set(location, '', undefined);
+    expect(stateStorage.get(location, '')).to.be.undefined();
+  });
+
+  it('should read undefined for invalid JSON', () => {
+    window.sessionStorage.setItem('test|location:0', '[}');
+
+    expect(stateStorage.get(location, '')).to.be.undefined();
+  });
+
+  it('should support fallback key', () => {
+    stateStorage.set({}, '', 1);
+
+    expect(stateStorage.get({}, '')).to.equal(1);
+  });
+});

package/test/basePath.test.js

@@ -0,0 +1,158 @@
+import { addBasePath, removeBasePath } from '../src/basePath';
+
+describe('addBasePath', () => {
+  it('should add `basePath` to location object', () => {
+    expect(
+      addBasePath(
+        {
+          pathname: '/foo',
+          search: '?bar=baz',
+          hash: '#qux',
+        },
+        '/base-path',
+      ),
+    ).to.deep.equal({
+      pathname: '/base-path/foo',
+      search: '?bar=baz',
+      hash: '#qux',
+    });
+  });
+
+  it('should add `basePath` to location object (`basePath` ends with a slash)', () => {
+    expect(
+      addBasePath(
+        {
+          pathname: '/foo',
+          search: '?bar=baz',
+          hash: '#qux',
+        },
+        '/base-path/',
+      ),
+    ).to.deep.equal({
+      pathname: '/base-path/foo',
+      search: '?bar=baz',
+      hash: '#qux',
+    });
+  });
+
+  it('should add `basePath` to location object (no `basePath` option)', () => {
+    expect(
+      addBasePath({
+        pathname: '/foo',
+        search: '?bar=baz',
+        hash: '#qux',
+      }),
+    ).to.deep.equal({
+      pathname: '/foo',
+      search: '?bar=baz',
+      hash: '#qux',
+    });
+  });
+
+  it('should add `basePath` to location URL', () => {
+    expect(addBasePath('/foo?bar=baz#qux', '/base-path')).to.equal(
+      '/base-path/foo?bar=baz#qux',
+    );
+  });
+
+  it('should add `basePath` to location URL (`basePath` ends with a slash)', () => {
+    expect(addBasePath('/foo?bar=baz#qux', '/base-path/')).to.equal(
+      '/base-path/foo?bar=baz#qux',
+    );
+  });
+
+  it('should add `basePath` to location URL (no `basePath` option)', () => {
+    expect(addBasePath('/foo?bar=baz#qux')).to.equal('/foo?bar=baz#qux');
+  });
+});
+
+describe('removeBasePath', () => {
+  it('should remove `basePath` from location object', () => {
+    expect(
+      removeBasePath(
+        {
+          pathname: '/base-path/foo',
+          search: '?bar=baz',
+          hash: '#qux',
+        },
+        '/base-path',
+      ),
+    ).to.deep.equal({
+      pathname: '/foo',
+      search: '?bar=baz',
+      hash: '#qux',
+    });
+  });
+
+  it('should remove `basePath` from location object (does not contain `basePath`)', () => {
+    expect(
+      removeBasePath(
+        {
+          pathname: '/foo',
+          search: '?bar=baz',
+          hash: '#qux',
+        },
+        '/base-path',
+      ),
+    ).to.deep.equal({
+      pathname: '/foo',
+      search: '?bar=baz',
+      hash: '#qux',
+    });
+  });
+
+  it('should remove `basePath` from location object (`basePath` ends with a slash)', () => {
+    expect(
+      removeBasePath(
+        {
+          pathname: '/base-path/foo',
+          search: '?bar=baz',
+          hash: '#qux',
+        },
+        '/base-path/',
+      ),
+    ).to.deep.equal({
+      pathname: '/foo',
+      search: '?bar=baz',
+      hash: '#qux',
+    });
+  });
+
+  it('should remove `basePath` from location object (no `basePath` option)', () => {
+    expect(
+      removeBasePath({
+        pathname: '/base-path/foo',
+        search: '?bar=baz',
+        hash: '#qux',
+      }),
+    ).to.deep.equal({
+      pathname: '/base-path/foo',
+      search: '?bar=baz',
+      hash: '#qux',
+    });
+  });
+
+  it('should remove `basePath` from location URL', () => {
+    expect(
+      removeBasePath('/base-path/foo?bar=baz#qux', '/base-path'),
+    ).to.equal('/foo?bar=baz#qux');
+  });
+
+  it('should remove `basePath` from location URL (does not contain `basePath`)', () => {
+    expect(removeBasePath('/foo?bar=baz#qux', '/base-path')).to.equal(
+      '/foo?bar=baz#qux',
+    );
+  });
+
+  it('should remove `basePath` from location URL (`basePath` ends with a slash)', () => {
+    expect(
+      removeBasePath('/base-path/foo?bar=baz#qux', '/base-path/'),
+    ).to.equal('/foo?bar=baz#qux');
+  });
+
+  it('should remove `basePath` from location URL (no `basePath` option)', () => {
+    expect(removeBasePath('/base-path/foo?bar=baz#qux')).to.equal(
+      '/base-path/foo?bar=baz#qux',
+    );
+  });
+});

package/test/createMiddlewares.test.js

@@ -0,0 +1,62 @@
+import { applyMiddleware, createStore } from 'redux';
+
+import Actions from '../src/Actions';
+import createMiddlewares from '../src/createMiddlewares';
+import MemoryEnvironment from '../src/environment/MemoryEnvironment';
+import locationReducer from '../src/locationReducer';
+
+describe('createMiddlewares', () => {
+  let store;
+
+  beforeEach(() => {
+    store = createStore(
+      locationReducer,
+      applyMiddleware(...createMiddlewares(new MemoryEnvironment('/foo'))),
+    );
+    store.dispatch(Actions.init());
+  });
+
+  afterEach(() => {
+    store.dispatch(Actions.dispose());
+  });
+
+  it('should support push and go', () => {
+    store.dispatch(Actions.push('/bar'));
+    expect(store.getState()).to.include({
+      pathname: '/bar',
+      index: 1,
+    });
+
+    store.dispatch(Actions.shift(-1));
+    expect(store.getState()).to.include({
+      pathname: '/foo',
+      index: 0,
+    });
+
+    store.dispatch(Actions.shift(+1));
+    expect(store.getState()).to.include({
+      pathname: '/bar',
+      index: 1,
+    });
+  });
+
+  it('should support replace', () => {
+    store.dispatch(Actions.replace('/bar'));
+    expect(store.getState()).to.include({
+      pathname: '/bar',
+      index: 0,
+    });
+  });
+
+  it('should ignore other actions', () => {
+    expect(
+      store.dispatch({
+        type: 'UNKNOWN',
+        payload: { unknown: {} },
+      }),
+    ).to.eql({
+      type: 'UNKNOWN',
+      payload: { unknown: {} },
+    });
+  });
+});