A tiny (2kb minified) JS library for reading & writing URL query strings.
npm install tiny-query-string --save
bower install tiny-query-string --save
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'
Note: The text
argument always defaults to window.location.search
if left unspecified, or ''
if window
does not exist.
Alias for the
.getOne()
,.getMany()
and.getAll()
methods:
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
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 }
Parse a URL and return all query-string values as an object.
Note: If using the
.get()
alias with a specific text argument, passfalse
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 }
Alias for the
.setOne()
and.setMany()
methods:
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'
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'
Alias for the
.removeOne()
,.removeMany()
and.removeAll()
methods:
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'
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'
Parse a URL and return all query-string values as an object.
Note: If using the
.remove()
alias with a specific text argument, passfalse
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'
Please read contributing.md for details on the code of conduct, and the process for working on this project and submitting pull requests.
Copyright (c) Richard Westenra
This project is licensed under the MIT License - see the LICENSE file for details