Package Exports

@amitkhare/indexed-storage

Readme

@amitkhare/indexed-storage

A modern, localStorage-like API for IndexedDB that provides a simple and intuitive interface for client-side data storage with enhanced capabilities.

✨ Features

localStorage-like API - Familiar setItem(), getItem(), removeItem() interface
Type Preservation - Stores and retrieves exact values (primitives, objects, arrays)
Async/Await Support - Modern Promise-based API
Configurable Database - Customize database name, version, and store name
Multiple Database Instances - Create separate databases for different purposes
Batch Operations - Get/set/remove multiple items at once
Optional Logging - Configurable console logging for debugging (disabled by default)
TypeScript Ready - Complete TypeScript declarations included
Environment-Aware - Easy configuration for development, staging, and production

🚀 Installation

npm install @amitkhare/indexed-storage

Import

import IndexedStorage from '@amitkhare/indexed-storage';
// or
import { IndexedStorage } from '@amitkhare/indexed-storage';

Basic Usage

// Store data
await IndexedStorage.setItem('username', 'john_doe');
await IndexedStorage.setItem('count', 42);
await IndexedStorage.setItem('user', { name: 'John', age: 30 });

// Retrieve data
const username = await IndexedStorage.getItem('username'); // 'john_doe'
const count = await IndexedStorage.getItem('count'); // 42
const user = await IndexedStorage.getItem('user'); // { name: 'John', age: 30 }

// Check if item exists
if (await IndexedStorage.hasItem('username')) {
  console.log('Username is stored');
}

// Remove item
await IndexedStorage.removeItem('username');

// Clear all data
await IndexedStorage.clear();

⚙️ Configuration

Enable/Disable Logging

By default, IndexedStorage operates silently. You can enable logging for debugging:

// Enable logging for debugging (disabled by default)
IndexedStorage.configure({ enableLogging: true });

// Disable logging
IndexedStorage.configure({ enableLogging: false });

// Check current configuration
const config = IndexedStorage.getConfig();
console.log(config); // { enableLogging: false }

🗄️ Configurable Database Settings

IndexedStorage now supports configurable IndexedDB settings, allowing you to customize the database name, version, and store name for different applications and use cases.

Basic Database Configuration

// Configure custom database settings
IndexedStorage.configure({
  enableLogging: true,
  indexedDB: {
    dbName: 'MyApplication',        // Database name (default: 'LocalStorageDB')
    dbVersion: 2,                   // Database version (default: 1)
    storeName: 'appData'            // Object store name (default: 'localStates')
  }
});

// All subsequent operations use the custom configuration
await IndexedStorage.setItem('user-data', { name: 'John' });

Multiple Database Instances

Create separate database instances for different purposes:

import { useIndexedDB, useStorageManager } from '@amitkhare/indexed-storage';

// User data database
const userDB = useIndexedDB({
  dbName: 'UserData',
  dbVersion: 1,
  storeName: 'users'
});

// Application cache database
const cacheDB = useIndexedDB({
  dbName: 'AppCache',
  dbVersion: 1,
  storeName: 'cache'
});

// Store data in different databases
await userDB.save('profile', { name: 'John', email: 'john@example.com' });
await cacheDB.save('api-data', { response: {...}, timestamp: Date.now() });

Environment-Specific Configuration

const isDevelopment = process.env.NODE_ENV === 'development';

IndexedStorage.configure({
  enableLogging: isDevelopment,
  indexedDB: {
    dbName: isDevelopment ? 'MyApp_Development' : 'MyApp_Production',
    dbVersion: isDevelopment ? 1 : 2,
    storeName: 'appData'
  }
});

📖 See Configurable Database Guide for comprehensive examples and best practices.

📚 API Reference

Core Methods

`getItem(key)`

Retrieves an item from storage.

Returns: The stored value or null if not found

`setItem(key, value)`

Stores an item in storage.

Supports: All JSON-serializable data types

`removeItem(key)`

Removes an item from storage.

`hasItem(key)`

Checks if an item exists in storage.

Returns: true if the key exists

`clear()`

Removes all items from storage.

`getAllKeys()`

Gets all keys from storage.

Returns: Array of all keys

`length()`

Gets the number of items in storage.

Batch Operations

`getMultiple(keys)`

Retrieves multiple items at once.

const data = await IndexedStorage.getMultiple(['user', 'settings']);
// Returns: { user: {...}, settings: {...} }

`setMultiple(items)`

Stores multiple items at once.

await IndexedStorage.setMultiple({
  'user': { name: 'John' },
  'settings': { theme: 'dark' }
});

`removeMultiple(keys)`

Removes multiple items at once.

await IndexedStorage.removeMultiple(['temp1', 'temp2']);

🎯 Usage Examples

Application State

// Save application state
await IndexedStorage.setItem('app-state', {
  currentView: 'dashboard',
  sidebarCollapsed: true,
  activeProject: 'project-123'
});

// Restore state on reload
const appState = await IndexedStorage.getItem('app-state');
if (appState) {
  navigateToView(appState.currentView);
  setSidebarState(appState.sidebarCollapsed);
}

User Preferences

// Save user preferences
await IndexedStorage.setItem('user-preferences', {
  theme: 'dark',
  language: 'en',
  notifications: true
});

// Load preferences on app start
const prefs = await IndexedStorage.getItem('user-preferences');
if (prefs) {
  applyTheme(prefs.theme);
  setLanguage(prefs.language);
}

Caching Data

// Cache API responses
await IndexedStorage.setItem('api-cache-users', {
  data: usersData,
  timestamp: Date.now(),
  expires: Date.now() + (1000 * 60 * 60) // 1 hour
});

// Check cache before API call
const cachedUsers = await IndexedStorage.getItem('api-cache-users');
if (cachedUsers && Date.now() < cachedUsers.expires) {
  return cachedUsers.data;
}

🔧 Error Handling

IndexedStorage includes comprehensive error handling:

try {
  await IndexedStorage.setItem('large-data', massiveObject);
} catch (error) {
  console.error('Failed to store data:', error);
  // Handle storage quota exceeded, etc.
}

// Check availability before using
if (await IndexedStorage.isAvailable()) {
  // Safe to proceed
} else {
  // Fallback to localStorage or other storage
}

🔄 Migration from localStorage

IndexedStorage is designed as a drop-in replacement for localStorage with async operations:

// localStorage (synchronous)
localStorage.setItem('key', JSON.stringify(data));
const data = JSON.parse(localStorage.getItem('key') || '{}');

// IndexedStorage (asynchronous)
await IndexedStorage.setItem('key', data);
const data = await IndexedStorage.getItem('key');

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.