README.md

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 and well-documented.

Installation

Install via npm:

npm install --save url-lib

Install via Yarn:

yarn add url-lib

Use with Node, webpack or browserify:

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

Usage

import { formatUrl } from 'url-lib'

const url = 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.
• parseQuery - Parses query parameters from a string, returning the query parameters as an object.
• 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.
• parseUrl - Parses the specified URL string into an object containing properties for the various logical segments.

Contributing

Contributions are welcome! See CONTRIBUTING 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.