README.md
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.2kb (gzipped, 16kb 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 Support
105
106 URI.equal("HTTP://ABC.COM:80", "http://abc.com/") === true
107
108### Mailto Support
109
110 URI.parse("mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&body=Sign%20me%20up!");
111 //returns:
112 //{
113 // scheme : "mailto",
114 // to : ["alpha@example.com", "bravo@example.com"],
115 // subject : "SUBSCRIBE",
116 // body : "Sign me up!"
117 //}
118
119 URI.serialize({
120 scheme : "mailto",
121 to : ["alpha@example.com"],
122 subject : "REMOVE",
123 body : "Please remove me",
124 headers : {
125 cc : "charlie@example.com"
126 }
127 }) === "mailto:alpha@example.com?cc=charlie@example.com&subject=REMOVE&body=Please%20remove%20me"
128
129### URN Support
130
131 URI.parse("urn:example:foo");
132 //returns:
133 //{
134 // scheme : "urn",
135 // nid : "example",
136 // nss : "foo",
137 //}
138
139#### URN UUID Support
140
141 URI.parse("urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6");
142 //returns:
143 //{
144 // scheme : "urn",
145 // nid : "example",
146 // uuid : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
147 //}
148
149## Usage
150
151To load in a browser, use the following tag:
152
153 <script type="text/javascript" src="uri-js/dist/es5/uri.all.min.js"></script>
154
155To load in a CommonJS (Node.js) environment, first install with npm by running on the command line:
156
157 npm install uri-js
158
159Then, in your code, load it using:
160
161 const URI = require("uri-js");
162
163If you are writing your code in ES6+ (ESNEXT) or TypeScript, you would load it using:
164
165 import * as URI from "uri-js";
166
167Or you can load just what you need using named exports:
168
169 import { parse, serialize, resolve, resolveComponents, normalize, equal, removeDotSegments, pctEncChar, pctDecChars, escapeComponent, unescapeComponent } from "uri-js";
170
171## Breaking changes
172
173### Breaking changes from 3.x
174
175URN 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.
176
177The UUID of a URN can now be found in the `uuid` property.
178
179### Breaking changes from 2.x
180
181URI validation has been removed as it was slow, exposed a vulnerabilty, and was generally not useful.
182
183### Breaking changes from 1.x
184
185The `errors` array on parsed components is now an `error` string.
186
187## License ([Simplified BSD](http://en.wikipedia.org/wiki/BSD_licenses#2-clause))
188
189Copyright 2011 Gary Court. All rights reserved.
190
191Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
192
1931. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
194
1952. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
196
197THIS SOFTWARE IS PROVIDED BY GARY COURT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GARY COURT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
198
199The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Gary Court.
200