@algoristic/tinyparams

Get, set and watch url query parameters without any dependencies.

Basic concepts

This library makes use of the History API to modify the browser URL for best integration with SPAs.

By default, all updates take place using history.pushState, but every method that modifies parameters has the option to use history.replaceState instead. (See section 'Single parameters' for examples.)

Updates to parameter values are detected by extending history.pushState and history.replaceState and also listing to popstate events to detect URL modifications via history.back(), history.foward() and the like.

Callbacks

Watching changes of search parameters happens through callbacks. If you want to escape the callback hell you can just use @algoristic/tinyparams-async, that acts as a rxjs wrapper and adds convenient .observe() methods.

Installation

npm i @algoristic/tinyparams

Usage

import { params } from '@algoristic/tinyparams';

Single parameters

Get a value

const foo: string | undefined = params('foo').getValue();

Set a value

params('foo').setValue('bar');
params('foo').setValue('bar', {
  updateMode: 'replace', // default 'push'
});

Remove / unset a value

params('foo').remove();
// equals to
params('foo').setValue(undefined);

Perform on changes

// url = '...?foo=bar'
params('foo').onChange((newValue, oldValue) => {
  console.log(`old=${oldValue}, new=${newValue}`);
});
params('foo').setValue('baz');
// console: 'old=bar, new=baz'

Watch values

Perform a callback on the current value when it changes. Unlinke .onChange the method .watch starts with the initial value and only passes the current value.

// url = '...?foo=bar'
params('foo').watch((foo) => {
  console.log(foo);
});
// console: 'bar'
params('foo').setValue('baz');
// console: 'baz'

Multiple parameters

Snapshot

Get a snapshot of the current state of all query parameters.

const { get, keys, values } = params.snapshot();

// get value from snapshot
let value: string | undefined = get('foo');
// analogous to params('foo').getValue()

// get all parameter keys
let keys: string[] = keys();
// returns ['foo', ...]

// get all parameter key-value pairs
let values: { key: string; value: string }[] = values();
// returns [{ key: 'foo', value: 'bar' }, ...]

Watch all parameter values

Behaves similar to params(key).watch(...).

params.watch(({ get, keys, values }) => {
  keys = keys();
  values = values();
  ...
});

Modify multiple parameters

const { setOne, setMany, setAll } = params.modifiers();

// set one value
setOne('foo', 'bar');
// analogous to `params('foo').setValue('bar')`

// set many values (but retain existing other parameters)
setMany({ foo: 'bar', answer: 42, debug: true });

// override all query parameters
setAll({ foo: 'bar', answer: 42 });

Configuration

@algoristic/tinyparams is fully compatible with hash routing by just setting:

params.useHash = true;

Personal note

This library may seem irrelevant in the age of frameworks and incredibly good routing. But when first meeting JavaScript I wrote this abomination of a "library" for a personal project: https://github.com/algoristic/js-url-parameters.

I keep this project publically visible to remind myself of how not to write code. And I just needed to rewrite this to prove myself I can do better now.