vault-storage

vault

vault is a sophisticated browser-based storage library that leverages the power of IndexedDB, offering significant improvements over traditional LocalStorage. As a high-performance, asynchronous solution for client-side storage, vault provides an intuitive and easy-to-use API to interact with IndexedDB, making client-side data storage efficient and scalable.

Features

• Similar API: Easy to use, similar to LocalStorage.
• Lightweight: No dependencies, micro footprint
  • Less than a KB (minified and gzipped), unsecured vault
  • Around a KB (minified and gzipped), secured vault
• Multiple Stores Support: Supports multiple stores with single api.
• Encrypted Vault: Provides a secure storage for sensitive data.
• Asynchronous: Non-blocking, asynchronous API.
• Structured Data: Supports structured data, including objects and arrays.

Installation

Install vault-storage using npm:

npm install vault-storage --save

Or using yarn:

yarn add vault-storage

Usage

First, import the vault from vault-storage. The vault is a default instance of the Vault storage class and hence does not need any special initialization or setup!!! The vault provides a ready to use instance similar to localStorage and sessionStorage. You can start using it right away without any setup.

import vault from 'vault-storage';

Initializing and Setup

Just start using it!

// Set the values.
vault.key1 = "value1";
vault.key2 = "value2";

// Get the values. Remember to use await! As it's asynchronous.
const value1 = await vault.key1; // "value1"
const value2 = await vault.key2; // "value2"

Custom Storage

You can also create a custom storage. This is useful when you want to use multiple storages for different purposes. All the custom storage also share the same API as the default vault storage and other built-in storages like localStorage and sessionStorage.

import Vault from 'vault-storage/vault';


const appStorage = new Vault("app-storage")
appStorage.setItem("key", "value")
console.log("key", await appStorage.getItem("key"))

const userStorage = new Vault("user-storage")
userStorage.setItem("key", "value")

Secure Storage

Secured storages are useful when you want to store sensitive data. It shares the same API but it encrypts the data before storing it in the storage. It uses browser's native crypto API to encrypt the data. The secured storage can be created using a fixed credentials or dynamic credentials (credentials that are generated based on the key).

import SecuredVault from 'vault-storage/secured-vault';

// Secured storage using fixed credentials (password and salt).
const authStorage = new SecuredVault("secured-storage", {
  password: "SADF@#$W$ERWESD",
  salt: "SDF@#$%SERWESD",
});

authStorage.token = "my-token"
console.log("token", await authStorage.token)

// Secured storage using dynamic credentials.
const securedStorage = new SecuredVault("secured-storage", (key) => {
  const password = key === "token" ? "ASF@#$%QER()SDF" : "SXDFW#$%@#SDF";
  const salt = key.startsWith("key1") ? "xxx@xxxxxxxxxx" : "yyy@yyyyyyyyyy";
  return { password, salt };
});

// Secured storage using promise based dynamic credentials.
const sensitiveStorage = new SecuredVault("secured-storage", async (key) => {
  return new Promise(async (resolve) => {
    const { password, salt } = await fetchOrGenerateCredentialsFor(key)
    resolve({ password, salt })
  });
});


// Once the secured valued is setup, usage is similar to the regular vault storage.
// Just start using it!

// Set the values. It stores the encrypted Uint8Array in the storage
// against the key. If you want to immediately use the value, then
// you must use await while setting the value.
await authStorage.setItem("token", "eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiQWRtaW4iLCJJc3N1ZXIiOiJJc3N1ZXIiLCJVc2VybmFtZSI6IkphdmFJblVzZSIsImV4cCI6MTcwNzA2NzgwMywiaWF0IjoxNzA3MDY3ODAzfQ.XmPqTUN3KJeEArX58xVfHIQGGtm291p9ZamBvrflCMo")

// Get the values. Remember to use await! As it's asynchronous.
const token = await authStorage.token; // Decrypted token from the authStorage
                                       // and returns the original token.

Setting Values

Store data using the setItem method, indexer syntax, or dot notation:

 // For set operation you can ignore await unless you want to wait for the
 // operation to complete or you want to catch any errors.
vault.setItem('yourKey', { any: 'data' });

// Indexer syntax.
vault['yourKey'] = { any: 'data' };

// Dot notation.
vault.yourKey = { any: 'data' };

Getting Values

Retrieve data using the getItem method, indexer syntax, or dot notation. For get operations you must use await as it's asynchronous.

// Get the value using the getItem method.
const data = await vault.getItem('yourKey');

// Indexer syntax.
const data = await vault['yourKey'];

// Dot notation.
const data = await vault.yourKey;

Removing Values

Remove data using the removeItem method:

// Remove the value using the remove method.
vault.removeItem('yourKey');

// Indexer syntax.
delete vault['yourKey'];

// Dot notation.
delete vault.yourKey;

Clearing All Data

Clear all data from the store:

await vault.clear();

Getting Store Length

Get the count of entries in the store:

const count = await vault.length();
console.log(count);

API Reference

• setItem(key: string, value: any): Store data in the storage.
• getItem(key: string): Retrieve data from the storage.
• removeItem(key: string): Remove data from the storage.
• clear(): Clear all data from the storage.
• length(): Get the count of entries in the storage.

Comparing Vault with LocalStorage

Feature	Vault	LocalStorage
API Complexity	Simple, intuitive API	Simple, intuitive API
Capacity	Large (up to browser limit, often no less than 250MB)	Limited (5MB typical)
Multiple Stores	Supports multiple stores	Single store
Encrypted Storage	Supports built-in secured storage	No built-in encryption support
Data Types	Supports structured data, including objects and arrays	Only stores strings
Performance	Asynchronous, non-blocking	Synchronous, can block UI

Vault Roadmap

Since the vault is baesd on IndexDB database as storage provider, it is possible to make it more powerful and useful. Here are some planned features and their implementation status.

Core Features (v1.0.*)

• Extensible Vault class that has following qualities
  • Provides a simple interface similar to local and session storages
  • Supports indexers and dot notation for intuitive and ergonomic access
  • Store large amount of data
  • Perorm transactional in non-blocking asynchronous manner
• Global default vault instance for ease of use
• Support custom databases

Advanced Features - Encryption (v1.1.*)

• Support for secured vault storage
• Support for dynamic password and salt for secured vault storage

Other Advanced Features (Future)

• Support multiple update in a single transaction
• Automatic expiration of values based on TTL, Session Timeout and other expiration policies
• Support for vault data backup and restore

Contributing

Contributions to vault-storage are welcome. Please ensure that your code adheres to the existing style and includes tests covering new features or bug fixes.

License

vault-storage is MIT licensed.