Skip to content

Latest commit

 

History

History
390 lines (250 loc) · 7.44 KB

README.md

File metadata and controls

390 lines (250 loc) · 7.44 KB
Raw

web-porridge

License Version Build

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
  • observability
  • 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()

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.

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

localPorridge.setItem('secondItem', { name: 'John Appleseed' });
localPorridge.setItem('secondItem', 'Ada Lovelace', { prop: 'name' });
IndexedDB 
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.

Storage 
localPorridge.getItem('firstItem');
localPorridge.getItem('secondItem', { prop: 'dot.notation.property' });
IndexedDB 
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.

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

clear()

Usage: clear()

Clears all keys stored in a given Storage object.

Storage 
localPorridge.clear();
IndexedDB 
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.

Storage 
localPorridge.key(0);
IndexedDB 
await idb.key(0);

length

Usage: length

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

Storage 
localPorridge.length;
IndexedDB 
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.

Storage 
localPorridge.hasItem('firstItem');
IndexedDB 
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.

Storage 
localPorridge.keys();
IndexedDB 
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.

Storage 
localPorridge.values();
IndexedDB 
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.

Storage 
localPorridge.entries();
IndexedDB 
await idb.entries();

didExpire()

Usage: didExpire(key: string)

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

Storage 
localPorridge.didExpire('firstItem');
IndexedDB 
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.

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

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.