qs

What is qs?

The qs package is a query string parsing and stringifying library with some added security. It is often used to parse and stringify query strings, handling complex data structures within query strings.

What are qs's main functionalities?

Parsing query strings

This feature allows you to convert a query string into an object, making it easy to access the values.

const qs = require('qs');
const query = qs.parse('a=c&b=d');
console.log(query); // { a: 'c', b: 'd' }

Stringifying objects

This feature enables you to take an object and convert it into a query string, which can be used in URLs.

const qs = require('qs');
const stringified = qs.stringify({ a: 'c', b: 'd' });
console.log(stringified); // 'a=c&b=d'

Handling arrays and objects

qs can parse and stringify nested objects and arrays, allowing for complex data structures in query strings.

const qs = require('qs');
const query = qs.parse('a[]=b&a[]=c');
console.log(query); // { a: ['b', 'c'] }

Custom parsing options

You can customize the parsing behavior by providing options such as delimiters, allowing for flexibility in the format of query strings.

const qs = require('qs');
const query = qs.parse('a=c&b=d', { delimiter: ';' });
console.log(query); // { 'a=c&b=d': '' }

Other packages similar to qs

query-string

query-string is a robust library for parsing and stringifying URL query strings. It is designed to be simpler than qs and does not support nested objects, but it is tree-shakable and can be used in both Node.js and the browser.

url-search-params

url-search-params is a polyfill for the URLSearchParams API, which is a native web API for handling query strings. It is not as feature-rich as qs, but it provides a standard way for parsing and stringifying query strings in the browser.

README

qs

A querystring parsing and stringifying library with some added security.

Lead Maintainer: Nathan LaFreniere

The qs module was original created and maintained by TJ Holowaychuk.

Usage

var Qs = require('qs');

var obj = Qs.parse('a=c');    // { a: 'c' }
var str = Qs.stringify(obj);  // 'a=c'

Objects

qs allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets []. For example, the string 'foo[bar]=baz' converts to:

{
  foo: {
    bar: 'baz'
  }
}

You can also nest your objects, like 'foo[bar][baz]=foobarbaz':

{
  foo: {
    bar: {
      baz: 'foobarbaz'
    }
  }
}

By default, when nesting objects qs will only parse up to 5 children deep. This means if you attempt to parse a string like 'a[b][c][d][e][f][g][h][i]=j' your resulting object will be:

{
  a: {
    b: {
      c: {
        d: {
          e: {
            f: {
              '[g][h][i]': 'j'
            }
          }
        }
      }
    }
  }
}

This depth can be overridden by passing a depth option to Qs.parse(string, depth):

Qs.parse('a[b][c][d][e][f][g][h][i]=j', 1);
// { a: { b: { '[c][d][e][f][g][h][i]': 'j' } } }

The depth limit mitigate abuse when qs is used to parse user input, and it is recommended to keep it a reasonably small number.

Arrays

qs can also parse arrays using a similar [] notation:

Qs.parse('a[]=b&a[]=c');
// { a: ['b', 'c'] }

You may specify an index as well:

Qs.parse('a[1]=c&a[0]=b');
// { a: ['b', 'c'] }

Note that the only difference between an index in an array and a key in an object is that the value between the brackets must be a number to create an array. When creating arrays with specific indices, qs will compact a sparse array to only the existing values preserving their order:

Qs.parse('a[1]=b&a[15]=c');
// { a: ['b', 'c'] }

qs will also limit specifying indices in an array to a maximum index of 20. Any array members with an index of greater than 20 will instead be converted to an object with the index as the key:

Qs.parse('a[100]=b');
// { a: { '100': 'b' } }

If you mix notations, qs will merge the two items into an object:

Qs.parse('a[0]=b&a[b]=c');
// { a: { '0': 'b', b: 'c' } }

You can also create arrays of objects:

Qs.parse('a[][b]=c');
// { a: [{ b: 'c' }] }

Changelog

1.0.2

• #5 array holes incorrectly copied into object on large index