A simple to use wrapper around JavaScript's LocalStorage/SessionStorage.
Install from npm:
npm install --save caddyjs
# or yarn
yarn add caddyjs
Get started by creating an instance of the Caddy class:
import { Caddy } from 'caddyjs';
const caddy = new Caddy();
The constructor takes an optional configuration object, see here.
Then you can set values:
caddy.set('key', 'value');
Get values:
caddy.get('key'); // 'value'
And more! Read the documentation below.
Caddy works by serializing an object into storage, so any value that can be JSON-ified with JSON.stringify
can be stored with Caddy.
The constructor takes an optional configuration object.
const caddy = new Caddy({
key: 'my_custom_key',
});
The options allowed are:
Key | Description | Default |
---|---|---|
key |
The unique key that is used when storing items. | caddy X where X is a number from 1 upwards1. |
driver |
The storage driver to use. Must have the same interface as sessionStorage/localStorage. | window.localStorage |
In most cases, the default options will be fine and you can just initiate caddy without any options:
const caddy = new Caddy();
Adds an item into the storage.
caddy.set('my_key', 'some sort of value');
set
returns this
, so you can chain multiple calls:
caddy.set('key_a', 1)
.set('key_b', 2)
Gets an item from storage. Will return undefined
if there is nothing stored against the given key.
caddy.get('my_key') // 'some sort of value'
caddy.get('key_we_havent_set') // undefined
Determines if a key exists in the store.
caddy.has('key_a') // true
caddy.has('key_b') // true
caddy.has('key_c') // false
A convenience method that pushes the given value into an array stored at the given key. If there is nothing stored for the key, an array will be created with the value. If the value stored at the key is not an array, an error will be thrown.
caddy.set('my_array', [1, 2, 3]);
caddy.push('my_array', 4);
caddy.get('my_array') // [1, 2, 3, 4]
caddy.has('new_key'); // false
caddy.push('new_key', 3);
caddy.get('new_key'); // [3]
caddy.set('key', 'string');
caddy.push('key', 2); // Error!
push
also returns this
, so it can be chained if you wish:
caddy.push('array', 1).push('array', 2);
Empties the entire store.
caddy.set('example', 123);
caddy.has('example'); // true
caddy.flush();
caddy.has('example'); // false
subscribe
allows you to perform some logic whenever the store is updated. You supply a callback function that will be passed the entire store object.
// Do something with the entire store
caddy.subscribe((store) => {
console.log(store);
});
// The store is just an object, so you can destructure to get just the properties you're interested in:
caddy.subscribe(({ my_key }) => {
console.log(my_key);
});
You can subscribe to a store as many times as you wish.
See also: listen
listen
allows you to listen to changes to an item. It's similar to subscribe, but only for a specific key, and is only called when the value is different to what it was before2.
caddy.listen('my_key', (value) => {
console.log(value);
});
You can listen to a value as many times as you wish.
See also: subscribe
- Caddy keeps track of how many instances have been created, and increments the key every time to avoid collisions.
- The way Caddy compares values is by using the strict equality operator (
===
). Because of the way Caddy works,listen
will not work properly if your value is an array or object, as Caddy will always see the value as different than last time. A workaround is to usesubscribe
and determine whether the value has changed yourself.