diff --git a/docs/api-reference.md b/docs/api-reference.md
index ec7c89c6e..7ec86f753 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -4,31 +4,101 @@
This is the API reference for [the history JavaScript library](https://github.com/ReactTraining/history).
-The [source code](https://github.com/ReactTraining/history/tree/dev/packages/history) for this 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.
+The 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.
-
+
-## Setup
+## Overview
-This library includes three `history` object initializers for the different modes we support. They are:
+
-- [Browser history](#browserhistory) - for building web apps
-- [Hash history](#hashhistory) - for building web apps where you don't want to/can't send the URL to the server for some reason
-- [Memory history](#memoryhistory) - for building native apps and testing
+### Environments
-An app should only ever need to use one of these modes.
+The history library includes support for three different "environments", or modes of operation.
-
+- [Browser history](#createbrowserhistory) is used in web apps
+- [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
+- [Memory history](#creatememoryhistory) - is used in native apps and testing
-### Browser History
+Just pick the right mode for your target environment and you're good to go.
-A "browser history" object is designed to be run in modern web browsers that support the HTML5 history interface including `pushState`, `replaceState`, and the `popstate` event.
+
-```ts
+### Listening
+
+To 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.
+
+To be notified when the location changes, setup a listener using [`history.listen`](#history.listen).
+
+
+
+### Navigation
+
+To change the current location, you'll want to use one of the following:
+
+- [`history.push`](#history.push) - Pushes a new location onto the history stack
+- [`history.replace`](#history.replace) - Replaces the current location with another
+- [`history.go`](#history.go) - Changes the current index in the history stack by a given delta
+- [`history.back`](#history.back) - Navigates one entry back in the history stack
+- [`history.forward`](#history.forward) - Navigates one entry forward in the history stack
+
+
+
+### Confirming Navigation
+
+To 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.
+
+
+
+### Creating Hrefs
+
+If 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 ``.
+
+----------
+
+
+
+## Reference
+
+The [source code](https://github.com/ReactTraining/history/tree/dev/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.
+
+
+
+### Action
+
+An [`Action`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L4) represents a type of change that occurred in the history stack. `Action` is an `enum` with three members:
+
+- `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.
+- `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.
+- `Action.Replace` - Indicates the entry at the current index in the history stack being replaced by a new one.
+
+See [the Getting Started guide](getting-started.md) for more information.
+
+
+
+
+### `createBrowserHistory`
+
+
declare createBrowserHistory({ window?: Window }): BrowserHistory;
-```
-`createBrowserHistory` returns a [`BrowserHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L306) instance for the given `window`, which defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).
+interface BrowserHistory<S extends State = State> {
+ readonly action: Action;
+ readonly location: Location<S>;
+ createHref(to: To): string;
+ push(to: To, state?: S): void;
+ replace(to: To, state?: S): void;
+ go(n: number): void;
+ back(): void;
+ forward(): void;
+ listen(listener: Listener<S>): () => void;
+ block(blocker: Blocker<S>): () => void;
+}
+
+
+A 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.
+
+`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).
```ts
import { createBrowserHistory } from 'history';
@@ -37,61 +107,75 @@ let history = createBrowserHistory();
See [the Getting Started guide](getting-started.md) for more information.
-
+
+
+
-### Hash History
+### `createPath` and `parsePath`
-A "hash history" object is designed to be run in modern web browsers that support the HTML5 history interface including `pushState`, `replaceState`, and the `popstate` event. The main difference between this and [browser history](#createbrowserhistory) is that a hash history stores the current location in the `hash` portion of the URL, which means that it is not ever sent to the server.
+The library also exports `createPath` and `parsePath` methods that are useful when working with URL paths.
```ts
-declare createHashHistory({ window?: Window }): HashHistory;
-```
-
-`createHashHistory` returns a [`HashHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L317) instance for the given `window`, which defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).
+declare createPath(partialPath: PartialPath): string;
+declare parsePath(path: string): PartialPath;
-```ts
-import { createHashHistory } from 'history';
-let history = createHashHistory();
+interface PartialPath {
+ pathname?: string;
+ search?: string;
+ hash?: string;
+}
```
-See [the Getting Started guide](getting-started.md) for more information.
+
+
-
+### `createHashHistory`
-### Memory History
+
+declare createHashHistory({ window?: Window }): HashHistory;
-A "memory history" object stores all locations internally in an array. This makes it ideal as a reference implementation and for situations where you need complete control over the history stack, like tests and React Native.
+interface HashHistory<S extends State = State> {
+ readonly action: Action;
+ readonly location: Location<S>;
+ createHref(to: To): string;
+ push(to: To, state?: S): void;
+ replace(to: To, state?: S): void;
+ go(n: number): void;
+ back(): void;
+ forward(): void;
+ listen(listener: Listener<S>): () => void;
+ block(blocker: Blocker<S>): () => void;
+}
+
-```ts
-declare createMemoryHistory({
- initialEntries?: InitialEntry[],
- initialIndex?: number
-}): MemoryHistory;
+A 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.
-type InitialEntry = Path | LocationPieces;
-```
+`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).
-`createMemoryHistory` returns a [`MemoryHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L324) instance.
+The 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.
```ts
-import { createMemoryHistory } from 'history';
-let history = createMemoryHistory();
+import { createHashHistory } from 'history';
+let history = createHashHistory();
```
-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`.
-
See [the Getting Started guide](getting-started.md) for more information.
-
+
+
-## History
+### `createMemoryHistory`
-A `history` object is similar to a [web browser's `window.history`](https://developer.mozilla.org/en-US/docs/Web/API/Window/history) instance but with a smaller API. `history` objects maintain a "stack" of [`location`](#location) objects that represent a user's browsing history. As you navigate around the app, the stack is automatically updated to reflect the changes.
+
+declare createMemoryHistory({
+ initialEntries?: InitialEntry[],
+ initialIndex?: number
+}): MemoryHistory;
-A `history` object has the following interface:
+type InitialEntry = string | PartialLocation;
-
-interface History<S extends State = State> {
+interface MemoryHistory<S extends State = State> {
+ readonly index: number;
readonly action: Action;
readonly location: Location<S>;
createHref(to: To): string;
@@ -105,70 +189,116 @@ interface History<S extends State = Sta
}
+A 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.
+
+`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`.
+
+```ts
+import { createMemoryHistory } from 'history';
+let history = createMemoryHistory();
+// Or, to pre-seed the history instance with some URLs:
+let history = createMemoryHistory({
+ initialEntries: ['/home', '/profile', '/about']
+});
+```
+
+See [the Getting Started guide](getting-started.md) for more information.
+
### `history.action`
-The current (most recent) [`Action`](#action) that modified the history stack.
+The current (most recent) [`Action`](#action) that modified the history stack. This property is mutable and automatically updates as the current location changes.
-
+See also [`history.listen`](#history.listen).
-### `history.location`
+
-The current [`Location`](#location).
+### `history.back()`
-
+Goes back one entry in the history stack. Alias for `history.go(-1)`.
-### `history.createHref(to: To)`
+See [the Navigation guide](navigation.md) for more information.
-Returns a string suitable for use as an `` value that will navigate to
-the given destination.
+
-
+### `history.block(blocker: Blocker)`
-### `history.push(to: To, state?: State)`
+```ts
+interface Blocker {
+ (tx: Transition): void;
+}
-Pushes a new entry onto the stack.
+interface Transition {
+ action: Action;
+ location: Location;
+ retry(): void;
+}
+```
-See [the Navigation guide](navigation.md) for more information.
+Prevents 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.
-
+```ts
+// To start blocking location changes...
+let unblock = history.block(({ action, location, retry }) => {
+ // A transition was blocked!
+});
-### `history.replace(to: To, state?: State)`
+// Later, when you want to start allowing transitions again...
+unblock();
+```
-Replaces the current entry in the stack with a new one.
+See [the guide on Blocking Transitions](blocking-transitions.md) for more information.
-See [the Navigation guide](navigation.md) for more information.
+
-
+### `history.createHref(to: To)`
-### `history.go(delta: number)`
+Returns a string suitable for use as an `` value that will navigate to
+the given destination.
-Navigates back/forward by `delta` entries in the stack.
+
+
+### `history.forward()`
+
+Goes forward one entry in the history stack. Alias for `history.go(1)`.
See [the Navigation guide](navigation.md) for more information.
-
+
-### `history.back()`
+### `history.go(delta: number)`
-Goes back one entry in the history stack. Alias for `history.go(-1)`.
+Navigates back/forward by `delta` entries in the stack.
See [the Navigation guide](navigation.md) for more information.
-
+
-### `history.forward()`
+### `history.index`
-Goes forward one entry in the history stack. Alias for `history.go(1)`.
+The current index in the history stack.
-See [the Navigation guide](navigation.md) for more information.
+> [!Note:]
+>
+> This property is available only on [memory history](#memoryhistory) instances.
### `history.listen(listener: Listener)`
-Starts listening for location changes and calls the given callback when it does.
+```ts
+interface Listener {
+ (update: Update): void;
+}
+
+interface Update {
+ action: Action;
+ location: Location;
+}
+```
+
+Starts listening for location changes and calls the given callback with an `Update` when it does.
```ts
// To start listening for location changes...
@@ -182,47 +312,51 @@ unlisten();
See [the Getting Started guide](getting-started.md#listening) for more information.
-
+
-### `history.block(blocker: Blocker)`
+### `history.location`
-Prevents changes to the history stack from happening. This is useful when you want to prevent the user navigating away from the current page for some reason.
+The current [`Location`](#location). This property is mutable and automatically updates as the current location changes.
-```ts
-// To start blocking location changes...
-let unblock = history.block(({ action, location, retry }) => {
- // A transition was blocked!
-});
+Also see [`history.listen`](#history.listen).
-// Later, when you want to start allowing transitions again...
-unblock();
-```
+
-See [the guide on Blocking Transitions](blocking-transitions.md) for more information.
+### `history.push(to: To, state?: State)`
-
+Pushes a new entry onto the stack.
-## Location
+See [the Navigation guide](navigation.md) for more information.
-A `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.
+
+
+### `history.replace(to: To, state?: State)`
+
+Replaces the current entry in the stack with a new one.
-A `location` object has the following interface:
+See [the Navigation guide](navigation.md) for more information.
+
+
+
+### Location
-interface Location {
+interface Location<S extends State = State> {
pathname: string;
search: string;
hash: string;
- state: State;
+ state: S;
key: string;
}
+A `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.
+
### `location.pathname`
-The `location.pathname` property contains an initial `/` followed by the remainder of the URL up to the `?`.
+The `location.pathname` property is a string that contains an initial `/` followed by the remainder of the URL up to the `?`.
See also [`URL.pathname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname).
@@ -230,7 +364,7 @@ See also [`URL.pathname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/p
### `location.search`
-The `location.search` property 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. `''`).
+The `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. `''`).
See also [`URL.search`](https://developer.mozilla.org/en-US/docs/Web/API/URL/search).
@@ -238,7 +372,7 @@ See also [`URL.search`](https://developer.mozilla.org/en-US/docs/Web/API/URL/sea
### `location.hash`
-The `location.hash` property 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. `''`).
+The `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. `''`).
See also [`URL.hash`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash).
@@ -246,9 +380,13 @@ See also [`URL.hash`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash)
### `location.state`
-The `location.state` property contains 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.
+The `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.
-Note: In web browsers, this state is managed using the browser's built-in `pushState`, `replaceState`, and `popstate` APIs. See also [`History.state`](https://developer.mozilla.org/en-US/docs/Web/API/History/state).
+> [!Note:]
+>
+> In web browsers, this state is managed using the browser's built-in
+> `pushState`, `replaceState`, and `popstate` APIs. See also
+> [`History.state`](https://developer.mozilla.org/en-US/docs/Web/API/History/state).
@@ -258,49 +396,18 @@ The `location.key` property is a unique string associated with this location. On
This 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.
-
-
-## Action
-
-An [`Action`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L4) represents a type of change that occurred in the history stack. `Action` is an `enum` with three members:
-
-- `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.
-- `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.
-- `Action.Replace` - Indicates the entry at the current index in the history stack being replaced by a new one.
-
-See [the Getting Started guide](getting-started.md) for more information.
-
-
-
-## To
-
-A [`To`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L212) 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).
-
-See [the Navigation guide](navigation.md) for more information.
-
-## State
+### State
A [`State`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L61) value is an object of extra information that is associated with a [`Location`](#location) but that does not appear in the URL. This value is always associated with that location.
See [the Navigation guide](navigation.md) for more information.
-
-
-## Creating and Parsing Paths
-
-The library also exports `createPath` and `parsePath` methods that are useful when working with URL paths.
+
-```ts
-declare createPath(pieces: PathPieces): Path;
-declare parsePath(path: Path): PathPieces;
+### To
-type Path = string;
+A [`To`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L212) 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).
-interface PathPieces {
- pathname?: string;
- search?: string;
- hash?: string;
-}
-```
+See [the Navigation guide](navigation.md) for more information.
\ No newline at end of file
diff --git a/packages/history/index.ts b/packages/history/index.ts
index ea14c5e67..fde50360d 100644
--- a/packages/history/index.ts
+++ b/packages/history/index.ts
@@ -25,12 +25,6 @@ export enum Action {
Replace = 'REPLACE'
}
-/**
- * A URL path including the pathname, search string, and hash. No URL protocol
- * or domain information should be part of a path.
- */
-export type Path = string;
-
/**
* A URL pathname, beginning with a /.
*
@@ -67,92 +61,98 @@ export type State = object | null;
export type Key = string;
/**
- * The pieces of a URL path.
+ * The pathname, search, and hash values of a URL.
*/
-export interface PathPieces {
+export interface Path {
/**
- * The URL pathname, beginning with a /.
+ * A URL pathname, beginning with a /.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/Location/pathname
*/
- pathname?: Pathname;
+ pathname: Pathname;
/**
- * The URL search string, beginning with a ?.
+ * A URL search string, beginning with a ?.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/Location/search
*/
- search?: Search;
+ search: Search;
/**
- * The URL fragment identifier, beginning with a #.
+ * A URL fragment identifier, beginning with a #.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/Location/hash
*/
- hash?: Hash;
+ hash: Hash;
}
/**
- * The pieces of a Location object.
+ * An entry in a history stack. A location contains information about the
+ * URL path, as well as possibly some arbitrary state and a key.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#location
*/
-export interface LocationPieces extends PathPieces {
+export interface Location extends Path {
/**
- * Additional state tied to this location.
+ * An object of arbitrary data associated with this location.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/History/state
*/
- state?: S;
+ state: S;
/**
* A unique string associated with this location. May be used to safely store
- * and retrieve data in some other storage API, like `localStorage`. This
- * value is always "default" on the initial location.
+ * and retrieve data in some other storage API, like `localStorage`.
+ *
+ * Note: This value is always "default" on the initial location.
*/
- key?: Key;
+ key: Key;
}
/**
- * A location represents the current state in a history stack. It contains
- * information about the URL path, as well as some state and a key. Analogous
- * to the web's window.location API, but much smaller.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/location
+ * A partial Path object that may be missing some properties.
*/
-export interface Location {
+export interface PartialPath {
/**
* The URL pathname, beginning with a /.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/Location/pathname
*/
- pathname: Pathname;
+ pathname?: Pathname;
/**
* The URL search string, beginning with a ?.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/Location/search
*/
- search: Search;
+ search?: Search;
/**
* The URL fragment identifier, beginning with a #.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/Location/hash
*/
- hash: Hash;
+ hash?: Hash;
+}
+/**
+ * A partial Location object that may be missing some properties.
+ */
+export interface PartialLocation extends PartialPath {
/**
- * Additional state tied to this location.
+ * An object of arbitrary data associated with this location.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/History/state
*/
- state: S;
+ state?: S;
/**
* A unique string associated with this location. May be used to safely store
- * and retrieve data in some other storage API, like `localStorage`. This
- * value is always "default" on the initial location.
+ * and retrieve data in some other storage API, like `localStorage`.
+ *
+ * Note: This value is always "default" on the initial location.
*/
- key: Key;
+ key?: Key;
}
/**
@@ -196,11 +196,11 @@ export interface Blocker {
}
/**
- * Describes a {@link Location} that is the destination of some navigation,
- * either via {@link history.push | `history.push`} or {@link history.replace |
- * `history.replace`}. May be either a URL or the pieces of a URL path.
+ * Describes a location that is the destination of some navigation, either via
+ * `history.push` or `history.replace`. May be either a URL or the pieces of a
+ * URL path.
*/
-export type To = Path | PathPieces;
+export type To = string | PartialPath;
/**
* A history is an interface to the navigation stack. The history serves as the
@@ -276,6 +276,7 @@ export interface History {
* Sets up a listener that will be called whenever the current location
* changes.
*
+ * @param listener - A function that will be called when the location changes
* @returns unlisten - A function that may be used to stop listening
*/
listen(listener: Listener): () => void;
@@ -284,6 +285,7 @@ export interface History {
* Prevents the current location from changing and sets up a listener that
* will be called instead.
*
+ * @param blocker - A function that will be called when a transition is blocked
* @returns unblock - A function that may be used to stop blocking
*/
block(blocker: Blocker): () => void;
@@ -293,6 +295,8 @@ export interface History {
* A browser history stores the current location in regular URLs in a web
* browser environment. This is the standard for most web apps and provides the
* cleanest URLs the browser's address bar.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#browserhistory
*/
export interface BrowserHistory extends History {}
@@ -304,6 +308,8 @@ export interface BrowserHistory extends History {}
* (because the fragment identifier is never sent to the server), including some
* shared hosting environments that do not provide fine-grained controls over
* which pages are served at which URLs.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#hashhistory
*/
export interface HashHistory extends History {}
@@ -311,6 +317,8 @@ export interface HashHistory extends History {}
* A memory history stores locations in memory. This is useful in stateful
* environments where there is no web browser, such as node tests or React
* Native.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#memoryhistory
*/
export interface MemoryHistory extends History {
index: number;
@@ -351,15 +359,14 @@ const BeforeUnloadEventType = 'beforeunload';
const HashChangeEventType = 'hashchange';
const PopStateEventType = 'popstate';
-/**
- * The type of options that are available in {@link createBrowserHistory}.
- */
export type BrowserHistoryOptions = { window?: Window };
/**
* Browser history stores the location in regular URLs. This is the standard for
* most web apps, but it requires some configuration on the server to ensure you
* serve the same app at multiple URLs.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#createbrowserhistory
*/
export function createBrowserHistory(
options: BrowserHistoryOptions = {}
@@ -570,9 +577,6 @@ export function createBrowserHistory(
// HASH
////////////////////////////////////////////////////////////////////////////////
-/**
- * The type of options that are available in {@link createHashHistory}.
- */
export type HashHistoryOptions = { window?: Window };
/**
@@ -580,6 +584,8 @@ export type HashHistoryOptions = { window?: Window };
* for situations where you don't want to send the location to the server for
* some reason, either because you do cannot configure it or the URL space is
* reserved for something else.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#createhashhistory
*/
export function createHashHistory(
options: HashHistoryOptions = {}
@@ -831,14 +837,11 @@ export function createHashHistory(
////////////////////////////////////////////////////////////////////////////////
/**
- * Describes an entry in the history stack. Useful when providing entries to
- * {@link createMemoryHistory} via its `initialEntries` option.
+ * A user-supplied object that describes a location. Used when providing
+ * entries to `createMemoryHistory` via its `initialEntries` option.
*/
-export type InitialEntry = Path | LocationPieces;
+export type InitialEntry = string | PartialLocation;
-/**
- * The type of options that are available in {@link createMemoryHistory}.
- */
export type MemoryHistoryOptions = {
initialEntries?: InitialEntry[];
initialIndex?: number;
@@ -846,8 +849,9 @@ export type MemoryHistoryOptions = {
/**
* Memory history stores the current location in memory. It is designed for use
- * in stateful non-browser environments like headless tests (in node.js) and
- * React Native.
+ * in stateful non-browser environments like tests and React Native.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#creatememoryhistory
*/
export function createMemoryHistory(
options: MemoryHistoryOptions = {}
@@ -1040,34 +1044,44 @@ function createKey() {
.substr(2, 8);
}
+/**
+ * Creates a string URL path from the given pathname, search, and hash components.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#createpath
+ */
export function createPath({
pathname = '/',
search = '',
hash = ''
-}: PathPieces) {
+}: PartialPath) {
return pathname + search + hash;
}
-export function parsePath(path: Path) {
- let pieces: PathPieces = {};
+/**
+ * Parses a string URL path into its separate pathname, search, and hash components.
+ *
+ * @see https://github.com/ReactTraining/history/tree/dev/docs/api-reference.md#parsepath
+ */
+export function parsePath(path: string) {
+ let partialPath: PartialPath = {};
if (path) {
let hashIndex = path.indexOf('#');
if (hashIndex >= 0) {
- pieces.hash = path.substr(hashIndex);
+ partialPath.hash = path.substr(hashIndex);
path = path.substr(0, hashIndex);
}
let searchIndex = path.indexOf('?');
if (searchIndex >= 0) {
- pieces.search = path.substr(searchIndex);
+ partialPath.search = path.substr(searchIndex);
path = path.substr(0, searchIndex);
}
if (path) {
- pieces.pathname = path;
+ partialPath.pathname = path;
}
}
- return pieces;
+ return partialPath;
}