navigation-stack 0.3.1 → 0.4.0

package/src/session/navigation/error/ServerSideNavigationError.js

@@ -0,0 +1,18 @@
+import getLocationUrl from '../../../getLocationUrl';
+
+export default class ServerSideNavigationError extends Error {
+  constructor(location) {
+    super(
+      location
+        ? `Navigate to ${getLocationUrl(location)}`
+        : 'Navigate to previous or next location',
+    );
+
+    if (location) {
+      // Remove `operation` property from `location`.
+      // eslint-disable-next-line no-unused-vars
+      const { operation, ...locationBase } = location;
+      this.location = locationBase;
+    }
+  }
+}

package/src/session/navigation/operation/operations.js

@@ -0,0 +1,6 @@
+export default {
+  INIT: 'INIT',
+  PUSH: 'PUSH',
+  REPLACE: 'REPLACE',
+  SHIFT: 'SHIFT',
+};

package/src/session/subscription/Subscription.js

@@ -0,0 +1,76 @@
+export default class Subscription {
+  constructor({ activateSubscription } = {}) {
+    this._activateSubscription = activateSubscription;
+
+    // This property is accessed in tests.
+    this._listeners = [];
+  }
+
+  notifySubscribers = (argument) => {
+    // `._latest` is only used in tests.
+    this._latest = argument;
+    for (const { listener } of this._listeners) {
+      listener(argument);
+    }
+  };
+
+  subscribe(listener) {
+    // If subscriptions are stopped, i.e. no new subscriptions are to be added,
+    // then don't add any listeners and return a "do nothing" function.
+    if (this._stopped) {
+      return () => {};
+    }
+
+    // Creating a `listenerEntry` object ensures that the `.filter()` function
+    // during "unsubscribe" step doesn't accidentally remove another listeners
+    // having the same `listener` function.
+    // I.e. it's not illegal to call `.subscribe(listener)` multiple times
+    // with the same argument, and those would be considered different subscriptions.
+    const listenerEntry = { listener };
+
+    // If it's the first listener, activate subscription.
+    if (this._listeners.length === 0) {
+      this._deactivateSubscription = this._activateSubscription(
+        this.notifySubscribers,
+      );
+    }
+
+    // Add the `listener` to the list.
+    this._listeners.push(listenerEntry);
+
+    // The returned `unsubscribe()` function is "idempotent", i.e. it can be called multiple times.
+    return () => {
+      // Remove the listener, if not already removed.
+      this._removeListener(listenerEntry);
+    };
+  }
+
+  stop() {
+    if (this._stopped) {
+      throw new Error('Already stopped');
+    }
+
+    this._stopped = true;
+
+    // Clear any remaining listeners.
+    for (const listener of this._listeners.slice()) {
+      this._removeListener(listener);
+    }
+  }
+
+  _removeListener(listenerEntry) {
+    // If no listeners are left, no need to do anything.
+    if (this._listeners.length === 0) {
+      return;
+    }
+
+    // Remove the `listener` from the list.
+    this._listeners = this._listeners.filter((_) => _ !== listenerEntry);
+
+    // If it was the last listener, deactivate subscription.
+    if (this._listeners.length === 0) {
+      this._deactivateSubscription();
+      this._deactivateSubscription = undefined;
+    }
+  }
+}

package/test/NavigationStack.test.js

