medialize/URI.jsPublic

NotificationsYou must be signed in to change notification settings
Fork475
Star6.3k

Javascript URL mutation library

License

MIT license

6.3k stars 475 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 689 Commits
prettify		prettify
src		src
test		test
utils		utils
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE.txt		LICENSE.txt
README.md		README.md
SECURITY.md		SECURITY.md
about-uris.html		about-uris.html
bower.json		bower.json
build.html		build.html
build.js		build.js
composer.json		composer.json
contributing.md		contributing.md
docs.html		docs.html
index.html		index.html
jquery-1.12.4.min.js		jquery-1.12.4.min.js
jquery-2.2.4.min.js		jquery-2.2.4.min.js
jquery-3.6.0.min.js		jquery-3.6.0.min.js
jquery-uri-plugin.html		jquery-uri-plugin.html
package.json		package.json
screen.css		screen.css
screen.js		screen.js
uri-template.html		uri-template.html

Repository files navigation

URI.js

IMPORTANT: Youmay not need URI.js anymore! Modern browsers provide theURL andURLSearchParams interfaces.

NOTE: The npm package name changed tourijs

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

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

Things are looking up withURL and theURL spec but until we can safely rely on that API, have a look at URI.js for a clean and simple API for mutating URIs:

varurl=newURI("http://example.org/foo?bar=baz");url.addQuery("foo","bar");

URI.js is here to help with that.

API Example

// mutating URLsURI("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 upURI("?&foo=bar&&foo=bar&foo=baz&").normalizeQuery();// -> ?foo=bar&foo=baz// working with relative pathsURI("/foo/bar/baz.html").relativeTo("/foo/bar/world.html");// -> ./baz.htmlURI("/foo/bar/baz.html").relativeTo("/foo/bar/sub/world.html")// -> ../baz.html.absoluteTo("/foo/bar/sub/world.html");// -> /foo/bar/baz.html// URI TemplatesURI.expand("/foo/{dir}/{file}",{dir:"bar",file:"world.html"});// -> /foo/bar/world.html

See theAbout Page andAPI 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 youneed 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 alternativeslisted below.

URI.js is available throughnpm,bower,bowercdn,cdnjs and manually from thebuild page:

# using bowerbower install uri.js# using npmnpm install urijs

Browser

I guess you'll manage to use thebuild tool or follow theinstructions 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 withnpm install urijs or add"urijs" to the dependencies in yourpackage.json.

// load URI.jsvarURI=require('urijs');// load an optional module (e.g. URITemplate)varURITemplate=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 thebuild tool or useGoogle 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

node-dom-urls passy's partial implementation of the W3C URL Spec Draft for Node
urlutils cofounders'window.URL constructor for Node

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

DOM-URL-Polyfill arv's polyfill of theDOM URL spec for browsers
inexorabletash inexorabletash'sWHATWG URL API

URL Manipulation

The simple URL Mutation "Hack" (jsPerf comparison)
URL.js
furl (Python)
mediawiki Uri (needs mw and jQuery)
jurlp
jsUri
URL Toolkit Build an absolute URL from a base URL and a relative URL (RFC 1808)

URL Parsers

The simple URL Mutation "Hack" (jsPerf comparison)
URI Parser
jQuery-URL-Parser
Google Closure Uri
URI.js by Gary Court

URI Template

uri-template (supporting extraction as well) by Rezigne
uri-templates (supporting extraction as well) by Geraint Luff
uri-templates by Marc Portier
uri-templates by Geraint Luff (including reverse operation)
URI Template JS by Franz Antesberger
Temple by Brett Stimmerman
(jsperf comparison)

Various

TLD.js - second level domain names
Public Suffix - second level domain names
uri-collection - underscore based utility for working with many URIs

Authors

Contains Code From

punycode.js - Mathias Bynens
IPv6.js - Rich Brown - (rewrite of the original)

License

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