ulocation
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.
Install
npm install --save ulocation
require
var Location =
import
use
var loc = 'https://joe:secret@example.com:80/home/faq?q=hello#footer'console // > 'https:'console // > 'joe'console // > 'example.com'console // > '?q=hello'console // > 'footer' lochref = 'http://example.com'console // > 'http:' locprotocol = 'ftp:'console // > 'ftp:'console // > '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.
href
field
The 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.
console // > '?q=hello'lochref = 'https://joe:secret@example.com:80/home/faq?q=goodbye'console // > '?q=goodbye'
change
event
The 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,
but you can also use Node's events
module.
var EventEmitter = var loc =
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 exampleloc lochref = '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.
// loc is the location object from the previous examplevar QS = var params = QSconsole // > Object {q:'hello'}
base
parameter
Relative URLs and the 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.
// loc is the location object from the previous examplevar rel = '/test?x=y#header' lochref // <-- use as baseconsole // > 'https://joe:secret@example.com:80/home/test?x=y#header'console // > 'https:'console // > 'joe'console // > 'example.com'console // > '?x=y'console // > '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 or Webpack to include it in your bundle.
Issues
Add an issue in this project's issue tracker to let me know of any problems you find, or questions you may have.
Copyright
Copyright 2017 by Stijn de Witt. Some rights reserved.
License
Licensed under the MIT Open Source license.