navigation-stack 0.1.0

package/.babelrc.cjs

@@ -0,0 +1,17 @@
+module.exports = (api) => ({
+  presets: [
+    [
+      '@4c',
+      {
+        modules: api.env() === 'esm' ? false : 'commonjs',
+      },
+    ],
+  ],
+  plugins: [api.env() !== 'esm' && 'add-module-exports'].filter(Boolean),
+
+  env: {
+    test: {
+      plugins: ['istanbul'],
+    },
+  },
+});

package/.eslintignore

@@ -0,0 +1,8 @@
+!.babelrc.js
+!.eslintrc.js
+
+**/*.d.ts
+**/coverage/
+**/lib/
+**/node_modules/
+README.md

package/.eslintrc.cjs

@@ -0,0 +1,10 @@
+module.exports = {
+  extends: ['4catalyzer', 'prettier'],
+  plugins: ['prettier'],
+  env: {
+    browser: true,
+  },
+  rules: {
+    'prettier/prettier': 'error',
+  },
+};

package/.github/workflows/main.yml

@@ -0,0 +1,39 @@
+name: Build and test
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+env:
+  DISPLAY: :99.0
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        browser: ['ChromeCi', 'Firefox']
+        node-version: [16.x]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Setup firefox
+        if: ${{ matrix.browser == 'Firefox' }}
+        uses: browser-actions/setup-firefox@latest
+        with:
+          firefox-version: 'latest'
+      - name: Setup xvfb
+        run: |
+          sudo apt-get install xvfb
+          Xvfb $DISPLAY -screen 0 1024x768x24 > /dev/null 2>&1 &
+      - run: yarn install --frozen-lockfile
+      - env:
+          BROWSER: ${{ matrix.browser }}
+        run: yarn test --coverage
+      - run: node_modules/.bin/codecov

