Table of Contents

1. Prerequisites
2. Installation
3. Usage ⇾ Encode a URL ⇾ Decode a URL
4. Configuration ⇾ URL Validation ⇾ Param Key Validation ⇾ Reserved Chars ⇾ Auto Question Mark ⇾ x-www-form-urlencoded ⇾ RFC 3986 Compatibility ⇾ Reset Configuration ⇾ Debugging
5. Roadmap
6. Contributing ⇾ Testing
7. License
8. Contact
9. References & Acknowledgements

Prerequisites

There are no dependencies. Library is written in pure JavaScript with pure functions.

Installation

Installing via npm

npm install @fralis/url-encoder

and then import it with:

const LisURLEncoder = require('@fralis/url-encoder');

or

import LisURLEncoder from '@fralis/url-encoder';

Including a script

You can download the minified version at this link and then include in your html.

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

and then use directly the class LisURLEncoder.

Usage

Importing the library you have the possibility to use the class LisURLEncoder that's composed only by two static methods: encode and decode.

Encode a URL 🠖 encode(baseURL, queryArray)

To encode a URL the best course of action is to separate the base URL from the queryString. In this way we can avoid bad interpretations in the coding phase.

Syntax

LisURLEncoder.encode(baseURL, queryArray);

Parameters

| Parameter | Description | Type | |------------|---------------------------------------------------------------------|-----------------------------| | baseURL | The base URL without the query string | string | | queryArray | An array of objects containing the list of query string parameters | Array<{key:string,value:string}> |

Returns

A new string representing the provided baseURL and the queryArray encoded as a URI.

Example of Use

const baseURL = "https://www.google.com/search";
const queryArray =  [
	{ key: "q", value: "lisandro francesco" }
];
const URL = LisURLEncoder.encode(baseURL, queryArray);
console.log(URL); // > https://www.google.com/search?q=lisandro%20francesco

Decode a URL 🠖 decode(encodedURL)

The decode() function decodes a URI previously encoded to a base URL and an array of parameters of the query string.

Syntax

LisURLEncoder.decode(encodedURL);

Parameters

| Parameter | Description | Type | |------------|---------------------------------------------------------------------|-----------------------------| | encodedURL| A previously encoded URL | string |

Returns

An object containing the following properties:

| Property | Description | Type | |------------|---------------------------------------------------------------------|-----------------------------| | baseURL | The base URL without the query string | string | | queryArray | An array of objects containing the list of query string parameters | Array<{key:string,value:string}> |

Example of Use

const result = LisURLEncoder.decode(
      "https://www.google.com/search?q=lisandro+francesco&oq=lisandro+francesco&aqs=chrome..69i57i60l3j69i65.9413j0j1&sourceid=chrome&ie=UTF-8"
    );
console.log(result);
/*
{
      baseURL: "https://www.google.com/search",
      queryString: [
        { key: "q", value: "lisandro francesco" },
        { key: "oq", value: "lisandro francesco" },
        { key: "aqs", value: "chrome..69i57i60l3j69i65.9413j0j1" },
        { key: "sourceid", value: "chrome" },
        { key: "ie", value: "UTF-8" },
      ],
    }
*/

Configuration

The library allows you to manage some validations on the inputs and certain parameters regarding the encoding. Obviously, you can change all of them to modify the behavior of the library.

URL Validation 🠖 URL_REGEX

By default, encode and decode methods validate respectively the baseURL and the encodedURL specified via the static property LisURLEncoder.URL_REGEX. Its default value is the following:

LisURLEncoder.URL_REGEX =
    "^(?:(?:(?:https?|ftp):)?\\/\\/)(?:\\S+(?::\\S*)?@)?(?:(?!(?:10|127)(?:\\.\\d{1,3}){3})(?!(?:169\\.254|192\\.168)" +
    "(?:\\.\\d{1,3}){2})(?!172\\.(?:1[6-9]|2\\d|3[0-1])(?:\\.\\d{1,3}){2})(?:[1-9]\\d?|1\\d\\d|2[01]\\d|22[0-3])" +
    "(?:\\.(?:1?\\d{1,2}|2[0-4]\\d|25[0-5])){2}(?:\\.(?:[1-9]\\d?|1\\d\\d|2[0-4]\\d|25[0-4]))|(?:(?:[a-z0-9\\u00a1-\\uffff][a-z0-9\\u00a1-\\uffff_-]{0,62}" +
    ")?[a-z0-9\\u00a1-\\uffff]\\.)+(?:[a-z\\u00a1-\\uffff]{2,}\\.?))(?::\\d{2,5})?(?:[/?#]\\S*)?$";

Safe Returns

• If baseURL does not respect the URL_REGEX, the encode method returns an empty string.
• If encodedURL does not respect the URL_REGEX, the decode method returns a null object.

Parameter Key Validation 🠖 PARAM_KEY_REGEX

By default, the encode method validate each key of the queryArray according to the regex specified in LisURLEncoder.PARAM_KEY_REGEX. Its default value is the following:

LisURLEncoder.PARAM_KEY_REGEX = "^[a-zA-Z0-9]*$";

Safe Returns

• If one of the key in the queryArray does not respect the PARAM_KEY_REGEX, the encode method returns an empty string.

Reserved Chars 🠖 RESERVED_CHARS

By default, the encode method checks if the baseURL contains one of the reserved chars specified in LisURLEncoder.RESERVED_CHARS. Its default value is the following:

LisURLEncoder.RESERVED_CHARS = ["&", "=", "?", "+"];

Safe Returns

• If one of the reserved char is present in the baseURL specified, the encode method returns an empty string.

Auto Question Mark 🠖 AUTO_QUESTION_MARK

By default, the encode method add the question mark ? after the baseURL to separate if from the query string. If you want to avoid it you can set the LisURLEncoder.AUTO_QUESTION_MARK to false. Its default value is the following:

LisURLEncoder.AUTO_QUESTION_MARK = true;

x-www-form-urlencoded 🠖 X_WWW_FORM_URLENCODED

By default, spaces in the parameters values are replaced by %20 char. For application/x-www-form-urlencoded, spaces are to be replaced by +. You can set LisURLEncoder.X_WWW_FORM_URLENCODED to true to make this change. Its default value is the following:

LisURLEncoder.X_WWW_FORM_URLENCODED = false;

RFC 3986 Compatibility 🠖 RFC3986

By default, the property LisURLEncoder.RFC3986 is equal to true. Its purpose is to make the encoding more stringent in adhering to RFC 3986 (which reserves !, ', (, ), and *), even though these characters have no formalized URI delimiting uses. You can set it to false to avoid this replacing.

Reset Configuration 🠖 reset()

You can reset the configuration to default values using the following function:

LisURLEncoder.reset();

Debugging 🠖 DEBUGGING

You can display errors specs as console.warn() by enabling the debug mode:

LisURLEncoder.DEBUGGING = true;

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Testing

Tests can be executed with npm test. The library uses Mocha.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

If you like, You can send to me an email.

References & Acknowledgements

The library uses the following functions to perform the encoding/decoding.

• Function encodeURI()
• Function encodeURIComponent()
• Function decodeURI()
• Function decodeURIComponent()