urlito
v1.0.2
Published
Simple API for persisting data structures to URL
Downloads
6
Readme
Urlito
Declarative API for persisting application state to URL.
Installation
npm i urlito
or yarn add urlito
Introduction
A helper library for Statium, Urlito makes it easier
to persist application state to the search
parameters portion of its URL.
The default export is a function (stateToUri
) that accepts two arguments. The first
argument is an object with keys and values corresponding to the default state of the
Store. The second argument is state key descriptors enumerating keys that should be
retrieved from the URL by getter function, and persisted to the URL by the setter function. If the second argument is not present, all keys defined in the first argument will be checked against URL search parameters and values are treated as strings.
The return value is a tuple of these functions: [getStateFromUri, setStateToUri]
.
import Store from 'statium';
import stateToUri from 'urlito';
// Default state values. In this example, we define a set of values,
// not all of which are persisted to the URI.
const defaultState = {
foo: 'frob',
bar: "fred",
baz: 42,
qux: Date.now(),
};
// The second argument is defining which values will be persisted,
// how to parse them from URI and how to convert them to stringified form
// when persisting back to URI.
const [getStateFromUri, setStateToUri] = stateToUri(defaultState, [
'foo',
{
// State key, as in defaultState
key: 'qux',
// URI key might be different (optional)
uriKey: 'time',
// Optional converter from URL format
fromUri: time => new Date(parseInt(time, 10)),
// Optional converter to URL format
toUri: time => time.toString(),
// Optional comparator
equals: (a, b) => a.getTime() === b.getTime(),
},
});
const Component = () => (
<Store initialState={getStateFromUri} onStateChange={setStateToUri}>
{/* ... */}
</Store>
);
Retrieving state
To read state from URI, the getStateFromUri
function should be called with no arguments.
It will iterate over the state keys defined in stateToUri
call, and if the key is present
in the URL search parameters, its value will be used instead of default. If the key is not present, the corresponding value from defaultState
will be returned instead.
The return value is an object with key/value pairs that can be passed to initialState
prop of a Statium Store.
Persisting state
To write state to the URI, the setStateToUri
function should be called with one argument:
a Statium Store API object, containint specifically the state
property. For each state key defined in the stateToUri
call, the actual value will be compared with default value; if the value in the actual state object is defined and does not equal to default, it will be persisted to the search parameters of the URL. If the value in the actual state object equals to default, this key will be deleted from the URL search parameters.
There is no return value for this function.
State key descriptors
The second argument to stateToUri
function is a data structure that describes state keys
to be persisted. This can be an object describing keys and their properties, or an array of descriptors.
An array is the simplified form:
const stateKeys = [
// Read parameter 'foo' in the URL search parameters, treat the value as a string,
// set the value to key 'foo' in the state object
'foo',
{ ... }, // See object form below
];
An object has the following format:
const stateKeys = {
foo: {
// Define key selector in array format, ignored for object format
key: 'foo',
// Name of the URL search parameter to read from/write to
uriKey: 'foobaroo',
// Function that parses the value when reading from the URL.
// Default is to return the value as is, which produces a string.
fromUri: value => value,
// Function that stringifies the value when writing to the URL.
// Default is no special conversion, which will stringify the value
// when assigning URL search parameters.
toUri: value => value,
// Function to compare default value with actual value when reading from
// URL (after parsing) and writing to URL (before stringification).
// This function is passed two arguments and is expected to return true
// when they are equal, false otherwise.
// Default is Object.is()
equals: (a, b) => Object.is(a, b),
},
};