package/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and free environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a censorship-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating an open and free environment
+include:
+
+- Not constraining the language to be "welcoming" or "inclusive"
+- Not demanding show of empathy towards other community members
+- Not dictating anyone to be respectful of differing viewpoints and experiences
+- Not forcing anyone to change their views or opinions regardless of those
+- Not intimidating other people into accepting your own views or opinions
+- Not blackmailing other people to disclose their personal views or opinions
+- Not constraining other people from publishing their personal views or opinions in an unintrusive way
+- Focusing on what is best for the ecosystem
+
+Examples of acceptable behavior by participants include:
+
+- The use of sexualized language
+- Occasional trolling or insulting comments that are not completely off-topic
+
+Examples of unacceptable behavior by participants include:
+
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Unwelcome sexual attention or advances
+- Public harassment or personal attacks when carried out in an bold or intrusive way
+- Private harassment
+- Any actions that are in violation of the local laws or otherwise considered illegal
+- Other conduct which could reasonably be considered inappropriate in an open and free setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are free to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and authority to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported by contacting the project team.
+The complaints will likely be reviewed and investigated and may result in a response that
+is deemed necessary and appropriate to the circumstances. The project team should maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 4Catalyzer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [navigation-stack](#navigation-stack)
+  - [Install](#install)
+  - [Use](#use)
+  - [Current Location](#current-location)
+  - [Why Redux?](#why-redux)
+  - [Environment](#environment)
+  - [Base Path](#base-path)
+  - [Location State Storage](#location-state-storage)
+  - [Block Navigation](#block-navigation)
+  - [Utility](#utility)
+  - [Development](#development)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# navigation-stack
+
+[![npm version](https://img.shields.io/npm/v/navigation-stack.svg?style=flat-square)](https://www.npmjs.com/package/navigation-stack)
+[![npm downloads](https://img.shields.io/npm/dm/navigation-stack.svg?style=flat-square)](https://www.npmjs.com/package/navigation-stack)
+
+Handles web browser navigation in a web application.
+
+Originally forked from [`farce`](http://npmjs.com/package/farce) package to fix a [bug](https://github.com/4Catalyzer/farce/issues/483).
+
+## Install
+
+```
+npm install navigation-stack
+```
+
+## Use
+
+`navigation-stack` provides "middlewares", "actions" and a "reducer" that could be used with `redux` or any other `redux`-compatible package such as [`mini-redux`](https://www.npmjs.com/package/mini-redux).
+
+```js
+import { createStore, applyMiddleware } from 'redux'
+
+import {
+  createMiddlewares,
+  locationReducer,
+  Actions,
+  BrowserEnvironment
+} from 'navigation-stack'
+
+const store = createStore(
+  locationReducer, // Reducer function. For example, `locationReducer()`.
+  applyMiddleware(...createMiddlewares(new BrowserEnvironment()))
+)
+
+store.dispatch(Actions.init())
+```
+
+After that, dispatch any of the `Actions` in order to navigate.
+
+```js
+// To navigate to a new page.
+store.dispatch(Actions.push('/new/location'))
+
+// To redirect to a new page.
+store.dispatch(Actions.replace('/new/location'))
+
+// To go back.
+store.dispatch(Actions.shift(-1))
+
+// To go forward.
+store.dispatch(Actions.shift(1))
+```
+
+To view the current location:
+
+```js
+// When `locationReducer()` is used,
+// `store.getState()` is the current location.
+console.log(store.getState())
+```
+
+(optional) (advanced) Stop and clean up:
+
+```js
+store.dispatch(Actions.dispose())
+```
+
+## Current Location
+
+To track the current location, the application could listen to `ActionTypes.UPDATE` action. The `payload` of the action is the current location.
+
+For example, below is the source code for the default `locationReducer`.
+
+```js
+import { ActionTypes } from 'navigation-stack'
+
+// With this reducer, `state` would always tell the current location.
+function reducer(state, action) {
+  if (action.type === ActionTypes.UPDATE) {
+    // `action.payload` is the current location.
+    return action.payload
+  }
+  return state
+}
+```
+
+Calling `store.dispatch(Actions.init())` will trigger the initial `ActionTypes.UPDATE` action which will set the current location. From then on, the current location will always stay in sync with the web browser's URL bar.
+
+The current location will also "magically" be updated when the user clicks "Back" or "Forward" button in the web browser.
+
+## Why Redux?
+
+Why complicate things by providing "middlewares", "actions" and a "reducer" when it could be just a conventional API? That's because always knowing the "current location" means having to deal with "state management" in one way or another, and the simplest and most popular "state management" toolkit to date seems to be Redux.
+
+If it was just about dispatching the `Actions` then of course it wouldn't require any "state management". But it's the "get current location" piece that changes the whole picture. One could say that using Redux for such a simple task is an overkill but actually reinventing a wheel is what I would consider "overkill". It's like crafting your own screwdriver just because the one from Walmart feels too bulky.
+
+## Environment
+
+```js
+import {
+  BrowserEnvironment,
+  ServerEnvironment,
+  MemoryEnvironment
+} from 'navigation-stack'
+
+new BrowserEnvironment()
+new ServerEnvironment('/location-url')
+new MemoryEnvironment('/location-url')
+```
+
+- Use `BrowserEnvironment` in a web browser.
+- Use `ServerEnvironment` in server-side rendering.
+- Use `MemoryEnvironment` in tests.
+  - `MemoryEnvironment` supports an optional second argument — an `options` object with properties:
+    - `save(state)` — Saves the environment state.
+    - `load()` — Loads a previously-saved environment state.
+
+## Base Path
+
+If the web application is hosted under a certain URL prefix, it should be specified in `createMiddlewares()` call as `basePath` parameter.
+
+```js
+createMiddlewares(environment, { basePath?: '/base/path' })
+```
+
+## Location State Storage
+
+One could use an environment-specific `LocationStateStorage` in order to store location-specific state. For example, one could store scroll position of a page and then restore that scroll position when the user decides to navigate "Back" to the page.
+
+```js
+import { BrowserEnvironment, LocationStateStorage } from 'navigation-stack'
+
+const environment = new BrowserEnvironment()
+
+const storage = new LocationStateStorage(environment, { namespace?: 'optional-namespace' })
+
+const location = { pathname: '/abc' }
+
+storage.set(location, 'key', 123)
+storage.get(location, 'key') === 123
+```
+
+`LocationStateStorage` doesn't provide any guarantees about actually storing the data: if it encounters any errors in the process, it simply ignores them. This simplifies the API in a way that the application doesn't have to wrap `.get()`/`.set()` calls in a `try/catch` block. And judging by the nature of location-specific state, that type of data is inherently non-essential and rather "nice-to-have".
+
+## Block Navigation
+
+```js
+import { createStore, applyMiddleware } from 'redux'
+
+import {
+  createMiddlewares,
+  locationReducer,
+  Actions,
+  BrowserEnvironment,
+  addNavigationBlocker
+} from 'navigation-stack'
+
+const environment = new BrowserEnvironment()
+
+const store = createStore(
+  locationReducer, // Reducer function. For example, `locationReducer()`.
+  applyMiddleware(...createMiddlewares(environment))
+)
+
+store.dispatch(Actions.init())
+
+const removeNavigationBlocker = addNavigationBlocker(
+  environment,
+  (newLocation) => {
+    // Returning `true` means "block this navigation".
+    return true
+  }
+);
+
+// This navigation won't be performed.
+store.dispatch(Actions.push('/new/location'))
+
+// Disable the navigation blocker.
+removeNavigationBlocker()
+
+// This navigation now will be performed.
+store.dispatch(Actions.push('/new/location'))
+```
+
+Navigation blocker should be a function that receives a `newLocation` argument and could be "synchronous" or "asynchronous" (i.e. return a `Promise`, aka `async`/`await`).
+
+Navigation blockers fire both when navigating from one page to another and when closing the current browser tab. In the latter case, `newLocation` argument will be `null`, the function can't return a `Promise`, and returning `true` will cause the web browser to show a confirmation modal with a non-customizable browser-specific text.
+
+## Utility
+
+This package exports a couple of utility functions.
+
+```js
+import {
+  addBasePath,
+  removeBasePath,
+  getLocationUrl,
+  parseLocationUrl
+} from 'navigation-stack'
+
+// Parses a location URL to a location object.
+// If there're no query parameters, `query` property will not be added.
+parseLocationUrl('/abc?d=e') === {
+  pathname: '/abc',
+  search: '?d=e',
+  query: { d: 'e' },
+  hash: ''
+}
+
+// Converts a location object to a location URL.
+getLocationUrl({ pathname: '/abc', search: '?d=e', hash: '' }) === '/abc?d=e'
+
+// Adds `basePath` to a location object or a location URL.
+addBasePath('/abc', '/base-path') === '/base-path/abc'
+addBasePath({ pathname: '/abc' }, '/base-path') === { pathname: '/base-path/abc' }
+
+// Removes `basePath` from a location object or a location URL.
+// If `basePath` is not present in location, it won't do anything.
+removeBasePath('/base-path/abc', '/base-path') === '/abc';
+removeBasePath({ pathname: '/base-path/abc' }, '/base-path') === { pathname: '/abc' }
+```
+
+## Development
+
+Clone the repository. Then:
+
+```
+yarn
+yarn format
+yarn test
+```

package/codecov.yml

@@ -0,0 +1 @@
+comment: off

package/karma.conf.cjs

@@ -0,0 +1,63 @@
+// An attempted rewrite in ESM threw an error: "ReferenceError: require is not defined"
+// when processing `import` in the `.js` files.
+//
+// import puppeteer from 'puppeteer';
+// import webpack from 'webpack'; // eslint-disable-line import/no-extraneous-dependencies
+//
+// process.env.CHROME_BIN = puppeteer.executablePath();
+
+const webpack = require('webpack'); // eslint-disable-line import/no-extraneous-dependencies
+
+process.env.CHROME_BIN = require('puppeteer').executablePath();
+
+module.exports = (config) => {
+  const { env } = process;
+
+  config.set({
+    frameworks: ['mocha', 'webpack', 'sinon-chai'],
+
+    files: ['test/index.js', { pattern: 'test/**/*.test.js', watched: false }],
+
+    preprocessors: {
+      'test/**/*.js': ['webpack', 'sourcemap'],
+    },
+
+    webpack: {
+      mode: 'development',
+      module: {
+        rules: [
+          { test: /\.js$/, exclude: /node_modules/, use: 'babel-loader' },
+        ],
+      },
+      plugins: [
+        new webpack.DefinePlugin({
+          __DEV__: true,
+        }),
+      ],
+    },
+
+    webpackMiddleware: {
+      noInfo: true,
+    },
+
+    reporters: ['mocha', 'coverage'],
+
+    mochaReporter: {
+      output: 'autowatch',
+    },
+
+    coverageReporter: {
+      type: 'lcov',
+      dir: 'coverage',
+    },
+
+    customLaunchers: {
+      ChromeCi: {
+        base: 'ChromeHeadless',
+        flags: ['--no-sandbox'],
+      },
+    },
+
+    browsers: env.BROWSER ? env.BROWSER.split(',') : ['Chrome'],
+  });
+};

package/lib/cjs/ActionTypes.js

@@ -0,0 +1,14 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _default = exports.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'
+};
+module.exports = exports.default;

package/lib/cjs/Actions.js

@@ -0,0 +1,27 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _ActionTypes = _interopRequireDefault(require("./ActionTypes"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _default = exports.default = {
+  init: () => ({
+    type: _ActionTypes.default.INIT
+  }),
+  push: location => ({
+    type: _ActionTypes.default.PUSH,
+    payload: location
+  }),
+  replace: location => ({
+    type: _ActionTypes.default.REPLACE,
+    payload: location
+  }),
+  shift: delta => ({
+    type: _ActionTypes.default.SHIFT,
+    payload: delta
+  }),
+  dispose: () => ({
+    type: _ActionTypes.default.DISPOSE
+  })
+};
+module.exports = exports.default;

package/lib/cjs/LocationStateStorage.js

@@ -0,0 +1,60 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _getLocationUrl = _interopRequireDefault(require("./getLocationUrl"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class LocationStateStorage {
+  constructor(environment, {
+    namespace
+  } = {}) {
+    this._environment = environment;
+    this._getFallbackLocationKey = _getLocationUrl.default;
+    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}`;
+  }
+}
+exports.default = LocationStateStorage;
+module.exports = exports.default;

package/lib/cjs/addNavigationBlocker.js

@@ -0,0 +1,7 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _navigationBlockers = require("./navigationBlockers");
+exports.default = _navigationBlockers.addNavigationBlocker;
+module.exports = exports.default;

package/lib/cjs/basePath.js

@@ -0,0 +1,58 @@
+"use strict";
+
+exports.__esModule = true;
+exports.addBasePath = addBasePath;
+exports.removeBasePath = removeBasePath;
+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;
+}
+function addBasePath(location, basePath) {
+  basePath = normalizeBasePath(basePath);
+  if (!basePath) {
+    return location;
+  }
+  if (typeof location === 'string') {
+    return `${basePath}${location}`;
+  }
+  return Object.assign({}, location, {
+    pathname: `${basePath}${location.pathname}`
+  });
+}
+function removeBasePath(location, basePath) {
+  basePath = normalizeBasePath(basePath);
+  if (!basePath) {
+    return location;
+  }
+  if (typeof location === 'string') {
+    return removeBasePathFromRelativeUrl(location, basePath);
+  }
+  return Object.assign({}, location, {
+    pathname: removeBasePathFromRelativeUrl(location.pathname, basePath)
+  });
+}