navigation-stack 0.5.3 → 0.6.1

package/test/session/{InMemorySession.test.js → Session.InMemoryEnvironment.test.js}

@@ -1,9 +1,10 @@
+import InMemoryEnvironment from '../../src/environment/InMemoryEnvironment';
 import parseInputLocation from '../../src/parseInputLocation';
-import InMemorySession from '../../src/session/InMemorySession';
+import Session from '../../src/session/Session';
 
-describe('InMemorySession', () => {
+describe('Session (InMemoryEnvironment)', () => {
   it('should parse the initial location', () => {
-    const session = new InMemorySession();
+    const session = new Session(InMemoryEnvironment);
 
     let location;
     session.subscribe((newLocation) => {
@@ -28,7 +29,7 @@ describe('InMemorySession', () => {
   });
 
   it('should support basic navigation', () => {
-    const session = new InMemorySession();
+    const session = new Session(InMemoryEnvironment);
 
     let location;
     session.subscribe((newLocation) => {
@@ -124,7 +125,7 @@ describe('InMemorySession', () => {
   });
 
   it('should support subscribing and unsubscribing', () => {
-    const session = new InMemorySession();
+    const session = new Session(InMemoryEnvironment);
     session.start(parseInputLocation('/initial'));
     session.navigate('push', { pathname: '/new' });
     session.navigate('push', { pathname: '/new-2' });
@@ -151,7 +152,7 @@ describe('InMemorySession', () => {
   });
 
   it('should respect stack bounds', () => {
-    const session = new InMemorySession();
+    const session = new Session(InMemoryEnvironment);
     session.start(parseInputLocation('/initial'));
     session.navigate('push', { pathname: '/new' });
     session.navigate('push', { pathname: '/new-2' });
@@ -205,7 +206,7 @@ describe('InMemorySession', () => {
   });
 
   it('should not reset forward entries on replace', () => {
-    const session = new InMemorySession();
+    const session = new Session(InMemoryEnvironment);
     session.start(parseInputLocation('/initial'));
     session.navigate('push', { pathname: '/new' });
     session.navigate('push', { pathname: '/new-2' });
@@ -228,7 +229,7 @@ describe('InMemorySession', () => {
   });
 
   it('should reset forward entries on push', () => {
-    const session = new InMemorySession();
+    const session = new Session(InMemoryEnvironment);
 
     session.start(parseInputLocation('/initial'));
     session.navigate('push', { pathname: '/new' });
@@ -249,7 +250,7 @@ describe('InMemorySession', () => {
   });
 
   it('should remove all subscriptions on stop', () => {
-    const session = new InMemorySession();
+    const session = new Session(InMemoryEnvironment);
 
     session.start(parseInputLocation('/initial'));
 

package/test/session/{ServerSession.test.js → Session.ServerSideRenderEnvironment.test.js}

@@ -1,9 +1,10 @@
+import ServerSideRenderEnvironment from '../../src/environment/ServerSideRenderEnvironment';
 import parseInputLocation from '../../src/parseInputLocation';
-import ServerSideRenderSession from '../../src/session/ServerSideRenderSession';
+import Session from '../../src/session/Session';
 
-describe('ServerSideRenderSession', () => {
+describe('Session (ServerSideRenderEnvironment)', () => {
   it('should parse the initial location', () => {
-    const session = new ServerSideRenderSession();
+    const session = new Session(ServerSideRenderEnvironment);
 
     let location;
     session.subscribe((newLocation) => {
@@ -24,7 +25,7 @@ describe('ServerSideRenderSession', () => {
   });
 
   it('should support subscriptions', () => {
-    const session = new ServerSideRenderSession();
+    const session = new Session(ServerSideRenderEnvironment);
     // eslint-disable-next-line no-unused-vars
     expect(() => session.subscribe((location) => {})).to.not.throw();
   });

package/test/session/{WebBrowserSession.test.js → Session.WebBrowserEnvironment.test.js}

@@ -1,9 +1,10 @@
 import delay from 'delay';
 
+import WebBrowserEnvironment from '../../src/environment/WebBrowserEnvironment';
 import parseInputLocation from '../../src/parseInputLocation';
-import WebBrowserSession from '../../src/session/WebBrowserSession';
+import Session from '../../src/session/Session';
 
-describe('WebBrowserSession.stop()', () => {
+describe('Session.stop() (WebBrowserEnvironment)', () => {
   const sandbox = sinon.createSandbox();
 
   afterEach(() => {
@@ -16,7 +17,7 @@ describe('WebBrowserSession.stop()', () => {
     sandbox.spy(window, 'addEventListener');
     sandbox.spy(window, 'removeEventListener');
 
-    const session = new WebBrowserSession();
+    const session = new Session(WebBrowserEnvironment);
 
     session.subscribe(() => {});
 
@@ -40,7 +41,7 @@ describe('WebBrowserSession.stop()', () => {
   });
 });
 
-describe('WebBrowserSession', () => {
+describe('Session (WebBrowserEnvironment)', () => {
   let session;
 
   afterEach(() => {
@@ -52,7 +53,7 @@ describe('WebBrowserSession', () => {
 
   it('should parse the initial location', () => {
     window.history.replaceState(null, null, '/initial?bar=baz#qux');
-    session = new WebBrowserSession();
+    session = new Session(WebBrowserEnvironment);
 
     let location;
     session.subscribe((newLocation) => {
@@ -75,7 +76,7 @@ describe('WebBrowserSession', () => {
   });
 
   it('should require initialization', () => {
-    session = new WebBrowserSession();
+    session = new Session(WebBrowserEnvironment);
 
     expect(() =>
       session.navigate('push', {
@@ -89,7 +90,7 @@ describe('WebBrowserSession', () => {
   it('should support basic navigation', async () => {
     window.history.replaceState(null, null, '/initial');
 
-    session = new WebBrowserSession();
+    session = new Session(WebBrowserEnvironment);
 
     let location;
     session.subscribe((newLocation) => {
@@ -178,7 +179,7 @@ describe('WebBrowserSession', () => {
       index: 2,
       delta: 0,
     });
-    await delay(20);
+    await delay(100);
 
     expect(window.location.pathname).to.equal('/new-3');
 
@@ -192,7 +193,7 @@ describe('WebBrowserSession', () => {
     listener.resetHistory();
 
     session.shift(-1);
-    await delay(20);
+    await delay(100);
 
     expect(window.location).to.include({
       pathname: '/new',
@@ -213,7 +214,7 @@ describe('WebBrowserSession', () => {
     listener.resetHistory();
 
     window.history.back();
-    await delay(20);
+    await delay(100);
 
     expect(window.location.pathname).to.equal('/initial');
 
@@ -229,7 +230,7 @@ describe('WebBrowserSession', () => {
 
   it('should support subscribing and unsubscribing', async () => {
     window.history.replaceState(null, null, '/');
-    session = new WebBrowserSession();
+    session = new Session(WebBrowserEnvironment);
     session.start(parseInputLocation(window.location));
     session.navigate('push', {
       pathname: '/new',
@@ -246,7 +247,7 @@ describe('WebBrowserSession', () => {
     const unsubscribe = session.subscribe(listener);
 
     session.shift(-1);
-    await delay(20);
+    await delay(100);
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.firstCall.args[0]).to.include({
@@ -258,8 +259,57 @@ describe('WebBrowserSession', () => {
     unsubscribe();
 
     session.shift(-1);
-    await delay(20);
+    await delay(100);
 
     expect(listener).not.to.have.been.called();
   });
 });
+
+describe('Session (WebBrowserEnvironment) (restart)', () => {
+  it('should restart a previously-started session', async () => {
+    window.history.replaceState(null, null, '/initial');
+
+    let currentLocation;
+    const locationListener = (location) => {
+      currentLocation = location;
+    };
+
+    const session = new Session(WebBrowserEnvironment);
+    session.subscribe(locationListener);
+    session.start();
+    session.navigate('push', parseInputLocation('/new'));
+    session.stop();
+
+    const latestLocationIndex = currentLocation.index;
+    expect(latestLocationIndex > 0).to.equal(true);
+
+    // Simulate the user refreshing the page in a web browser.
+    // In such case, `window.history` will be retained
+    // but every javascript variable will be recreated from scratch.
+    const newSession = new Session(WebBrowserEnvironment);
+    newSession.subscribe(locationListener);
+    newSession.start();
+
+    // eslint-disable-next-line no-underscore-dangle
+    expect(newSession._subscription._latest.operation).to.equal('init');
+
+    expect(currentLocation.pathname).to.equal('/new');
+    expect(currentLocation.index).to.equal(latestLocationIndex);
+
+    newSession.shift(-1);
+
+    await delay(100);
+
+    expect(currentLocation.pathname).to.equal('/initial');
+    expect(currentLocation.index).to.equal(latestLocationIndex - 1);
+
+    newSession.shift(1);
+
+    await delay(100);
+
+    expect(currentLocation.pathname).to.equal('/new');
+    expect(currentLocation.index).to.equal(latestLocationIndex);
+
+    newSession.stop();
+  });
+});

package/test/shouldWarn.js

@@ -0,0 +1,44 @@
+// With such `import`, tests wouldn't work and would throw an error:
+// "console.warn.restore is not a function".
+// It could or could not be related to using `karma` test runner.
+//
+// import sinon from 'sinon';
+
+export default function shouldWarn(about) {
+  console.warn.expected.push(about); // eslint-disable-line no-console
+}
+
+export function stubWarn() {
+  /* eslint-disable no-console */
+  sinon.stub(console, 'warn').callsFake((message) => {
+    let expected = false;
+
+    console.warn.expected.forEach((about) => {
+      if (message.includes(about)) {
+        console.warn.warned[about] = true;
+        expected = true;
+      }
+    });
+
+    if (expected) {
+      return;
+    }
+
+    console.warn.threw = true;
+    throw new Error(message);
+  });
+
+  console.warn.expected = [];
+  console.warn.warned = Object.create(null);
+  console.warn.threw = false;
+
+  return () => {
+    const { expected, warned, threw } = console.warn;
+    console.warn.restore();
+
+    if (!threw && expected.length) {
+      expect(warned).to.have.keys(expected);
+    }
+  };
+  /* eslint-enable no-console */
+}

package/test/stringifyQuery.test.js

@@ -0,0 +1,65 @@
+import stringifyQuery from '../src/stringifyQuery';
+
+describe('stringifyQuery', () => {
+  it('stringify', () => {
+    expect(stringifyQuery({ foo: 'bar' })).to.equal('foo=bar');
+    expect(
+      stringifyQuery({
+        foo: 'bar',
+        bar: 'baz',
+      }),
+    ).to.equal('foo=bar&bar=baz');
+  });
+
+  it('different types', () => {
+    expect(stringifyQuery({})).to.equal('');
+  });
+
+  it('primitive types', () => {
+    expect(stringifyQuery({ a: 'string' })).to.equal('a=string');
+    expect(stringifyQuery({ a: true, b: false })).to.equal('a=true&b=false');
+    expect(stringifyQuery({ a: 0, b: 1n })).to.equal('a=0&b=1');
+    expect(stringifyQuery({ a: null, b: undefined })).to.equal('a');
+  });
+
+  it('URI encode', () => {
+    expect(stringifyQuery({ 'foo bar': 'baz faz' })).to.equal(
+      'foo%20bar=baz%20faz',
+    );
+    expect(stringifyQuery({ 'foo bar': "baz'faz" })).to.equal(
+      'foo%20bar=baz%27faz',
+    );
+  });
+
+  it('handle array value', () => {
+    expect(() => {
+      stringifyQuery({
+        abc: 'abc',
+        foo: ['bar', 'baz'],
+      });
+    }).to.throw('Array values are not supported');
+  });
+
+  it('should not encode undefined values', () => {
+    expect(
+      stringifyQuery({
+        abc: undefined,
+        foo: 'baz',
+      }),
+    ).to.equal('foo=baz');
+  });
+
+  it('should encode null values as just a key', () => {
+    expect(
+      stringifyQuery({
+        'x y z': null,
+        'abc': null,
+        'foo': 'baz',
+      }),
+    ).to.equal('x%20y%20z&abc&foo=baz');
+  });
+
+  it('encoding', () => {
+    expect(stringifyQuery({ foo: "'bar'" })).to.equal('foo=%27bar%27');
+  });
+});

package/types/index.d.ts

@@ -1,5 +1,3 @@
-// TypeScript Version: 3.0
-
 export {};
 
 export type Query = Record<string, string>;
@@ -97,11 +95,11 @@ export type NavigationBlockerResult =
  *
  * * The `location` argument is `null` when the web browser tab is about to be closed.
  * * The `location` argument is of type `LocationBase` when a `.push()` or `.replace()` navigation is blocked.
- * * The `location` argument is of type `Location` when blocking a navigation that was initiated outside of the application code.
+ * * The `location` argument is of type `LocationBase` 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 type NavigationBlocker = (
-  location: Location | LocationBase | null,
+  location: LocationBase | null,
 ) => NavigationBlockerResult;
 
 // I dunno why did they use an `interface` here.
@@ -123,20 +121,18 @@ export function parseLocationUrl(locationUrl: string): LocationBase;
 
 export function parseInputLocation(location: InputLocation): LocationBase;
 
-export function addNavigationBlocker(
-  session: Session,
-  blocker: NavigationBlocker,
-): () => void;
-
-export interface NavigationStackOptions {
+export interface NavigationStackOptions<ScrollableContainer, Anchor> {
   basePath?: string;
-  maintainScrollPosition?: boolean;
+  manageScrollPosition?: boolean;
+  scrollPositionSetter?: Constructor<
+    ScrollPositionSetter<ScrollableContainer, Anchor>
+  >;
 }
 
 export class NavigationStack<ScrollableContainer = any, Anchor = any> {
   constructor(
-    session: Session<ScrollableContainer, Anchor>,
-    options?: NavigationStackOptions,
+    environment: Constructor<Environment<ScrollableContainer, Anchor>>,
+    options?: NavigationStackOptions<ScrollableContainer, Anchor>,
   );
 
   addScrollableContainer(
@@ -144,6 +140,10 @@ export class NavigationStack<ScrollableContainer = any, Anchor = any> {
     scrollableContainer: ScrollableContainer,
   ): () => void;
 
+  addNavigationBlocker(blocker: NavigationBlocker): () => void;
+
+  dataStorage: LocationDataStorage;
+
   subscribe(listener: (location: Location) => void): () => void;
 
   current(): Location;
@@ -156,7 +156,7 @@ export class NavigationStack<ScrollableContainer = any, Anchor = any> {
 
   shift(delta: number): void;
 
-  locationRendered(): Promise<void>;
+  locationRendered(location: Location): Promise<void>;
 
   stop(): void;
 }
@@ -173,7 +173,7 @@ export type SessionExecutionStatusListener = (
 
 export type ScrollListener = () => void;
 
-export class ServerSideNavigationError extends Error {
+export class ServerSideRedirectError extends Error {
   constructor(location: LocationBase);
 
   location: LocationBase;
@@ -185,9 +185,11 @@ export class NavigationOutOfBoundsError extends Error {
   index: number;
 }
 
-export class Navigation {
-  // Subscribes to "location change" events.
-  subscribe(listener: (location: LocationInternal) => void): () => void;
+export class EnvironmentNavigation {
+  // Subscribes to "asynchronous" changes of the current location.
+  subscribeToAsyncrhonousLocationUpdates(
+    listener: (location: LocationInternal) => void,
+  ): () => void;
 
   init(
     initialLocation: LocationBase,
@@ -218,13 +220,19 @@ export interface EnvironmentDataStorage {
   set(key: string, value: string): void;
 }
 
-export interface SessionLifecycle {
+export interface EnvironmentLifecycle {
   addTerminationBlocker(blocker: SessionTerminationBlocker): () => void;
   addExecutionStatusListener(
     listener: SessionExecutionStatusListener,
   ): () => void;
 }
 
+export interface EnvironmentLog {
+  debug(...args: any[]): void;
+  warn(...args: any[]): void;
+  error(...args: any[]): void;
+}
+
 // Manages scroll position in an environment such as a web browser.
 export interface EnvironmentScrollPosition<ScrollableContainer, Anchor> {
   // Gets numeric scroll position of a page.
@@ -255,10 +263,13 @@ export interface EnvironmentScrollPosition<ScrollableContainer, Anchor> {
 
 export interface Environment<ScrollableContainer, Anchor> {
   dataStorage: EnvironmentDataStorage;
+  log: EnvironmentLog;
+  lifecycle: EnvironmentLifecycle;
+  navigation: EnvironmentNavigation;
   scrollPosition: EnvironmentScrollPosition<ScrollableContainer, Anchor>;
 }
 
-export interface Session<ScrollableContainer = any, Anchor = any> {
+interface Session<ScrollableContainer = any, Anchor = any> {
   // `key` should be unique within `environment.dataStorage`.
   // For example, `BrowserEnvironment` uses `window.sessionStorage`
   // that is shared across different sessions within a given web browser tab,
@@ -268,7 +279,7 @@ export interface Session<ScrollableContainer = any, Anchor = any> {
   // Private varibles. Not public API.
   environment: Environment<ScrollableContainer, Anchor>;
 
-  lifecycle: SessionLifecycle;
+  lifecycle: EnvironmentLifecycle;
 
   subscribe(listener: (location: LocationInternal) => void): () => void;
 
@@ -282,12 +293,12 @@ export interface Session<ScrollableContainer = any, Anchor = any> {
 }
 
 // This is just a copy-paste of the `session` interface above.
-declare abstract class SessionBaseClass<
-  ScrollableContainer = any,
-  Anchor = any,
-> implements Session<ScrollableContainer, Anchor>
+declare abstract class SessionClass<ScrollableContainer = any, Anchor = any>
+  implements Session<ScrollableContainer, Anchor>
 {
-  constructor(parameters: { navigation: Navigation });
+  constructor(
+    environmentClass: Constructor<Environment<ScrollableContainer, Anchor>>,
+  );
 
   // `key` should be unique within `environment.dataStorage`.
   // For example, `BrowserEnvironment` uses `window.sessionStorage`
@@ -295,10 +306,11 @@ declare abstract class SessionBaseClass<
   // hence the uniqueness requirement.
   key: string;
 
-  // Private varibles. Not public API.
+  // Private varible. Not public API.
   environment: Environment<ScrollableContainer, Anchor>;
 
-  lifecycle: SessionLifecycle;
+  // Private varible. Not public API.
+  lifecycle: EnvironmentLifecycle;
 
   subscribe(listener: (location: LocationInternal) => void): () => void;
 
@@ -311,14 +323,148 @@ declare abstract class SessionBaseClass<
   shift(delta: number): void;
 }
 
-export class WebBrowserSession extends SessionBaseClass<HTMLElement, string> {
-  constructor();
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface WebBrowserEnvironment
+  extends Environment<HTMLElement, string> {}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ServerSideRenderEnvironment
+  extends Environment<string, string> {}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface InMemoryEnvironment extends Environment<string, string> {}
+
+// Theoretically, a developer could pass their own `ScrollPositionSetter` implementation
+// when calling `.addScrollableContainer()` or
+export interface ScrollPositionSetter<ScrollableContainer, Anchor> {
+  // Sets scroll position of a page or a scrollable element.
+  // Returns a `Promise` that resolves when it has finished setting the scroll position.
+  set(
+    // This is the scrollable container whose scroll position should be set.
+    // * When setting page scroll position, `scrollableContainer` is `undefined`.
+    // * When setting scrollable element scroll position, `scrollableContainer` is the scrollable element.
+    scrollableContainer: ScrollableContainer,
+    // This is the scroll position to set.
+    // * When setting page scroll position, it could be either an anchor or numeric coordinates.
+    // * When setting scrollable element scroll position, it could only be numeric coordinates.
+    scrollPositionOrAnchor: Anchor | [number, number],
+    // `scrollPosition` provides various "helper" methods for setting scroll position according to the environment.
+    // For example, in the context of a `WebBrowserEnvironment`, it provides the methods for setting scroll position in a web browser.
+    scrollPositionHelper: EnvironmentScrollPosition<
+      ScrollableContainer,
+      Anchor
+    >,
+  ): Promise<void>;
+
+  // Cancels any pending (or in-progress) setting of scroll position.
+  cancel(): void;
+}
+
+// https://stackoverflow.com/questions/39392853/is-there-a-type-for-class-in-typescript-and-does-any-include-it
+export type Constructor<T = any> = new (...args: any[]) => T;
+
+export type DataStorageValue =
+  | string
+  | number
+  | boolean
+  | Record<string, unknown>
+  | null
+  | undefined;
+
+declare class DataStorage<
+  Key extends string = string,
+  Value extends DataStorageValue = DataStorageValue,
+> {
+  constructor(session: Session, options: { namespace: string });
+
+  get(key: Key): Value | undefined;
+
+  set(key: Key, value: Value | undefined): void;
 }
 
-export class ServerSideRenderSession extends SessionBaseClass<string, string> {
-  constructor();
+declare class LocationDataStorage<
+  Key extends string = string,
+  Value extends DataStorageValue = DataStorageValue,
+> {
+  constructor(session: Session, options: { namespace: string });
+
+  get(location: Location, key: Key): Value;
+
+  set(location: Location, key: Key, value: Value): void;
 }
 
-export class InMemorySession extends SessionBaseClass<string, string> {
-  constructor();
+export class ScrollPositionRestoration<
+  ScrollableContainer = any,
+  Anchor = any,
+> {
+  constructor(
+    session: Session<ScrollableContainer, Anchor>,
+
+    options?: {
+      // Using this option, a developer could provide their own implementation of setting
+      // a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // When specified, it applies to both page and any scrollable containers.
+      scrollPositionSetter: ScrollPositionSetter<ScrollableContainer, Anchor>;
+
+      shouldChangePageScrollPositionOnLocationChange?: (
+        prevLocation: Location | undefined,
+        newLocation: Location,
+      ) => boolean;
+
+      // `options._getSavedPageScrollPositionOnLocationChange`
+      // isn't used in real life and is not part of the public API.
+      // It's only used in tests.
+      _getSavedPageScrollPositionOnLocationChange?: (
+        location: Location,
+        prevLocation: Location | undefined,
+      ) => [number, number] | undefined;
+
+      // Using this option, a developer could theoretically provide their own implementation
+      // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // This could be part of the public API if anyone provided a sensible real-world use case for it.
+      _pageScrollPositionSetter?: ScrollPositionSetter<
+        ScrollableContainer,
+        Anchor
+      >;
+    },
+  );
+
+  addScrollableContainer(
+    scrollableContainerKey: string,
+    scrollableContainer: ScrollableContainer,
+
+    options?: {
+      shouldChangeScrollPositionOnLocationChange?: (
+        prevLocation: Location | undefined,
+        newLocation: Location,
+      ) => boolean;
+
+      // `_options._getSavedScrollPositionOnLocationChange`
+      // isn't used in real life and is not part of the public API.
+      // It's only used in tests.
+      _getSavedScrollPositionOnLocationChange?: (
+        location: Location,
+        prevLocation: Location | undefined,
+      ) => [number, number] | undefined;
+
+      // Using this option, a developer could theoretically provide their own implementation
+      // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // This could be part of the public API if anyone provided a sensible real-world use case for it.
+      _scrollPositionSetter: ScrollPositionSetter<ScrollableContainer, Anchor>;
+    },
+  ): () => void;
+
+  locationRendered: (location: Location) => Promise<void>;
+
+  stop(): void;
+
+  // `_enableSavingScrollPosition()` and `_disableSavingScrollPosition()`
+  // aren't used in real life and are not part of the public API.
+  // They're only used in tests.
+  _enableSavingScrollPosition(): void;
+
+  // `_enableSavingScrollPosition()` and `_disableSavingScrollPosition()`
+  // aren't used in real life and are not part of the public API.
+  // They're only used in tests.
+  _disableSavingScrollPosition(): void;
 }

package/types/tsconfig.json

@@ -6,7 +6,6 @@
     "strict": true,
     "types": [],
     "noEmit": true,
-    "baseUrl": ".",
     "paths": {
       "navigation-stack": ["."]
     }