npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

histloc

v5.0.1

Published

A window.location-like browser history location implementation with events

Downloads

7

Readme

npm GitHub browser TypeScript

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});
    }
}