navigation-stack 0.1.2 → 0.2.0

package/test/{environment/BrowserEnvironment.test.js → session/BrowserSession.test.js}

@@ -1,39 +1,54 @@
 import delay from 'delay';
 
-import BrowserEnvironment from '../../src/environment/BrowserEnvironment';
+import BrowserSession from '../../src/session/BrowserSession';
 
-describe('BrowserEnvironment', () => {
+describe('BrowserSession', () => {
   beforeEach(() => {
     window.history.replaceState(null, null, '/');
   });
 
   it('should parse the initial location', () => {
     window.history.replaceState(null, null, '/foo?bar=baz#qux');
-    const environment = new BrowserEnvironment();
+    const session = new BrowserSession();
 
-    expect(environment.init()).to.eql({
-      action: 'POP',
+    expect(session.navigation.init()).to.deep.include({
+      action: 'INIT',
       pathname: '/foo',
       search: '?bar=baz',
       query: {
         bar: 'baz',
       },
       hash: '#qux',
-      key: undefined,
       index: 0,
       delta: 0,
       state: undefined,
     });
   });
 
+  it('should require initialization', () => {
+    const session = new BrowserSession();
+
+    expect(() =>
+      session.navigation.navigate({
+        action: 'PUSH',
+        pathname: '/bar',
+        search: '?search',
+        hash: '#hash',
+        state: { the: 'state' },
+      }),
+    ).to.throw('Browser session must be initialized before navigation');
+  });
+
   it('should support basic navigation', async () => {
     window.history.replaceState(null, null, '/foo');
-    const environment = new BrowserEnvironment();
+    const session = new BrowserSession();
 
     const listener = sinon.spy();
-    environment.subscribe(listener);
+    session.navigation.subscribe(listener);
 
-    const barLocation = environment.navigate({
+    session.navigation.init();
+
+    const barLocation = session.navigation.navigate({
       action: 'PUSH',
       pathname: '/bar',
       search: '?search',
@@ -58,7 +73,7 @@ describe('BrowserEnvironment', () => {
     expect(barLocation.key).not.to.be.empty();
 
     expect(
-      environment.navigate({
+      session.navigation.navigate({
         action: 'PUSH',
         pathname: '/baz',
         search: '',
@@ -74,7 +89,7 @@ describe('BrowserEnvironment', () => {
     expect(window.location.pathname).to.equal('/baz');
 
     expect(
-      environment.navigate({
+      session.navigation.navigate({
         action: 'REPLACE',
         pathname: '/qux',
         search: '',
@@ -91,7 +106,7 @@ describe('BrowserEnvironment', () => {
     expect(window.location.pathname).to.equal('/qux');
     expect(listener).not.to.have.been.called();
 
-    environment.shift(-1);
+    session.navigation.shift(-1);
     await delay(20);
 
     expect(window.location).to.include({
@@ -124,18 +139,20 @@ describe('BrowserEnvironment', () => {
       delta: -1,
       state: undefined,
     });
+
     listener.resetHistory();
   });
 
   it('should support subscribing and unsubscribing', async () => {
-    const environment = new BrowserEnvironment();
-    environment.navigate({
+    const session = new BrowserSession();
+    session.navigation.init();
+    session.navigation.navigate({
       action: 'PUSH',
       pathname: '/bar',
       search: '',
       hash: '',
     });
-    environment.navigate({
+    session.navigation.navigate({
       action: 'PUSH',
       pathname: '/baz',
       search: '',
@@ -143,9 +160,9 @@ describe('BrowserEnvironment', () => {
     });
 
     const listener = sinon.spy();
-    const unsubscribe = environment.subscribe(listener);
+    const unsubscribe = session.navigation.subscribe(listener);
 
-    environment.shift(-1);
+    session.navigation.shift(-1);
     await delay(20);
 
     expect(listener).to.have.been.calledOnce();
@@ -157,7 +174,7 @@ describe('BrowserEnvironment', () => {
 
     unsubscribe();
 
-    environment.shift(-1);
+    session.navigation.shift(-1);
     await delay(20);
 
     expect(listener).not.to.have.been.called();

package/test/session/MemorySession.test.js

@@ -0,0 +1,244 @@
+import MemorySession from '../../src/session/MemorySession';
+
+describe('MemorySession', () => {
+  it('should parse the initial location', () => {
+    const session = new MemorySession('/foo?bar=baz#qux');
+
+    expect(session.navigation.init()).to.deep.include({
+      action: 'INIT',
+      pathname: '/foo',
+      search: '?bar=baz',
+      query: {
+        bar: 'baz',
+      },
+      hash: '#qux',
+      index: 0,
+      delta: 0,
+    });
+  });
+
+  it('should support basic navigation', () => {
+    const session = new MemorySession('/foo');
+
+    const listener = sinon.spy();
+    session.navigation.subscribe(listener);
+
+    const barLocation = session.navigation.navigate({
+      action: 'PUSH',
+      pathname: '/bar',
+      state: { the: 'state' },
+    });
+
+    expect(barLocation).to.deep.include({
+      action: 'PUSH',
+      pathname: '/bar',
+      index: 1,
+      delta: 1,
+      state: { the: 'state' },
+    });
+    expect(barLocation.key).not.to.be.empty();
+
+    expect(
+      session.navigation.navigate({ action: 'PUSH', pathname: '/baz' }),
+    ).to.include({
+      action: 'PUSH',
+      pathname: '/baz',
+      index: 2,
+      delta: 1,
+    });
+
+    expect(
+      session.navigation.navigate({ action: 'REPLACE', pathname: '/qux' }),
+    ).to.include({
+      action: 'REPLACE',
+      pathname: '/qux',
+      index: 2,
+      delta: 0,
+    });
+
+    expect(listener).not.to.have.been.called();
+
+    session.navigation.shift(-1);
+
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.firstCall.args[0]).to.deep.include({
+      action: 'POP',
+      pathname: '/bar',
+      key: barLocation.key,
+      index: 1,
+      delta: -1,
+      state: { the: 'state' },
+    });
+  });
+
+  it('should support subscribing and unsubscribing', () => {
+    const session = new MemorySession('/foo');
+    session.navigation.navigate({ action: 'PUSH', pathname: '/bar' });
+    session.navigation.navigate({ action: 'PUSH', pathname: '/baz' });
+
+    const listener = sinon.spy();
+    const unsubscribe = session.navigation.subscribe(listener);
+
+    session.navigation.shift(-1);
+
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.firstCall.args[0]).to.include({
+      action: 'POP',
+      pathname: '/bar',
+    });
+    listener.resetHistory();
+
+    unsubscribe();
+
+    session.navigation.shift(-1);
+
+    expect(listener).not.to.have.been.called();
+  });
+
+  it('should respect stack bounds', () => {
+    const session = new MemorySession('/foo');
+    session.navigation.navigate({ action: 'PUSH', pathname: '/bar' });
+    session.navigation.navigate({ action: 'PUSH', pathname: '/baz' });
+
+    const listener = sinon.spy();
+    session.navigation.subscribe(listener);
+
+    session.navigation.shift(-390);
+
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.firstCall.args[0]).to.include({
+      action: 'POP',
+      pathname: '/foo',
+      delta: -2,
+    });
+    listener.resetHistory();
+
+    session.navigation.shift(-1);
+
+    expect(listener).not.to.have.been.called();
+
+    session.navigation.shift(+22);
+
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.firstCall.args[0]).to.include({
+      action: 'POP',
+      pathname: '/baz',
+      delta: 2,
+    });
+    listener.resetHistory();
+
+    session.navigation.shift(+1);
+
+    expect(listener).not.to.have.been.called();
+  });
+
+  it('should reset forward entries on push', () => {
+    const session = new MemorySession('/foo');
+    session.navigation.navigate({ action: 'PUSH', pathname: '/bar' });
+    session.navigation.navigate({ action: 'PUSH', pathname: '/baz' });
+    session.navigation.shift(-2);
+    session.navigation.navigate({ action: 'REPLACE', pathname: '/qux' });
+
+    const listener = sinon.spy();
+    session.navigation.subscribe(listener);
+
+    session.navigation.shift(+1);
+
+    expect(listener).to.have.been.calledOnce();
+    expect(listener.firstCall.args[0]).to.include({
+      action: 'POP',
+      pathname: '/bar',
+      delta: 1,
+    });
+  });
+
+  it('should not reset forward entries on replace', () => {
+    const session = new MemorySession('/foo');
+    session.navigation.navigate({ action: 'PUSH', pathname: '/bar' });
+    session.navigation.navigate({ action: 'PUSH', pathname: '/baz' });
+    session.navigation.shift(-2);
+    session.navigation.navigate({ action: 'PUSH', pathname: '/qux' });
+
+    const listener = sinon.spy();
+    session.navigation.subscribe(listener);
+
+    session.navigation.shift(+1);
+
+    expect(listener).not.to.have.been.called();
+  });
+
+  describe('persistence', () => {
+    // beforeEach(() => {
+    //   window.sessionStorage.clear();
+    // });
+
+    it('should support persistence', () => {
+      // function save(key, data) {
+      //   window.sessionStorage.setItem(key, data);
+      // }
+      //
+      // function load(key) {
+      //   return window.sessionStorage.getItem(key);
+      // }
+
+      const storage = {};
+
+      const save = (key, data) => {
+        storage[key] = data;
+      };
+
+      const load = (key) => {
+        return storage[key];
+      };
+
+      const session1 = new MemorySession('/foo', { save, load });
+      expect(session1.navigation.init()).to.include({
+        pathname: '/foo',
+      });
+
+      session1.navigation.navigate({ action: 'PUSH', pathname: '/bar' });
+      session1.navigation.navigate({ action: 'PUSH', pathname: '/baz' });
+      session1.navigation.shift(-1);
+
+      const session2 = new MemorySession('/foo', { save, load });
+      expect(session2.navigation.init()).to.include({
+        pathname: '/bar',
+      });
+
+      session2.navigation.shift(+1);
+      expect(session2.navigation.init()).to.include({
+        pathname: '/baz',
+      });
+    });
+
+    it('should ignore broken session storage entry', () => {
+      // function save(key, data) {
+      //   window.sessionStorage.setItem(key, data);
+      // }
+      //
+      // function load(key) {
+      //   return window.sessionStorage.getItem(key);
+      // }
+
+      const storage = {};
+
+      const save = (key, data) => {
+        storage[key] = data;
+      };
+
+      const load = (key) => {
+        return storage[key];
+      };
+
+      save(
+        // `stack` should have sufficient items so that the `index` wouldn't be out of bounds.
+        JSON.stringify({ stack: [], index: 2 }),
+      );
+
+      const session = new MemorySession('/foo', { save, load });
+      expect(session.navigation.init()).to.include({
+        pathname: '/foo',
+      });
+    });
+  });
+});

package/test/session/ServerSession.test.js

@@ -0,0 +1,23 @@
+import ServerSession from '../../src/session/ServerSession';
+
+describe('ServerSession', () => {
+  it('should parse the initial location', () => {
+    const session = new ServerSession('/foo?bar=baz#qux');
+
+    expect(session.navigation.init()).to.deep.include({
+      action: 'INIT',
+      pathname: '/foo',
+      search: '?bar=baz',
+      query: {
+        bar: 'baz',
+      },
+      hash: '#qux',
+    });
+  });
+
+  it('should have dummy support for subscriptions', () => {
+    const session = new ServerSession('/foo?bar=baz#qux');
+    const unsubscribe = session.navigation.subscribe();
+    expect(unsubscribe).to.not.throw();
+  });
+});

package/types/index.d.ts

@@ -13,12 +13,9 @@ export type InputLocationQuery = Record<
 
 export interface Location<TState = any> {
   /**
-   * 'PUSH' or 'REPLACE' if the location was reached via FarceActions.push or
-   * FarceActions.replace respectively; 'POP' on the initial location, or if
-   * the location was reached via the browser back or forward buttons or
-   * via FarceActions.shift
+   * See the README on the `action` property of `location`.
    */
-  action: 'PUSH' | 'REPLACE' | 'POP';
+  action: 'PUSH' | 'REPLACE' | 'POP' | 'INIT';
   /**
    * the path name; as on window.location e.g. '/foo'
    */
@@ -36,9 +33,9 @@ export interface Location<TState = any> {
    */
   hash: string;
   /**
-   * if present, a unique key identifying the current history entry
+   * a unique key identifying the current history entry
    */
-  key?: string;
+  key: string;
   /**
    * the current index of the history entry, starting at 0 for the initial
    * entry; this increments on FarceActions.push but not on
@@ -46,12 +43,11 @@ export interface Location<TState = any> {
    */
   index: number;
   /**
-   * the difference between the current index and the index of the previous
-   * location
+   * the difference between the current index and the index of the previous location
    */
   delta: number;
   /**
-   * additional location state that is not part of the URL
+   * any additional location state that the application might explicitly define and store
    */
   state: TState;
 }
@@ -70,11 +66,15 @@ export interface InputLocationObject {
 export interface LocationBase {
   pathname: Location['pathname'];
   search: Location['search'];
-  query?: Query;
+  query: Query;
   hash: Location['hash'];
   state?: Location['state'];
 }
 
+export interface NavigationLocation extends LocationBase {
+  action: 'PUSH' | 'REPLACE';
+}
+
 /**
  * Location descriptor string:
  *  store.dispatch(FarceActions.push('/foo?bar=baz#qux'));
@@ -109,13 +109,20 @@ export type NavigationBlockerResult =
   | Promise<NavigationBlockerSyncResult>;
 
 /**
- * The navigation listener function receives the `location` to which the user
- * is attempting to navigate.
+ * Navigation blocker function receives a `location` to which the application (or the user) is attempting to navigate.
  *
- * The `location` argument is `null` when the web browser tab is about to be closed.
+ * * The `location` argument is `null` when the web browser tab is about to be closed.
+ * * The `location` argument is of type `NavigationLocation` when a `.push()` or `.replace()` action is blocked.
+ * * The `location` argument is of type `Location` when blocking a navigation that was initiated outside of the application code.
+ *   For example, when the user clicks "Back" or "Forward" button in a web browser.
  */
 export interface NavigationBlocker {
-  (location: Location | LocationBase | null): NavigationBlockerResult;
+  (location: Location | NavigationLocation | null): NavigationBlockerResult;
+}
+
+// I dunno why did they use an `interface` here.
+export interface BeforeLocationChangeListener {
+  (location: Location): void;
 }
 
 export function addBasePath<L extends InputLocation>(
@@ -131,15 +138,20 @@ export function getLocationUrl(location: InputLocationObject): string;
 export function parseLocationUrl(locationUrl: string): LocationBase;
 
 export function createMiddlewares(
-  environment: Environment,
+  session: SessionBase,
   options?: CreateMiddlewaresOptions,
 ): Middleware[];
 
 export function addNavigationBlocker(
-  environment: EnvironmentBase,
+  session: SessionBase,
   blocker: NavigationBlocker,
 ): () => void;
 
+export function addBeforeLocationChangeListener(
+  session: SessionBase,
+  listener: BeforeLocationChangeListener,
+): () => void;
+
 export const ActionTypes: {
   INIT: '@@navigation-stack/INIT';
   PUSH: '@@navigation-stack/PUSH';
@@ -190,78 +202,71 @@ export const Actions: {
 
 type BeforeDestroyListener = () => boolean | undefined;
 
-export interface Environment {
+interface SessionNavigation {
   init(): void;
 
   // Subscribes to changes in location,
   // excluding ones that happened as a result of calling `.navigate()`.
   subscribe(listener: (location: Location) => void): () => void;
 
-  navigate(location: LocationBase): Location;
+  navigate(location: NavigationLocation): Location;
 
   shift(delta: number): void;
-
-  addBeforeDestroyListener(listener: BeforeDestroyListener): void;
-
-  getState(key: string): string | null;
-  removeState(key: string): void;
-  setState(key: string, value: string): void;
 }
 
-// This is just a copy-paste of the `Environment` interface above.
-declare abstract class EnvironmentBase implements Environment {
-  init(): void;
-
-  // Subscribes to changes in location,
-  // excluding ones that happened as a result of calling `.navigate()`.
-  subscribe(listener: (location: Location) => void): () => void;
+interface SessionDataStorage {
+  get(key: string): string | null;
+  remove(key: string): void;
+  set(key: string, value: string): void;
+}
 
-  navigate(location: LocationBase): Location;
+export interface Session {
+  navigation: SessionNavigation;
+  dataStorage: SessionDataStorage;
+  addBeforeDestroyListener(listener: BeforeDestroyListener): void;
 
-  shift(delta: number): void;
+  // These're internal variables that're manually set under the hood.
+  // _beforeLocationChangeListenersList?: Array<BeforeLocationChangeListener>;
+  // _navigationBlockersList?: Array<NavigationBlocker>;
+  // _removeBeforeDestroyListener?: () => void;
+  // _navigationBlockersEvaluationStatus?: { cancelled?: boolean };
+}
 
+// This is just a copy-paste of the `session` interface above.
+declare abstract class SessionBase implements Session {
+  navigation: SessionNavigation;
+  dataStorage: SessionDataStorage;
   addBeforeDestroyListener(listener: BeforeDestroyListener): void;
 
-  getState(key: string): string | null;
-  removeState(key: string): void;
-  setState(key: string, value: string): void;
+  // These're internal variables that're manually set under the hood.
+  // _beforeLocationChangeListenersList?: Array<BeforeLocationChangeListener>;
+  // _navigationBlockersList?: Array<NavigationBlocker>;
+  // _removeBeforeDestroyListener?: () => void;
+  // _navigationBlockersEvaluationStatus?: { cancelled?: boolean };
 }
 
-export class BrowserEnvironment extends EnvironmentBase {}
+export class BrowserSession extends SessionBase {}
 
-export interface MemoryEnvironmentOptions<MemoryEnvironmentState = any> {
-  save?: (state: MemoryEnvironmentState) => void;
-  load?: () => MemoryEnvironmentState | undefined | null;
+export interface MemorySessionOptions {
+  save?: (data: string) => void;
+  load?: () => string | undefined | null;
 }
 
-export class ServerEnvironment extends EnvironmentBase {
+export class ServerSession extends SessionBase {
   constructor(initialLocation: InputLocation);
 }
 
-export class MemoryEnvironment extends EnvironmentBase {
+export class MemorySession extends SessionBase {
   constructor(
     initialLocation: InputLocation,
-    options?: MemoryEnvironmentOptions,
+    options?: MemorySessionOptions,
   );
 }
 
-export interface QueryMiddlewareOptions {
-  stringify(query: InputLocationQuery): string;
-  parse(str: string): Query;
-}
-
-export function createQueryMiddleware(
-  options: QueryMiddlewareOptions,
-): Middleware;
-
-export const queryMiddleware: Middleware;
-
-export function createBasePathMiddleware(basePath?: string): Middleware;
-
 export const locationReducer: Reducer<Location, Action>;
 
-export class LocationStateStorage {
-  constructor(environment: Environment, options?: { namespace?: string });
+export class LocationDataStorage {
+  constructor(session: Session, options?: { namespace?: string });
 
   get(location: Location, key: string): any;
   set(location: Location, key: string, value: any): void;