This is a glossary of common terms used in the history codebase and documentation listed in alphabetical order, along with their type signatures.
type Action = 'PUSH' | 'REPLACE' | 'POP';
An action describes the type of change to a URL. Possible values are:
PUSH– indicates a new item was added to the historyREPLACE– indicates the current item in history was alteredPOP– indicates there is a new current item, i.e. the "current pointer" changed
type BeforeUnloadHook = () => ?string;
A before unload hook is a function that is used in web browsers to prevent the user from navigating away from the page or closing the window.
type CreateHistory = (options: ?HistoryOptions) => History;
type CreateHistoryEnhancer = (createHistory: CreateHistory) => CreateHistory;
A createHistory enhancer (or simply a "history enhancer") is a function that augments the capabilities of a createHistory function. It usually does this in one of three ways:
- Adding
options(i.e. making more options available) - Supplying default
options - Augmenting the returned
historyobject
type History = {
listenBefore: (hook: TransitionHook) => Function;
listen: (listener: LocationListener) => Function;
transitionTo(location: Location) => void;
pushState(state: LocationState, path: Path) => void;
replaceState(state: LocationState, path: Path) => void;
go(n: number) => void;
goBack() => void;
goForward() => void;
createKey() => LocationKey;
createPath(path: Path) => Path;
createHref(path: Path) => Href;
};
type HistoryOptions = Object;
A history options object contains options that are used to create a new history object.
type Href = string;
An href is a URL string that may be used as the value of <a href>. The main reason to distinguish this type from a path is due to the fact that hash history puts a # in front of hrefs.
type Location = {
pathname: Pathname;
search: QueryString;
query: Query;
state: LocationState;
action: Action;
key: LocationKey;
};
A location answers two important (philosophical) questions:
- Where am I?
- How did I get here?
New locations are typically created each time the URL changes. You can read more about locations in the history docs.
type LocationKey = string;
A location key is a string that is unique to a particular location. It is the one piece of data that most accurately answers the question "Where am I?".
type LocationListener = (location: Location) => void;
type LocationState = ?Object;
A location state is an arbitrary object of data associated with a particular location. This is basically a way to tie extra state to a location that is not contained in the URL.
This type gets its name from the first argument to HTML5's pushState and replaceState methods.
type Path = Pathname + QueryString;
A path represents a URL path.
type Pathname = string;
A pathname is the portion of a URL that describes a hierarchical path, including the preceding /. For example, in http://example.com/the/path?the=query, /the/path is the pathname. It is synonymous with window.location.pathname in web browsers.
type QueryString = string;
A query string is the portion of the URL that follows the pathname, including any preceding ?. For example, in http://example.com/the/path?the=query, ?the=query is the query string. It is synonymous with window.location.search in web browsers.
type Query = Object;
A query is the parsed version of a query string.
A transition is the process of notifying listeners when the location changes. It is not an API; rather, it is a concept. Transitions may be interrupted by transition hooks.
Note: A transition does not refer to the exact moment the URL actually changes. For example, in web browsers the user may click the back button or otherwise directly manipulate the URL by typing into the address bar. This is not a transition, but a history object will start a transition as a result of the URL changing.
type TransitionHook = (location: Location, callback: ?Function) => any;
A transition hook is a function that is called just before listeners are notified of a new location.