1# URI.js 2 3URI.js is an [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt) compliant, scheme extendable URI parsing/validating/resolving library for all JavaScript environments (browsers, Node.js, etc). 4It is also compliant with the IRI ([RFC 3987](http://www.ietf.org/rfc/rfc3987.txt)), IDNA ([RFC 5890](http://www.ietf.org/rfc/rfc5890.txt)), IPv6 Address ([RFC 5952](http://www.ietf.org/rfc/rfc5952.txt)), IPv6 Zone Identifier ([RFC 6874](http://www.ietf.org/rfc/rfc6874.txt)) specifications. 5 6URI.js has an extensive test suite, and works in all (Node.js, web) environments. It weighs in at 6.4kb (gzipped, 17kb deflated). 7 8## API 9 10### Parsing 11 12 URI.parse("uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body"); 13 //returns: 14 //{ 15 // scheme : "uri", 16 // userinfo : "user:pass", 17 // host : "example.com", 18 // port : 123, 19 // path : "/one/two.three", 20 // query : "q1=a1&q2=a2", 21 // fragment : "body" 22 //} 23 24### Serializing 25 26 URI.serialize({scheme : "http", host : "example.com", fragment : "footer"}) === "http://example.com/#footer" 27 28### Resolving 29 30 URI.resolve("uri://a/b/c/d?q", "../../g") === "uri://a/g" 31 32### Normalizing 33 34 URI.normalize("HTTP://ABC.com:80/%7Esmith/home.html") === "http://abc.com/~smith/home.html" 35 36### Comparison 37 38 URI.equal("example://a/b/c/%7Bfoo%7D", "eXAMPLE://a/./b/../b/%63/%7bfoo%7d") === true 39 40### IP Support 41 42 //IPv4 normalization 43 URI.normalize("//192.068.001.000") === "//192.68.1.0" 44 45 //IPv6 normalization 46 URI.normalize("//[2001:0:0DB8::0:0001]") === "//[2001:0:db8::1]" 47 48 //IPv6 zone identifier support 49 URI.parse("//[2001:db8::7%25en1]"); 50 //returns: 51 //{ 52 // host : "2001:db8::7%en1" 53 //} 54 55### IRI Support 56 57 //convert IRI to URI 58 URI.serialize(URI.parse("http://examplé.org/rosé")) === "http://xn--exampl-gva.org/ros%C3%A9" 59 //convert URI to IRI 60 URI.serialize(URI.parse("http://xn--exampl-gva.org/ros%C3%A9"), {iri:true}) === "http://examplé.org/rosé" 61 62### Options 63 64All of the above functions can accept an additional options argument that is an object that can contain one or more of the following properties: 65 66* `scheme` (string) 67 68 Indicates the scheme that the URI should be treated as, overriding the URI's normal scheme parsing behavior. 69 70* `reference` (string) 71 72 If set to `"suffix"`, it indicates that the URI is in the suffix format, and the validator will use the option's `scheme` property to determine the URI's scheme. 73 74* `tolerant` (boolean, false) 75 76 If set to `true`, the parser will relax URI resolving rules. 77 78* `absolutePath` (boolean, false) 79 80 If set to `true`, the serializer will not resolve a relative `path` component. 81 82* `iri` (boolean, false) 83 84 If set to `true`, the serializer will unescape non-ASCII characters as per [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt). 85 86* `unicodeSupport` (boolean, false) 87 88 If set to `true`, the parser will unescape non-ASCII characters in the parsed output as per [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt). 89 90* `domainHost` (boolean, false) 91 92 If set to `true`, the library will treat the `host` component as a domain name, and convert IDNs (International Domain Names) as per [RFC 5891](http://www.ietf.org/rfc/rfc5891.txt). 93 94## Scheme Extendable 95 96URI.js supports inserting custom [scheme](http://en.wikipedia.org/wiki/URI_scheme) dependent processing rules. Currently, URI.js has built in support for the following schemes: 97 98* http \[[RFC 2616](http://www.ietf.org/rfc/rfc2616.txt)\] 99* https \[[RFC 2818](http://www.ietf.org/rfc/rfc2818.txt)\] 100* mailto \[[RFC 6068](http://www.ietf.org/rfc/rfc6068.txt)\] 101* urn \[[RFC 2141](http://www.ietf.org/rfc/rfc2141.txt)\] 102* urn:uuid \[[RFC 4122](http://www.ietf.org/rfc/rfc4122.txt)\] 103 104### HTTP/HTTPS Support 105 106 URI.equal("HTTP://ABC.COM:80", "http://abc.com/") === true 107 URI.equal("https://abc.com", "HTTPS://ABC.COM:443/") === true 108 109### WS/WSS Support 110 111 URI.parse("wss://example.com/foo?bar=baz"); 112 //returns: 113 //{ 114 // scheme : "wss", 115 // host: "example.com", 116 // resourceName: "/foo?bar=baz", 117 // secure: true, 118 //} 119 120 URI.equal("WS://ABC.COM:80/chat#one", "ws://abc.com/chat") === true 121 122### Mailto Support 123 124 URI.parse("mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&body=Sign%20me%20up!"); 125 //returns: 126 //{ 127 // scheme : "mailto", 128 // to : ["alpha@example.com", "bravo@example.com"], 129 // subject : "SUBSCRIBE", 130 // body : "Sign me up!" 131 //} 132 133 URI.serialize({ 134 scheme : "mailto", 135 to : ["alpha@example.com"], 136 subject : "REMOVE", 137 body : "Please remove me", 138 headers : { 139 cc : "charlie@example.com" 140 } 141 }) === "mailto:alpha@example.com?cc=charlie@example.com&subject=REMOVE&body=Please%20remove%20me" 142 143### URN Support 144 145 URI.parse("urn:example:foo"); 146 //returns: 147 //{ 148 // scheme : "urn", 149 // nid : "example", 150 // nss : "foo", 151 //} 152 153#### URN UUID Support 154 155 URI.parse("urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"); 156 //returns: 157 //{ 158 // scheme : "urn", 159 // nid : "example", 160 // uuid : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", 161 //} 162 163## Usage 164 165To load in a browser, use the following tag: 166 167 <script type="text/javascript" src="uri-js/dist/es5/uri.all.min.js"></script> 168 169To load in a CommonJS/Module environment, first install with npm/yarn by running on the command line: 170 171 npm install uri-js 172 # OR 173 yarn add uri-js 174 175Then, in your code, load it using: 176 177 const URI = require("uri-js"); 178 179If you are writing your code in ES6+ (ESNEXT) or TypeScript, you would load it using: 180 181 import * as URI from "uri-js"; 182 183Or you can load just what you need using named exports: 184 185 import { parse, serialize, resolve, resolveComponents, normalize, equal, removeDotSegments, pctEncChar, pctDecChars, escapeComponent, unescapeComponent } from "uri-js"; 186 187## Breaking changes 188 189### Breaking changes from 3.x 190 191URN parsing has been completely changed to better align with the specification. Scheme is now always `urn`, but has two new properties: `nid` which contains the Namspace Identifier, and `nss` which contains the Namespace Specific String. The `nss` property will be removed by higher order scheme handlers, such as the UUID URN scheme handler. 192 193The UUID of a URN can now be found in the `uuid` property. 194 195### Breaking changes from 2.x 196 197URI validation has been removed as it was slow, exposed a vulnerabilty, and was generally not useful. 198 199### Breaking changes from 1.x 200 201The `errors` array on parsed components is now an `error` string. 202