ulocation
Version:
Microscopically small universal URL to Location parser
147 lines (114 loc) • 5.53 kB
Markdown
# ulocation
Microscopically small universal URL to Location parser
[](https://npmjs.com/package/ulocation)
[](https://github.com/Download/ulocation/blob/master/LICENSE.md)
[](https://travis-ci.org/Download/ulocation)
[](https://greenkeeper.io/)
**ulocation** is a microscopically small universal (works in node and the browser)
url parser that returns location objects that closely mimic those used in browsers.
If you need to parse the querystring in the `search` field, use [uqs](https://npmjs.com/package/uqs).
ulocation supports the `origin` field on locations, shimming it in browsers that still lack support.
You can listen for any changes to a location object by turning it into an [EventEmitter](https://npmjs.com/package/uevents).
## Install
```sh
npm install --save ulocation
```
## require
```js
var Location = require('ulocation')
```
## import
```js
import Location from 'ulocation'
```
## use
```js
import Location from 'ulocation'
var loc = new Location('https://joe:secret@example.com:80/home/faq?q=hello#footer')
console.info(loc.protocol) // > 'https:'
console.info(loc.username) // > 'joe'
console.info(loc.hostname) // > 'example.com'
console.info(loc.search) // > '?q=hello'
console.info(loc.hash) // > 'footer'
loc.href = 'http://example.com'
console.info(loc.protocol) // > 'http:'
loc.protocol = 'ftp:'
console.info(loc.protocol) // > 'ftp:'
console.info(loc.href) // > 'ftp://example.com'
// ...
```
### The parts of the URL
The url is parsed into it's constitutent parts (using native parsing in browsers and some logic in Node):
```
https://joe:secret@example.com:80/home/faq?q=hello#footer
\____/ \_/ \____/ \_________/ \/\_______/\______/\_____/
| | | | | | | |
protocol | password | port | search |
username hostname pathname hash
```
You can set any of these fields to a different value later and all other fields will update automatically.
### The `href` field
The `href` field is backed by getter and setter functions and works like in browsers: set the field
and all others will update to match it.
```js
console.info(loc.search) // > '?q=hello'
loc.href = 'https://joe:secret@example.com:80/home/faq?q=goodbye'
console.info(loc.search) // > '?q=goodbye'
```
### The `change` event
ulocation objects have built-in support for `EventEmitter`. If a change is made and the location
object has an `emit` function, a `change` event will be emitted.
To change a location into an event emitter, I recommend [uevents](https://npmjs.com/package/uevents),
but you can also use Node's `events` module.
```js
var EventEmitter = require('uevents')
var loc = EventEmitter(Location('http://example.com'))
```
Now, whenever the `href` field is updated, `loc` emits a `'change'` event.
To listen for it, attach a listener using `on()`:
```js
// loc is the location object from the previous example
loc.on('change', function(){
console.info(this.href)
})
loc.href = 'https://joe:secret@example.com:80/home/faq?q=hello#footer'
// > 'https://joe:secret@example.com:80/home/faq?q=hello#footer'
```
### Parsing the querystring
Given a location `loc`, you can parse the querystring in it's `search` field
using [uqs](https://github.com/download/uqs).
```js
// loc is the location object from the previous example
var QS = require('uqs')
var params = QS.parse(loc.search)
console.info(params) // > Object {q:'hello'}
```
### Relative URLs and the `base` parameter
Relative URLs are normally interpreted relative to the current location automatically on
browsers. We can make ulocations work the same way by passing a `base` parameter to `Location`.
It will use the passed URL as the base URL when constructing the location or updating
it when the `href` field is set. If no `base` is passed, it uses the current URL as
base for the new URL when setting `href` to a relative URL.
```js
// loc is the location object from the previous example
var rel = new Location('/test?x=y#header', loc.href) // <-- use as base
console.info(rel.href) // > 'https://joe:secret@example.com:80/home/test?x=y#header'
console.info(rel.protocol) // > 'https:'
console.info(rel.username) // > 'joe'
console.info(rel.hostname) // > 'example.com'
console.info(rel.search) // > '?x=y'
console.info(rel.hash) // > 'header'
```
## Microscopically small
The browser version of ulocation is just ~1kB minified and zipped.
Due to it's tiny size it does not come as a separate download. Instead you should use
[Browserify](http://browserify.org/) or [Webpack](https://webpack.js.org/) to include
it in your bundle.
## Issues
Add an issue in this project's [issue tracker](https://github.com/download/ulocation/issues)
to let me know of any problems you find, or questions you may have.
## Copyright
Copyright 2017 by [Stijn de Witt](https://StijnDeWitt.com). Some rights reserved.
## License
Licensed under the [MIT](https://github.com/download/ulocation/blob/master/LICENSE.md) Open Source license.