fluent-url v1.2.0

fluent-url

A chainable version of the global URL class

Installation

npm install fluent-url

Goals

A simple class that uses URL and URLSearchParams built-ins in a fluent (chainable) manner.

Example Usage

import url from 'fluent-url';

// simple construction with query string
const endpoint = url('https://api.example.com/search', { term: 'Foo' });
endpoint.href();
// => "https://api.example.com/search?term=Foo"

// chainable example
const endpoint = url('https://api.example.com/search?term=Foo');
endpoint
	.port('8080')
	.search({
		b: 'two',
		a: 'one',
	})
	.sort()
	.path('/login')
	.hash('#username')
	.href();
// => "https://api.example.com:8080/login?a=one&b=two#username"

// extend search query instead of overwriting it
const endpoint = url('https://api.example.com/search?term=Foo');
endpoint.qsExtend({
	limit: 10,
	sort: 'created_at',
});
endpoint.href();
// => "https://api.example.com/search?term=Foo&limit=10&sort=created_at"

// manipulate relative URLs
url('/search?term=Foo').qsAppend('limit', 10).href();
// => "/search?term=Foo&limit=10"

Instantiating

FluentURL can be instantiated using multiple signatures:

url(myUrl); // myUrl may be string or instance of URL
url(myUrl, searchParams); // searchParams is a plain object or instance of URLSearchParams
url(relative, base); // relative is the path and base is a string with protocol, port, domain
url(relative, base, searchParams); // searchParams is a string, plain object or instance of URLSearchParams

URL Built-in Methods

Custom Methods

Query String Methods

Wait, what is FluentURLSearchParams? It is a class used internally for all the qs* methods. Its methods are named without the qs such as append(), clear(), delete(), etc. If you would like to use it directly, it is exported by name so it can be used like this:

import url, { FluentURLSearchParams } from 'fluent-url';
const FluentURLSearchParams = require('fluent-url').FluentUrlSearchParams;

Properties

Hash routing URLs

fluent-url supports manipulating URLs that have hash routing:

import url from 'fluent-url';

// simple construction with query string
const controller = url('https://example.com/home#/dashboard?msg=Hello');
controller.hashPath(); // "/dashboard"
controller.hashSearch(); // { msg: "Hello" }

controller
	.hashPath('/projects')
	.hashSearch({ query: 'new construction', sort: '-created' })
	.href(); // https://example.com/home#/projects?query=new+construction&sort=-created

Unit Tests and Code Coverage

Powered by jest

npm test
npm run coverage

Contributing

Contributions are welcome. Please open a GitHub ticket for bugs or feature requests. Please make a pull request for any fixes or new code you'd like to be incorporated.

License

Open Source under the ISC License.