⚡️ StorageProxy

Use web storage (localStorage/sessionStorage) just like plain objects using ES6 Proxies.

💁🏼‍♂️ Introduction

Interact with localStorage or sessionStorage like a plain JavaScript object. You can even iterate over keys and entries as with plain objects.

🔗 Installation

Install via yarn (recommended):

yarn add storage-proxy

Install via npm:

npm install storage-proxy

🛠️ Usage

import { StorageProxy } from 'storage-proxy';

const myLocalStorage = StorageProxy.createLocalStorage('my-namespace');
const mySessionStorage = StorageProxy.createSessionStorage('my-namespace');

// Here's a (non-exhaustive) list of some possibilities:

myLocalStorage.hello = 'world';
myLocalStorage.foo = [1, 2, 3];
myLocalStorage.foo.push(4);
myLocalStorage.bar = { baz: 'This works!' };
myLocalStorage.bar.spam = 'This works too!';
const copied = { ...myLocalStorage };

Additionally, you can pass default values. This is handy if your stored data contains deep objects that need to be accessible even when the contained data is undefined:

const myLocalStorage = StorageProxy.createLocalStorage('my-namespace', {
  one: {
    two: 'three',
    four: {},
  },
});

console.log(myLocalStorage.one.two)    // => "three"
myLocalStorage.one.four.five = 'six';  // Works!

In TypeScript, you can define the shape of your stored data by passing a generic type parameter to the factory function:

const myStorage = StorageProxy.createLocalStorage<{
  hello: string;
  foo: number[];
  bar: { baz: string, spam?: string };
}>('my-namespace');

myStorage.foo      // Works!
myStorage.bar.baz  // Works!
myStorage.yolo     // Compiler error!

Utilities

For convenience, StorageProxy also provides several lightweight utilities for interacting with web storage.

StorageProxy.verifyCache(storageProxy: StorageProxyObject, seed: string)

Checks a cache key in the given StorageProxyObject and verifies whether the cache integrity is sound. This is handy for cache-busting localStorage and sessionStorage.

StorageProxy.clearStorage(storageProxy: StorageProxyObject)

Clear the given web storage proxy object from localStorage or sessionStorage. Only keys under the namespace indicated by the StorageProxyObject are removed from the web storage caches.

StorageProxy.restoreDefaults(storageProxy: StorageProxyObject)

Restores the default values given to StorageProxy.createLocalStorage() and StorageProxy.createSessionStorage(). However, unlike when the StorageProxyObject was initially created, this function privelages the default values over what is currently in WebStorage.

StorageProxy.isStorageAvailable(storageTarget?: StorageTarget)

Asserts whether the supplied WebStorage type is available. The storageTarget parameter defaults to localStorage. StorageProxy uses this utility internally to prevent raising errors in incompatible browser environments. This means you are protected from WebStorage permissions issues, but also counts as an important gotcha! It's crucial that your application works with or without WebStorage, so please try to gracefully degrade functionality in such occurrences. This utility is exposed for that very purpose. Use it to your advantage!