local-save is a lightweight wrapper around IndexedDB for secure and structured client-side data storage. It provides encryption, expiration, and organized data storage across configurable categories.

---

Looking to experience how local-save can securely store and retrieve data?

👉 Try the Live Demo 👈

Features

• Lightweight & Widespread Support: No external dependencies and works in all modern browsers.
• TypeScript Support : Written in TypeScript for maximum type-safety and a great developer experience.
• Encryption Support : Uses SubtleCrypto for secure data encryption with AES-GCM algorithm.
• Category Management : Organize data into predefined categories.
• Data Expiry : Allows setting an expiration threshold for data and a method to clear expired data.
• IndexedDB Management : Handles IndexedDB, object store creation and IndexedDB versioning management automatically.
• Logging : Debug logs for detailed insights.

---

Installation

npm install @febkosq8/local-save

---

Usage

Configuration Options

Option Key	Type	Default	Description
dbName	string	"LocalSave"	Name of the IndexedDB database.
encryptionKey	string	undefined	Encryption key that should be either [16, 24, or 32] characters to be used for AES-GCM encryption. If not provided, data will be stored in plain text.
categories	string[]	["userData"]	Array of categories (Object store names).
expiryThreshold	number	30	Data expiration threshold in days.
clearOnDecryptError	boolean	true	Whether to clear a category if decryption fails.
printLogs	boolean	false	Whether to print logs (Debug and errors).

Initialization

Create a new instance of LocalSave with the available configuration options

import LocalSave from "@febkosq8/local-save";
...
const localSaveConfig = {
  encryptionKey: "MyRandEncryptKeyThatIs32CharLong", // Encryption key for data
  categories: ["userData", "settings"], // Define categories for data storage
  expiryThreshold: 14, // Clear data older than 14 days
};
const localSave = new LocalSave(localSaveConfig);

Storing data

Store data in a category

Here userData is the category. The key is user001 for the data { name: "John Doe", age: 30 }.

await localSave.set('userData', 'user001', { name: 'John Doe', age: 30 });

Fetching data

Fetch data from a category using the category and key

The data will be returned along with the timestamp when it was stored. If the data is expired, it will return null.

try {
    const localDataFetch = await localSave.get('userData', 'user001');
    const { timestamp, data } = localDataFetch;
    console.log(data); // { name: "John Doe", age: 30 }
    console.log(timestamp); // UNIX timestamp of calling `set` method
    //handle data here
} catch (error) {
    //Error will be thrown if the decryption fails
    //handle error here
}

Removing data

Remove data using the category and key

await localSave.remove('userData', 'user001');

Clearing a category

Clear all data from a category

await localSave.clear('userData');

Clearing expired data

Clear all expired data from all categories

// If a value is provided, it will override the default expiry threshold
// This can be placed on top of the file to clear expired data on page load
await localSave.expire(14); // Clear data older than 14 days from all categories

Destroying the entire database

Clear all data from all categories and delete the database

await localSave.destroy();

Decrypting data manually

Decrypt data using the encryption key

This is useful when you want to decrypt the DBItemEncryptedBase64 string manually without using the get method

const decryptedData = await localSave.decryptData(DBItemEncryptedBase64);