UrlBuilder

branch	build	coverage
main
develop

Utility to help building http urls for your API.

Installing

npm install http-url-builder

To install the latest version with security updates applied use @dev tag when installing:

npm install http-url-builder@dev

Examples

Importing the library:

// old CommonJS syntax
const UrlBuilder = require('http-url-builder').UrlBuilder;
// new ES6 syntax
import { UrlBuilder } from 'http-url-builder';

Basic setup:

const url = UrlBuilder.create('localhost', 8080).build();

console.log(url);
// https://localhost:8080

Build an url:

// 'false' uses 'http' instead of 'https'
const url = UrlBuilder.create('localhost', 8080/*, false*/)
    .addPath('foo')
    .addPathVariable('John Doe')
    .addPath('bar')
    .addQueryParam('baz', 'qux')
    .addQueryParam('test', 123)
    .build();

console.log(url);
// https://localhost:8080/foo/John Doe/bar?baz=qux&test=123

addPath() does not allow spaces in the url and automatically trims the path value to prevent errors.

addPathVariable() instead allows to insert spaces since query params do not need to follow the strict rules applied to paths. Moreover, / characters will be replaced with %2F.

const url = UrlBuilder.create('localhost', 8080)
    .addPath('example')
    // 'true' will trim the path variable as it happens with .addPath()
    .addPathVariable(' John/Doe '/*, true*/)
    .addPath('operation')
    .build();

console.log(url);
// https://localhost:8080/example/ John%2FDoe /operation

addQueryParam() accepts strings, numbers, booleans and objects. Objects will be converted to their JSON representation to create the url.

const obj = {
    foo: 'bar',
    baz: 0,
    qux: true,
};
const url = UrlBuilder.create('localhost', 8080)
    .addPath('example')
    .addQueryParam('myObj', obj)
    .build();

console.log(url);
// https://localhost:8080/example?myObj={"foo":"bar","baz":0,"qux":true}

Each addPath(), addPathVariable() and addQueryParam() operation creates a new UrlBuilder instance. Thanks to immutability, paths can not be accidentally modified:

const base = UrlBuilder.create('localhost', 8080).addPath('base');

const fooUrl = base.addPath('foo');
const barUrl = base.addPath('bar');

console.log(base.build());   // https://localhost:8080/base
console.log(fooUrl.build()); // https://localhost:8080/base/foo
console.log(barUrl.build()); // https://localhost:8080/base/bar

If you already have an url, you can convert it to an UrlBuilder instance by using its constructor:

const url = new UrlBuilder("https://localhost:8080/my/path");

License

MIT

gturi/url-builder

UrlBuilder

Installing

Examples

License