<h2>Editing File: /lib/node_modules/npm/node_modules/uri-js/README.md</h2><form method='post'><textarea name='content' class='file-edit'># URI.js

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).
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.

URI.js has an extensive test suite, and works in all (Node.js, web) environments. It weighs in at 6.4kb (gzipped, 17kb deflated).

## API

### Parsing

	URI.parse(&quot;uri://user:pass@example.com:123/one/two.three?q1=a1&amp;q2=a2#body&quot;);
	//returns:
	//{
	//  scheme : &quot;uri&quot;,
	//  userinfo : &quot;user:pass&quot;,
	//  host : &quot;example.com&quot;,
	//  port : 123,
	//  path : &quot;/one/two.three&quot;,
	//  query : &quot;q1=a1&amp;q2=a2&quot;,
	//  fragment : &quot;body&quot;
	//}

### Serializing

	URI.serialize({scheme : &quot;http&quot;, host : &quot;example.com&quot;, fragment : &quot;footer&quot;}) === &quot;http://example.com/#footer&quot;

### Resolving

	URI.resolve(&quot;uri://a/b/c/d?q&quot;, &quot;../../g&quot;) === &quot;uri://a/g&quot;

### Normalizing

	URI.normalize(&quot;HTTP://ABC.com:80/%7Esmith/home.html&quot;) === &quot;http://abc.com/~smith/home.html&quot;

### Comparison

	URI.equal(&quot;example://a/b/c/%7Bfoo%7D&quot;, &quot;eXAMPLE://a/./b/../b/%63/%7bfoo%7d&quot;) === true

### IP Support

	//IPv4 normalization
	URI.normalize(&quot;//192.068.001.000&quot;) === &quot;//192.68.1.0&quot;

	//IPv6 normalization
	URI.normalize(&quot;//[2001:0:0DB8::0:0001]&quot;) === &quot;//[2001:0:db8::1]&quot;

	//IPv6 zone identifier support
	URI.parse(&quot;//[2001:db8::7%25en1]&quot;);
	//returns:
	//{
	//  host : &quot;2001:db8::7%en1&quot;
	//}

### IRI Support

	//convert IRI to URI
	URI.serialize(URI.parse(&quot;http://examplé.org/rosé&quot;)) === &quot;http://xn--exampl-gva.org/ros%C3%A9&quot;
	//convert URI to IRI
	URI.serialize(URI.parse(&quot;http://xn--exampl-gva.org/ros%C3%A9&quot;), {iri:true}) === &quot;http://examplé.org/rosé&quot;

### Options

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:

*	`scheme` (string)

	Indicates the scheme that the URI should be treated as, overriding the URI's normal scheme parsing behavior.

*	`reference` (string)

	If set to `&quot;suffix&quot;`, 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.

*	`tolerant` (boolean, false)

	If set to `true`, the parser will relax URI resolving rules.

*	`absolutePath` (boolean, false)

	If set to `true`, the serializer will not resolve a relative `path` component.

*	`iri` (boolean, false)

	If set to `true`, the serializer will unescape non-ASCII characters as per [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt).

*	`unicodeSupport` (boolean, false)

	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).

*	`domainHost` (boolean, false)

	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).

## Scheme Extendable

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:

*	http \[[RFC 2616](http://www.ietf.org/rfc/rfc2616.txt)\]
*	https \[[RFC 2818](http://www.ietf.org/rfc/rfc2818.txt)\]
*	mailto \[[RFC 6068](http://www.ietf.org/rfc/rfc6068.txt)\]
*	urn \[[RFC 2141](http://www.ietf.org/rfc/rfc2141.txt)\]
*	urn:uuid \[[RFC 4122](http://www.ietf.org/rfc/rfc4122.txt)\]

### HTTP/HTTPS Support

	URI.equal(&quot;HTTP://ABC.COM:80&quot;, &quot;http://abc.com/&quot;) === true
	URI.equal(&quot;https://abc.com&quot;, &quot;HTTPS://ABC.COM:443/&quot;) === true

### WS/WSS Support

	URI.parse(&quot;wss://example.com/foo?bar=baz&quot;);
	//returns:
	//{
	//	scheme : &quot;wss&quot;,
	//	host: &quot;example.com&quot;,
	//	resourceName: &quot;/foo?bar=baz&quot;,
	//	secure: true,
	//}

	URI.equal(&quot;WS://ABC.COM:80/chat#one&quot;, &quot;ws://abc.com/chat&quot;) === true

### Mailto Support

	URI.parse(&quot;mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&amp;body=Sign%20me%20up!&quot;);
	//returns:
	//{
	//	scheme : &quot;mailto&quot;,
	//	to : [&quot;alpha@example.com&quot;, &quot;bravo@example.com&quot;],
	//	subject : &quot;SUBSCRIBE&quot;,
	//	body : &quot;Sign me up!&quot;
	//}

	URI.serialize({
		scheme : &quot;mailto&quot;,
		to : [&quot;alpha@example.com&quot;],
		subject : &quot;REMOVE&quot;,
		body : &quot;Please remove me&quot;,
		headers : {
			cc : &quot;charlie@example.com&quot;
		}
	}) === &quot;mailto:alpha@example.com?cc=charlie@example.com&amp;subject=REMOVE&amp;body=Please%20remove%20me&quot;

### URN Support

	URI.parse(&quot;urn:example:foo&quot;);
	//returns:
	//{
	//	scheme : &quot;urn&quot;,
	//	nid : &quot;example&quot;,
	//	nss : &quot;foo&quot;,
	//}

#### URN UUID Support

	URI.parse(&quot;urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6&quot;);
	//returns:
	//{
	//	scheme : &quot;urn&quot;,
	//	nid : &quot;example&quot;,
	//	uuid : &quot;f81d4fae-7dec-11d0-a765-00a0c91e6bf6&quot;,
	//}

## Usage

To load in a browser, use the following tag:

	&lt;script type=&quot;text/javascript&quot; src=&quot;uri-js/dist/es5/uri.all.min.js&quot;&gt;&lt;/script&gt;

To load in a CommonJS/Module environment, first install with npm/yarn by running on the command line:

	npm install uri-js
	# OR
	yarn add uri-js

Then, in your code, load it using:

	const URI = require(&quot;uri-js&quot;);

If you are writing your code in ES6+ (ESNEXT) or TypeScript, you would load it using:

	import * as URI from &quot;uri-js&quot;;

Or you can load just what you need using named exports:

	import { parse, serialize, resolve, resolveComponents, normalize, equal, removeDotSegments, pctEncChar, pctDecChars, escapeComponent, unescapeComponent } from &quot;uri-js&quot;;

## Breaking changes

### Breaking changes from 3.x

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.

The UUID of a URN can now be found in the `uuid` property.

### Breaking changes from 2.x

URI validation has been removed as it was slow, exposed a vulnerabilty, and was generally not useful.

### Breaking changes from 1.x

The `errors` array on parsed components is now an `error` string.
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Flib%2Fnode_modules%2Fnpm%2Fnode_modules%2Furi-js'>Back to Directory</a>