navigation-stack 0.1.0

package/lib/esm/normalizeInputLocation.js

@@ -0,0 +1,41 @@
+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 = Object.assign({}, 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 = Object.assign({}, location, {
+      search: createSearchFromQuery(location.query)
+    });
+  }
+
+  // Set default values on `search` and `hash`
+  // if those properties are not present.
+  return Object.assign({}, location, {
+    search: location.search || '',
+    hash: location.hash || ''
+  });
+}

package/lib/esm/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/lib/esm/parseLocationUrl.js

@@ -0,0 +1,33 @@
+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/lib/esm/parseQueryFromSearch.js

@@ -0,0 +1,11 @@
+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/lib/index.d.ts

@@ -0,0 +1,301 @@
+// TypeScript Version: 3.0
+
+export {};
+
+export type Query = Record<string, string>;
+
+// `InputLocationQuery` may specify query parameter values as any type of data.
+// Those values will later be converted to strings.
+export type InputLocationQuery = Record<
+  string,
+  string | number | boolean | null | undefined
+>;
+
+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
+   */
+  action: 'PUSH' | 'REPLACE' | 'POP';
+  /**
+   * the path name; as on window.location e.g. '/foo'
+   */
+  pathname: string;
+  /**
+   * map version of search string
+   */
+  query: Query;
+  /**
+   * the search string; as on window.location e.g. '?bar=baz'
+   */
+  search: string;
+  /**
+   * the location hash; as on window.location e.g. '#qux'
+   */
+  hash: string;
+  /**
+   * if present, a unique key identifying the current history entry
+   */
+  key?: string;
+  /**
+   * the current index of the history entry, starting at 0 for the initial
+   * entry; this increments on FarceActions.push but not on
+   * FarceActions.replace
+   */
+  index: number;
+  /**
+   * 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
+   */
+  state: TState;
+}
+
+/**
+ * Location descriptor object used in #push and #replace.
+ */
+export interface InputLocationObject {
+  pathname: Location['pathname'];
+  search?: Location['search'];
+  query?: InputLocationQuery;
+  hash?: Location['hash'];
+  state?: Location['state'];
+}
+
+export interface LocationBase {
+  pathname: Location['pathname'];
+  search: Location['search'];
+  query?: Query;
+  hash: Location['hash'];
+  state?: Location['state'];
+}
+
+/**
+ * Location descriptor string:
+ *  store.dispatch(FarceActions.push('/foo?bar=baz#qux'));
+ *
+ * Equivalent location descriptor object:
+ *    store.dispatch(FarceActions.push({
+ *     pathname: '/foo',
+ *     search: '?bar=baz',
+ *     hash: '#qux',
+ *   }));
+ *
+ * https://github.com/4Catalyzer/farce#locations-and-location-descriptors
+ */
+export type InputLocationString = string;
+
+// Using an interface allows consumers to use object merging to add other
+//  location descriptor types.
+export interface InputLocationTypes {
+  object: InputLocationObject;
+  string: InputLocationString;
+}
+
+export type InputLocation = InputLocationTypes[keyof InputLocationTypes];
+
+export interface CreateMiddlewaresOptions {
+  basePath?: string;
+}
+
+export type NavigationBlockerSyncResult = boolean | undefined;
+export type NavigationBlockerResult =
+  | NavigationBlockerSyncResult
+  | Promise<NavigationBlockerSyncResult>;
+
+/**
+ * The navigation listener function receives the `location` to which the user
+ * is attempting to navigate.
+ *
+ * The `location` argument is `null` when the web browser tab is about to be closed.
+ */
+export interface NavigationBlocker {
+  (location: Location | LocationBase | null): NavigationBlockerResult;
+}
+
+export function addBasePath<L extends InputLocation>(
+  location: L,
+  basePath?: string,
+): L;
+export function removeBasePath<L extends InputLocation>(
+  location: L,
+  basePath?: string,
+): L;
+
+export function getLocationUrl(location: InputLocationObject): string;
+export function parseLocationUrl(locationUrl: string): LocationBase;
+
+export function createMiddlewares(
+  environment: Environment,
+  options?: CreateMiddlewaresOptions,
+): Middleware[];
+
+export function addNavigationBlocker(
+  environment: EnvironmentBase,
+  blocker: NavigationBlocker,
+): () => void;
+
+export const ActionTypes: {
+  INIT: '@@navigation-stack/INIT';
+  PUSH: '@@navigation-stack/PUSH';
+  REPLACE: '@@navigation-stack/REPLACE';
+  NAVIGATE: '@@navigation-stack/NAVIGATE';
+  SHIFT: '@@navigation-stack/SHIFT';
+  UPDATE: '@@navigation-stack/UPDATE';
+  DISPOSE: '@@navigation-stack/DISPOSE';
+};
+
+export interface InitAction {
+  type: (typeof ActionTypes)['INIT'];
+}
+
+export interface PushAction {
+  type: (typeof ActionTypes)['PUSH'];
+  payload: InputLocation;
+}
+
+export interface ReplaceAction {
+  type: (typeof ActionTypes)['REPLACE'];
+  payload: InputLocation;
+}
+
+export interface RewindAction {
+  type: (typeof ActionTypes)['SHIFT'];
+  payload: number;
+}
+
+export interface DisposeAction {
+  type: (typeof ActionTypes)['DISPOSE'];
+}
+
+export type Action =
+  | InitAction
+  | PushAction
+  | ReplaceAction
+  | RewindAction
+  | DisposeAction;
+
+export const Actions: {
+  init(): InitAction;
+  push(location: InputLocation): PushAction;
+  replace(location: InputLocation): ReplaceAction;
+  go(delta: number): RewindAction;
+  dispose(): DisposeAction;
+};
+
+type BeforeDestroyListener = () => boolean | undefined;
+
+export interface Environment {
+  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;
+
+  go(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;
+
+  navigate(location: LocationBase): Location;
+
+  go(delta: number): void;
+
+  addBeforeDestroyListener(listener: BeforeDestroyListener): void;
+
+  getState(key: string): string | null;
+  removeState(key: string): void;
+  setState(key: string, value: string): void;
+}
+
+export class BrowserEnvironment extends EnvironmentBase {}
+
+export interface MemoryEnvironmentOptions<MemoryEnvironmentState = any> {
+  save?: (state: MemoryEnvironmentState) => void;
+  load?: () => MemoryEnvironmentState | undefined | null;
+}
+
+export class ServerEnvironment extends EnvironmentBase {
+  constructor(initialLocation: InputLocation);
+}
+
+export class MemoryEnvironment extends EnvironmentBase {
+  constructor(
+    initialLocation: InputLocation,
+    options?: MemoryEnvironmentOptions,
+  );
+}
+
+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 });
+
+  get(location: Location, key: string): any;
+  set(location: Location, key: string, value: any): void;
+}
+
+// The following types are copy-pasted from `redux`.
+
+interface ReduxAction<T = any> {
+  type: T;
+}
+
+interface AnyAction extends ReduxAction {
+  // Allows any extra properties to be defined in an action.
+  [extraProps: string]: any;
+}
+
+interface Dispatch<A extends Action = AnyAction> {
+  <T extends A>(action: T): T;
+}
+
+interface MiddlewareAPI<D extends Dispatch = Dispatch, S = any> {
+  dispatch: D;
+  getState(): S;
+}
+
+interface Middleware<
+  DispatchExt = {},
+  S = any,
+  D extends Dispatch = Dispatch,
+> {
+  (api: MiddlewareAPI<D, S>): (next: Dispatch) => (action: any) => any;
+}
+
+type Reducer<S = any, A extends Action = AnyAction> = (
+  state: S | undefined,
+  action: A,
+) => S;

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "navigation-stack",
+  "version": "0.1.0",
+  "description": "Handles web browser navigation in a web application",
+  "keywords": [
+    "history",
+    "browser",
+    "navigation",
+    "router"
+  ],
+  "homepage": "https://gitlab.com/catamphetamine/navigation-stack#readme",
+  "bugs": {
+    "url": "https://gitlab.com/catamphetamine/navigation-stack/issues"
+  },
+  "license": "MIT",
+  "author": "catamphetamine",
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.js",
+  "types": "lib/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/catamphetamine/navigation-stack.git"
+  },
+  "scripts": {
+    "build": "rimraf lib && 4c build --types false src && npm run build:pick && npm run build:types",
+    "build:pick": "cherry-pick --cjs-dir cjs --esm-dir esm --cwd lib ../src",
+    "build:types": "cpy types/*.d.ts lib",
+    "format": "4c format --prettier-ignore .eslintignore .",
+    "lint": "4c lint --prettier-ignore .eslintignore .",
+    "prepublish": "npm run build",
+    "release": "4c release",
+    "tdd": "cross-env NODE_ENV=test karma start karma.conf.cjs",
+    "test": "npm run lint && npm run test:ts && npm run testonly",
+    "test:ts": "dtslint types",
+    "testonly": "npm run tdd -- --single-run"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*": "yarn 4c lint --fix --prettier-ignore .eslintignore",
+    "README.md": "doctoc"
+  },
+  "prettier": "@4c/prettier-config",
+  "dependencies": {
+    "query-string": "^5.1.1"
+  },
+  "devDependencies": {
+    "@4c/babel-preset": "^9.1.0",
+    "@4c/cli": "^3.0.1",
+    "@4c/prettier-config": "^1.1.0",
+    "@babel/core": "^7.17.10",
+    "@typescript-eslint/eslint-plugin": "^5.23.0",
+    "@typescript-eslint/parser": "^5.23.0",
+    "babel-loader": "^8.2.5",
+    "babel-plugin-add-module-exports": "^1.0.4",
+    "babel-plugin-istanbul": "^6.1.1",
+    "chai": "^4.3.6",
+    "cherry-pick": "^0.5.0",
+    "codecov": "^3.8.3",
+    "cpy-cli": "^3.1.1",
+    "cross-env": "^7.0.3",
+    "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",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "husky": "^4.3.8",
+    "karma": "^6.3.19",
+    "karma-chrome-launcher": "^3.1.1",
+    "karma-coverage": "^2.2.0",
+    "karma-firefox-launcher": "^2.1.2",
+    "karma-mocha": "^2.0.1",
+    "karma-mocha-reporter": "^2.2.5",
+    "karma-sinon-chai": "^2.0.2",
+    "karma-sourcemap-loader": "^0.3.8",
+    "karma-webpack": "^5.0.0",
+    "lint-staged": "^12.4.1",
+    "mocha": "^9.2.2",
+    "p-defer": "^3.0.0",
+    "prettier": "^2.6.2",
+    "puppeteer": "^13.7.0",
+    "redux": "^4.1.2",
+    "rimraf": "^3.0.2",
+    "sinon": "^11.1.2",
+    "sinon-chai": "^3.7.0",
+    "webpack": "^5.72.1"
+  },
+  "resolutions": {
+    "dtslint/@definitelytyped/header-parser": "^0.0.41",
+    "dtslint/@definitelytyped/typescript-versions": "^0.0.41",
+    "dtslint/@definitelytyped/utils": "^0.0.41"
+  }
+}

