https://github.com/idleberg/web-porridge
Feature-enhanced wrappers for the Storage and IndexedDB APIs
https://github.com/idleberg/web-porridge
html5-storage local-storage node-module session-storage storage web-api web-storage web-storage-api
Last synced: about 2 months ago
JSON representation
Feature-enhanced wrappers for the Storage and IndexedDB APIs
- Host: GitHub
- URL: https://github.com/idleberg/web-porridge
- Owner: idleberg
- License: mit
- Created: 2020-02-13T22:09:24.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-02-06T00:12:40.000Z (4 months ago)
- Last Synced: 2025-04-27T10:04:53.006Z (about 2 months ago)
- Topics: html5-storage, local-storage, node-module, session-storage, storage, web-api, web-storage, web-storage-api
- Language: TypeScript
- Homepage: https://www.npmjs.org/package/web-porridge
- Size: 1.17 MB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# web-porridge
[](https://github.com/idleberg/web-porridge/blob/main/LICENSE)
[](https://www.npmjs.org/package/web-porridge)
[](https://jsr.io/@idleberg/porridge)
[](https://github.com/idleberg/web-porridge/actions/workflows/node.yml)
[](https://github.com/idleberg/web-porridge/actions/workflows/deno.yml)
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
```ts
import { Porridge, PorridgeDB } from 'web-porridge';
const localPorridge = new Porridge();
const idb = new PorridgeDB();
```
### Instance
#### `Porridge`
```ts
new Porridge(storageArea: 'localStorage' | 'sessionStorage' = 'localStorage', eventName = 'porridge.didChange')
```
#### `PorridgeDB`
```ts
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()`](#setitem)
- [`getItem()`](#getitem)
- [`removeItem()`](#removeitem)
- [`clear()`](#clear)
- [`key()`](#key)
- [`length`](#length)
- [`hasItem()`](#hasitem)
- [`keys()`](#keys)
- [`values()`](#values)
- [`entries()`](#entries)
- [`didExpire()`](#didexpire)
- [`observe()`](#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.
Storage
```ts
localPorridge.setItem('firstItem', 'Hello World');
localPorridge.setItem('secondItem', { name: 'John Appleseed' });
localPorridge.setItem('secondItem', 'Ada Lovelace', { prop: 'name' });
```
IndexedDB
```ts
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
```ts
localPorridge.getItem('firstItem');
localPorridge.getItem('secondItem', { prop: 'dot.notation.property' });
```
IndexedDB
```ts
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
```ts
localPorridge.removeItem('firstItem');
localPorridge.removeItem('secondItem', { prop: 'dot.notation.property' });
```
IndexedDB
```ts
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
```ts
localPorridge.clear();
```
IndexedDB
```ts
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
```ts
localPorridge.key(0);
```
IndexedDB
```ts
await idb.key(0);
```
#### `length`
Usage: `length`
Returns the number of data items stored in a given Storage object.
Storage
```ts
localPorridge.length;
```
IndexedDB
```ts
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
```ts
localPorridge.hasItem('firstItem');
```
IndexedDB
```ts
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
```ts
localPorridge.keys();
```
IndexedDB
```ts
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
```ts
localPorridge.values();
```
IndexedDB
```ts
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
```ts
localPorridge.entries();
```
IndexedDB
```ts
await idb.entries();
```
#### `didExpire()`
Usage: `didExpire(key: string)`
When passed a key name, will return whether that key has expired.
Storage
```ts
localPorridge.didExpire('firstItem');
```
IndexedDB
```ts
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
```ts
const unobserve =localPorridge.observe('demo', ({ key, newValue }) => {
console.log(`${key} has changed to:`, newValue);
});
// Later, to stop observing
unobserve();
```
IndexedDB
```ts
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](LICENSE).
[dot notation]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors#Dot_notation
[storage api]: https://developer.mozilla.org/en-US/docs/Web/API/Storage
[indexeddb api]: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API