url-parse
The url-parse
method exposes two different API interfaces. The url
interface that you know from Node.js and the new URL
interface that is available in the latest browsers.
In version 0.1
we moved from a DOM based parsing solution, using the <a>
element, to a full Regular Expression solution. The main reason for this was to make the URL parser available in different JavaScript environments as you don't always have access to the DOM. An example of such environment is the Worker
interface. The RegExp based solution didn't work well as it required a lot of lookups causing major problems in FireFox. In version 1.0.0
we ditched the RegExp based solution in favor of a pure string parsing solution which chops up the URL into smaller pieces. This module still has a really small footprint as it has been designed to be used on the client side.
In addition to URL parsing we also expose the bundled querystringify
module.
Installation
This module is designed to be used using either browserify or Node.js it's released in the public npm registry and can be installed using:
Usage
All examples assume that this library is bootstrapped using:
To parse an URL simply call the URL
method with the URL that needs to be transformed into an object.
The new
keyword is optional but it will save you an extra function invocation. The constructor takes the following arguments:
url
(String
): A string representing an absolute or relative URL.baseURL
(Object
|String
): An object or string representing the base URL to use in caseurl
is a relative URL. This argument is optional and defaults tolocation
in the browser.parser
(Boolean
|Function
): This argument is optional and specifies how to parse the query string. By default it isfalse
so the query string is not parsed. If you passtrue
the query string is parsed using the embeddedquerystringify
module. If you pass a function the query string will be parsed using this function.
As said above we also support the Node.js interface so you can also use the library in this way:
The returned url
instance contains the following properties:
protocol
: The protocol scheme of the URL (e.g.http:
).slashes
: A boolean which indicates whether theprotocol
is followed by two forward slashes (//
).auth
: Authentication information portion (e.g.username:password
).username
: Username of basic authentication.password
: Password of basic authentication.host
: Host name with port number.hostname
: Host name without port number.port
: Optional port number.pathname
: URL path.query
: Parsed object containing query string, unless parsing is set to false.hash
: The "fragment" portion of the URL including the pound-sign (#
).href
: The full URL.origin
: The origin of the URL.
Note that when url-parse
is used in a browser environment, it will default to using the browser's current window location as the base URL when parsing all inputs. To parse an input independently of the browser's current URL (e.g. for functionality parity with the library in a Node environment), pass an empty location object as the second parameter:
Url.set(key, value)
A simple helper function to change parts of the URL and propagating it through all properties. When you set a new host
you want the same value to be applied to port
if has a different port number, hostname
so it has a correct name again and href
so you have a complete URL.
It's aware of default ports so you cannot set a port 80 on an URL which has http
as protocol.
Url.toString()
The returned url
object comes with a custom toString
method which will generate a full URL again when called. The method accepts an extra function which will stringify the query string for you. If you don't supply a function we will use our default method.
You would rarely need to use this method as the full URL is also available as href
property. If you are using the URL.set
method to make changes, this will automatically update.
Testing
The testing of this module is done in 3 different ways:
We have unit tests that run under Node.js. You can run these tests with the
npm test
command.Code coverage can be run manually using
npm run coverage
.For browser testing we use Sauce Labs and
zuul
. You can run browser tests using thenpm run test-browser
command.
License
Last updated