package/renovate.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["github>4Catalyzer/renovate-config:library", ":automergeMinor"]
+}

package/src/ActionTypes.js

@@ -0,0 +1,9 @@
+export default {
+  INIT: '@@navigation-stack/INIT',
+  PUSH: '@@navigation-stack/PUSH',
+  REPLACE: '@@navigation-stack/REPLACE',
+  NAVIGATE: '@@navigation-stack/NAVIGATE',
+  SHIFT: '@@navigation-stack/SHIFT',
+  UPDATE: '@@navigation-stack/UPDATE',
+  DISPOSE: '@@navigation-stack/DISPOSE',
+};

package/src/Actions.js

@@ -0,0 +1,26 @@
+import ActionTypes from './ActionTypes';
+
+export default {
+  init: () => ({
+    type: ActionTypes.INIT,
+  }),
+
+  push: (location) => ({
+    type: ActionTypes.PUSH,
+    payload: location,
+  }),
+
+  replace: (location) => ({
+    type: ActionTypes.REPLACE,
+    payload: location,
+  }),
+
+  shift: (delta) => ({
+    type: ActionTypes.SHIFT,
+    payload: delta,
+  }),
+
+  dispose: () => ({
+    type: ActionTypes.DISPOSE,
+  }),
+};

package/src/LocationStateStorage.js

