Tiny Query String

A tiny (2kb minified) JS library for reading & writing URL query strings.

Installation

NPM:

npm install tiny-query-string --save

Bower:

bower install tiny-query-string --save

Usage examples

const tinyQS = require('tiny-query-string');

tinyQS.get('foo', 'example.com?foo=bar&baz'); // 'bar'
tinyQS.get(['foo', 'baz'], 'example.com?foo=bar&baz'); // {'foo':'bar', 'baz':true}
tinyQS.get('example.com?foo=bar&baz', false); // {'foo':'bar', 'baz':true}

tinyQS.set('foo', 'bar', 'example.com?baz'); // 'example.com?baz&foo=bar'
tinyQS.set(['foo', 'bar'], 'example.com?baz'); // 'example.com?baz&foo&bar'
tinyQS.set({'foo':123, 'bar':'qux'}, 'example.com?baz'); // 'example.com?baz&foo=123&bar=qux'

tinyQS.remove('foo', 'example.com?foo=bar&baz'); // 'example.com?bar'
tinyQS.remove(['foo', 'bar'], 'example.com?foo&bar&baz'); // 'example.com?baz'
tinyQS.remove('example.com?foo=bar&baz', false); // 'example.com'

Documentation

Note: The text argument always defaults to window.location.search if left unspecified, or '' if window does not exist.

.get()

Alias for the .getOne(), .getMany() and .getAll() methods:

.getOne( name [, text] )

Parse a URL to match a single key name, and return the corresponding value as a string or Boolean.

• name (string): The key to search for.
• text (string) [optional]: The URL text to search in.

tinyQS.getOne('foo', 'example.com?foo=bar'); // 'bar'
tinyQS.getOne('foo', 'example.com?foo'); // true

.getMany( names [, text] )

Parse a URL to match an array of keys, and return the corresponding values in an object literal.

• names (array): The keys to search for.
• text (string) [optional]: The URL text to search in.

tinyQS.getMany(['foo', 'bar', 'baz'], 'example.com?foo=123&baz'); // { foo: '123', bar: false, baz: true }

.getAll( [text] )

Parse a URL and return all query-string values as an object.

Note: If using the .get() alias with a specific text argument, pass false as the second argument (e.g. tinyQS.get('example.com?foo', false)).

• text (string) [optional]: The URL text to search in.

tinyQS.getAll('example.com?foo=bar&baz'); // { foo: 'bar', baz: true }

.set()

Alias for the .setOne() and .setMany() methods:

.setOne( name, value, [, text] )

Add a single key (and its corresponding value) to the end of a URL.

• name (string): The key to add.
• value (string|Boolean|number): The corresponding value. If the value is a Boolean then only the key will be added.
• text (string) [optional]: The text URL to add the key/value to.

tinyQS.setOne('foo', 'bar', 'example.com'); // 'example.com?foo=bar'
tinyQS.setOne('foo', true, 'example.com'); // 'example.com?foo'

.setMany( values [, text] )

Add several keys to a URL.

• values (array|object): The keys to add. Accepts an array of valueless keys, or an object literal of key/value pairs.
• text (string) [optional]: The text URL to add the key/value to.

tinyQS.setMany(['foo', 'bar'], 'example.com'); // 'example.com?foo&bar'
tinyQS.setMany({foo: 'bar', baz: true}, 'example.com'); // 'example.com?foo=bar&baz'

.remove()

Alias for the .removeOne(), .removeMany() and .removeAll() methods:

.removeOne( name [, text] )

Remove a key from a URL query string, and return the updated URL.

• name (string): The key to remove.
• text (string) [optional]: The URL to parse and remove a key from.

tinyQS.removeOne('foo', 'example.com?foo=bar&baz'); // 'example.com?baz'

.removeMany( names [, text] )

Remove an array of keys from a URL query string, and return the updated URL.

• names (array): The keys to remove.
• text (string) [optional]: The URL to parse and remove keys from.

tinyQS.removeMany(['foo', 'bar'], 'example.com?foo=123&bar&baz'); // 'example.com?baz'

.removeAll( [text] )

Parse a URL and return all query-string values as an object.

Note: If using the .remove() alias with a specific text argument, pass false as the second argument (e.g. tinyQS.remove('example.com?foo', false)).

• text (string) [optional]: The URL text to search in.

tinyQS.removeAll('example.com?foo=bar&baz'); // 'example.com'

Contributing

Please read contributing.md for details on our code of conduct, and the process for working on this project and submitting pull requests.

License

Copyright (c) Richard Westenra

This project is licensed under the MIT License - see the LICENSE file for details