@@ -0,0 +1,296 @@
+import delay from 'delay';
+
+import NavigationStack from '../src/NavigationStack';
+import InMemorySession from '../src/session/InMemorySession';
+import WebBrowserSession from '../src/session/WebBrowserSession';
+
+describe('NavigationStack', () => {
+  let navigationStack;
+
+  beforeEach(() => {
+    navigationStack = new NavigationStack(new InMemorySession());
+    navigationStack.init('/initial');
+  });
+
+  afterEach(() => {
+    // Even if a test errors, the `NavigationStack` should still be stopped
+    // in order to remove the potential "popstate" listener so that it doesn't
+    // interfere with other tests.
+    navigationStack.stop();
+  });
+
+  it('should support `push` and `shift` navigation operations', () => {
+    navigationStack.push('/new');
+    expect(navigationStack.current()).to.include({
+      pathname: '/new',
+      // index: 1,
+    });
+
+    navigationStack.shift(-1);
+    expect(navigationStack.current()).to.include({
+      pathname: '/initial',
+      // index: 0,
+    });
+
+    navigationStack.shift(+1);
+    expect(navigationStack.current()).to.include({
+      pathname: '/new',
+      // index: 1,
+    });
+  });
+
+  it('should support `replace` navigation operation', () => {
+    navigationStack.replace('/new');
+    expect(navigationStack.current()).to.include({
+      pathname: '/new',
+      // index: 0,
+    });
+  });
+});
+
+describe('NavigationStack (WebBrowserSession)', () => {
+  let navigationStack;
+
+  beforeEach(() => {
+    window.history.replaceState(null, null, '/initial');
+
+    navigationStack = new NavigationStack(new WebBrowserSession());
+
+    navigationStack.init();
+  });
+
+  afterEach(() => {
+    // Even if a test errors, the `NavigationStack` should still be stopped
+    // in order to remove the potential "popstate" listener so that it doesn't
+    // interfere with other tests.
+    navigationStack.stop();
+  });
+
+  it('should allow calling `init()` without an argument, and then support `push` and `shift` navigation operations', async () => {
+    navigationStack.push('/new');
+    await delay(20);
+    expect(navigationStack.current()).to.include({
+      pathname: '/new',
+      // index: 1,
+    });
+
+    navigationStack.shift(-1);
+    await delay(20);
+    expect(navigationStack.current()).to.include({
+      pathname: '/initial',
+      // index: 0,
+    });
+
+    navigationStack.shift(+1);
+    await delay(20);
+    expect(navigationStack.current()).to.include({
+      pathname: '/new',
+      // index: 1,
+    });
+  });
+
+  it('should allow calling `init()` without an argument, and then support `replace` navigation operation', async () => {
+    navigationStack.replace('/new');
+    await delay(20);
+    expect(navigationStack.current()).to.include({
+      pathname: '/new',
+      // index: 0,
+    });
+  });
+});
+
+describe('NavigationStack.subscribe', () => {
+  let navigationStack;
+
+  afterEach(() => {
+    // Even if a test errors, the `NavigationStack` should still be stopped
+    // in order to remove the potential "popstate" listener so that it doesn't
+    // interfere with other tests.
+    navigationStack.stop();
+  });
+
+  it('should subscribe to location changes', () => {
+    navigationStack = new NavigationStack(new InMemorySession());
+
+    const listener = sinon.spy();
+
+    const unsubscribe = navigationStack.subscribe(listener);
+
+    navigationStack.init('/initial');
+
+    // `.init()` calls subscription listeners.
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.lastCall.args[0]).to.include({
+      // operation: 'INIT',
+      pathname: '/initial',
+    });
+    listener.resetHistory();
+
+    navigationStack.push('/new');
+
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.lastCall.args[0]).to.include({
+      // operation: 'PUSH',
+      pathname: '/new',
+    });
+    listener.resetHistory();
+
+    navigationStack.replace('/new-2');
+
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.lastCall.args[0]).to.include({
+      // operation: 'REPLACE',
+      pathname: '/new-2',
+    });
+    listener.resetHistory();
+
+    navigationStack.shift(-1);
+
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.lastCall.args[0]).to.include({
+      // operation: 'SHIFT',
+      // delta: -1,
+      pathname: '/initial',
+    });
+    listener.resetHistory();
+
+    unsubscribe();
+
+    navigationStack.push('/new-3');
+
+    // Unsubscribed, so the listener doesn't get called.
+    expect(listener).to.not.have.been.called();
+  });
+
+  it('should subscribe to location changes (WebBrowserSession)', () => {
+    window.history.replaceState(null, null, '/initial');
+
+    navigationStack = new NavigationStack(new WebBrowserSession());
+
+    const listener = sinon.spy();
+
+    const unsubscribe = navigationStack.subscribe(listener);
+
+    navigationStack.init();
+
+    // `.init()` calls subscription listeners.
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.lastCall.args[0]).to.include({
+      // operation: 'INIT',
+      pathname: '/initial',
+    });
+    listener.resetHistory();
+
+    unsubscribe();
+  });
+});
+
+describe('NavigationStack.stop()', () => {
+  const sandbox = sinon.createSandbox();
+
+  afterEach(() => {
+    // Even if a test errors, the spies should be removed, otherwise it'll say:
+    // "Attempted to wrap addEventListener which is already wrapped".
+    sandbox.restore();
+  });
+
+  it('should remove "popstate" listener on stop', () => {
+    sandbox.spy(window, 'addEventListener');
+    sandbox.spy(window, 'removeEventListener');
+
+    const session = new WebBrowserSession();
+
+    const navigationStack = new NavigationStack(session);
+
+    // This subscription won't be "unsubscribed" by the code.
+    // It is expected to be "unsubscribed" automatically on `navigationStack.stop()`
+    // and not hold off the clearing of `popstate` listener.
+    navigationStack.subscribe(() => {});
+
+    navigationStack.init();
+
+    navigationStack.push('/new');
+
+    navigationStack.stop();
+
+    expect(window.addEventListener)
+      .to.have.been.calledOnce()
+      .and.to.have.been.called.with('popstate');
+
+    expect(window.removeEventListener)
+      .to.have.been.calledOnce()
+      .and.to.have.been.called.with('popstate');
+  });
+});
+
+describe('NavigationStack', () => {
+  let navigationStack;
+
+  afterEach(() => {
+    // Even if a test errors, the `NavigationStack` should still be stopped
+    // in order to remove the potential "popstate" listener so that it doesn't
+    // interfere with other tests.
+    //
+    // `navigationStack.stop()` method is "idempotent", i.e. it can be called multiple times.
+    //
+    navigationStack.stop();
+  });
+
+  it('should support `basePath`', () => {
+    const session = new InMemorySession();
+
+    navigationStack = new NavigationStack(session, {
+      basePath: '/base',
+    });
+
+    navigationStack.init('/initial');
+
+    navigationStack.push('/new');
+
+    // eslint-disable-next-line no-underscore-dangle
+    expect(session._subscription._latest.pathname).to.equal('/base/new');
+
+    expect(navigationStack.current()).to.include({
+      pathname: '/new',
+      // index: 1,
+    });
+  });
+
+  it('should support `maintainScrollPosition: true` option', async () => {
+    navigationStack = new NavigationStack(new WebBrowserSession(), {
+      maintainScrollPosition: true,
+    });
+
+    navigationStack.init();
+
+    navigationStack.locationRendered();
+
+    navigationStack.push('/new');
+
+    navigationStack.locationRendered();
+
+    const scrollableContainer = document.createElement('div');
+    document.body.appendChild(scrollableContainer);
+
+    const removeScrollableContainer = navigationStack.addScrollableContainer(
+      'container',
+      scrollableContainer,
+    );
+
+    // `PageScrollPositionSetter` works in an asynchronous fashion,
+    // so this delay lets it finish setting page scroll position
+    // before proceeding to next location.
+    await delay(20);
+
+    removeScrollableContainer();
+
+    navigationStack.shift(-1);
+
+    navigationStack.locationRendered();
+
+    // `PageScrollPositionSetter` works in an asynchronous fashion,
+    // so this delay lets it finish setting page scroll position
+    // before proceeding to next location.
+    await delay(20);
+  });
+});

