A lightweight and complete tool written in JavaScript for URL Encoding and Decoding
- Prerequisites
- Installation
- Usage
βΎ Encode a URL
βΎ Decode a URL - Configuration
βΎ URL Validation
βΎ Param Key Validation
βΎ Reserved Chars
βΎ Auto Question Mark
βΎ x-www-form-urlencoded
βΎ RFC 3986 Compatibility
βΎ Reset Configuration
βΎ Debugging - Roadmap
- Contributing
βΎ Testing - License
- Contact
- References & Acknowledgements
There are no dependencies. Library is written in pure JavaScript with pure functions.
npm install @fralis/url-encoder
and then import it with:
const LisURLEncoder = require('@fralis/url-encoder');
or
import LisURLEncoder from '@fralis/url-encoder';
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
.
Importing the library you have the possibility to use the class LisURLEncoder
that's composed only by two static methods: encode
and decode
.
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.
LisURLEncoder.encode(baseURL, queryArray);
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}> |
A new string representing the provided baseURL
and the queryArray
encoded as a URI.
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
The decode()
function decodes a URI previously encoded to a base URL and an array of parameters of the query string.
LisURLEncoder.decode(encodedURL);
Parameter | Description | Type |
---|---|---|
encodedURL |
A previously encoded URL | string |
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}> |
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" },
],
}
*/
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.
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*)?$";
- If
baseURL
does not respect theURL_REGEX
, theencode
method returns an empty string. - If
encodedURL
does not respect theURL_REGEX
, thedecode
method returns anull
object.
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]*$";
- If one of the key in the
queryArray
does not respect thePARAM_KEY_REGEX
, theencode
method returns an empty string.
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 = ["&", "=", "?", "+"];
- If one of the reserved char is present in the
baseURL
specified, theencode
method returns an empty string.
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;
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;
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.
You can reset the configuration to default values using the following function:
LisURLEncoder.reset();
You can display errors specs as console.warn()
by enabling the debug mode:
LisURLEncoder.DEBUGGING = true;
See the open issues for a list of proposed features (and known issues).
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.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Tests can be executed with npm test
. The library uses Mocha.
Distributed under the MIT License. See LICENSE
for more information.
If you like, You can send to me an email.
The library uses the following functions to perform the encoding/decoding.
- Function encodeURI()
- Function encodeURIComponent()
- Function decodeURI()
- Function decodeURIComponent()