simple-query-string

Fast and simple way to parse and stringify URL query strings.

Utility javascript methods to encode and decode query string parameters with extreme performance and low memory usage.

---

Installation

NPM

$ npm install simple-query-string --save

Bower

$ bower install simple-query-string

Download

• simplequerystring.js - development

• simplequerystring.min.js - production

Browser - CDN

<script src="https://cdn.rawgit.com/khalidsalomao/simple-query-string/22cc5bbe/src/simplequerystring.min.js"></script>

---

Features

Query String Decoding

• fast

  Several benchmarks are run at each release to ensure maximum performance.

• query string parsing

  simpleQueryString.parse("key=val&param=1")

• url with query string detection

  There is no need to use url.split('?')[1] or any other code, just put the entire string!

  simpleQueryString.parse("http://example.org/test/?key=val&param=1")

• location.hash support

  simpleQueryString.parse(location.hash)

• location.search support

  simpleQueryString.parse(location.search)

• array detection

  simpleQueryString.parse("myarr=1&myarr=2&myarr=3&myarr=4") // myarr: [1,2,3,4]

• anchor detection

  simpleQueryString.parse("http://example.org/test/?key=val&param=1#anchor") // #anchor will be ignored

• node.js module

  var qs = require('simple-query-string');
  
  var parsed = qs.parse("key=val&param=1");
  
  console.log(parsed["key"]);
  console.log(parsed["param"]);

• browser

  <script src="https://cdn.rawgit.com/khalidsalomao/simple-query-string/22cc5bbe/src/simplequerystring.min.js"></script>
  <script>
      var parsed = simpleQueryString.parse('key=val&param=1');
  
      console.log(parsed["key"]);
  </script>

• AMD module

  require(['simple-query-string'], function(qs){
      var p = qs.parse('key=val&param=1');
      console.log(p);
  });

• for..in safe

  Safe to be used in a for in loop. The object is created with Object.create(null).

  var dic = simpleQueryString.parse("http://example.org/?p1=val&p2=true&p3=3&p4=str");
  for (var k in dic) {
      console.log(dic[k]);
  }

• safely deals with invalid/empty input

  simpleQueryString.parse(null) // equals to {}

• Custom delimiter

  In some cases, you may want to use another separator instead of ampersand. Example using semicolon (';') as separator:

  simpleQueryString.parse('p1=a;p2=1', ';') // equals to '{ p1:'a', p2: 1}'

Query String Encoding

• fast

  Several benchmarks are run at each release to ensure maximum performance.

• properties detection

  simpleQueryString.stringify({ key: "val", param: 1 })
  //=> 'key=val&param=1'

• type detection

  simpleQueryString.stringify({ p: 1, p2: true, p3: false }) // equals to 'p=1&p2=true&p3=false'

• array encoding

  simpleQueryString.stringify({ myarr: [1,2,3,4] }) // equals to 'myarr=1&myarr=2&myarr=3&myarr=4'

• node.js module

  var qs = require('simple-query-string');
  
  var str = qs.stringify({ param: 1, p2: true, p3: false });
  
  console.log(str); // equals to 'param=1&p2=true&p3=false'

• browser

  <script src="https://cdn.rawgit.com/khalidsalomao/simple-query-string/22cc5bbe/src/simplequerystring.min.js"></script>
  <script>
      var str = simpleQueryString.stringify({ param: 1, p2: true, p3: false });
  
      console.log(str);
  </script>

• AMD module

  require(['simple-query-string'], function(qs){
      var str = qs.stringify({ param: 1, p2: true, p3: false });
      console.log(str);
  });

• safely ignore functions and prototype properties

  simpleQueryString.stringify({ p1: function(){ return 0; }, p2: 1 }) // equals to 'p2=1'

• safely deals with invalid/empty input

  simpleQueryString.stringify(null) // equals to ''

• Custom delimiter

  In some cases, you may want to use another separator instead of ampersand. Example using semicolon (';') as separator:

  simpleQueryString.stringify({ p1: 'a', p2: 1 }, ';') // equals to 'p1=a;p2=1'

---

Getting Started

Decode example:

var obj = simpleQueryString.parse("http://example.org/test/?key=val&param=1");

// obj["key"] === "val"

// obj["param"] === "1"

Encode example:

var p = {
    key1: true,
    key2: [0, 1, 2],
    key3: "string",
    key4: 4321
};

var qStr = simpleQueryString.stringify(p);

---

How to Test

Node.js

Install dependencies

$ npm install mocha -g

Run tests in node.js

Use npm to run the test script 'spec/simplequerystring-test.js'

$ npm test

Run tests in any browser

Run the tests by opening ./spec/testpage.html.

---

Query string references

Some documentation for future reference.

Wikipedia on Query string structure

• The query string is composed of a series of field-value pairs.
• Within each pair, the field name and value are separated by an equals sign, '='.
• The series of pairs is separated by the ampersand, '&' (or semicolon, ';' for URLs embedded in HTML and not generated by a <form>...</form>; see below).

W3C semicolon recommendation

W3C - Ampersands in URI attribute values

We recommend that HTTP server implementors, and in particular, CGI implementors support the use of ";" in place of "&" to save authors the trouble of escaping "&" characters in this manner.

RFC 3986 on Query component

RFC 3986

Some relevant parts of the documentation for future reference.

https://tools.ietf.org/html/rfc3986#section-3.4

The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") character or by the end of the URI

https://tools.ietf.org/html/rfc3986#section-4.2

relative-ref = relative-part [ "?" query ] [ "#" fragment ]

---

License

MIT © 2016 Khalid Salomão