histloc v5.0.1

histloc

The Location class introduced in this package produces a browser history location object with an API similar to window.location (.href, .assign(), .replace()).

As an extension to the window.location interface, this class exposes methods for subscription to changes of the browser history and for pattern matching.

Usage

Initialization

import {Location} from 'histloc';
export const location = new Location();

Subscription to URL changes

Adding a handler of an exact URL path:

// We are using the `location` instance declared above.
let locationListener = location.addListener('/home', ({href}) => {
    console.log(href);
});

of a specific URL path pattern:

location.addListener(/^\/section\/(?<id>\d+)\/?$/, ({href, params}) => {
    console.log(href, params.id);
});

and removing a previously created location listener:

locationListener.remove();

Tracking all location changes:

let unsubscribe = location.onChange(({href}) => {
    console.log(href);
});

and unsubscribing from them:

unsubscribe();

Matching

Checking a location pattern (or an array thereof) if it matches the current path:

// Provided that the current location is '/item/42':
location.match('/home'); // null
location.match('/item/42'); // {}
location.match(/^\/item\/(?<id>\d+)\/?$/); // {0: '42', id: '42'}

location.matches('/home'); // false
location.matches('/item/42'); // true
location.matches(/^\/item\/(?<id>\d+)\/?$/); // true

The evaluate() method works much like the conditional ternary operator (condition ? x : y): if the current location matches the given location pattern it returns based on the second argument and falls back to the third argument otherwise.

// Provided that the current location is '/item/42':
location.evaluate('/home', 1, 0); // 0
location.evaluate('/item/42', 'a', 'b'); // 'a'
location.evaluate(/^\/item\/(?<id>\d+)\/?$/, 5); // 5

// If the second or the third argument is a function it will be called
// with `{href, params}` as its argument.
location.evaluate('/home', () => 1, ({href}) => href); // '/item/42'
location.evaluate(/^\/item\/(?<id>\d+)\/?$/, ({params}) => params.id);
// 42

Navigation

Getting the current location:

console.log(location.href);

Changing the current location:

// With the current location saved in the browser history
location.assign('/home');

// Without saving the current location in the browser history
location.replace('/home');

Reloading the current location (by re-dispatching the current location event to the subscribers of the location instance):

location.reload();

Jumping to browser history entries:

location.go(-2); // to go 2 entries back in the browser history
location.back(); // = location.go(-1);
location.forward(); // = location.go(+1);

Custom behavior

The interaction of a Location instance with window.history or window.location is isolated in a number of methods that can be overriden in descendant classes to apply custom behavior. These methods are: initialize(), transition(), go(), deriveHref().

For example: By default, a Location instance derives its href from the pathname, search, and hash portions of the URL combined. To make a Location instance disregard the URL search and hash, the Location class can be extended to redefine the deriveHref() method:

import {Location, getPath} from 'histloc';

export class PathLocation extends Location {
    deriveHref(location) {
        return getPath(location, {search: false, hash: false});
    }
}