diff --git a/.prettierignore b/.prettierignore index c99ed473f..cce027906 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,2 @@ -.travis.yml package.json package-lock.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56c2461c0..8578d092e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -All development happens [on GitHub](https://github.com/ReactTraining/history). When [creating a pull request](https://help.github.com/articles/creating-a-pull-request/), please make sure that all of the following apply: +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: - 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. - 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. diff --git a/README.md b/README.md index b1642ac73..7c6e70622 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@ -# history · [![npm package][npm-badge]][npm] [![Travis][build-badge]][build] +# history · [![npm package][npm-badge]][npm] [npm-badge]: https://img.shields.io/npm/v/history.svg?style=flat-square [npm]: https://www.npmjs.org/package/history -[build-badge]: https://img.shields.io/travis/ReactTraining/history/master.svg?style=flat-square -[build]: https://travis-ci.org/ReactTraining/history The 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. @@ -11,17 +9,17 @@ The history library lets you easily manage session history anywhere JavaScript r Documentation 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. -Documentation for version 4 can be found [on the v4 branch](https://github.com/ReactTraining/history/tree/v4/docs). Version 4 is used in React Router versions 4 and 5. +Documentation 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. ## Changes -To see the changes that were made in a given release, please lookup the tag on [the releases page](https://github.com/ReactTraining/history/releases). +To 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). -For changes released in version 4.6.3 and earlier, please see [the `CHANGES.md` file](https://github.com/ReactTraining/history/blob/845d690c5576c7f55ecbe14babe0092e8e5bc2bb/CHANGES.md). +For 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). ## Development -Development of the current stable release, version 5, happens on [the `master` branch](https://github.com/ReactTraining/history/tree/master). 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 `master` is always stable, you should feel free to build your own working release straight from master at any time. +Development 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. If you're interested in helping out, please read [our contributing guidelines](CONTRIBUTING.md). diff --git a/docs/api-reference.md b/docs/api-reference.md index c9c5c1fe9..e56f94db1 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -2,7 +2,7 @@ # history API Reference -This is the API reference for [the history JavaScript library](https://github.com/ReactTraining/history). +This is the API reference for [the history JavaScript library](https://github.com/remix-run/history). 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. @@ -50,17 +50,17 @@ To prevent the location from changing, use [`history.block`](#history.block). Th -### Creating Hrefs +### Creating `href` values 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/master/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. +The [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. @@ -77,27 +77,41 @@ See [the Getting Started guide](getting-started.md) for more information. -### `createBrowserHistory` +### `History` + +A `History` object represents the shared interface for `BrowserHistory`, `HashHistory`, and `MemoryHistory`.
Type declaration -```tsx -declare createBrowserHistory({ window?: Window }): BrowserHistory; - -interface BrowserHistory { +```ts +interface History { readonly action: Action; - readonly location: Location; + readonly location: Location; createHref(to: To): string; - push(to: To, state?: S): void; - replace(to: To, state?: S): void; - go(n: number): void; + push(to: To, state?: any): void; + replace(to: To, state?: any): void; + go(delta: number): void; back(): void; forward(): void; - listen(listener: Listener): () => void; - block(blocker: Blocker): () => void; + listen(listener: Listener): () => void; + block(blocker: Blocker): () => void; } ``` + +
+ +### `createBrowserHistory` + +
+ Type declaration + +```tsx +function createBrowserHistory(options?: { window?: Window }): BrowserHistory; + +interface BrowserHistory extends History {} +``` +
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. @@ -121,15 +135,16 @@ See [the Getting Started guide](getting-started.md) for more information. Type declaration ```ts -declare createPath(partialPath: PartialPath): string; -declare parsePath(path: string): PartialPath; +function createPath(partialPath: Partial): string; +function parsePath(path: string): Partial; -interface PartialPath { - pathname?: string; - search?: string; - hash?: string; +interface Path { + pathname: string; + search: string; + hash: string; } ``` + The `createPath` and `parsePath` functions are useful for creating and parsing URL paths. @@ -148,21 +163,11 @@ parsePath('/login?next=home'); // { pathname: '/login', search: '?next=home' } Type declaration ```ts -declare createHashHistory({ window?: Window }): HashHistory; +createHashHistory({ window?: Window }): HashHistory; -interface HashHistory { - readonly action: Action; - readonly location: Location; - 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): () => void; - block(blocker: Blocker): () => void; -} +interface HashHistory extends History {} ``` + 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. @@ -187,27 +192,18 @@ See [the Getting Started guide](getting-started.md) for more information. Type declaration ```ts -declare createMemoryHistory({ +function createMemoryHistory({ initialEntries?: InitialEntry[], initialIndex?: number }): MemoryHistory; -type InitialEntry = string | PartialLocation; +type InitialEntry = string | Partial; -interface MemoryHistory { +interface MemoryHistory extends History { readonly index: number; - readonly action: Action; - readonly location: Location; - 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): () => void; - block(blocker: Blocker): () => void; } ``` + 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. @@ -249,16 +245,17 @@ See [the Navigation guide](navigation.md) for more information. Type declaration ```ts -interface Blocker { - (tx: Transition): void; +interface Blocker { + (tx: Transition): void; } -interface Transition { +interface Transition { action: Action; - location: Location; + location: Location; retry(): void; } ``` + 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. @@ -316,15 +313,16 @@ The current index in the history stack. Type declaration ```ts -interface Listener { - (update: Update): void; +interface Listener { + (update: Update): void; } -interface Update { +interface Update { action: Action; - location: Location; + location: Location; } ``` + Starts listening for location changes and calls the given callback with an `Update` when it does. @@ -351,7 +349,7 @@ Also see [`history.listen`](#history.listen). -### `history.push(to: To, state?: State)` +### `history.push(to: To, state?: any)` Pushes a new entry onto the stack. @@ -359,7 +357,7 @@ See [the Navigation guide](navigation.md) for more information. -### `history.replace(to: To, state?: State)` +### `history.replace(to: To, state?: any)` Replaces the current entry in the stack with a new one. @@ -373,14 +371,15 @@ See [the Navigation guide](navigation.md) for more information. Type declaration ```ts -interface Location { +interface Location { pathname: string; search: string; hash: string; - state: S; + state: unknown; 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. @@ -433,15 +432,7 @@ This can be useful in situations where you need to keep track of 2 different sta ### State -
- Type declaration - -```ts -type State = object | null; -``` -
- -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. +A `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. See [the Navigation guide](navigation.md) for more information. @@ -453,16 +444,17 @@ See [the Navigation guide](navigation.md) for more information. Type declaration ```ts -type To = string | PartialPath; +type To = string | Partial; -interface PartialPath { - pathname?: string; - search?: string; - hash?: string; +interface Path { + pathname: string; + search: string; + hash: 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). +A [`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). -See [the Navigation guide](navigation.md) for more information. \ No newline at end of file +See [the Navigation guide](navigation.md) for more information. diff --git a/packages/history/index.ts b/packages/history/index.ts index 7fa83f9a5..e38d9bbcf 100644 --- a/packages/history/index.ts +++ b/packages/history/index.ts @@ -1,7 +1,7 @@ /** * Actions represent the type of change to a location value. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#action + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#action */ export enum Action { /** @@ -30,21 +30,21 @@ export enum Action { /** * A URL pathname, beginning with a /. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.pathname + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.pathname */ export type Pathname = string; /** * A URL search string, beginning with a ?. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.search + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.search */ export type Search = string; /** * A URL fragment identifier, beginning with a #. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.hash + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.hash */ export type Hash = string; @@ -52,15 +52,16 @@ export type Hash = string; * An object that is used to associate some arbitrary data with a location, but * that does not appear in the URL path. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.state + * @deprecated + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.state */ -export type State = object | null; +export type State = unknown; /** * A unique string associated with a location. May be used to safely store * and retrieve data in some other storage API, like `localStorage`. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.key + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.key */ export type Key = string; @@ -71,21 +72,21 @@ export interface Path { /** * A URL pathname, beginning with a /. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.pathname + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.pathname */ pathname: Pathname; /** * A URL search string, beginning with a ?. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.search + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.search */ search: Search; /** * A URL fragment identifier, beginning with a #. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.hash + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.hash */ hash: Hash; } @@ -94,15 +95,15 @@ export interface Path { * 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/master/docs/api-reference.md#location + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location */ -export interface Location extends Path { +export interface Location extends Path { /** * A value of arbitrary data associated with this location. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.state + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.state */ - state: S | null; + state: unknown; /** * A unique string associated with this location. May be used to safely store @@ -110,20 +111,24 @@ export interface Location extends Path { * * Note: This value is always "default" on the initial location. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.key + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.key */ key: Key; } /** * A partial Path object that may be missing some properties. + * + * @deprecated */ export type PartialPath = Partial; /** * A partial Location object that may be missing some properties. + * + * @deprecated */ -export type PartialLocation = Partial>; +export type PartialLocation = Partial; /** * A change to the current location. @@ -170,7 +175,7 @@ export interface Blocker { * `history.push` or `history.replace`. May be either a URL or the pieces of a * URL path. */ -export type To = string | PartialPath; +export type To = string | Partial; /** * A history is an interface to the navigation stack. The history serves as the @@ -180,19 +185,19 @@ export type To = string | PartialPath; * It is similar to the DOM's `window.history` object, but with a smaller, more * focused API. */ -export interface History { +export interface History { /** * The last action that modified the current location. This will always be * Action.Pop when a history instance is first created. This value is mutable. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.action + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.action */ readonly action: Action; /** * The current location. This value is mutable. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.location + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.location */ readonly location: Location; @@ -202,7 +207,7 @@ export interface History { * * @param to - The destination URL * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.createHref + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.createHref */ createHref(to: To): string; @@ -214,9 +219,9 @@ export interface History { * @param to - The new URL * @param state - Data to associate with the new location * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.push + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.push */ - push(to: To, state?: S | null): void; + push(to: To, state?: any): void; /** * Replaces the current location in the history stack with a new one. The @@ -225,9 +230,9 @@ export interface History { * @param to - The new URL * @param state - Data to associate with the new location * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.replace + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.replace */ - replace(to: To, state?: S | null): void; + replace(to: To, state?: any): void; /** * Navigates `n` entries backward/forward in the history stack relative to the @@ -235,7 +240,7 @@ export interface History { * * @param delta - The delta in the stack index * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.go + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.go */ go(delta: number): void; @@ -245,14 +250,14 @@ export interface History { * Warning: if the current location is the first location in the stack, this * will unload the current document. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.back + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.back */ back(): void; /** * Navigates to the next entry in the stack. Identical to go(1). * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.forward + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.forward */ forward(): void; @@ -263,7 +268,7 @@ export interface History { * @param listener - A function that will be called when the location changes * @returns unlisten - A function that may be used to stop listening * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.listen + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.listen */ listen(listener: Listener): () => void; @@ -274,7 +279,7 @@ export interface History { * @param blocker - A function that will be called when a transition is blocked * @returns unblock - A function that may be used to stop blocking * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.block + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.block */ block(blocker: Blocker): () => void; } @@ -284,9 +289,9 @@ export interface History { * 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/master/docs/api-reference.md#browserhistory + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#browserhistory */ -export interface BrowserHistory extends History {} +export interface BrowserHistory extends History {} /** * A hash history stores the current location in the fragment identifier portion @@ -297,19 +302,19 @@ export interface BrowserHistory extends History {} * 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/master/docs/api-reference.md#hashhistory + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#hashhistory */ -export interface HashHistory extends History {} +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/master/docs/api-reference.md#memoryhistory + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#memoryhistory */ -export interface MemoryHistory extends History { - index: number; +export interface MemoryHistory extends History { + readonly index: number; } const readOnly: (obj: T) => Readonly = __DEV__ @@ -354,7 +359,7 @@ export type BrowserHistoryOptions = { window?: Window }; * 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/master/docs/api-reference.md#createbrowserhistory + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#createbrowserhistory */ export function createBrowserHistory( options: BrowserHistoryOptions = {} @@ -576,7 +581,7 @@ export type HashHistoryOptions = { window?: Window }; * 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/master/docs/api-reference.md#createhashhistory + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#createhashhistory */ export function createHashHistory( options: HashHistoryOptions = {} @@ -835,7 +840,7 @@ export function createHashHistory( * A user-supplied object that describes a location. Used when providing * entries to `createMemoryHistory` via its `initialEntries` option. */ -export type InitialEntry = string | PartialLocation; +export type InitialEntry = string | Partial; export type MemoryHistoryOptions = { initialEntries?: InitialEntry[]; @@ -846,7 +851,7 @@ export type MemoryHistoryOptions = { * Memory history stores the current location in memory. It is designed for use * in stateful non-browser environments like tests and React Native. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#creatememoryhistory + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#creatememoryhistory */ export function createMemoryHistory( options: MemoryHistoryOptions = {} @@ -1042,13 +1047,13 @@ function createKey() { /** * Creates a string URL path from the given pathname, search, and hash components. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#createpath + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#createpath */ export function createPath({ pathname = '/', search = '', hash = '' -}: PartialPath) { +}: Partial) { if (search && search !== '?') pathname += search.charAt(0) === '?' ? search : '?' + search; if (hash && hash !== '#') @@ -1059,10 +1064,10 @@ export function createPath({ /** * Parses a string URL path into its separate pathname, search, and hash components. * - * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#parsepath + * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#parsepath */ -export function parsePath(path: string): PartialPath { - let parsedPath: PartialPath = {}; +export function parsePath(path: string): Partial { + let parsedPath: Partial = {}; if (path) { let hashIndex = path.indexOf('#'); diff --git a/packages/history/package.json b/packages/history/package.json index 99a9d0339..6276d39e9 100644 --- a/packages/history/package.json +++ b/packages/history/package.json @@ -2,8 +2,8 @@ "name": "history", "version": "5.1.0", "description": "Manage session history with JavaScript", - "author": "React Training ", - "repository": "ReactTraining/history", + "author": "Remix Software ", + "repository": "remix-run/history", "license": "MIT", "main": "main.js", "module": "index.js", diff --git a/scripts/karma.conf.js b/scripts/karma.conf.js index 21a661c97..59d983046 100644 --- a/scripts/karma.conf.js +++ b/scripts/karma.conf.js @@ -43,7 +43,6 @@ module.exports = function (config) { } // Safari throws an error if you use replaceState more // than 100 times in 30 seconds :/ - // See https://travis-ci.com/ReactTraining/history/jobs/254197476 // BS_Safari: { // base: 'BrowserStack', // os: 'OS X',