Microscopically small universal URL to Location parser
MIT License
Microscopically small universal URL to Location parser
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.
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.
npm install --save ulocation
var Location = require('ulocation')
import Location from 'ulocation'
import Location from 'ulocation'
var loc = new Location('https://joe:[email protected]: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 url is parsed into it's constitutent parts (using native parsing in browsers and some logic in Node):
https://joe:[email protected]: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.
href
fieldThe 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.
console.info(loc.search) // > '?q=hello'
loc.href = 'https://joe:[email protected]:80/home/faq?q=goodbye'
console.info(loc.search) // > '?q=goodbye'
change
eventulocation 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,
but you can also use Node's events
module.
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()
:
// loc is the location object from the previous example
loc.on('change', function(){
console.info(this.href)
})
loc.href = 'https://joe:[email protected]:80/home/faq?q=hello#footer'
// > 'https://joe:[email protected]:80/home/faq?q=hello#footer'
Given a location loc
, you can parse the querystring in it's search
field
using uqs.
// 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'}
base
parameterRelative 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.
// 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:[email protected]: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'
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 or Webpack to include it in your bundle.
Add an issue in this project's issue tracker to let me know of any problems you find, or questions you may have.
Copyright 2017 by Stijn de Witt. Some rights reserved.
Licensed under the MIT Open Source license.