Improved URL objects for node.js
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

nURL - A simple URL object for node.js

This module provides a simple URL object that provides a clean, easy-to-use interface to accessing a URLs values as well as for creating and manipulating URLs. Each URL object is immutable: whenever a value is altered, a new instance is returned leaving the original unchanged.

This module builds on top of the core 'url' and 'querystring' modules.


Nothing more than:

npm install nurl

Sample usage

URLs are modelled as:


Note that the // following the scheme is optional for certain schema (eg mailto).

Now, starting with:

var nurl = require('nurl');

you can create a URL object using one of:

var u = nurls.parse('');
var u = (new nurl.Url()).setScheme('http')
						.setQueryParam('q', 'node.js')
var u = new nurl.Url('http', Null, Null, '', Null, '/search', 'q=node.js', 'top');

The various components of u can be accessed through both read-only properties and getter methods:

u.protocol, u.scheme, u.getProtocol(), u.getScheme() // => 'http'
u.getUser() // => Null
u.getPassword() // => Null
u.auth, u.getAuth() // => Null
u.hostname, u.getHostname() // => ''
u.port, u.getPort() // => 80
u.pathname, u.getPathname() // => '/search', u.getSearch() // => '?node.js'
u.fragment, u.hash, u.getFragment(), u.getHash() // => 'top'
u.href, u.getHref() // => ''

Note that:

  • both the properties and getters return Null when the component has no value. w
  • some property names are aliases (such as 'protocol' and 'scheme')

More detailed interrogation can be performed using:

u.getSubdomains() // => ['www', 'google', 'com']
u.getSubdomain(0) // => 'www'
u.hasQueryParam('q') // => True
u.getQueryParam('q') // => 'node.js'
u.getPathSegments() // => ['search']
u.getPathSegment(0) // => 'search'
u.isRelative() // => False
u.isAbsolute() // => True

Setters follow a similar pattern, each returning a new URL object:

u.setProtocol('https'), u.setScheme('https')
u.setAuth('user', 'secret')
u.setSubdomain(0, 'sample') // => ''
u.setPathSegment(1, 'extension') // => '/search/extension'
u.setPathSegments(['search', 'some query here'])
u.setQueryParam('q', 'testing')

URL objects can be merged to create a new object - the properties of the passed in URL will fill in any missing components:

var u1 = nurl.parse('');
var u2 = nurl.parse('/search?q=test.js');
u1.mergeWith(u2) // => ''


All tests are written in the excellent vows library. To run them, use

$ cd /path/to/nurl
$ vows --spec


David Winterbottom (