Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/reallyland/url-observer

URLObserver observes for URL changes in a web browser
https://github.com/reallyland/url-observer

hashchange history observer popstate pushstate route url url-observer urlobserver

Last synced: about 2 months ago
JSON representation

URLObserver observes for URL changes in a web browser

Awesome Lists containing this project

README

        


url-observer

URLObserver observes URL changes in web browsers



Buy Me A Coffee
[![tippin.me][tippin-me-badge]][tippin-me-url]
[![Follow me][follow-me-badge]][follow-me-url]

[![Version][version-badge]][version-url]
[![MIT License][mit-license-badge]][mit-license-url]

[![Downloads][downloads-badge]][downloads-url]
[![Total downloads][total-downloads-badge]][downloads-url]
[![Packagephobia][packagephobia-badge]][packagephobia-url]
[![Bundlephobia][bundlephobia-badge]][bundlephobia-url]

[![ci][ga-ci-badge]][ga-ci-url]
[![Dependency Status][daviddm-badge]][daviddm-url]
[![codecov][codecov-badge]][codecov-url]

[![codebeat badge][codebeat-badge]][codebeat-url]
[![Language grade: JavaScript][lgtm-badge]][lgtm-url]
[![Code of Conduct][coc-badge]][coc-url]

> Inspired by PerformanceObserver but for observing history on browsers.

## Table of contents

