source: trip-planner-front/node_modules/uri-js/README.md@ 8d391a1

Last change on this file since 8d391a1 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit
  • Property mode set to 100644
File size: 6.3 KB
Line 
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* ws \[[RFC 6455](http://www.ietf.org/rfc/rfc6455.txt)\]
101* wss \[[RFC 6455](http://www.ietf.org/rfc/rfc6455.txt)\]
102* mailto \[[RFC 6068](http://www.ietf.org/rfc/rfc6068.txt)\]
103* urn \[[RFC 2141](http://www.ietf.org/rfc/rfc2141.txt)\]
104* urn:uuid \[[RFC 4122](http://www.ietf.org/rfc/rfc4122.txt)\]
105
106### HTTP/HTTPS Support
107
108 URI.equal("HTTP://ABC.COM:80", "http://abc.com/") === true
109 URI.equal("https://abc.com", "HTTPS://ABC.COM:443/") === true
110
111### WS/WSS Support
112
113 URI.parse("wss://example.com/foo?bar=baz");
114 //returns:
115 //{
116 // scheme : "wss",
117 // host: "example.com",
118 // resourceName: "/foo?bar=baz",
119 // secure: true,
120 //}
121
122 URI.equal("WS://ABC.COM:80/chat#one", "ws://abc.com/chat") === true
123
124### Mailto Support
125
126 URI.parse("mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&body=Sign%20me%20up!");
127 //returns:
128 //{
129 // scheme : "mailto",
130 // to : ["alpha@example.com", "bravo@example.com"],
131 // subject : "SUBSCRIBE",
132 // body : "Sign me up!"
133 //}
134
135 URI.serialize({
136 scheme : "mailto",
137 to : ["alpha@example.com"],
138 subject : "REMOVE",
139 body : "Please remove me",
140 headers : {
141 cc : "charlie@example.com"
142 }
143 }) === "mailto:alpha@example.com?cc=charlie@example.com&subject=REMOVE&body=Please%20remove%20me"
144
145### URN Support
146
147 URI.parse("urn:example:foo");
148 //returns:
149 //{
150 // scheme : "urn",
151 // nid : "example",
152 // nss : "foo",
153 //}
154
155#### URN UUID Support
156
157 URI.parse("urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6");
158 //returns:
159 //{
160 // scheme : "urn",
161 // nid : "uuid",
162 // uuid : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
163 //}
164
165## Usage
166
167To load in a browser, use the following tag:
168
169 <script type="text/javascript" src="uri-js/dist/es5/uri.all.min.js"></script>
170
171To load in a CommonJS/Module environment, first install with npm/yarn by running on the command line:
172
173 npm install uri-js
174 # OR
175 yarn add uri-js
176
177Then, in your code, load it using:
178
179 const URI = require("uri-js");
180
181If you are writing your code in ES6+ (ESNEXT) or TypeScript, you would load it using:
182
183 import * as URI from "uri-js";
184
185Or you can load just what you need using named exports:
186
187 import { parse, serialize, resolve, resolveComponents, normalize, equal, removeDotSegments, pctEncChar, pctDecChars, escapeComponent, unescapeComponent } from "uri-js";
188
189## Breaking changes
190
191### Breaking changes from 3.x
192
193URN 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.
194
195The UUID of a URN can now be found in the `uuid` property.
196
197### Breaking changes from 2.x
198
199URI validation has been removed as it was slow, exposed a vulnerabilty, and was generally not useful.
200
201### Breaking changes from 1.x
202
203The `errors` array on parsed components is now an `error` string.
Note: See TracBrowser for help on using the repository browser.