package/test/{LocationDataStorage.test.js → data-storage/LocationDataStorage.test.js}

@@ -1,5 +1,5 @@
-import LocationDataStorage from '../src/LocationDataStorage';
-import MemorySession from '../src/session/MemorySession';
+import LocationDataStorage from '../../src/data-storage/LocationDataStorage';
+import InMemorySession from '../../src/session/InMemorySession';
 
 describe('LocationDataStorage', () => {
   let session;
@@ -12,7 +12,7 @@ describe('LocationDataStorage', () => {
   beforeEach(() => {
     window.sessionStorage.clear();
 
-    session = new MemorySession('/initial-location');
+    session = new InMemorySession();
     stateStorage = new LocationDataStorage(session, {
       namespace: 'test',
     });

package/test/data-storage/index.test.js

@@ -0,0 +1,8 @@
+import * as exports from '../../src/data-storage';
+
+describe('index', () => {
+  it('should export top level correctly', () => {
+    expect(exports.DataStorage).to.exist();
+    expect(exports.LocationDataStorage).to.exist();
+  });
+});

package/test/index.js

@@ -1,7 +1,19 @@
 import dirtyChai from 'dirty-chai';
 
+// `dirty-chai` package is used to create functions like `.to.be.true()`
+// from `chai` `expect` properties like `.to.be.true`.
+//
+// The rationale is that the latter form — i.e. when not using `dirty-chai` —
+// is prone to typos like `.to.be.ture` which wouldn't throw any error and the test would still pass.
+// Contrary to that, `.to.be.ture()` notation would catch the typo and would throw an error.
+//
+// https://stackoverflow.com/questions/54332284/what-exactly-does-dirty-chai-js-do
 global.chai.use(dirtyChai);
 
+// Ensure all files in src folder are loaded for proper code coverage analysis.
+const srcContext = require.context('../src', true, /.*\.js$/);
+srcContext.keys().forEach(srcContext);
+
 // const testsContext = import.meta.webpackContext('.', true, /\.test\.js$/);
 const testsContext = require.context('.', true, /\.test\.js$/);
 testsContext.keys().forEach(testsContext);

package/test/index.test.js

@@ -2,8 +2,6 @@ import * as exports from '../src';
 
 describe('index', () => {
   it('should export top level correctly', () => {
-    expect(exports.Actions).to.exist();
-    expect(exports.ActionTypes).to.exist();
     expect(exports.addBasePath).to.exist();
     expect(exports.removeBasePath).to.exist();
     expect(exports.getLocationUrl).to.exist();
@@ -11,10 +9,13 @@ describe('index', () => {
     expect(exports.addNavigationBlocker).to.exist();
     expect(exports.getLocationUrl).to.exist();
     expect(exports.parseLocationUrl).to.exist();
-    expect(exports.createMiddlewares).to.exist();
-    expect(exports.locationReducer).to.exist();
-    expect(exports.BrowserSession).to.exist();
-    expect(exports.MemorySession).to.exist();
-    expect(exports.ServerSession).to.exist();
+    expect(exports.parseInputLocation).to.exist();
+    expect(exports.NavigationStack).to.exist();
+    expect(exports.Session).to.exist();
+    expect(exports.InMemorySession).to.exist();
+    expect(exports.WebBrowserSession).to.exist();
+    expect(exports.ServerSideRenderSession).to.exist();
+    expect(exports.ServerSideNavigationError).to.exist();
+    expect(exports.NavigationOutOfBoundsError).to.exist();
   });
 });

package/test/{helpers.js → middlewareTestUtil.js}

@@ -1,8 +1,5 @@
-import ActionTypes from '../src/ActionTypes';
-
-export function shouldWarn(about) {
-  console.warn.expected.push(about); // eslint-disable-line no-console
-}
+import ActionTypes from '../src/redux/ActionTypes';
+import ActionTypesInternal from '../src/redux/ActionTypesInternal';
 
 export function invokeLocationMiddleware(middleware, action) {
   let result;
@@ -19,16 +16,16 @@ export function invokeLocationMiddleware(middleware, action) {
 export function transformInputLocationUsingMiddleware(middleware, location) {
   return invokeLocationMiddleware(middleware, {
     type: ActionTypes.NAVIGATE,
-    payload: location,
-  }).payload;
+    payload: {
+      operation: 'PUSH',
+      location,
+    },
+  }).payload.location;
 }
 
-export function transformSubscriptionLocationUsingMiddleware(
-  middleware,
-  location,
-) {
+export function transformOutputLocationUsingMiddleware(middleware, location) {
   return invokeLocationMiddleware(middleware, {
-    type: ActionTypes.UPDATE,
+    type: ActionTypesInternal.INTERNAL_LOCATION_UPDATE,
     payload: location,
   }).payload;
 }

package/test/{normalizeInputLocation.test.js → parseInputLocationMiddleware.test.js}

@@ -1,9 +1,9 @@
-import normalizeInputLocation from '../src/normalizeInputLocation';
+import parseInputLocation from '../src/parseInputLocation';
 
-describe('normalizeInputLocation', () => {
+describe('parseInputLocation', () => {
   it('should create `query` from `search`', () => {
     expect(
-      normalizeInputLocation({
+      parseInputLocation({
         pathname: '/foo',
         search: '?bar=baz',
         hash: '#qux',
@@ -20,7 +20,7 @@ describe('normalizeInputLocation', () => {
 
   it('should add default `search` and `hash`', () => {
     expect(
-      normalizeInputLocation({
+      parseInputLocation({
         pathname: '/new/pathname',
       }),
     ).to.eql({
@@ -32,14 +32,14 @@ describe('normalizeInputLocation', () => {
   });
 
   it('should parse location URL', () => {
-    expect(normalizeInputLocation('/foo')).to.eql({
+    expect(parseInputLocation('/foo')).to.eql({
       pathname: '/foo',
       search: '',
       query: {},
       hash: '',
     });
 
-    expect(normalizeInputLocation('/foo?bar=baz')).to.eql({
+    expect(parseInputLocation('/foo?bar=baz')).to.eql({
       pathname: '/foo',
       search: '?bar=baz',
       query: {
@@ -48,14 +48,14 @@ describe('normalizeInputLocation', () => {
       hash: '',
     });
 
-    expect(normalizeInputLocation('/foo#qux')).to.eql({
+    expect(parseInputLocation('/foo#qux')).to.eql({
       pathname: '/foo',
       search: '',
       query: {},
       hash: '#qux',
     });
 
-    expect(normalizeInputLocation('/foo?bar=baz#qux')).to.eql({
+    expect(parseInputLocation('/foo?bar=baz#qux')).to.eql({
       pathname: '/foo',
       search: '?bar=baz',
       query: {
@@ -67,7 +67,7 @@ describe('normalizeInputLocation', () => {
 
   it('should create `search` from `query` when `search` is not present', () => {
     expect(
-      normalizeInputLocation({
+      parseInputLocation({
         pathname: '/foo',
         query: { bar: 'baz' },
         hash: '#qux',

package/test/{Action.test.js → redux/Action.test.js}

@@ -1,10 +1,11 @@
-import ActionTypes from '../src/ActionTypes';
-import Actions from '../src/Actions';
+import ActionTypes from '../../src/redux/ActionTypes';
+import Actions from '../../src/redux/Actions';
 
 describe('Actions', () => {
   it('#init should create an INIT action', () => {
-    expect(Actions.init()).to.eql({
+    expect(Actions.init('/foo?bar=baz#qux')).to.eql({
       type: ActionTypes.INIT,
+      payload: '/foo?bar=baz#qux',
     });
   });
 
@@ -64,9 +65,9 @@ describe('Actions', () => {
     });
   });
 
-  it('#dispose should create a DISPOSE action', () => {
-    expect(Actions.dispose()).to.eql({
-      type: ActionTypes.DISPOSE,
+  it('#stop should create a STOP action', () => {
+    expect(Actions.stop()).to.eql({
+      type: ActionTypes.STOP,
     });
   });
 });

package/test/{ActionTypes.test.js → redux/ActionTypes.test.js}

@@ -1,4 +1,4 @@
-import ActionTypes from '../src/ActionTypes';
+import ActionTypes from '../../src/redux/ActionTypes';
 
 describe('ActionTypes', () => {
   it('should have the correct exports', () => {
@@ -8,6 +8,6 @@ describe('ActionTypes', () => {
     expect(ActionTypes.NAVIGATE).to.exist();
     expect(ActionTypes.SHIFT).to.exist();
     expect(ActionTypes.UPDATE).to.exist();
-    expect(ActionTypes.DISPOSE).to.exist();
+    expect(ActionTypes.STOP).to.exist();
   });
 });