url-lib

url-lib

A simple, lightweight string utility for Node and browsers that supports serializing and parsing URLs and query strings.

The primary use case is for building string URLs with query parameters for the Fetch API that is polyfilled in the browser via fetch and in Node via node-fetch libraries. isomorphic-fetch combines the two.

url-lib is derived from the Uize.Url module that is a part of the open-source UIZE JavaScript Framework. It is stable, dependency-free, heavily-tested, well-documented, and under 800B when minified & gzipped.

Installation

Install via NPM:

npm install --save url-lib

Use with Node, webpack or browserify:

import * as urllib from 'url-lib'; // ES6+
var urllib = require('url-lib'); // ES5-

As a last resort, you can download dist/url-lib.min.js (or just dist/url-lib-core.min.js) and include it on your web page via a <script> tag. It will create a global window.urllib object (or define the module if you are using RequireJS):

<script src="/lib/url-lib.min.js" type="text/javascript"></script>

Usage

var urllib = require('url-lib');

var url = urllib.formatUrl('http://www.benmvp.com/search?sort=recent&results=20&pg=1', {
    sort: 'popular',        // overwrites existing `sort` param in URL
    category: 'holiday',
    type: 'all',
    results: 100            // overwrites existing `results` param in URL
});

With the above code, url will be 'http://www.benmvp.com/search?sort=popular&results=100&pg=1&category=holiday&type=all'

Check out the docs for more usage examples or try out url-lib in your browser!

API Docs

• formatQuery - Serializes the properties of a params object to produce a URL query string.
• formatUrl - Serializes the specified URL path with properties of a params object to produce a URL.
• getCacheDefeatStr - Returns a string value (generated using the time and a random number) that can be used as a query parameter value to cause a URL to be unique in order to defeat caching.
• parseQuery - Parses query parameters from a string, returning the query parameters as an object.
• parseUrl - Parses the specified URL string into an object containing properties for the various logical segments.

Polyfills needed to support older browsers

url-lib uses a number of ES5 features that are unsupported in older browsers (e.g. IE8-). The easiest way to add support to non-ES5 browsers is to use es5-shim.

Specifically the ES5 features in use are:

• Array.isArray
• Array.prototype.reduce
• Object.keys

Contributing

Contributions are welcome! See CONTRIBUTING.md for more details.

Project philosophy

We take the stability of this utility package very seriously. url-lib follows the SemVer standard for versioning.

All updates must pass the CI build while maintaining 100% code coverage.

License

MIT. Copyright (c) 2016 Ben Ilegbodu.