@@ -0,0 +1,59 @@
+import getLocationUrl from './getLocationUrl';
+
+export default class LocationStateStorage {
+  constructor(environment, { namespace } = {}) {
+    this._environment = environment;
+    this._getFallbackLocationKey = getLocationUrl;
+    this._stateKeyPrefix = namespace ? `${namespace}|` : '';
+  }
+
+  get(location, key) {
+    const stateKey = this._getStateKey(location, key);
+
+    try {
+      const value = this._environment.getState(stateKey);
+      // === null is probably sufficient.
+      if (value === null) {
+        return undefined;
+      }
+
+      // We want to catch JSON parse errors in case someone separately threw
+      // junk into sessionStorage under our namespace.
+      return JSON.parse(value);
+    } catch (error) {
+      // Pretend that the entry doesn't exist.
+      return undefined;
+    }
+  }
+
+  set(location, key, value) {
+    const stateKey = this._getStateKey(location, key);
+
+    if (value === undefined) {
+      try {
+        this._environment.removeState(stateKey);
+      } catch (error) {
+        // No need to handle errors here.
+      }
+
+      return;
+    }
+
+    // Unlike with read, we want to fail on invalid values here, since the
+    // value here is provided by the caller of this method.
+    const valueString = JSON.stringify(value);
+
+    try {
+      this._environment.setState(stateKey, valueString);
+    } catch (error) {
+      // No need to handle errors here either. If it didn't work, it didn't
+      // work. We make no guarantees about actually saving the value.
+    }
+  }
+
+  _getStateKey(location, key) {
+    const locationKey = location.key || this._getFallbackLocationKey(location);
+    const keyPrefix = `${this._stateKeyPrefix}${locationKey}`;
+    return `${keyPrefix}|${key}`;
+  }
+}

