navigation-stack 0.2.0 → 0.3.0

package/README.md

@@ -95,7 +95,7 @@ A `location` object has all the properties of a [standard web browser location](
 * `index: number` — The index of the location in the navigation history, starting with `0` for the initial location.
 * `action: string` — The type of navigation that led to the location.
   * `INIT` in case of the initial location before any navigation has taken place.
-  * `POP` when the user performs a "Back" or "Forward" navigation, or after a `.shift()` navigation which is essentially a "back or forward navigation".
+  * `SHIFT` when the user performs a "Back" or "Forward" navigation, or after a `.shift()` navigation which is essentially a "back or forward navigation".
   * `PUSH` in case of a `.push()` navigation, i.e. "normal navigation via a hyperlink".
   * `REPLACE` in case of a `.replace()` navigation, i.e. "redirect".
 * `delta: number` — the difference between the `index` of the current location and the `index` of the previous location.

package/lib/cjs/session/BrowserSession.js

@@ -61,15 +61,21 @@ class BrowserNavigation {
     this._index = INITIAL_INDEX;
   }
   init() {
-    return this._createEntryFromCurrentLocation();
+    return this._createEntryFromCurrentLocation('INIT');
   }
-  _createEntryFromCurrentLocation() {
+  _createEntryFromCurrentLocation(action) {
     const {
       pathname,
       search,
       hash
     } = window.location;
     const isSettingInitialLocation = this._index === INITIAL_INDEX;
+    if (action === 'INIT' && !isSettingInitialLocation) {
+      throw Error('Browser session has already been initialized');
+    }
+    if (isSettingInitialLocation && action !== 'INIT') {
+      throw Error('Browser session must be initialized before reacting to location changes');
+    }
     const {
       key,
       index,
@@ -80,7 +86,7 @@ class BrowserNavigation {
       state: undefined
     }) : this._restoreAdditionalPropertiesForCurrentLocation();
     return {
-      action: isSettingInitialLocation ? 'INIT' : 'POP',
+      action,
       pathname,
       search,
       query: (0, _parseQueryFromSearch.default)(search),
@@ -96,7 +102,7 @@ class BrowserNavigation {
   // excluding ones that happened as a result of calling `.navigate()`.
   subscribe(listener) {
     const onPopState = () => {
-      listener(this._createEntryFromCurrentLocation());
+      listener(this._createEntryFromCurrentLocation('SHIFT'));
     };
     window.addEventListener('popstate', onPopState);
     return () => {

package/lib/cjs/session/MemorySession.js

@@ -120,7 +120,7 @@ class MemoryNavigation {
     }
     if (this._subscriptionListener) {
       this._subscriptionListener(this._createLocationObject({
-        action: 'POP',
+        action: 'SHIFT',
         delta: this._index - prevIndex
       }));
     }

package/lib/esm/session/BrowserSession.js

@@ -57,15 +57,21 @@ class BrowserNavigation {
     this._index = INITIAL_INDEX;
   }
   init() {
-    return this._createEntryFromCurrentLocation();
+    return this._createEntryFromCurrentLocation('INIT');
   }
-  _createEntryFromCurrentLocation() {
+  _createEntryFromCurrentLocation(action) {
     const {
       pathname,
       search,
       hash
     } = window.location;
     const isSettingInitialLocation = this._index === INITIAL_INDEX;
+    if (action === 'INIT' && !isSettingInitialLocation) {
+      throw Error('Browser session has already been initialized');
+    }
+    if (isSettingInitialLocation && action !== 'INIT') {
+      throw Error('Browser session must be initialized before reacting to location changes');
+    }
     const {
       key,
       index,
@@ -76,7 +82,7 @@ class BrowserNavigation {
       state: undefined
     }) : this._restoreAdditionalPropertiesForCurrentLocation();
     return {
-      action: isSettingInitialLocation ? 'INIT' : 'POP',
+      action,
       pathname,
       search,
       query: parseQueryFromSearch(search),
@@ -92,7 +98,7 @@ class BrowserNavigation {
   // excluding ones that happened as a result of calling `.navigate()`.
   subscribe(listener) {
     const onPopState = () => {
-      listener(this._createEntryFromCurrentLocation());
+      listener(this._createEntryFromCurrentLocation('SHIFT'));
     };
     window.addEventListener('popstate', onPopState);
     return () => {

package/lib/esm/session/MemorySession.js

@@ -116,7 +116,7 @@ class MemoryNavigation {
     }
     if (this._subscriptionListener) {
       this._subscriptionListener(this._createLocationObject({
-        action: 'POP',
+        action: 'SHIFT',
         delta: this._index - prevIndex
       }));
     }

package/lib/index.d.ts

@@ -15,7 +15,7 @@ export interface Location<TState = any> {
   /**
    * See the README on the `action` property of `location`.
    */
-  action: 'PUSH' | 'REPLACE' | 'POP' | 'INIT';
+  action: 'PUSH' | 'REPLACE' | 'SHIFT' | 'INIT';
   /**
    * the path name; as on window.location e.g. '/foo'
    */
@@ -235,7 +235,9 @@ export interface Session {
 // 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;
 
   // These're internal variables that're manually set under the hood.
@@ -257,10 +259,7 @@ export class ServerSession extends SessionBase {
 }
 
 export class MemorySession extends SessionBase {
-  constructor(
-    initialLocation: InputLocation,
-    options?: MemorySessionOptions,
-  );
+  constructor(initialLocation: InputLocation, options?: MemorySessionOptions);
 }
 
 export const locationReducer: Reducer<Location, Action>;
@@ -269,6 +268,7 @@ export class LocationDataStorage {
   constructor(session: Session, options?: { namespace?: string });
 
   get(location: Location, key: string): any;
+
   set(location: Location, key: string, value: any): void;
 }
 
@@ -292,11 +292,7 @@ interface MiddlewareAPI<D extends Dispatch = Dispatch, S = any> {
   getState(): S;
 }
 
-interface Middleware<
-  DispatchExt = {},
-  S = any,
-  D extends Dispatch = Dispatch,
-> {
+interface Middleware<S = any, D extends Dispatch = Dispatch> {
   (api: MiddlewareAPI<D, S>): (next: Dispatch) => (action: any) => any;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navigation-stack",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Handles navigation in a web browser",
   "keywords": [
     "history",
@@ -51,6 +51,7 @@
     "@4c/cli": "^3.0.1",
     "@4c/prettier-config": "^1.1.0",
     "@babel/core": "^7.17.10",
+    "@definitelytyped/dtslint": "0.0.182",
     "@typescript-eslint/eslint-plugin": "^5.23.0",
     "@typescript-eslint/parser": "^5.23.0",
     "babel-loader": "^8.2.5",
@@ -64,7 +65,6 @@
     "delay": "^4.4.1",
     "dirty-chai": "^2.0.1",
     "doctoc": "^2.2.0",
-    "dtslint": "^4.2.1",
     "eslint-config-4catalyzer": "^1.4.1",
     "eslint-config-4catalyzer-typescript": "^3.2.1",
     "eslint-config-prettier": "^8.5.0",
@@ -90,10 +90,5 @@
     "sinon": "^11.1.2",
     "sinon-chai": "^3.7.0",
     "webpack": "^5.72.1"
-  },
-  "resolutions": {
-    "@definitelytyped/header-parser": "^0.0.41",
-    "@definitelytyped/typescript-versions": "^0.0.41",
-    "@definitelytyped/utils": "^0.0.41"
   }
 }

package/src/session/BrowserSession.js

@@ -58,14 +58,24 @@ class BrowserNavigation {
   }
 
   init() {
-    return this._createEntryFromCurrentLocation();
+    return this._createEntryFromCurrentLocation('INIT');
   }
 
-  _createEntryFromCurrentLocation() {
+  _createEntryFromCurrentLocation(action) {
     const { pathname, search, hash } = window.location;
 
     const isSettingInitialLocation = this._index === INITIAL_INDEX;
 
+    if (action === 'INIT' && !isSettingInitialLocation) {
+      throw Error('Browser session has already been initialized');
+    }
+
+    if (isSettingInitialLocation && action !== 'INIT') {
+      throw Error(
+        'Browser session must be initialized before reacting to location changes',
+      );
+    }
+
     const { key, index, delta, state } = isSettingInitialLocation
       ? this._createAdditionalPropertiesForNewLocation({
           delta: 1,
@@ -74,7 +84,7 @@ class BrowserNavigation {
       : this._restoreAdditionalPropertiesForCurrentLocation();
 
     return {
-      action: isSettingInitialLocation ? 'INIT' : 'POP',
+      action,
       pathname,
       search,
       query: parseQueryFromSearch(search),
@@ -90,7 +100,7 @@ class BrowserNavigation {
   // excluding ones that happened as a result of calling `.navigate()`.
   subscribe(listener) {
     const onPopState = () => {
-      listener(this._createEntryFromCurrentLocation());
+      listener(this._createEntryFromCurrentLocation('SHIFT'));
     };
 
     window.addEventListener('popstate', onPopState);

package/src/session/MemorySession.js

@@ -118,7 +118,7 @@ class MemoryNavigation {
     if (this._subscriptionListener) {
       this._subscriptionListener(
         this._createLocationObject({
-          action: 'POP',
+          action: 'SHIFT',
           delta: this._index - prevIndex,
         }),
       );

package/test/middleware/createBeforeLocationChangeListenerMiddleware.test.js

@@ -94,7 +94,7 @@ describe('createBeforeLocationChangeListenerMiddleware', () => {
     });
   });
 
-  describe('POP navigations', () => {
+  describe('SHIFT navigations', () => {
     beforeEach(() => {
       store.dispatch(Actions.push('/bar'));
     });
@@ -109,7 +109,7 @@ describe('createBeforeLocationChangeListenerMiddleware', () => {
       expect(listener).to.have.been.calledOnce();
 
       expect(listener.firstCall.args[0]).to.include({
-        action: 'POP',
+        action: 'SHIFT',
         pathname: '/foo',
         delta: -1,
       });

package/test/middleware/createNavigationBlockerMiddleware.test.js

@@ -210,7 +210,7 @@ describe('createNavigationBlockerMiddleware', () => {
     });
   });
 
-  describe('POP navigations', () => {
+  describe('SHIFT navigations', () => {
     beforeEach(() => {
       store.dispatch(Actions.push('/bar'));
     });
@@ -223,7 +223,7 @@ describe('createNavigationBlockerMiddleware', () => {
       expect(store.getState().pathname).to.equal('/foo');
 
       expect(blocker.firstCall.args[0]).to.include({
-        action: 'POP',
+        action: 'SHIFT',
         pathname: '/foo',
         delta: -1,
       });
@@ -309,7 +309,7 @@ describe('createNavigationBlockerMiddleware', () => {
 
       store.dispatch(Actions.shift(-1));
 
-      // session popped, update to store blocked.
+      // session shifted, update to store blocked.
       expect(session.navigation.init().pathname).to.equal('/foo');
       expect(store.getState().pathname).to.equal('/bar');
 
@@ -326,7 +326,7 @@ describe('createNavigationBlockerMiddleware', () => {
       sessionDeferred.resolve();
       await delay(10);
 
-      // session re-popped, update to store delayed.
+      // session re-shifted (the rewind was undone), update to store delayed.
       expect(session.navigation.init().pathname).to.equal('/foo');
       expect(store.getState().pathname).to.equal('/foo');
     });
@@ -335,7 +335,7 @@ describe('createNavigationBlockerMiddleware', () => {
       const deferred = pDefer();
       addNavigationBlocker(() => deferred.promise);
 
-      // Update location with a `POP` action.
+      // Update location with a `SHIFT` action.
       /* eslint-disable no-underscore-dangle */
       session.navigation._index = 0;
       session.navigation._subscriptionListener(session.navigation.init(null));
@@ -354,7 +354,7 @@ describe('createNavigationBlockerMiddleware', () => {
     //   const deferred = pDefer();
     //   addNavigationBlocker(() => deferred.promise);
     //
-    //   // Update location with a `POP` action.
+    //   // Update location with a `SHIFT` action.
     //   /* eslint-disable no-underscore-dangle */
     //   session.navigation._index = 0;
     //   session.navigation._subscriptionListener(session.navigation.init(null));

package/test/session/BrowserSession.test.js

@@ -116,7 +116,7 @@ describe('BrowserSession', () => {
     });
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.deep.include({
-      action: 'POP',
+      action: 'SHIFT',
       pathname: '/bar',
       search: '?search',
       hash: '#hash',
@@ -133,7 +133,7 @@ describe('BrowserSession', () => {
     expect(window.location.pathname).to.equal('/foo');
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.deep.include({
-      action: 'POP',
+      action: 'SHIFT',
       pathname: '/foo',
       index: 0,
       delta: -1,
@@ -167,7 +167,7 @@ describe('BrowserSession', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.include({
-      action: 'POP',
+      action: 'SHIFT',
       pathname: '/bar',
     });
     listener.resetHistory();

package/test/session/MemorySession.test.js

@@ -62,7 +62,7 @@ describe('MemorySession', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.deep.include({
-      action: 'POP',
+      action: 'SHIFT',
       pathname: '/bar',
       key: barLocation.key,
       index: 1,
@@ -83,7 +83,7 @@ describe('MemorySession', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.include({
-      action: 'POP',
+      action: 'SHIFT',
       pathname: '/bar',
     });
     listener.resetHistory();
@@ -107,7 +107,7 @@ describe('MemorySession', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.include({
-      action: 'POP',
+      action: 'SHIFT',
       pathname: '/foo',
       delta: -2,
     });
@@ -121,7 +121,7 @@ describe('MemorySession', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.include({
-      action: 'POP',
+      action: 'SHIFT',
       pathname: '/baz',
       delta: 2,
     });
@@ -146,7 +146,7 @@ describe('MemorySession', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.include({
-      action: 'POP',
+      action: 'SHIFT',
       pathname: '/bar',
       delta: 1,
     });

package/types/index.d.ts

@@ -15,7 +15,7 @@ export interface Location<TState = any> {
   /**
    * See the README on the `action` property of `location`.
    */
-  action: 'PUSH' | 'REPLACE' | 'POP' | 'INIT';
+  action: 'PUSH' | 'REPLACE' | 'SHIFT' | 'INIT';
   /**
    * the path name; as on window.location e.g. '/foo'
    */
@@ -235,7 +235,9 @@ export interface Session {
 // 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;
 
   // These're internal variables that're manually set under the hood.
@@ -257,10 +259,7 @@ export class ServerSession extends SessionBase {
 }
 
 export class MemorySession extends SessionBase {
-  constructor(
-    initialLocation: InputLocation,
-    options?: MemorySessionOptions,
-  );
+  constructor(initialLocation: InputLocation, options?: MemorySessionOptions);
 }
 
 export const locationReducer: Reducer<Location, Action>;
@@ -269,6 +268,7 @@ export class LocationDataStorage {
   constructor(session: Session, options?: { namespace?: string });
 
   get(location: Location, key: string): any;
+
   set(location: Location, key: string, value: any): void;
 }
 
@@ -292,11 +292,7 @@ interface MiddlewareAPI<D extends Dispatch = Dispatch, S = any> {
   getState(): S;
 }
 
-interface Middleware<
-  DispatchExt = {},
-  S = any,
-  D extends Dispatch = Dispatch,
-> {
+interface Middleware<S = any, D extends Dispatch = Dispatch> {
   (api: MiddlewareAPI<D, S>): (next: Dispatch) => (action: any) => any;
 }