[
{
"path": ".browserslistrc",
"content": "# Browsers we support\n> 0.5%\nChrome >= 73\nChromeAndroid >= 75\nFirefox >= 67\nEdge >= 17\nIE 11\nSafari >= 12.1\niOS >= 11.3\n"
},
{
"path": ".eslintignore",
"content": "/build\n/fixtures\n\nnode_modules/\n"
},
{
"path": ".eslintrc",
"content": "{\n \"extends\": \"react-app\",\n \"rules\": {\n \"import/no-anonymous-default-export\": 0\n }\n}\n"
},
{
"path": ".github/lock.yml",
"content": "# Configuration for lock-threads - https://github.com/dessant/lock-threads\n\n# Number of days of inactivity before a closed issue or pull request is locked\ndaysUntilLock: 60\n\n# Issues and pull requests with these labels will not be locked. Set to `[]` to disable\nexemptLabels: []\n\n# Label to add before locking, such as `outdated`. Set to `false` to disable\nlockLabel: false\n\n# Comment to post before locking. Set to `false` to disable\nlockComment: false\n# Limit to only `issues` or `pulls`\n# only: issues\n\n# Optionally, specify configuration settings just for `issues` or `pulls`\n# issues:\n# exemptLabels:\n# - help-wanted\n# lockLabel: outdated\n\n# pulls:\n# daysUntilLock: 30\n"
},
{
"path": ".github/workflows/format.yml",
"content": "name: Format\n\non:\n push:\n branches:\n - main\n\njobs:\n format:\n runs-on: ubuntu-latest\n\n steps:\n - name: Cancel Previous Runs\n uses: styfle/cancel-workflow-action@0.9.1\n\n - name: Checkout Repository\n uses: actions/checkout@v2\n\n - name: Use Node.js\n uses: actions/setup-node@v2\n with:\n node-version: 14\n\n - name: Install dependencies\n run: yarn install --frozen-lockfile\n\n - name: Format\n run: npm run format --if-present\n\n - name: Commit\n run: |\n git config --local user.email \"github-actions@remix.run\"\n git config --local user.name \"Remix Run Bot\"\n\n git add .\n if [ -z \"$(git status --porcelain)\" ]; then\n echo \"💿 no formatting changed\"\n exit 0\n fi\n git commit -m \"chore: format\" -m \"formatted $GITHUB_SHA\"\n git push\n echo \"💿 pushed formatting changes https://github.com/$GITHUB_REPOSITORY/commit/$(git rev-parse HEAD)\"\n"
},
{
"path": ".github/workflows/release.yml",
"content": "name: release\non:\n release:\n types: [published]\n\njobs:\n release:\n if: github.repository == 'remix-run/history'\n runs-on: ubuntu-latest\n\n strategy:\n matrix:\n node-version: [14.x]\n\n steps:\n - uses: actions/checkout@v2\n\n - name: Use Node.js ${{ matrix.node-version }}\n uses: actions/setup-node@v1\n with:\n node-version: ${{ matrix.node-version }}\n\n # https://github.com/actions/setup-node/issues/213#issuecomment-833724757\n - name: Install npm v7\n run: npm i -g npm@7 --registry=https://registry.npmjs.org\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build\n run: npm run build\n\n - name: Test\n run: npm run test & npm run size\n\n - name: Publish\n env:\n NPM_TOKEN: ${{ secrets.NPM_TOKEN }}\n run: |\n echo \"//registry.npmjs.org/:_authToken=$NPM_TOKEN\" > ~/.npmrc\n node scripts/publish.js\n"
},
{
"path": ".github/workflows/test.yml",
"content": "name: test\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n\n strategy:\n matrix:\n node-version: [14.x]\n\n steps:\n - uses: actions/checkout@v2\n\n - name: Use Node.js ${{ matrix.node-version }}\n uses: actions/setup-node@v1\n with:\n node-version: ${{ matrix.node-version }}\n\n # https://github.com/actions/setup-node/issues/213#issuecomment-833724757\n - name: Install npm v7\n run: npm i -g npm@7 --registry=https://registry.npmjs.org\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build\n run: npm run build\n\n - name: Test\n run: npm run test & npm run size\n"
},
{
"path": ".gitignore",
"content": "/build/\n/fixtures/*/history.js\n\nnode_modules/\n"
},
{
"path": ".prettierignore",
"content": "package.json\npackage-lock.json\n"
},
{
"path": ".prettierrc",
"content": "{}\n"
},
{
"path": "CONTRIBUTING.md",
"content": "All development happens [on GitHub](https://github.com/remix-run/history). When [creating a pull request](https://help.github.com/articles/creating-a-pull-request/), please make sure that all of the following apply:\n\n- If you're adding a new feature or \"fixing\" a bug, please go into detail about your use case and why you think you need that feature or that bug fixed. This library has lots and lots of dependents, and we can't afford to make changes lightly without understanding why.\n- The tests pass. The test suite will automatically run when you create the PR. All you need to do is wait a few minutes to see the result in the PR.\n- Each commit in your PR should describe a significant piece of work. Work that was done in one commit and then undone later should be squashed into a single commit.\n\nIf your PR fails to meet these guidelines, it may be closed without much of an explanation besides a link to this document.\n\nThank you for your contribution!\n"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) React Training 2016-2020\nCopyright (c) Remix Software 2020-2021\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "# history · [![npm package][npm-badge]][npm]\n\n[npm-badge]: https://img.shields.io/npm/v/history.svg?style=flat-square\n[npm]: https://www.npmjs.org/package/history\n\nThe history library lets you easily manage session history anywhere JavaScript runs. A `history` object abstracts away the differences in various environments and provides a minimal API that lets you manage the history stack, navigate, and persist state between sessions.\n\n## Documentation\n\nDocumentation for version 5 can be found in the [docs](docs) directory. This is the current stable release. Version 5 is used in React Router version 6.\n\nDocumentation for version 4 can be found [on the v4 branch](https://github.com/remix-run/history/tree/v4/docs). Version 4 is used in React Router versions 4 and 5.\n\n## Changes\n\nTo see the changes that were made in a given release, please lookup the tag on [the releases page](https://github.com/remix-run/history/releases).\n\nFor changes released in version 4.6.3 and earlier, please see [the `CHANGES.md` file](https://github.com/remix-run/history/blob/845d690c5576c7f55ecbe14babe0092e8e5bc2bb/CHANGES.md).\n\n## Development\n\nDevelopment of the current stable release, version 5, happens on [the `main` branch](https://github.com/remix-run/history/tree/main). Please keep in mind that this branch may include some work that has not yet been published as part of an official release. However, since `main` is always stable, you should feel free to build your own working release straight from `main` at any time.\n\nIf you're interested in helping out, please read [our contributing guidelines](CONTRIBUTING.md).\n\n## About\n\n`history` is developed and maintained by [Remix](https://remix.run). If you're interested in learning more about what React can do for your company, please [get in touch](mailto:hello@remix.run)!\n\n## Thanks\n\nA big thank-you to [BrowserStack](https://www.browserstack.com/) for providing the infrastructure that allows us to run our build in real browsers.\n\nAlso, thanks to [Dan Shaw](https://www.npmjs.com/~dshaw) for letting us use the `history` npm package name. Thanks, Dan!\n"
},
{
"path": "docs/README.md",
"content": "Welcome to the history docs!\n\nThe history library lets you easily manage session history anywhere JavaScript\nruns. A `history` object abstracts away the differences in various environments\nand provides a minimal API that lets you manage the history stack, navigate, and\npersist state between sessions.\n\nThe library is very small, so there are really just a few files here for you to\nbrowse.\n\nIf this is your first time here, we'd recommend you start with the [Getting\nStarted](getting-started.md) guide.\n\nYou may also be interested in reading one of the following guides:\n\n- [Installation](installation.md)\n- [Navigation](navigation.md)\n- [Blocking Transitions](blocking-transitions.md)\n\nAn [API Reference](api-reference.md) is also available.\n"
},
{
"path": "docs/api-reference.md",
"content": "\n\n# history API Reference\n\nThis is the API reference for [the history JavaScript library](https://github.com/remix-run/history).\n\nThe history library provides an API for tracking application history using [location](#location) objects that contain URLs and state. This reference includes type signatures and return values for the interfaces in the library. Please read the [getting started guide](getting-started.md) if you're looking for explanations about how to use the library to accomplish a specific task.\n\n\n\n## Overview\n\n\n\n### Environments\n\nThe history library includes support for three different \"environments\", or modes of operation.\n\n- [Browser history](#createbrowserhistory) is used in web apps\n- [Hash history](#createhashhistory) is used in web apps where you don't want to/can't send the URL to the server for some reason\n- [Memory history](#creatememoryhistory) - is used in native apps and testing\n\nJust pick the right mode for your target environment and you're good to go.\n\n\n\n### Listening\n\nTo read the current location and action, use [`history.location`](#history.location) and [`history.action`](#history.action). Both of these properties are mutable and automatically update as the location changes.\n\nTo be notified when the location changes, setup a listener using [`history.listen`](#history.listen).\n\n\n\n### Navigation\n\nTo change the current location, you'll want to use one of the following:\n\n- [`history.push`](#history.push) - Pushes a new location onto the history stack\n- [`history.replace`](#history.replace) - Replaces the current location with another\n- [`history.go`](#history.go) - Changes the current index in the history stack by a given delta\n- [`history.back`](#history.back) - Navigates one entry back in the history stack\n- [`history.forward`](#history.forward) - Navigates one entry forward in the history stack\n\n\n\n### Confirming Navigation\n\nTo prevent the location from changing, use [`history.block`](#history.block). This API allows you to prevent the location from changing so you can prompt the user before retrying the transition.\n\n\n\n### Creating `href` values\n\nIf you're building a link, you'll want to use [`history.createHref`](#history.createhref) to get a URL you can use as the value of ``.\n\n---\n\n\n\n## Reference\n\nThe [source code](https://github.com/remix-run/history/tree/main/packages/history) for the history library is written in TypeScript, but it is compiled to JavaScript before publishing. Some of the function signatures in this reference include their TypeScript type annotations, but you can always refer to the original source as well.\n\n\n\n### Action\n\nAn `Action` represents a type of change that occurred in the history stack. `Action` is an `enum` with three members:\n\n- `Action.Pop` - A change to an arbitrary index in the stack, such as a back or forward navigation. This does not describe the direction of the navigation, only that the index changed. This is the default action for newly created history objects.\n- `Action.Push` - Indicates a new entry being added to the history stack, such as when a link is clicked and a new page loads. When this happens, all subsequent entries in the stack are lost.\n- `Action.Replace` - Indicates the entry at the current index in the history stack being replaced by a new one.\n\nSee [the Getting Started guide](getting-started.md) for more information.\n\n\n\n\n### `History`\n\nA `History` object represents the shared interface for `BrowserHistory`, `HashHistory`, and `MemoryHistory`.\n\n\n Type declaration\n\n```ts\ninterface History {\n readonly action: Action;\n readonly location: Location;\n createHref(to: To): string;\n push(to: To, state?: any): void;\n replace(to: To, state?: any): void;\n go(delta: number): void;\n back(): void;\n forward(): void;\n listen(listener: Listener): () => void;\n block(blocker: Blocker): () => void;\n}\n```\n\n\n\n### `createBrowserHistory`\n\n\n Type declaration\n\n```tsx\nfunction createBrowserHistory(options?: { window?: Window }): BrowserHistory;\n\ninterface BrowserHistory extends History {}\n```\n\n\n\nA browser history object keeps track of the browsing history of an application using the browser's built-in history stack. It is designed to run in modern web browsers that support the HTML5 history interface including `pushState`, `replaceState`, and the `popstate` event.\n\n`createBrowserHistory` returns a `BrowserHistory` instance. `window` defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).\n\n```ts\nimport { createBrowserHistory } from \"history\";\nlet history = createBrowserHistory();\n```\n\nSee [the Getting Started guide](getting-started.md) for more information.\n\n\n\n\n\n### `createPath` and `parsePath`\n\n\n Type declaration\n\n```ts\nfunction createPath(partialPath: Partial): string;\nfunction parsePath(path: string): Partial;\n\ninterface Path {\n pathname: string;\n search: string;\n hash: string;\n}\n```\n\n\n\nThe `createPath` and `parsePath` functions are useful for creating and parsing URL paths.\n\n```ts\ncreatePath({ pathname: \"/login\", search: \"?next=home\" }); // \"/login?next=home\"\nparsePath(\"/login?next=home\"); // { pathname: '/login', search: '?next=home' }\n```\n\n\n\n\n### `createHashHistory`\n\n\n Type declaration\n\n```ts\ncreateHashHistory({ window?: Window }): HashHistory;\n\ninterface HashHistory extends History {}\n```\n\n\n\nA hash history object keeps track of the browsing history of an application using the browser's built-in history stack. It is designed to be run in modern web browsers that support the HTML5 history interface including `pushState`, `replaceState`, and the `popstate` event.\n\n`createHashHistory` returns a `HashHistory` instance. `window` defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).\n\nThe main difference between this and [browser history](#createbrowserhistory) is that a hash history stores the current location in the [`hash` portion of the URL](https://developer.mozilla.org/en-US/docs/Web/API/Location/hash#:~:text=The%20hash%20property%20of%20the,an%20empty%20string%2C%20%22%22%20.), which means that it is not ever sent to the server. This can be useful if you are hosting your site on a domain where you do not have full control over the server routes, or e.g. in an Electron app where you don't want to configure the \"server\" to serve the same page at different URLs.\n\n```ts\nimport { createHashHistory } from \"history\";\nlet history = createHashHistory();\n```\n\nSee [the Getting Started guide](getting-started.md) for more information.\n\n\n\n\n### `createMemoryHistory`\n\n\n Type declaration\n\n```ts\nfunction createMemoryHistory({\n initialEntries?: InitialEntry[],\n initialIndex?: number\n}): MemoryHistory;\n\ntype InitialEntry = string | Partial;\n\ninterface MemoryHistory extends History {\n readonly index: number;\n}\n```\n\n\n\nA memory history object keeps track of the browsing history of an application using an internal array. This makes it ideal in situations where you need complete control over the history stack, like React Native and tests.\n\n`createMemoryHistory` returns a `MemoryHistory` instance. You can provide initial entries to this history instance through the `initialEntries` property, which defaults to `['/']` (a single location at the root `/` URL). The `initialIndex` defaults to the index of the last item in `initialEntries`.\n\n```ts\nimport { createMemoryHistory } from \"history\";\nlet history = createMemoryHistory();\n// Or, to pre-seed the history instance with some URLs:\nlet history = createMemoryHistory({\n initialEntries: [\"/home\", \"/profile\", \"/about\"],\n});\n```\n\nSee [the Getting Started guide](getting-started.md) for more information.\n\n\n\n### `history.action`\n\nThe current (most recent) [`Action`](#action) that modified the history stack. This property is mutable and automatically updates as the current location changes.\n\nSee also [`history.listen`](#history.listen).\n\n\n\n### `history.back()`\n\nGoes back one entry in the history stack. Alias for `history.go(-1)`.\n\nSee [the Navigation guide](navigation.md) for more information.\n\n\n\n### `history.block(blocker: Blocker)`\n\n\n Type declaration\n\n```ts\ninterface Blocker {\n (tx: Transition): void;\n}\n\ninterface Transition {\n action: Action;\n location: Location;\n retry(): void;\n}\n```\n\n\n\nPrevents changes to the history stack from happening. This is useful when you want to prevent the user navigating away from the current page, for example when they have some unsaved data on the current page.\n\n```ts\n// To start blocking location changes...\nlet unblock = history.block(({ action, location, retry }) => {\n // A transition was blocked!\n});\n\n// Later, when you want to start allowing transitions again...\nunblock();\n```\n\nSee [the guide on Blocking Transitions](blocking-transitions.md) for more information.\n\n\n\n### `history.createHref(to: To)`\n\nReturns a string suitable for use as an `` value that will navigate to\nthe given destination.\n\n\n\n### `history.forward()`\n\nGoes forward one entry in the history stack. Alias for `history.go(1)`.\n\nSee [the Navigation guide](navigation.md) for more information.\n\n\n\n### `history.go(delta: number)`\n\nNavigates back/forward by `delta` entries in the stack.\n\nSee [the Navigation guide](navigation.md) for more information.\n\n\n\n### `history.index`\n\nThe current index in the history stack.\n\n> [!Note:]\n>\n> This property is available only on [memory history](#memoryhistory) instances.\n\n\n\n### `history.listen(listener: Listener)`\n\n\n Type declaration\n\n```ts\ninterface Listener {\n (update: Update): void;\n}\n\ninterface Update {\n action: Action;\n location: Location;\n}\n```\n\n\n\nStarts listening for location changes and calls the given callback with an `Update` when it does.\n\n```ts\n// To start listening for location changes...\nlet unlisten = history.listen(({ action, location }) => {\n // The current location changed.\n});\n\n// Later, when you are done listening for changes...\nunlisten();\n```\n\nSee [the Getting Started guide](getting-started.md#listening) for more information.\n\n\n\n### `history.location`\n\nThe current [`Location`](#location). This property is mutable and automatically updates as the current location changes.\n\nAlso see [`history.listen`](#history.listen).\n\n\n\n### `history.push(to: To, state?: any)`\n\nPushes a new entry onto the stack.\n\nSee [the Navigation guide](navigation.md) for more information.\n\n\n\n### `history.replace(to: To, state?: any)`\n\nReplaces the current entry in the stack with a new one.\n\nSee [the Navigation guide](navigation.md) for more information.\n\n\n\n### Location\n\n\n Type declaration\n\n```ts\ninterface Location {\n pathname: string;\n search: string;\n hash: string;\n state: unknown;\n key: string;\n}\n```\n\n\n\nA `location` is a particular entry in the history stack, usually analogous to a \"page\" or \"screen\" in your app. As the user clicks on links and moves around the app, the current location changes.\n\n\n\n### `location.pathname`\n\nThe `location.pathname` property is a string that contains an initial `/` followed by the remainder of the URL up to the `?`.\n\nSee also [`URL.pathname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname).\n\n\n\n### `location.search`\n\nThe `location.search` property is a string that contains an initial `?` followed by the `key=value` pairs in the query string. If there are no parameters, this value may be the empty string (i.e. `''`).\n\nSee also [`URL.search`](https://developer.mozilla.org/en-US/docs/Web/API/URL/search).\n\n\n\n### `location.hash`\n\nThe `location.hash` property is a string that contains an initial `#` followed by fragment identifier of the URL. If there is no fragment identifier, this value may be the empty string (i.e. `''`).\n\nSee also [`URL.hash`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash).\n\n\n\n### `location.state`\n\nThe `location.state` property is a user-supplied [`State`](#state) object that is associated with this location. This can be a useful place to store any information you do not want to put in the URL, e.g. session-specific data.\n\n> [!Note:]\n>\n> In web browsers, this state is managed using the browser's built-in\n> `pushState`, `replaceState`, and `popstate` APIs. See also\n> [`History.state`](https://developer.mozilla.org/en-US/docs/Web/API/History/state).\n\n\n\n### `location.key`\n\nThe `location.key` property is a unique string associated with this location. On the initial location, this will be the string `default`. On all subsequent locations, this string will be a unique identifier.\n\nThis can be useful in situations where you need to keep track of 2 different states for the same URL. For example, you could use this as the key to some network or device storage API.\n\n\n\n### State\n\nA `State` value is an arbitrary value that holds extra information associated with a [`Location`](#location) but does not appear in the URL. This value is always associated with that location.\n\nSee [the Navigation guide](navigation.md) for more information.\n\n\n\n### To\n\n\n Type declaration\n\n```ts\ntype To = string | Partial;\n\ninterface Path {\n pathname: string;\n search: string;\n hash: string;\n}\n```\n\n\n\nA [`To`](https://github.com/remix-run/history/blob/main/packages/history/index.ts#L178) value represents a destination location, but doesn't contain all the information that a normal [`location`](#location) object does. It is primarily used as the first argument to [`history.push`](#history.push) and [`history.replace`](#history.replace).\n\nSee [the Navigation guide](navigation.md) for more information.\n"
},
{
"path": "docs/blocking-transitions.md",
"content": "# Blocking Transitions\n\n`history` lets you block navigation away from the current page using the\n[`history.block(blocker: Blocker)`](api-reference.md#history.block) API. For\nexample, you can make sure the user knows that if they leave the current page\nthey will lose some unsaved changes they've made.\n\n```js\n// Block navigation and register a callback that\n// fires when a navigation attempt is blocked.\nlet unblock = history.block((tx) => {\n // Navigation was blocked! Let's show a confirmation dialog\n // so the user can decide if they actually want to navigate\n // away and discard changes they've made in the current page.\n let url = tx.location.pathname;\n if (window.confirm(`Are you sure you want to go to ${url}?`)) {\n // Unblock the navigation.\n unblock();\n\n // Retry the transition.\n tx.retry();\n }\n});\n```\n\nThis example uses\n[`window.confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm),\nbut you could also use your own custom confirm dialog if you'd prefer.\n\n## Caveats\n\n`history.block` will call your callback for all in-page navigation attempts, but\nfor navigation that reloads the page (e.g. the refresh button or a link that\ndoesn't use `history.push`) it registers [a `beforeunload`\nhandler](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event)\nto prevent the navigation. In modern browsers you are not able to customize this\ndialog. Instead, you'll see something like this (Chrome):\n\n\n\nOne subtle side effect of registering a `beforeunload` handler is that the page\nwill not be [salvageable](https://html.spec.whatwg.org/#unloading-documents) in\n[the `pagehide`\nevent](https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event).\nThis means the page may not be reused by the browser, so things like timers,\nscroll position, and event sources will not be reused when the user navigates\nback to that page.\n"
},
{
"path": "docs/getting-started.md",
"content": "\n\n\n# Intro\n\nThe history library provides history tracking and navigation primitives for JavaScript applications that run in browsers and other stateful environments.\n\nIf you haven't yet, please take a second to read through [the Installation guide](installation.md) to get the library installed and running on your system.\n\nWe provide 3 different methods for working with history, depending on your environment:\n\n- A \"browser history\" is for use in modern web browsers that support the [HTML5 history API](http://diveintohtml5.info/history.html) (see [cross-browser compatibility](http://caniuse.com/#feat=history))\n- A \"hash history\" is for use in web browsers where you want to store the location in the [hash](https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/hash) portion of the current URL to avoid sending it to the server when the page reloads\n- A \"memory history\" is used as a reference implementation that may be used in non-browser environments, like [React Native](https://facebook.github.io/react-native/) or tests\n\nThe main bundle exports one method for each environment: [`createBrowserHistory`](api-reference.md#createbrowserhistory) for browsers, [`createHashHistory`](api-reference.md#createhashhistory) for using hash history in browsers, and [`createMemoryHistory`](api-reference.md#creatememoryhistory) for creating an in-memory history.\n\nIn addition to the main bundle, the library also includes `history/browser` and `history/hash` bundles that export singletons you can use to quickly get a history instance for [the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Window/document) (web page).\n\n## Basic Usage\n\nBasic usage looks like this:\n\n```js\n// Create your own history instance.\nimport { createBrowserHistory } from \"history\";\nlet history = createBrowserHistory();\n\n// ... or just import the browser history singleton instance.\nimport history from \"history/browser\";\n\n// Alternatively, if you're using hash history import\n// the hash history singleton instance.\n// import history from 'history/hash';\n\n// Get the current location.\nlet location = history.location;\n\n// Listen for changes to the current location.\nlet unlisten = history.listen(({ location, action }) => {\n console.log(action, location.pathname, location.state);\n});\n\n// Use push to push a new entry onto the history stack.\nhistory.push(\"/home\", { some: \"state\" });\n\n// Use replace to replace the current entry in the stack.\nhistory.replace(\"/logged-in\");\n\n// Use back/forward to navigate one entry back or forward.\nhistory.back();\n\n// To stop listening, call the function returned from listen().\nunlisten();\n```\n\nIf you're using memory history you'll need to create your own `history` object\nbefore you can use it.\n\n```js\nimport { createMemoryHistory } from \"history\";\nlet history = createMemoryHistory();\n```\n\nIf you're using browser or hash history with a `window` other than that of the\ncurrent `document` (like an iframe), you'll need to create your own browser/hash\nhistory:\n\n```js\nimport { createBrowserHistory } from \"history\";\nlet history = createBrowserHistory({\n window: iframe.contentWindow,\n});\n```\n\n\n\n## Properties\n\nEach `history` object has the following properties:\n\n- [`history.location`](api-reference.md#history.location) - The current location (see below)\n- [`history.action`](api-reference.md#history.action) - The current navigation action (see below)\n\nAdditionally, memory history provides `history.index` that tells you the current index in the history stack.\n\n\n\n## Listening\n\nYou can listen for changes to the current location using `history.listen`:\n\n```js\nhistory.listen(({ action, location }) => {\n console.log(\n `The current URL is ${location.pathname}${location.search}${location.hash}`\n );\n console.log(`The last navigation action was ${action}`);\n});\n```\n\nThe [`location`](api-reference.md#location) object implements a subset of [the `window.location` interface](https://developer.mozilla.org/en-US/docs/Web/API/Location), including:\n\n- [`location.pathname`](api-reference.md#location.pathname) - The path of the URL\n- [`location.search`](api-reference.md#location.search) - The URL query string\n- [`location.hash`](api-reference.md#location.hash) - The URL hash fragment\n- [`location.state`](api-reference.md#location.state) - Some extra state for this\n location that does not reside in the URL (may be `null`)\n- [`location.key`](api-reference.md#location.key) - A unique string representing this location\n\nThe [`action`](api-reference.md#action) is one of `Action.Push`, `Action.Replace`, or `Action.Pop` depending on how the user got to the current location.\n\n- `Action.Push` means one more entry was added to the history stack\n- `Action.Replace` means the current entry in the stack was replaced\n- `Action.Pop` means we went to some other location already in the stack\n\n\n\n## Cleaning up\n\nWhen you attach a listener using `history.listen`, it returns a function that can be used to remove the listener, which can then be invoked in cleanup logic:\n\n```js\nlet unlisten = history.listen(myListener);\n\n// Later, when you're done...\nunlisten();\n```\n\n\n\n## Utilities\n\nThe main history bundle also contains both `createPath` and `parsePath` methods that may be useful when working with URL paths.\n\n```js\nlet pathPieces = parsePath(\"/the/path?the=query#the-hash\");\n// pathPieces = {\n// pathname: '/the/path',\n// search: '?the=query',\n// hash: '#the-hash'\n// }\n\nlet path = createPath(pathPieces);\n// path = '/the/path?the=query#the-hash'\n```\n"
},
{
"path": "docs/installation.md",
"content": "# Installation\n\nThe history library is published to the public [npm](https://www.npmjs.com/)\nregistry. You can install it using:\n\n $ npm install --save history\n\n## Using a Bundler\n\nThe best way to use the `history` library is with a bundler that supports\nJavaScript modules (we recommend [Rollup](https://rollupjs.org)). Recent\nversions of Webpack and Parcel are also good choices.\n\nThen you can write your code using JavaScript `import` statements, like this:\n\n```js\nimport { createBrowserHistory } from \"history\";\n// ...\n```\n\nIf you're using a bundler that doesn't understand JavaScript modules and only\nunderstands CommonJS, you can use `require` as you would with anything else:\n\n```js\nvar createBrowserHistory = require(\"history\").createBrowserHistory;\n```\n\n## Using `\n```\n\nThe `history.development.js` build is also available for non-production apps.\n\nIn legacy browsers that do not yet support JavaScript modules, you can use one\nof our UMD (global) builds:\n\n```html\n\n\n```\n\nYou can find the library on `window.HistoryLibrary`.\n"
},
{
"path": "docs/navigation.md",
"content": "# Navigation\n\n`history` objects may be used to programmatically change the current location\nusing the following methods:\n\n- [`history.push(to: To, state?: State)`](api-reference.md#history.push)\n- [`history.replace(to: To, state?: State)`](api-reference.md#history.replace)\n- [`history.go(delta: number)`](api-reference.md#history.go)\n- [`history.back()`](api-reference.md#history.back)\n- [`history.forward()`](api-reference.md#history.forward)\n\nAn example:\n\n```js\n// Push a new entry onto the history stack.\nhistory.push(\"/home\");\n\n// Push a new entry onto the history stack with a query string\n// and some state. Location state does not appear in the URL.\nhistory.push(\"/home?the=query\", { some: \"state\" });\n\n// If you prefer, use a location-like object to specify the URL.\n// This is equivalent to the example above.\nhistory.push(\n {\n pathname: \"/home\",\n search: \"?the=query\",\n },\n {\n some: state,\n }\n);\n\n// Go back to the previous history entry. The following\n// two lines are synonymous.\nhistory.go(-1);\nhistory.back();\n```\n"
},
{
"path": "fixtures/block-library/index.html",
"content": "\n\n \n