URI.js #

URI.js


I always want to shoot myself in the head when looking at code like the following:

var url = "http://example.org/foo?bar=baz";
var separator = url.indexOf('?') > -1 ? '&' : '?';

url += separator + encodeURIComponent("foo") + "=" + encodeURIComponent("bar");

I still can’t believe javascript - the f**ing backbone-language of the web - doesn’t offer an API for mutating URLs. Browsers (Firefox) don’t expose the Location object (the structure behind window.location). Yes, one could think of decomposed IDL attributes as a native URL management library. But it relies on the DOM element <a>, it’s slow and doesn’t offer any convenience at all.

How about a nice, clean and simple API for mutating URIs:

var url = new URI("http://example.org/foo?bar=baz");
url.addQuery("foo", "bar");

URI.js is here to help with that.

API Example

// mutating URLs
URI("http://example.org/foo.html?hello=world")
  .username("rodneyrehm")
    // -> http://rodneyrehm@example.org/foo.html?hello=world
  .username("")
    // -> http://example.org/foo.html?hello=world
  .directory("bar")
    // -> http://example.org/bar/foo.html?hello=world
  .suffix("xml")
    // -> http://example.org/bar/foo.xml?hello=world
  .query("")
    // -> http://example.org/bar/foo.xml
  .tld("com")
    // -> http://example.com/bar/foo.xml
  .query({ foo: "bar", hello: ["world", "mars"] });
    // -> http://example.com/bar/foo.xml?foo=bar&hello=world&hello=mars

// cleaning things up
URI("?&foo=bar&&foo=bar&foo=baz&")
  .normalizeQuery();
    // -> ?foo=bar&foo=baz

// working with relative paths
URI("/foo/bar/baz.html")
  .relativeTo("/foo/bar/world.html");
    // -> ./baz.html

URI("/foo/bar/baz.html")
  .relativeTo("/foo/bar/sub/world.html")
    // -> ../baz.html
  .absoluteTo("/foo/bar/sub/world.html");
    // -> /foo/bar/baz.html

// URI Templates
URI.expand("/foo/{dir}/{file}", {
  dir: "bar",
  file: "world.html"
});
// -> /foo/bar/world.html

See the About Page and API Docs for more stuff.

Using URI.js

URI.js (without plugins) has a gzipped weight of about 7KB - if you include all extensions you end up at about 13KB. So unless you need second level domain support and use URI templates, we suggest you don’t include them in your build. If you don’t need a full featured URI mangler, it may be worth looking into the much smaller parser-only alternatives listed below.

URI.js is available through npm, bower, Jam, spm and manually from the build page:

# using bower
bower install uri.js

# using Jam
jam install URIjs

# using npm
npm install URIjs

# using spm
spm install urijs

Browser

I guess you’ll manage to use the build tool or follow the instructions below to combine and minify the various files into URI.min.js - and I’m fairly certain you know how to <script src=".../URI.min.js"></script> that sucker, too.

Node.js and NPM

Install with npm install URIjs or add "URIjs" to the dependencies in your package.json.

// load URI.js
var URI = require('URIjs');
// load an optional module (e.g. URITemplate)
var URITemplate = require('URIjs/src/URITemplate');

URI("/foo/bar/baz.html")
  .relativeTo("/foo/bar/sub/world.html")
    // -> ../baz.html

RequireJS

Clone the URI.js repository or use a package manager to get URI.js into your project.

require.config({
  paths: {
    URIjs: 'where-you-put-uri.js/src'
  }
});

require(['URIjs/URI'], function(URI) {
  console.log("URI.js and dependencies: ", URI("//amazon.co.uk").is('sld') ? 'loaded' : 'failed');
});
require(['URIjs/URITemplate'], function(URITemplate) {
  console.log("URITemplate.js and dependencies: ", URITemplate._cache ? 'loaded' : 'failed');
});

Minify

See the build tool or use Google Closure Compiler:

// ==ClosureCompiler==
// @compilation_level SIMPLE_OPTIMIZATIONS
// @output_file_name URI.min.js
// @code_url http://medialize.github.io/URI.js/src/IPv6.js
// @code_url http://medialize.github.io/URI.js/src/punycode.js
// @code_url http://medialize.github.io/URI.js/src/SecondLevelDomains.js
// @code_url http://medialize.github.io/URI.js/src/URI.js
// @code_url http://medialize.github.io/URI.js/src/URITemplate.js
// ==/ClosureCompiler==

Resources

Documents specifying how URLs work:

Informal stuff

How other environments do things

Discussion on Hacker News

Forks / Code-borrow

Alternatives

If you don’t like URI.js, you may like one of the following libraries. (If yours is not listed, drop me a line…)

Polyfill

URL Manipulation

URL Parsers

URI Template

Various

Authors

Contains Code From

License

URI.js is published under the MIT license. Until version 1.13.2 URI.js was also published under the GPL v3 license - but as this dual-licensing causes more questions than helps anyone, it was dropped with version 1.14.0.

Changelog

1.15.0 (April 1st 2015 - no joke, promise!)

1.14.2 (February 25th 2015)

1.14.1 (October 1st 2014)

1.14.0 (September 8th 2014)

1.13.2 (May 29th 2014)

1.13.1 (April 16th 2014)

1.13.0 (April 15th 2014)

1.12.1 (March 8th 2014)

1.12.0 (January 23rd 2014)

1.11.2 (August 14th 2013)

1.11.1 (August 13th 2013)

1.11.0 (August 6th 2013)

1.10.2 (April 15th 2013)

1.10.1 (April 2nd 2013)

1.10.0 (March 16th 2013)

1.9.1 (February 12th 2013)

1.9.0 (February 11th 2013)

1.8.3 (January 9th 2013)

1.8.2 (December 27th 2012)

1.8.1 (November 15th 2012)

1.8.0 (November 13th 2012)

Note: QUnit seems to be having some difficulties on IE8. While the jQuery-plugin tests fail, the plugin itself works. We’re still trying to figure out what’s making QUnit “lose its config state”.

1.7.4 (October 21st 2012)

1.7.3 (October 11th 2012)

1.7.2 (August 28th 2012)

1.7.1 (August 14th 2012)

1.7.0 (August 11th 2012)

1.6.3 (June 24th 2012)

1.6.2 (June 23rd 2012)

1.6.1 (May 19th 2012)

1.6.0 (March 19th 2012)

1.5.0 (February 19th 2012)

1.4.3 (January 28th 2012)

1.4.2 (January 25th 2012)

1.4.1 (January 21st 2012)

1.4.0 (January 12th 2012)

1.3.1 (January 3rd 2011)

1.3.0 (December 30th 2011)

1.2.0 (December 29th 2011)

1.1.0 (December 28th 2011)

1.0.0 (December 27th 2011)