URI Parser for Catberry Framework

 

Installation

``bash
npm install catberry-uri
`

Description

This is well-tested URI parser implementation that has been developed strictly
according to RFC 3986.

It supports percent-encoding for all URI components except scheme and port.
Percent encoding/decoding happens automatically.

It validates scheme and port component values during URI recombination.

It implements relative reference resolution algorithm from
RFC 3986 5.2.

Usage

$3

`javascript
const catberryURI = require('catberry-uri');
const URI = catberryURI.URI;
const uri = new URI('http://user:pass@example.org:3000/some/path?some=value&some2=value&some2=value2&some3#fragment');
console.log(uri);
`

And you will get such object

`javascript
scheme: 'http',
authority:
{ userInfo: { user: 'user', password: 'pass' },
port: '3000',
host: 'example.org' },
path: '/some/path',
query: { values: { some: 'value', some2: [ 'value', 'value2' ], some3: null } },
fragment: 'fragment' }
`
This object is instance of URI constructor, authority field is instance
of Authority, authority.userInfo is instance of UserInfo and query is
instance of Query.

$3


You can safely edit every component of parsed URI and then get URI string back.
When you convert URI object to string scheme and port values are validated and
could throw exception if values are not satisfy /^[a-z]+[a-z\d\+\.-]*$/i and
/^\d+$/ respectively.

To get string representation of all these URI components just use toString()

`javascript
uri.authority.userInfo.toString(); // user:pass
uri.authority.toString(); // user:pass@example.org:3000
uri.query.toString(); // some=value&some2=value
console.log(uri.toString());
// http://user:pass@example.org:3000/some/path?some=value&some2=value&some2=value2&some3#fragment
`

$3


Also, every URI component including URI itself has clone method to create
a cloned URI component for building another URI.

You can create new empty URI like this:
`javascript
const uri = new URI();
uri.scheme = 'http';
// there is a static method in the URI class
uri.authority = URI.createAuthority();
// and also, an instance method
uri.authority.userInfo = uri.createUserInfo();
uri.authority.userInfo.user = 'user';
uri.authority.userInfo.password = 'pass';
uri.authority.host = 'example.org';
uri.authority.port = '3000';
uri.path = '/some/path';
uri.query = uri.createQuery();
uri.query.values = {
some: 'value',
some2: [ 'value', 'value2' ],
some3: null
}
uri.fragment = 'fragment';

console.log(uri.toString());
// http://user:pass@example.org:3000/some/path?some=value&some2=value&some2=value2&some3#fragment
`
All URI components are optional and null by default.
null and undefined values of every component are ignored otherwise any value
will be converted to string.

$3

Also, you can resolve any relative URI using base URI.

`javascript
const uri = new URI('../../../../g');
const baseUri = new URI('http://a/b/c/d;p?q');

const absoluteUri = uri.resolveRelative(baseUri);
console.log(absoluteUri.toString()); // http://a/g
`

$3

`javascript
class URI {

/**
* Creates a new URI authority component.
* @param {string?} Existing string.
* @return {Authority} The authority component.
*/
static createAuthority(string) {}

/**
* Creates a new URI authority component.
* @param {string?} Existing string.
* @return {Authority} The authority component.
*/
createAuthority(string) {}

/**
* Creates a new URI user info component.
* @param {string?} Existing string.
* @return {UserInfo} The user info component.
*/
static createUserInfo(string) {}

/**
* Creates a new URI user info component.
* @param {string?} Existing string.
* @return {UserInfo} The user info component.
*/
createUserInfo(string) {}

/**
* Creates a new URI query component.
* @param {string?} Existing string.
* @return {Query} The query component.
*/
static createQuery(string)}

/**
* Creates a new URI query component.
* @param {string?} Existing string.
* @return {Query} The query component.
*/
createQuery(string) {}

/**
* Creates new instance of URI according to RFC 3986.
* @param {string?} uriString URI string to parse components.
*/
constructor(uriString) {}

/**
* Converts a URI reference that might be relative to a given base URI
* into the reference's target URI.
* https://tools.ietf.org/html/rfc3986#section-5.2
* @param {URI} baseUri Base URI.
* @returns {URI} Resolved URI.
*/
resolveRelative(baseUri) {}

/**
* Clones current URI to a new object.
* @returns {URI} New clone of current object.
*/
clone() {}

/**
* Recomposes URI components to URI string,
* https://tools.ietf.org/html/rfc3986#section-5.3
* @returns {string} URI string.
*/
toString() {}
}
``

Contributing

There are a lot of ways to contribute:

* Give it a star
* Join the Gitter room and leave a feedback or help with answering users' questions
* Submit a bug or a feature request
* Submit a PR

Denis Rechkunov