🚀 Pocketstore

A lightweight, type-safe storage library for browser and Node.js environments with support for namespacing, TTL, and basic obfuscation.

✨ Features

• 🌐 Works in both browser and Node.js/SSR environments
• 🔒 Optional basic obfuscation support (not encryption)
• ⏰ Time-To-Live (TTL) support
• 🏷️ Namespace support to prevent key collisions
• 💾 Automatic fallback to memory storage in non-browser environments
• 🧹 Automatic cleanup of expired items
• 📦 Zero dependencies
• 🔍 Type-safe with TypeScript support

📦 Installation

1# Using npm
2npm install @m4dm4x/pocketstore
3
4# Using yarn
5yarn add @m4dm4x/pocketstore
6
7# Using pnpm
8pnpm add @m4dm4x/pocketstore

🎯 Use Cases

1. User Preferences & Settings

Perfect for storing user preferences, theme settings, or UI state that should persist across page reloads:

1const settingsStore = createStore<{theme: string, fontSize: number}>('settings');
2settingsStore.set('userPrefs', { theme: 'dark', fontSize: 14 });

2. Form Data Auto-Save

Automatically save form data to prevent loss during accidental page refreshes:

1const formStore = createStore('forms', { autoCleanup: true });
2formStore.set('draft', formData, 3600); // Auto-expires after 1 hour

3. API Response Caching

Cache API responses with automatic expiration:

1const cacheStore = createStore('api-cache', { autoCleanup: true });
2cacheStore.set('user-data', apiResponse, 300); // Cache for 5 minutes

4. Session Management

Handle session data with automatic cleanup:

1const sessionStore = createStore('session', {
2  storage: 'session',
3  autoCleanup: true
4});
5sessionStore.set('auth', { token: '...', user: '...' }, 1800); // 30 minutes

5. Multi-Tab Communication

Store data that needs to be shared between browser tabs:

1const sharedStore = createStore('shared');
2sharedStore.set('notification', { message: 'New update!' });

🔒 Security Considerations

1. Data Sensitivity

   • Use obfuscate: true only for non-sensitive data
   • Do NOT store sensitive information (passwords, tokens) without proper encryption
   • Consider using Web Crypto API for sensitive data

2. TTL & Cleanup

   • Use TTL for temporary data (e.g., cache, sessions)
   • Enable autoCleanup to automatically remove expired items
   • Manually call clear() when handling sensitive data

3. Storage Limitations

   • Be aware of browser storage limits (usually 5-10MB)
   • Handle storage quota exceeded errors
   • Use compression for large data sets

🚀 Performance Tips

1. Storage Type

   • Use localStorage for persistent data
   • Use sessionStorage for temporary session data
   • Memory storage is automatically used in SSR

2. Automatic Cleanup

   • Enable autoCleanup only when necessary
   • Large stores might benefit from manual cleanup
   • Use appropriate TTL values to prevent storage bloat

3. Data Size

   • Store minimal necessary data
   • Consider compressing large objects
   • Use namespaces to organize and manage data

🌐 Browser Compatibility

Feature	Chrome	Firefox	Safari	Edge	IE11
Basic Storage	✅	✅	✅	✅	✅
TTL Support	✅	✅	✅	✅	✅
Obfuscation	✅	✅	✅	✅	✅
TypeScript	✅	✅	✅	✅	✅
SSR Support	✅	✅	✅	✅	✅

📊 Comparison with Other Libraries

Feature	Pocketstore	localforage	store.js	js-cookie
Size (min+gzip)	2KB	8KB	2KB	1KB
API Type	Promise-free	Promise-based	Sync	Sync
Storage Types	localStorage, sessionStorage, memory	IndexedDB, WebSQL, localStorage	localStorage, memory	Cookies
TypeScript	✅ Native	⚠️ Types available	⚠️ Types available	⚠️ Types available
SSR Support	✅ Built-in	❌ Requires setup	✅ Built-in	✅ Built-in
Namespacing	✅ Built-in	❌ Manual	❌ Manual	✅ Built-in
TTL Support	✅ Built-in	❌ Manual	❌ Manual	✅ Built-in
Auto Cleanup	✅ Built-in	❌ No	❌ No	✅ Built-in
Type Safety	✅ Full	⚠️ Partial	⚠️ Partial	⚠️ Partial
Browser Support	Modern + IE11	Modern only	Modern + IE8	All browsers

Why Choose Pocketstore?

1. Simplicity First

   • No dependencies
   • Synchronous API (no Promises)
   • Intuitive TypeScript support