- [Pre-requisites](#pre-requisites)
- [Installation](#installation)
- [Usage](#usage)
- [API References](#api-references)
- [Contributing](#contributing)
- [Code of Conduct](#code-of-conduct)
- [License](#license)

## Pre-requisites

- ES2018+ (_This module uses [RegExp named capture groups] for route matching._)

## Installation

```sh
# Install via NPM
$ npm install url-observer
```

## Usage

```ts
import 'url-observer';

const observer = new URLObserver((list, observer) => {
for (const entry of list.getEntries()) {
/** Process entry for each URL update */
}
});
const routes = [
/^\/test$\//i,
/^\/test\/(?[^\/]+)$/i,
];
const options = {
dwellTime: 2e3, /** Default dwellTime. Set -1 to always push new URL */
debug: false, /** Set to enable debug mode. This exposes hidden `routes` property. */
matcherCallback() {
/**
* Override how route matching works internally.
* By default, ES2018's RegExp named capture groups are used.
*/
},
};

/** Call .observe() to start observing history */
observe.observe(routes, options);

/** Call .add() to add new route or before route handler to existing registered route */
observer.add({
handleEvent: () => {
/** Do anything before route changes. Return true to navigate to new route. */
return true;
}
pathRegExp: routes[0],
/**
* A scoped route handler enables multiple before route handler to be registered to the
* same route. E.g.
*
* A .data-scope property or `data-scope` attribute can be set in an anchor tag so that URLObserver
* knows which before route handler it needs to trigger before navigating to a new URL.
*
* When .data-scope (or `data-scope`) is an empty string, it defaults to ':default', which is the
* default scope value when registering a route unless specified.
*
* 1. /test/456
* - No before route handler will be triggered on link click as it is not a scoped link.
*
* 2. /test/123
* - Only before route handler registered to ':default' scope will be triggered.
*
* 3. /test/456
* - Only before route handler registered to '456' scope will be triggered.
*
*/
scope: '',
});

/** Dynamically add new route without before route handler */
observer.add({ pathRegExp: /^\/test2$/i });

/** Call .disconnect() to stop observing history */
observer.disconnect();

/** Call .match() to determine if current URL is being observed by URLObserver */
const {
/** Return true for a matched route */
found,
/**
* Return URL parameters after matching the route RegExp with current URL. E.g.
*
* 1. /^\/test/i
* - This does not output any matches
* 2. /^\/test\/(?[^\/]+)$/i
* - This matches URL like '/test/123' and returns { test: 123 }. However, this requires
* ES2018's RegExp named capture groups to work as expected.
*/
params,
} = observer.match();

/** Remove a route from the observer */
observer.remove(routes[0]);

/** Remove a before route handler from an observing route */
observer.remove(routes[1], '456');

/** Return the history entries */
observer.takeRecords();

/** Async-ly call .updateHistory to manually update to new URL */
await observer.updateHistory('/test/789');

/**
* Async-ly call .updateHistory to manually update to new URL and trigger before route handler
* with defined scope value.
*/
await observer.updateHistory('/test/456', '456');
```

## API References

* [URLObserver]

## Contributing

### Code of Conduct

Please note that this project is released with a [Contributor Code of Conduct][coc-url]. By participating in this project you agree to abide by its terms.

## License

[MIT License](https://motss.mit-license.org/) © Rong Sen Ng

[npm-url]: https://www.npmjs.com
[RegExp named capture groups]: https://github.com/tc39/proposal-regexp-named-groups
[typescript-url]: https://github.com/Microsoft/TypeScript
[URLObserver]: /API_REFERENCES.md
[vscode-url]: https://code.visualstudio.com

[array-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
[boolean-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[function-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
[map-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
[number-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
[object-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
[promise-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
[regexp-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
[set-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
[string-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String

[tippin-me-badge]: https://badgen.net/badge/%E2%9A%A1%EF%B8%8Ftippin.me/@igarshmyb/F0918E
[follow-me-badge]: https://flat.badgen.net/twitter/follow/igarshmyb?icon=twitter

[version-badge]: https://flat.badgen.net/npm/v/url-observer?icon=npm
[mit-license-badge]: https://flat.badgen.net/npm/license/url-observer

[downloads-badge]: https://flat.badgen.net/npm/dm/url-observer
[total-downloads-badge]: https://flat.badgen.net/npm/dt/url-observer?label=total%20downloads
[packagephobia-badge]: https://flat.badgen.net/packagephobia/install/url-observer
[bundlephobia-badge]: https://flat.badgen.net/bundlephobia/minzip/url-observer

[ga-ci-badge]: https://github.com/reallyland/url-observer/workflows/ci/badge.svg?branch=master
[ga-sl-badge]: https://github.com/reallyland/url-observer/workflows/Sauce%20Labs/badge.svg?branch=master
[daviddm-badge]: https://flat.badgen.net/david/dep/reallyland/url-observer
[codecov-badge]: https://flat.badgen.net/codecov/c/github/reallyland/url-observer?label=codecov&icon=codecov

[codebeat-badge]: https://codebeat.co/badges/381c2791-cf71-4725-81da-c8f4d19d8735
[lgtm-badge]: https://flat.badgen.net/lgtm/grade/javascript/g/reallyland/url-observer?icon=lgtm
[coc-badge]: https://flat.badgen.net/badge/code%20of/conduct/pink

[tippin-me-url]: https://tippin.me/@igarshmyb
[follow-me-url]: https://twitter.com/igarshmyb

[version-url]: https://www.npmjs.com/package/url-observer
[mit-license-url]: /LICENSE

[downloads-url]: https://www.npmtrends.com/url-observer
[packagephobia-url]: https://packagephobia.now.sh/result?p=url-observer
[bundlephobia-url]: https://bundlephobia.com/result?p=url-observer

[ga-ci-url]: https://github.com/reallyland/url-observer/actions?query=workflow%3Aci
[ga-sl-url]: https://github.com/reallyland/url-observer/actions?query=workflow%3A%22Sauce+Labs%22
[daviddm-url]: https://david-dm.org/reallyland/url-observer
[codecov-url]: https://codecov.io/gh/reallyland/url-observer

[codebeat-url]: https://codebeat.co/projects/github-com-reallyland-url-observer-master
[lgtm-url]: https://lgtm.com/projects/g/reallyland/url-observer/context:javascript
[coc-url]: /CODE-OF-CONDUCT.md