/querystate

🔎 Simple and dependency free query string state management

Primary LanguageJavaScriptMIT LicenseMIT

querystate

Simple and dependency free query string state management

travis npm version npm downloads npm license prs Welcome eslint

querystate

Installation

npm install querystate --save

Usage

all()

Get all parameters in the query string

// URL: xo.com/?rainbow=awesome&colors=red,blue,green

const state = require('querystate')();

state.all();

//=> {
//=>   rainbow: 'awesome',
//=>   colors: [
//=>     'red',
//=>     'blue',
//=>     'green',
//=>   ]
//=> }

get(key, [default = null])

Get a value from the query string by key, or a provided default.

// URL: xo.com/?rainbow=awesome&colors=red,blue,green

const state = require('querystate')();

state.get('colors');
//=> ['red', 'blue', 'green']

state.get('pony');
//=> null

state.get('wizard', 'Merlin');
//=> Merlin

state.get('wizard', () => 1 + 2 + 3 + 4);
//=> 10

set(key, value)

Set a key and value pair in to the query string set() will by default update the actual URL when called. This can be avoided using a config Disable auto applying*

// URL: xo.com/?a=b

const state = require('querystate')();

state.set('c', 'd');
// URL: xo.com/?a=b&c=d

state.all();

//=> {
//=>   a: 'b',
//=>   c: 'd',
//=> }

remove(key)

Remove a key and value pair in to the query string remove() will by default update the actual URL when called. This can be avoided using a config. Disable auto applying

// URL: xo.com/?a=b&c=d

const state = require('querystate')();

state.remove('c');
// URL: xo.com/?a=b

state.all();

//=> {
//=>   a: 'b',
//=> }

toQueryString()

If you want the current state as a simple query string, you can call this method

// URL: xo.com/?a=b

const state = require('querystate')();

state.set('c', 'd');

state.toQueryString();
//=> ?a=b&c=d

Config

Casts to array

Sometimes you always want your data to be in a specific way. Let's imagine we have an API where we can limit our result by users by providing an array of the user_ids that we want. That API endpoint always expects an array, but if we provide just one user in our query string, it will get parsed to a string. But there is an easy way to always cast our data to an array.

const state = require('querystate')({ castsToArray: true });

// URL: xo.com/?user_ids=2
state.get('user_id');
//=> [2]

state.all();
//=> {
//=>   user_id: [2],
//=> }

Disable auto updating of window.history.pushState

If you want to disable auto applying state when using set() and remove(), you may pass a config to querystate

// Using [window.location.search] as default state
const state = require('querystate')({ autoApply: false });

// Custom state
const state = require('querystate')('?foo=bar', { autoApply: false });

When setting autoApply to false you need to explicitly tell querystate to update after a change.

// URL: xo.com/?a=b&c=d

const state = require('querystate')({ autoApply: false });

state.remove('c');
// URL: xo.com/?a=b&c=d

state.apply();
// URL: xo.com/?a=b

License

MIT © Daniel Eckermann