IndexedDB Storage Adapter

The IndexedDBAdapter extends the abstract StorageAdapter class, providing a concrete implementation for persisting data to the browser's IndexedDB. This adapter offers persistent, high-capacity client-side storage with enhanced capabilities including encryption, expiration management, metadata tracking, and optional cross-tab synchronization.

1. Getting Started

Initialize the adapter with the desired options:

        
import IndexedDBAdapter from "storagefy";

const adapter = new IndexedDBAdapter({
  dbName: "my-app",               // required - database name
  storeName: "my-store",          // optional - defaults to `${dbName}_store`
  encrypt: true,                  // optional, default false
  version: 1,                     // optional, default 1
  expireCheckInterval: 2000,      // optional, default 1000ms
  description: "App database",    // optional
  channelName: "idb-channel"      // optional - used for sync between tabs
  enableSyncTabs: false,          // optional, default false - Whether to enable sync 
                                  // automatically on change key value
});
        
      

The channelName enables automatic synchronization of data across open tabs using the CrossTabChannel communication system. This is particularly useful for applications where you want to maintain state consistency across multiple tabs.

2. Core Concepts

3. Test It

4. API Reference

          
await adapter.set("userId", "user123");
const value = await adapter.get("userId"); // "user123"
          
        

          
// Save user data that expires in 7 days
await adapter.set("userData", userData, 7 * 24 * 60 * 60 * 1000);
          
        

          await adapter.delete("userId");
        

          
await adapter.set("user.name", "John");
await adapter.set("user.email", "john@example.com");
const userData = await adapter.list("user."); 
// [{ key: "user.name", value: "John" }, { key: "user.email", value: "john@example.com" }]
          
        

await adapter.has("userId"); // true or false

await adapter.clear();

await adapter.reset();

          
const futureDate = Date.now() + 30 * 24 * 60 * 60 * 1000; // 30 days
await adapter.setExpire("userData", futureDate);
          
        

          
const expireTime = await adapter.getExpire("userData");
// Returns timestamp or null
          
        

          
await adapter.deleteExpire("userData");
          
        

          
await adapter.clearExpire();
          
        

          
await adapter.waitReadiness();
// Now safe to perform operations
          
        

          
adapter.destroy(); // Clean up before component unmount
          
        

          
adapter.emitDataChange("appState", newState, "tab-123");
          
        

          
adapter.onDataChanged(({ key, value, origin }) => {
  console.log(`Data for ${key} changed in tab ${origin}`);
  // Update UI or app state accordingly
});
          
        

5. Advanced Usage

          
// Store application data for offline use
async function cacheApplicationData(data) {
  await adapter.set("app.cache", data);
  await adapter.set("app.lastSyncTime", Date.now());
}

// Retrieve cached data when offline
async function getOfflineData() {
  return await adapter.get("app.cache");
}

// Check if cache needs refreshing (older than 1 day)
async function shouldRefreshCache() {
  const lastSync = await adapter.get("app.lastSyncTime");
  if (!lastSync) return true;
  const oneDay = 24 * 60 * 60 * 1000;
  return (Date.now() - lastSync) > oneDay;
}
          
        

          
// Store user preferences
async function saveUserPreferences(preferences) {
  await adapter.set("preferences", preferences);
}

// Load user preferences
async function loadUserPreferences() {
  return await adapter.get("preferences") || getDefaultPreferences();
}

// Update a single preference
async function updatePreference(key, value) {
  const prefs = await loadUserPreferences();
  prefs[key] = value;
  await saveUserPreferences(prefs);
}
          
        

          
// Store product data
async function saveProduct(product) {
  await adapter.set(`product.${product.id}`, product);
}

// Add product to favorites
async function addToFavorites(productId) {
  await adapter.set(`favorite.${productId}`, true);
}

// Get all favorite products
async function getFavoriteProducts() {
  const favorites = await adapter.list("favorite.");
  const productIds = favorites.map(f => f.key.replace("favorite.", ""));
  
  const products = [];
  for (const id of productIds) {
    const product = await adapter.get(`product.${id}`);
    if (product) products.push(product);
  }
  
  return products;
}
          
        

          
// Create a separate adapter instance for sensitive data
const secureAdapter = new IndexedDBAdapter({
  dbName: "secure_storage",
  encrypt: true
});

// Store encrypted credentials
async function storeCredentials(username, accessToken, refreshToken) {
  await secureAdapter.set("auth.username", username);
  await secureAdapter.set("auth.accessToken", accessToken);
  await secureAdapter.set("auth.refreshToken", refreshToken);
  await secureAdapter.set("auth.timestamp", Date.now());
}

// Get authentication data
async function getAuthData() {
  const authData = await secureAdapter.list("auth.");
  return authData.reduce((obj, item) => {
    obj[item.key.replace("auth.", "")] = item.value;
    return obj;
  }, {});
}

// Clear authentication on logout
async function logout() {
  const authKeys = await secureAdapter.list("auth.");
  for (const item of authKeys) {
    await secureAdapter.delete(item.key);
  }
}
          
        

5. Comparison with Other Storage Adapters

6. Notes

• IndexedDB operations are asynchronous - always use await when calling adapter methods.
• Consider calling waitReadiness() after initialization to ensure the database is open before performing operations.
• Use encrypt: true for sensitive data that should be protected even in the client-side storage.
• Keys are namespaced under {dbName}__ to avoid conflicts.
• A beforeunload event listener is registered to properly clean up resources.
• Expirations are automatically checked and cleared at the specified interval (default 1s).
• For very large datasets, consider implementing pagination or lazy loading patterns.
• IndexedDB has excellent support across modern browsers but may require polyfills for older browsers.
• For complex data models, consider using multiple adapters with different store names within the same database.