web-porridge

Feature-enhanced wrapper for both, Web Storage API and IndexedDB API, sharing the common interfaced known from the former.

Features

• stores structured data
• automatic (de)serialization
• Object-level read & write access
• data expiry
• additional convenience methods

Installation

npm install web-porridge -S

Usage

Module

All methods and properties of the Web Storage API have equivalents on localPorridge / sessionPorridge, completed by additional methods for batch operations.

import { WebPorridge, WebPorridgeDB } from 'web-porridge';

const localPorridge = new WebPorridge();
const sessionPorridge = new WebPorridge('sessionStorage');
const idb = new WebPorridgeDB();

Methods

The following methods are available for both, Web Storage and IndexedDB. However, the key difference is that the former API is synchronous, while the latter is mostly asynchronous.

setItem()

Usage: setItem(key: string, value: any, options?)

When passed a key name and value, will add that key to the given Storage object, or update that key's value if it already exists.

localPorridge.setItem('firstItem', 'Hello World');

localPorridge.setItem('secondItem', { name: 'John Appleseed' });
localPorridge.setItem('secondItem', 'Ada Lovelace', { prop: 'name' });

await idb.setItem('firstItem', 'Hello World');

await idb.setItem('secondItem', { name: 'John Appleseed' });
await idb.setItem('secondItem', 'Ada Lovelace', { prop: 'name' });

getItem()

Usage: getItem(key: string, options?)

When passed a key name, will return that key's value, or null if the key does not exist, in the given Storage object.

localPorridge.getItem('firstItem');
localPorridge.getItem('secondItem', { prop: 'dot.notation.property' });

await idb.getItem('firstItem');
await idb.getItem('secondItem', { prop: 'dot.notation.property' });

removeItem()

Usage: removeItem(key: string, options?)

When passed a key name, will remove that key from the given Storage object if it exists.

localPorridge.removeItem('firstItem');
localPorridge.removeItem('secondItem', { prop: 'dot.notation.property' });

await idb.removeItem('firstItem');
await idb.removeItem('secondItem', { prop: 'dot.notation.property' });

clear()

Usage: clear()

Clears all keys stored in a given Storage object.

localPorridge.clear();

await idb.clear();

key()

Usage: key(index: number)

When passed a number n, returns the name of the nth key in a given Storage object.

localPorridge.key(0);

await idb.key(0);

length

Usage: length

Returns the number of data items stored in a given Storage object.

localPorridge.length;

await idb.length;

hasItem()

Usage: hasItem(key: string)

When passed a key name, returns a boolean indicating whether that key exists in a given Storage object.

localPorridge.hasItem('firstItem');

await idb.hasItem('firstItem');

keys()

Usage: keys()

Returns an array of a given object's Storage own enumerable property names, iterated in the same order that a normal loop would.

localPorridge.keys();

await idb.keys();

values()

Usage: values()

Returns an array of a given Storage object's own enumerable property values, iterated in the same order that a normal loop would.

localPorridge.values();

await idb.values();

entries()

Usage: entries()

Returns an array of a given object's own enumerable string-keyed property [key, value] pairs, iterated in the same order that a normal loop would.

localPorridge.entries();

await idb.entries();

observe()

Usage: observe(key: string, callback)

When passed a key name and callback funcrion, it will listen to changes to the given Storage object's value.

localPorridge.observe('demo', ({ key, value }) => {
    console.log(`${key} has changed to:`, value);
});

idb.observe('demo', ({ key, value }) => {
    console.log(`${key} has changed to:`, value);
});

License

This work is licensed under The MIT License