web-porridge

Feature-enhanced wrapper for both, Storage API and IndexedDB API, sharing a common, familiar interface.

Features

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

Installation

npm install web-porridge -S

Usage

Import

import { Porridge, PorridgeDB } from 'web-porridge';

const localPorridge = new Porridge();
const idb = new PorridgeDB();

Instance

Porridge

new Porridge(storageArea: 'localStorage' | 'sessionStorage' = 'localStorage', eventName = 'porridge.didChange')

PorridgeDB

new PorridgeDB(options?: {db: string; eventName = 'porridgeDB.didChange'; store: string})

Methods

All methods and properties of the Storage API have equivalents on localPorridge / sessionPorridge, completed by additional convenience methods as listed below.

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

Table of contents

• setItem()
• getItem()
• removeItem()
• clear()
• key()
• length
• hasItem()
• keys()
• values()
• entries()
• didExpire()
• observe()

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();

didExpire()

Usage: didExpire(key: string)

When passed a key name, will return whether that key has expired.

localPorridge.didExpire('firstItem');

await idb.didExpire('firstItem');

observe()

Usage: observe(key: string, callback: function)

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

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

// Later, to stop observing
unobserve();

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

// Later, to stop observing
unobserve();

Options

expires

Type: string

Sets an expiry date for the storage value. Can be anything that can be parsed by new Date().

prop

Type: string

Specifies an object property as a dot notation string. Allows granular reads and updates.

License

This work is licensed under The MIT License.