README.md (7491B)
1 # URI.js 2 3 URI.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). 4 It 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 6 URI.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 64 All 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 96 URI.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 151 To 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 155 To load in a CommonJS (Node.js) environment, first install with npm by running on the command line: 156 157 npm install uri-js 158 159 Then, in your code, load it using: 160 161 const URI = require("uri-js"); 162 163 If you are writing your code in ES6+ (ESNEXT) or TypeScript, you would load it using: 164 165 import * as URI from "uri-js"; 166 167 Or 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 175 URN 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 177 The UUID of a URN can now be found in the `uuid` property. 178 179 ### Breaking changes from 2.x 180 181 URI validation has been removed as it was slow, exposed a vulnerabilty, and was generally not useful. 182 183 ### Breaking changes from 1.x 184 185 The `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 189 Copyright 2011 Gary Court. All rights reserved. 190 191 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 192 193 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 194 195 2. 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 197 THIS 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 199 The 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.