🔒 @ultimate/vault

1KB typed localStorage and sessionStorage utility with data structure and prefix support.

Installation

Install via npm i @ultimate/vault.

Documentation

ESModule: Import Vault into your TypeScript or JavaScript project and create a new instance:

import{Vault}from'@ultimate/vault';constlocalStorage=newVault();

Global: Access window.Vault if you are not using a module system:

<scriptsrc="vault.min.js"></script><script>// implicitly uses localStorage until specifiedconstlocalStorage=newVault();</script>

Local or Session Storage

By default new Vault() will use localStorage. You may specify the type of storage:

constlocalStorage=newVault({type: 'local'});constsessionStorage=newVault({type: 'session'});

As Vault is a class each instance works independently.

Key Prefixes

Create a prefix for each Vault instance:

constlocalStorage=newVault({prefix: 'x9ea45'});

All keys set into storage via this instance will be stored as x9ea45-<key>.

isSupported property

Browser support is IE8+ so this shouldn't be wildly needed, but it's there anyway:

constlocalStorage=newVault();if(localStorage.isSupported){// initialize...}

set<T>(key: string, value: T): void

Set a key and value into storage using the typed set method:

// TypeScriptconstlocalStorage=newVault();interfaceUser{name: string}localStorage.set<User>('user',{name: 'Todd Motto'});

All methods are available to use without TypeScript:

constlocalStorage=newVault();localStorage.set('user',{name: 'Todd Motto'});

get<T>(key: string): T | undefined

Get a value from storage using the typed get method:

constlocalStorage=newVault();interfaceUser{name: string}localStorage.get<User>('user');

remove(key: string): void

Remove an item from storage using the remove method:

constlocalStorage=newVault();localStorage.remove('user');

removeAll(): void

Remove all items from storage:

constlocalStorage=newVault();localStorage.removeAll();

onChange(key: string, fn: (e: StorageEvent) => void): () => void

Listen to the storage change event from another tab, which is emitted when any storage value is changed. Here we can specify to only listen to specific property changes:

constlocalStorage=newVault();constunsubscribe=localStorage.onChange('user',(e: StorageEvent)=>{// `user` was changed in another tab// we could use this new data to sync our UIconsole.log(e);});// remove the event listener when you're readyunsubscribe();

Get all values

Obtain all storage values by accessing the value getter:

constlocalStorage=newVault();console.log(localStorage.value);// { "user": "Todd Motto", ... }

Returns an object with all keys and values. Values will remain a string type and will need parsing with JSON.parse() if you need to access the value.

Length of Storage

Access how many items are currently in storage with length:

constlocalStorage=newVault();console.log(localStorage.length);// 3