Postman URL Encoder Build Status codecov

Postman URL Encoder is a NodeJS module that provides various URL encoding related APIs. This module is created to implement the WHATWG URL specification to remove dependency on Node's URL APIs across Postman systems. These APIs are useful to encode different parts (like hostname, path, query) of URL and convert PostmanUrl object into Node's Url like object.

Installing the Postman URL Encoder

Postman URL Encoder can be installed using NPM or directly from the git repository within your NodeJS projects. If installing from NPM, the following command installs the module and saves in your package.json

> npm install postman-url-encoder --save

Getting Started

Following example snippet shows how to convert PostmanUrl object into Node's Url like object.

var PostmanUrl = require('postman-collection').Url,
    pmEncoder = require('postman-url-encoder'),

// Create PostmanUrl object
myUrl = new PostmanUrl('');

// convert PostmanUrl object to Node's Url like object
myUrl = pmEncoder.toNodeUrl(myUrl));
// {
//   protocol: 'http:',
//   slashes: true,
//   auth: null,
//   host: '',
//   port: null,
//   hostname: '',
//   hash: null,
//   search: '?q1=v1',
//   query: 'q1=v1',
//   pathname: '/p/a/t/h',
//   path: '/p/a/t/h?q1=v1',
//   href: ''
// }

To know more about provided APIs, head over to Postman URL Encoder Docs.


An EncodeSet represents a set of characters that should be percent-encoded.

Different characters need to be encoded in different parts of an URL. For example, a literal ? question mark in an URL’s path would indicate the start of the query string. A question mark meant to be part of the path therefore needs to be percent-encoded. In the query string however, a question mark does not have any special meaning and does not need to be percent-encoded.

A few sets are defined in this module. Use the EncodeSet class to define different ones.


postman-url-encoder/encoder~ encoder/index.js

This module determines which of the reserved characters in the different URL components should be percent-encoded and which can be safely used.

The generic URI syntax consists of a hierarchical sequence of components referred to as the scheme, authority, path, query, and fragment.

 URI         = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

 hier-part   = "//" authority path-abempty
             / path-absolute
             / path-rootless
             / path-empty

 authority   = [ userinfo "@" ] host [ ":" port ]


A percent-encoding mechanism is used to represent a data octet in a component when that octet's corresponding character is outside the allowed set or is being used as a delimiter of, or within, the component. A percent-encoded octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits representing that octet's numeric value.

For example, "%20" is the percent-encoding for the binary octet "00100000" (ABNF: %x20), which in US-ASCII corresponds to the space character (SP).