jsuri

What is jsuri?

The jsuri npm package is a lightweight library for working with URIs in JavaScript. It provides a simple API for parsing, manipulating, and building URIs.

What are jsuri's main functionalities?

Parsing URIs

This feature allows you to parse a URI and extract its components such as protocol, host, port, path, query, and fragment.

const Uri = require('jsuri');
const uri = new Uri('http://user:[e-mail]:8080/path?query=string#fragment');
console.log(uri.protocol()); // 'http'
console.log(uri.host()); // 'www.example.com'
console.log(uri.port()); // '8080'
console.log(uri.path()); // '/path'
console.log(uri.query()); // 'query=string'
console.log(uri.fragment()); // 'fragment'

Manipulating URIs

This feature allows you to manipulate different parts of a URI, such as changing the protocol, host, port, path, query parameters, and fragment.

const Uri = require('jsuri');
let uri = new Uri('http://www.example.com');
uri.setProtocol('https');
uri.setHost('example.org');
uri.setPort('3000');
uri.setPath('/newpath');
uri.setQuery('key', 'value');
uri.setFragment('newfragment');
console.log(uri.toString()); // 'https://example.org:3000/newpath?key=value#newfragment'

Building URIs

This feature allows you to build a URI from scratch by setting its components and adding query parameters.

const Uri = require('jsuri');
let uri = new Uri();
uri.setProtocol('https');
uri.setHost('www.example.com');
uri.setPath('/path');
uri.addQueryParam('key1', 'value1');
uri.addQueryParam('key2', 'value2');
console.log(uri.toString()); // 'https://www.example.com/path?key1=value1&key2=value2'

Other packages similar to jsuri

url

The 'url' package is a core Node.js module that provides utilities for URL resolution and parsing. It offers similar functionalities to jsuri but is more integrated into the Node.js ecosystem. It is more suitable for server-side applications.

query-string

The 'query-string' package focuses on parsing and stringifying URL query strings. While it doesn't offer full URI manipulation like jsuri, it excels in handling query parameters and is often used in conjunction with other URL manipulation libraries.

url-parse

The 'url-parse' package is a lightweight URL parser that works in both Node.js and browser environments. It provides similar functionalities to jsuri for parsing and manipulating URLs but is designed to be more lightweight and performant.

README

jsUri

URI parsing and manipulation for node.js and the browser.

Pass any URL into the constructor:

var uri = new Uri('http://user:[e-mail]:81/index.html?q=books#fragment')

Use property methods to get at the various parts:

uri.protocol()    // http
uri.userInfo()    // user:pass
uri.host()        // www.test.com
uri.port()        // 81
uri.path()        // /index.html
uri.query()       // q=books
uri.anchor()      // fragment

Property methods accept an optional value to set:

uri.protocol('https')
uri.toString()    // https://user:[e-mail]:81/index.html?q=books#fragment

uri.host('mydomain.com')
uri.toString()    // https://user:[e-mail]:81/index.html?q=books#fragment

Chainable setter methods help you compose strings:

new Uri()
    .setPath('/archives/1979/')
    .setQuery('?page=1')                   // /archives/1979?page=1

new Uri()
    .setPath('/index.html')
    .setAnchor('content')
    .setHost('www.test.com')
    .setPort(8080)
    .setUserInfo('username:password')
    .setProtocol('https')
    .setQuery('this=that&some=thing')      // https://username:[e-mail]:8080/index.html?this=that&some=thing#content

new Uri('http://www.test.com')
    .setHost('www.yahoo.com')
    .setProtocol('https')                  // https://www.yahoo.com

Query param methods

Returns the first query param value for the key:

new Uri('?cat=1&cat=2&cat=3').getQueryParamValue('cat')             // 1

Returns all query param values for the given key:

new Uri('?cat=1&cat=2&cat=3').getQueryParamValues('cat')            // [1, 2, 3]

Internally, query key/value pairs are stored as a series of two-value arrays in the Query object:

new Uri('?a=b&c=d').query().params                  // [ ['a', 'b'], ['c', 'd']]

Add query param values:

new Uri().addQueryParam('q', 'books')               // ?q=books

new Uri('http://www.github.com')
    .addQueryParam('testing', '123')
    .addQueryParam('one', 1)                        // http://www.github.com/?testing=123&one=1

// insert param at index 0
new Uri('?b=2&c=3&d=4').addQueryParam('a', '1', 0)  // ?a=1&b=2&c=3&d=4

Replace every query string parameter named key with newVal:

new Uri().replaceQueryParam('page', 2)     // ?page=2

new Uri('?a=1&b=2&c=3')
    .replaceQueryParam('a', 'eh')          // ?a=eh&b=2&c=3

new Uri('?a=1&b=2&c=3&c=4&c=5&c=6')
    .replaceQueryParam('c', 'five', '5')   // ?a=1&b=2&c=3&c=4&c=five&c=6

Removes instances of query parameters named key:

new Uri('?a=1&b=2&c=3')
    .deleteQueryParam('a')                 // ?b=2&c=3

new Uri('test.com?a=1&b=2&c=3&a=eh')
    .deleteQueryParam('a', 'eh')           // test.com/?a=1&b=2&c=3

Create an identical URI object with no shared state:

var baseUri = new Uri('http://localhost/')

baseUri.clone().setProtocol('https')   // https://localhost/
baseUri                                // http://localhost/

This project incorporates the parseUri regular expression by Steven Levithan.