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 and query string manipulation in javascript.

This project incorporates the excellent parseUri regular expression library by Steven Levithan. You can safely parse URLs of all shapes and sizes, however invalid or hideous.

Usage

Pass anything that your browser would recognize as a url to the new Uri() constructor

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

and then use the following accessor 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

The accessor methods accept an optional value for setting the property

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

Fluent Setters

The fluent interface provides a simple way to chain property assignment

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

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

Query Parameter Access and Manipulation

Special methods are available for fetching, building and modifying query string parameters. An emhpasis is placed on query string integrity; duplicate parameter names and values are preserved. Parameter ordering is preserved when possible. URI Components are decoded for comparision, but are otherwise left in their original state.

Getting query param values by name

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]

Getting all query param keys and values

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']]

Adding 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

Replacing query param values

Replaces every query string parameter named key with a single instance with the value newVal. If oldValue is supplied, only parameters valued oldVal will be replaced.

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

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

Deleting query param values

Removes instances of query parameters named key. If value is passed, only params named key and valued value will be deleted.

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

Object Cloning

Duplication (via .clone()) is an easy way to inflate an identical uri object, which you can muck around with as much as you like without destroying the original.

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

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

Testing

There is a comprensive set of unit tests written in jasmine. To run them, simply open testrunner.html from the root of the project in a browser.

License

Copyright (c) 2012 Derek Watson Copyright (c) 2007 Steven Levithan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.