README

Url-Builder

A lightweight library with many features to easy build URLs

Features
Installation
Usage
Advanced
API
Licence
Authors
Contributors

:bookmark_tabs: Features

This library allows :

Create URLs most easly
Parse and decompose your URLs
Ride up in the URL tree
Make comparisons between URLs

:hammer_and_wrench: Installation

To import the library you just need to run this command :

npm install @innova2/url-builder

:memo: Usage

Create from existing URL

const url = UrlBuilder.createFromUrl('http://localhost:8080/users');
// or create new url with the constructor

Handle path

Add new path segment(s)

const userId = '170b16cd-ad47-4c9c-86cf-7c83bd40d775';
url.addPath(':id/comments').addParam('id', userId);
// Or
url.addPath(':id/comments', { id: userId });

Add multiples parameters

const userId = '170b16cd-ad47-4c9c-86cf-7c83bd40d775';
const commentId = '218dd1c4-0bb0-425a-be0b-85427304e100';
url.addPath(':userId/comments/:commentId').addParams({ userId, commentId });
// Or
url.addPath(':userId/comments/:commentId', { userId, commentId });

Get the first path segment

const rowNum = 10;
const url = UrlBuilder.createFromUrl('http://localhost:8080/rows/:rowNum/cells').addParam('rowNum', rowNum);
url.getFirstPath(); // Output: 'rows'

Get the last path segment

url.getLastPath(); // Output: 'cells'

Handle query param

Add new query param

const page = 2;
url.addQuery('page', page);

Add multiples query params

const page = 2;
const order = 'DESC';
url.addQueries({ page, order });

Merge path and query params

It's possible to merge path and query params with another url

const url = UrlBuilder.createFromUrl('http://localhost:3000').addPath('groups');

const anotherUrl = new UrlBuilder()
    .addPath(':id/users', { id: 2 })
    .addQuery('page', 1)

url.mergePathWith(anotherUrl).toString() // Get 'http://localhost:3000/groups/2/users?page=1'

Note : This function merge only path, params and query params with current url.

Work with parent

Get parent URL easly.
This function return a new instance of UrlBuilder

const url = UrlBuilder.createFromUrl('http://localhost:8080/orders/:orderId/products/:productId');
const parent = url.getParent(); // Get 'http://localhost:8080/orders/:orderId/products'

Or up to the specific level

url.getParent(3); // Get 'http://localhost:8080/orders'

Get relative path

Retrieve the relative path in string format

const postId = 'a937b39e-9664-404a-ac56-f3da2b83a951';
const url = UrlBuilder.createFromUrl('http://localhost:8080/posts/:id').addParam('id', postId);
url.getRelativePath(); // Output: '/posts/a937b39e-9664-404a-ac56-f3da2b83a951'

And with query params
Don't forget to add 'true' parameter to allow query params conversion

url.addQuery('displaySimilar', true);
url.getRelativePath(); // Output: '/posts/a937b39e-9664-404a-ac56-f3da2b83a951'
url.getRelativePath(true); // Output: '/posts/a937b39e-9664-404a-ac56-f3da2b83a951?displaySimilar=true'

Get query params in string

Retrieve the query params in string format

const url = UrlBuilder.createFromUrl('http://localhost:8080/vehicles').addQueries({
  page: 2,
  order: 'ASC',
});
url.getQueryString(); // Output: '?page=2&order=ASC'

Convert full URL to string

Retrieve the query params in string format

const name = 'url-builder';
const url = UrlBuilder.createFromUrl('https://github.com/InnovA2')
        .addPath(':name/pulls')
        .addParam('name', name);
url.toString(); // Output: 'https://github.com/InnovA2/url-builder/pulls'

:memo: Advanced

Compare URL to another

Compare the current URL to another URL (UrlBuilder instance)

const id = '434f65eb-4e5f-4b29-899c-b3e159fff61c';
const id2 = '3e972ca2-b422-4ac9-b793-e6f305c7bfb2';
const url = UrlBuilder.createFromUrl('http://localhost:8080/users/:id').addParam('id', id);
const url2 = UrlBuilder.createFromUrl('http://localhost:8080/users/:id').addParam('id', id);
const url3 = UrlBuilder.createFromUrl('http://localhost:8080/users/:id').addParam('id', id2);
url.compareTo(url2); // Output: true
url.compareTo(url3); // Output: false

Get word between two others

Compare the current URL to another URL (UrlBuilder instance)

const url = UrlBuilder.createFromUrl('http://localhost:8080/users/10/comments');
url.getBetween2Words('users', 'comments'); // Output: 10

Split path from string (static)

Split path string by slash

UrlBuilder.splitPath('/InnovA2/url-builder/pulls/'); // Output: ['InnovA2', 'url-builder', 'pulls']
// or if you have more slashes
UrlBuilder.splitPath('/InnovA2///url-builder/pulls/'); // Output: ['InnovA2', 'url-builder', 'pulls']

Trim path from string (static)

Trim path string by removing useless slashes

UrlBuilder.trimPath('/InnovA2/url-builder/pulls/'); // Output: 'InnovA2/url-builder/pulls'
// or if you have more slashes
UrlBuilder.trimPath('/InnovA2///url-builder/pulls/'); // Output: 'InnovA2/url-builder/pulls'

:gear: API

static createFromUrl(baseUrl: string): UrlBuilder
static splitPath(path: string): string[]
static trimPath(path: string): string
compareTo(url: UrlBuilder, relative = true): boolean
getScheme(): Scheme
setScheme(scheme: Scheme): UrlBuilder
getHost(): string
setHost(host: string): UrlBuilder
getPort(): numbe
setPort(port: number): UrlBuilder
getPathSegments(): string[]
setPathSegments(segments: string[], params: Record<string, string | number>): UrlBuilder
addPath(path: string, params: Record<string, string | number>): UrlBuilder
getParams(): Map<string, string | number>
setParams(params: Map<string, string | number>): UrlBuilder
addParam(key: string, value: string | number): UrlBuilder
addParams(params: Record<string, string | number>): UrlBuilder
getParams(): Map<string, string | number>
getQuery(): Map<string, string | number>
setQuery(query: Map<string, string | number>): UrlBuilder
addQuery(key: string, value: string | number): UrlBuilder
addQueries(queries: Record<string, string | number>): UrlBuilder
getQuery(): Map<string, string | number>
mergePathWith(url: UrlBuilder): UrlBuilder
getFirstPath(): string
getLastPath(): string
getParent(n = 1): UrlBuilder
getBetween2Words(a: string, b: string): string
getRelativePath(query = false): string
getQueryString(): string
toString(): string

Note : Only the non-static getParent() method return new instance of UrlBuilder. Others return the current instance.

:balance_scale: Licence

MIT

:busts_in_silhouette: Authors

:handshake: Contributors

Do not hesitate to participate in the project! Contributors list will be displayed below.

Usage no npm install needed!