Browser storage for ArkhamJS with enhanced performance and modern ESNext features
npm install @nlabs/arkhamjs-storage-browserEnhanced browser storage for ArkhamJS with modern ESNext features, performance optimizations, and advanced caching capabilities.
- 🚀 High Performance: In-memory caching and optimized storage operations
- 🔒 Type Safe: Full TypeScript support with strict type checking
- 🎯 Modern ESNext: Built with latest JavaScript features (ES2022+)
- 📦 Tree Shakeable: Optimized for bundle size reduction
- ⚡ Smart Caching: Automatic cache management with TTL support
- 🛡️ Error Resilient: Graceful handling of storage errors and quota limits
- 🔧 Configurable: Flexible options for prefix, compression, and size limits
- 📊 Monitoring: Built-in storage statistics and usage tracking
``bash`
npm install @nlabs/arkhamjs-storage-browser
`typescript
import { BrowserStorage } from '@nlabs/arkhamjs-storage-browser';
// Create storage instance with default settings
const storage = new BrowserStorage();
// Store data
await storage.setStorageData('user', { id: 1, name: 'John' });
// Retrieve data
const user = await storage.getStorageData('user');
console.log(user); // { id: 1, name: 'John' }
`
`typescript
import { BrowserStorage } from '@nlabs/arkhamjs-storage-browser';
const storage = new BrowserStorage({
type: 'local', // 'local' or 'session' storage
prefix: 'myapp_', // Custom key prefix
compression: true, // Enable compression for large data
maxSize: 10 1024 1024, // 10MB size limit
ttl: 60 60 1000 // 1 hour time-to-live
});
`
`typescript
import { Flux } from '@nlabs/arkhamjs';
import { BrowserStorage } from '@nlabs/arkhamjs-storage-browser';
const storage = new BrowserStorage({
type: 'local',
prefix: 'myapp_',
ttl: 24 60 60 * 1000 // 24 hours
});
// Initialize ArkhamJS with storage
await Flux.init({
name: 'myapp',
storage,
stores: [/ your stores /]
});
`
`typescript`
interface BrowserStorageOptions {
type?: 'local' | 'session'; // Storage type (default: 'session')
prefix?: string; // Key prefix (default: 'arkhamjs_')
compression?: boolean; // Enable compression (default: false)
maxSize?: number; // Max size in bytes (default: 5MB)
ttl?: number; // Time-to-live in ms (default: 24h)
}
#### getStorageData(key: string): Promise
Retrieves data from storage with caching and TTL validation.
`typescript`
const data = await storage.getStorageData('user');
#### setStorageData(key: string, value: any): Promise
Stores data with validation, compression, and automatic cleanup.
`typescript`
const success = await storage.setStorageData('user', { id: 1, name: 'John' });
#### removeStorageData(key: string): Promise
Removes specific data from storage.
`typescript`
const success = await storage.removeStorageData('user');
#### clearStorageData(): Promise
Clears all data with the configured prefix.
`typescript`
const success = await storage.clearStorageData();
#### getStorageStats(): { used: number; available: number; total: number }
Returns storage usage statistics.
`typescriptUsed: ${stats.used} bytes, Available: ${stats.available} bytes
const stats = storage.getStorageStats();
console.log();`
For backward compatibility, static methods are still available:
`typescript
// Local storage
BrowserStorage.setLocalData('key', value);
const data = BrowserStorage.getLocalData('key');
BrowserStorage.delLocalData('key');
// Session storage
BrowserStorage.setSessionData('key', value);
const data = BrowserStorage.getSessionData('key');
BrowserStorage.delSessionData('key');
// Storage instances
const localStorage = BrowserStorage.getLocalStorage();
const sessionStorage = BrowserStorage.getSessionStorage();
`
The storage automatically caches frequently accessed data in memory for faster retrieval:
`typescript
// First call - reads from storage
const user1 = await storage.getStorageData('user');
// Second call - served from cache (much faster)
const user2 = await storage.getStorageData('user');
`
Expired data is automatically cleaned up to prevent storage bloat:
`typescript
const storage = new BrowserStorage({
ttl: 60 60 1000 // 1 hour
});
// Data will be automatically removed after 1 hour
await storage.setStorageData('temp', 'data');
`
Large data is validated before storage to prevent quota errors:
`typescript
const storage = new BrowserStorage({
maxSize: 1024 * 1024 // 1MB limit
});
// This will fail if data exceeds 1MB
const success = await storage.setStorageData('large', bigData);
if (!success) {
console.log('Data too large for storage');
}
`
The storage gracefully handles various error conditions:
`typescript`
try {
const data = await storage.getStorageData('key');
if (data === null) {
console.log('Data not found or expired');
}
} catch (error) {
console.error('Storage error:', error);
}
Common error scenarios handled automatically:
- Storage not available (private browsing, etc.)
- Quota exceeded
- Corrupted data
- Invalid JSON
The new version is fully backward compatible. Existing code will continue to work:
`typescript
// Old code - still works
const storage = new BrowserStorage({ type: 'session' });
await storage.setStorageData('key', value);
const data = await storage.getStorageData('key');
// New features available
const stats = storage.getStorageStats();
await storage.removeStorageData('key');
await storage.clearStorageData();
`
For better performance, consider these updates:
`typescript
// Before
const storage = new BrowserStorage({ type: 'session' });
// After - with optimizations
const storage = new BrowserStorage({
type: 'local', // Use localStorage for persistence
prefix: 'myapp_', // Custom prefix for organization
ttl: 24 60 60 * 1000, // 24 hour TTL
maxSize: 10 1024 1024 // 10MB limit
});
``
- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+
- Minified: ~3.2KB
- Gzipped: ~1.1KB
- Tree-shakeable: Only includes what you use
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
MIT License - see LICENSE file for details.