histloc
v5.0.1
Published
A window.location-like browser history location implementation with events
Downloads
7
Readme
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});
}
}