package/src/addNavigationBlocker.js

@@ -0,0 +1,2 @@
+// eslint-disable-next-line no-restricted-exports
+export { addNavigationBlocker as default } from './navigationBlockers';

package/src/basePath.js

@@ -0,0 +1,65 @@
+function normalizeBasePath(basePath) {
+  if (!basePath || basePath === '/') {
+    return undefined;
+  }
+
+  // Validate `basePath`.
+  if (basePath[0] !== '/') {
+    throw new Error('`basePath` must start with a slash');
+  }
+
+  // Remove trailing slash from `basePath`.
+  if (basePath.slice(-1) === '/') {
+    basePath = basePath.slice(0, -1);
+  }
+
+  return basePath;
+}
+
+function removeBasePathFromRelativeUrl(url, basePath) {
+  if (url.indexOf(basePath) === 0) {
+    // `farce` had a bug here:
+    // `location.pathname` is supposed to always be non-empty.
+    // If `basePath` is set to `/basePath` and the user navigates to `/basePath` URL,
+    // originally here it would simply strips the whole string from the URL
+    // and the result would be incorrect: `pathname: ""`.
+    // The fix below is adding `|| '/'` in the `return` statement.
+    // https://github.com/4Catalyzer/farce/issues/483
+    return url.slice(basePath.length) || '/';
+  }
+  return url;
+}
+
+export function addBasePath(location, basePath) {
+  basePath = normalizeBasePath(basePath);
+
+  if (!basePath) {
+    return location;
+  }
+
+  if (typeof location === 'string') {
+    return `${basePath}${location}`;
+  }
+
+  return {
+    ...location,
+    pathname: `${basePath}${location.pathname}`,
+  };
+}
+
+export function removeBasePath(location, basePath) {
+  basePath = normalizeBasePath(basePath);
+
+  if (!basePath) {
+    return location;
+  }
+
+  if (typeof location === 'string') {
+    return removeBasePathFromRelativeUrl(location, basePath);
+  }
+
+  return {
+    ...location,
+    pathname: removeBasePathFromRelativeUrl(location.pathname, basePath),
+  };
+}