README.md

proper-url-join

Like path.join but for a URL.

Installation

$ npm install proper-url-join

This library expects the host environment to be up-to-date or polyfilled with core-js or similar.

This library is written in ES9 and is using ES modules. You must compile the source code to support older browsers.

Motivation

There are a lot of packages that attempt to provide this functionality but they all have issues.
This package exists with the hope to do it right:

• Consistent behavior
• Support adding/removing leading and trailing slashes
• Supports absolute URLs, e.g.: http//google.com
• Supports protocol relative URLs, e.g.: //google.com
• Supports query strings

Usage

import urlJoin from 'proper-url-join';

urlJoin('foo', 'bar'); // /foo/bar
urlJoin('/foo/', '/bar/'); // /foo/bar
urlJoin('foo', '', 'bar'); // /foo/bar
urlJoin('foo', undefined, 'bar'); // /foo/bar
urlJoin('foo', null, 'bar'); // /foo/bar

// With leading & trailing slash options
urlJoin('foo', 'bar', { leadingSlash: false }); // foo/bar
urlJoin('foo', 'bar', { trailingSlash: true }); // /foo/bar/
urlJoin('foo', 'bar', { leadingSlash: false, trailingSlash: true }); // foo/bar/

// Absolute URLs
urlJoin('http://google.com', 'foo'); // http://google.com/foo

// Protocol relative URLs
urlJoin('//google.com', 'foo', { protocolRelative: true }); // //google.com/foo

// With query string as an url part
urlJoin('foo', 'bar?queryString'); // /foo/bar?queryString
urlJoin('foo', 'bar?queryString', { trailingSlash: true }); // /foo/bar/?queryString

// With query string as an object
urlJoin('foo', { query: { biz: 'buz', foo: 'bar' } }); // /foo?biz=buz&foo=bar

// With both query string as an url part and an object
urlJoin('foo', 'bar?queryString', { query: { biz: 'buz', foo: 'bar' } }); // /foo/bar?biz=buz&foo=bar&queryString

options

leadingSlash

Type: boolean / string
Default: true

Adds or removes leading /. You may pass keep to preserve what the leading slash only if it's present on the input.

trailingSlash

Type: boolean / string
Default: false

Adds or removes trailing /. You may pass keep to preserve what the trailing slash only if it's present on the input.

protocolRelative

Type: boolean
Default: false

Enables support for protocol relative URLs

query

Type: object

Query string object that will be properly stringified and appended to the url. It will be merged with the query string in the url, if it exists.

queryOptions

Type: object

Options to be considered when stringifying the query

Tests

$ npm test
$ npm test -- --watch during development

License

MIT License