@zakkudo/query-string

Make working with url query-strings enjoyable.

Why use this?

• Consistancy with simplicity
• The instance acts like a plain-old-object
• JSON.stringify() will serialize it to json like it was a normal object
• Casting to a string will format it to be directly usable in a query Update the properties after initialization and the serialization will reflect the updates
• Complex params are automatically serialized and deserialized from json

Install

# Install using npm
npm install @zakkudo/query-string

# Install using yarn
yarn add @zakkudo/query-string

Examples

Initializing with an object

import QueryString from '@zakkudo/query-string';

const query = new QueryString({
  page: 3,
  title: 'awesomeness',
  complex: {'test': 'value'}
});

String(query) // '?page=3&title=awesomeness&complex=%7B%22test%22%3A%22value%22%7D&'
query.toString() // '?page=3&title=awesomeness&complex=%7B%22test%22%3A%22value%22%7D&'

const url = `http://example${query}` //Automatically serializes correctly

const url = `http://example${query}` //Automatically serializes correctly with changes

Initializing with a URL and making changes dynamically

import QueryString from '@zakkudo/query-string';

const query = new QueryString('http://example?page=3&title=awesomeness');

delete query.page;

String(query) // '?title=awesomeness'
query.toString() // '?title=awesomeness'

Error handling

import QueryString from '@zakkudo/query-string';
import QueryStringError from '@zakkudo/query-string/QueryStringError';

try {
    const query = new QueryString('http://invalid.com/?first=1?second=2')
} catch(e) {
    if (e instanceof QueryStringError) {
        console.error(e.message); // Trying to add duplicate query param when already exists
    } else {
        throw e;
    }
}

API

@zakkudo/query-string~QueryString ⏏

Kind: Exported class

new QueryString([data], [options])

Throws:

• QueryStringError On issues parsing or serializing the configuration

Param	Type	Default	Description
[data]	String | Object | QueryString		Initial data. A url String will be parsed, and Object/QueryString instances will be copied.
[options]	Object		Modifiers for how the query string object is contructed
[options.unsafe]	Boolean	false	Disable url escaping of key/value pairs. Useful for servers that use unsafe characters as delimiters

@zakkudo/query-string/QueryStringError~QueryStringError ⇐ Error ⏏

Error class used by QueryString for raising errors generated during parsing or serialization.

Kind: Exported class

Extends: Error

• ~QueryStringError ⇐ Error
  • new QueryStringError(message, url)
  • .url

new QueryStringError(message, url)

Param	Type	Description
message	String	A message describing the reason for the error.
url	String	The related url fragment when the error was generated

queryStringError.url

The related url fragment when the error was generated

Kind: instance property of QueryStringError