Glossary.md

December 6, 2015 · View on GitHub

Glossary

This is a glossary of common terms used in the history codebase and documentation listed in alphabetical order, along with their type signatures.

Action

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 history
  • REPLACE – indicates the current item in history was altered
  • POP – indicates there is a new current item, i.e. the "current pointer" changed

BeforeUnloadHook

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.

CreateHistory

type CreateHistory = (options: ?HistoryOptions) => History;

CreateHistoryEnhancer

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 history object

Hash

type Hash = string;

A hash is a string that represents the hash portion of the URL. It is synonymous with window.location.hash in web browsers.

History

type History = {
  listenBefore: (hook: TransitionHook) => Function;
  listen: (listener: LocationListener) => Function;
  transitionTo(location: Location) => void;
  push(location: LocationDescriptor) => void;
  replace(location: LocationDescriptor) => void;
  go(n: number) => void;
  goBack() => void;
  goForward() => void;
  createKey() => LocationKey;
  createPath(location: LocationDescriptor) => Path;
  createHref(location: LocationDescriptor) => Href;
};

HistoryOptions

type HistoryOptions = Object;

A history options object contains options that are used to create a new history object.

Href

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.

Location

type Location = {
  pathname: Pathname;
  search: Search;
  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.

LocationDescriptor

type LocationDescriptorObject = {
  pathname: Pathname;
  search: Search;
  query: Query;
  state: LocationState;
};

type LocationDescriptor = LocationDescriptorObject | Path;

A location descriptor is the pushable analogue of a location. The history object uses locations to tell its listeners where they are, while history users use location descriptors to tell the history object where to go.

The object signature is compatible with that of location, differing only in ignoring the internally-generated action and key fields. This allows you to build a location descriptor from an existing location, which can be used to change only specific fields on the location.

For convenience, you can always use path strings instead of objects wherever a location descriptor is expected.

LocationKey

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?".

LocationListener

type LocationListener = (location: Location) => void;

LocationState

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.

Path

type Path = Pathname + Search + Hash;

A path represents a URL path as a string.

Pathname

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.

Query

type Query = Object;

A query is the parsed version of a search string.

type Search = string;

A search 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 search. It is synonymous with window.location.search in web browsers.

Transition

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.

TransitionHook

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.