2. Modern Features

   • Built-in TTL support
   • Automatic cleanup
   • Type-safe by default

3. Universal Usage

   • Works in browsers
   • Works in Node.js/SSR
   • Works in all modern frameworks

4. Developer Experience

   • Full TypeScript support
   • Comprehensive documentation
   • Active maintenance

🚀 Quick Start

1import { createStore } from '@m4dm4x/pocketstore';
2
3// Create a store with a namespace
4const store = createStore('myapp');
5
6// Store a value
7store.set('user', { name: 'John', age: 30 });
8
9// Get a value
10const user = store.get('user'); // { name: 'John', age: 30 }
11
12// Remove a value
13store.remove('user');
14
15// Clear all values in the namespace
16store.clear();

💡 Usage Examples

Basic Usage

1const store = createStore('myapp');
2
3// Set and get values
4store.set('theme', 'dark');
5const theme = store.get('theme'); // 'dark'
6
7// Remove values
8store.remove('theme');
9const removedTheme = store.get('theme'); // null

With TTL (Time-To-Live)

1const store = createStore('myapp');
2
3// Set a value that expires in 60 seconds
4store.set('token', '123456', 60);
5
6// Value is available until TTL expires
7const token = store.get('token'); // '123456'
8
9// After 60 seconds:
10const expiredToken = store.get('token'); // null

With Basic Obfuscation

1const store = createStore('myapp', {
2  obfuscate: true,
3  secret: 'your-secret-key'
4});
5
6// Values are automatically obfuscated before storage
7store.set('data', { apiKey: '12345' });
8
9// Values are automatically deobfuscated when retrieved
10const data = store.get('data'); // { apiKey: '12345' }

⚠️ Security Note: The obfuscation feature is NOT encryption and should NOT be used for sensitive data. It provides basic obfuscation only and is suitable for non-sensitive data that you want to make slightly harder to read in the browser's dev tools.

With Automatic Cleanup

1const store = createStore('myapp', {
2  autoCleanup: true // Enable automatic cleanup
3});
4
5// Set some values with TTL
6store.set('temp1', 'value1', 1); // Expires in 1 second
7store.set('temp2', 'value2', 60); // Expires in 60 seconds
8
9// After 2 seconds:
10store.getAll(); // Automatically cleans up expired items
11// Returns: { temp2: 'value2' }

Using Different Storage Types

1// Use localStorage (default)
2const localStore = createStore('myapp');
3
4// Use sessionStorage
5const sessionStore = createStore('myapp', {
6  storage: 'session'
7});

Namespacing

1// Create stores with different namespaces
2const userStore = createStore('users');
3const settingsStore = createStore('settings');
4
5// Values don't conflict even with the same key
6userStore.set('data', { name: 'John' });
7settingsStore.set('data', { theme: 'dark' });
8
9userStore.get('data'); // { name: 'John' }
10settingsStore.get('data'); // { theme: 'dark' }

Advanced Usage

1const store = createStore('myapp');
2
3// Check if a key exists
4store.has('user'); // true/false
5
6// Get all keys
7const keys = store.keys(); // ['user', 'theme', ...]
8
9// Get all values
10const all = store.getAll(); // { user: {...}, theme: 'dark', ... }
11
12// Initialize store (cleans up expired items if autoCleanup is enabled)
13store.init();

🔧 API Reference

createStore<T>(namespace: string, options?: StoreOptions)

Creates a new store instance.

Parameters

• namespace: String to prefix all keys with
• options: Configuration object (optional)
  • storage: Storage type ('local' | 'session')
  • obfuscate: Enable basic obfuscation (boolean)
  • secret: Obfuscation secret key (required if obfuscate is true)
  • autoCleanup: Enable automatic cleanup of expired items (boolean)

Returns

Object with methods:

• set(key: string, value: T, ttlSeconds?: number): void
• get(key: string): T | null
• remove(key: string): void
• clear(): void
• has(key: string): boolean
• keys(): string[]
• getAll(): Record<string, T>
• init(): void

🔐 Type Safety

The library includes TypeScript definitions out of the box:

1import { createStore } from '@m4dm4x/pocketstore';
2
3interface UserData {
4  name: string;
5  age: number;
6}
7
8const store = createStore<UserData>('myapp');
9store.set('user', { name: 'John', age: 30 });
10const user = store.get('user'); // Type is UserData | null

🌐 SSR Support

The library automatically falls back to in-memory storage when running in Node.js or SSR environments, making it safe to use in server-side rendered applications.

📝 License

ISC

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

🌟 Show your support

Give a ⭐️ if this project helped you!