🗜️ NanoStorage

High-performance LocalStorage compression using native CompressionStream API.

Store up to 10x more data in LocalStorage with browser-native GZIP compression. Zero dependencies, under 1KB, non-blocking.

---

✨ Features

Feature	Description
🚀 Native Speed	Uses browser's C++ compression engine, not JavaScript
📦 < 1KB	Minimal footprint, zero dependencies
⚡ Non-Blocking	Stream-based async API prevents UI freezing
🔧 Smart Threshold	Auto-skips compression for small data
📝 TypeScript	Full type definitions included
🎯 Simple API	Just setItem and getItem

---

📊 Performance Comparison

Benchmark Results (5 MB JSON, Chrome)

Metric	NanoStorage	lz-string	Winner
Compress Time	95 ms	1.3 s	🏆 NanoStorage (14x)
Decompress Time	57 ms	67 ms	🏆 NanoStorage
Compressed Size	70 KB	168 KB	🏆 NanoStorage (2.4x)
Compression Ratio	98.6%	96.6%	🏆 NanoStorage

💡 4/4 categories won! 5 MB JSON → 70 KB in 95ms with faster decompression.

Why So Fast?

Feature	lz-string	NanoStorage
Engine	JavaScript (Main Thread)	C++ (Browser Native)
UI Blocking	❌ Yes, freezes on big data	✅ No, async streams
Bundle Size	~18 KB	< 1 KB
Algorithm	LZW (1984)	GZIP/Deflate (Industry Standard)

Real-World Example

📁 Original:     1 MB JSON
   ↓ GZIP:       ~100 KB
   ↓ Base64:     ~133 KB
💾 Final:        133 KB (87% savings!)

---

📦 Installation

npm install @qantesm/nanostorage

yarn add @qantesm/nanostorage

pnpm add @qantesm/nanostorage

---

🚀 Quick Start

import { nanoStorage } from '@qantesm/nanostorage';

// Store data (automatically compressed)
await nanoStorage.setItem('user', {
  name: 'Muhammet',
  preferences: { theme: 'dark', language: 'tr' },
  history: [...largeArray]
});

// Retrieve data (automatically decompressed)
const user = await nanoStorage.getItem('user');
console.log(user.name); // 'Muhammet'

---

📖 API Reference

Default Instance

import { nanoStorage } from '@qantesm/nanostorage';

A pre-configured instance ready to use.

Create Custom Instance

import { createStorage } from '@qantesm/nanostorage';

const storage = createStorage({
  threshold: 500,      // Bytes. Skip compression for smaller data
  algorithm: 'gzip',   // 'gzip' or 'deflate'
  keyPrefix: 'myapp:', // Prefix for all keys
});

Methods

setItem<T>(key: string, value: T): Promise<void>

Store any JSON-serializable value with automatic compression.

await storage.setItem('settings', { theme: 'dark' });
await storage.setItem('items', [1, 2, 3, 4, 5]);
await storage.setItem('count', 42);

getItem<T>(key: string): Promise<T | null>

Retrieve and decompress a stored value.

const settings = await storage.getItem<Settings>('settings');
if (settings) {
  console.log(settings.theme);
}

removeItem(key: string): Promise<void>

Remove an item from storage.

await storage.removeItem('settings');

hasItem(key: string): Promise<boolean>

Check if a key exists.

if (await storage.hasItem('user')) {
  // User data exists
}

keys(): Promise<string[]>

Get all stored keys.

const allKeys = await storage.keys();
// ['user', 'settings', 'cache']

clear(): Promise<void>

Remove all items managed by this instance.

await storage.clear();

getStats(): Promise<StorageStats>

Get compression statistics.

const stats = await storage.getStats();
console.log(`Compression ratio: ${(1 - stats.compressionRatio) * 100}%`);
// "Compression ratio: 85%"

Low-Level Functions

For advanced use cases, you can use the compression functions directly:

import { compress, decompress, isSupported } from '@qantesm/nanostorage';

// Check browser support
if (!isSupported()) {
  console.warn('CompressionStream not available');
}

// Direct compression
const result = await compress({ data: 'large payload' });
console.log(result.data);           // Compressed string
console.log(result.originalSize);   // Original byte size
console.log(result.compressedSize); // Compressed byte size
console.log(result.wasCompressed);  // true if compression was applied

// Direct decompression
const original = await decompress(result.data);

---

🔧 Configuration Options

Option	Type	Default	Description
threshold	number	500	Minimum bytes to trigger compression. Smaller data is stored raw.
algorithm	'gzip' | 'deflate'	'gzip'	Compression algorithm to use.
keyPrefix	string	'ns:'	Prefix added to all storage keys.

Why Threshold?

GZIP adds ~18 bytes of header overhead. For tiny data like { theme: 'dark' }, compression would actually increase size. The threshold ensures only beneficial compressions occur.

---

🌐 Browser Support

Browser	Version	Status
Chrome	80+	✅ Supported
Edge	80+	✅ Supported
Firefox	113+	✅ Supported
Safari	16.4+	✅ Supported
Opera	67+	✅ Supported
IE	All	❌ Not Supported

---

💡 Use Cases

🎮 Game Save Data

await nanoStorage.setItem('gameState', {
  level: 42,
  inventory: [...hundredsOfItems],
  achievements: [...],
  settings: {...}
});

📝 Form Draft Auto-Save

// Save draft as user types
await nanoStorage.setItem('formDraft', formData);

// Restore on page reload
const draft = await nanoStorage.getItem('formDraft');
if (draft) {
  restoreForm(draft);
}

🛒 E-Commerce Cart

await nanoStorage.setItem('cart', {
  items: cartItems,
  lastUpdated: Date.now()
});

📊 Dashboard State (Redux/Vuex)

// Persist state
store.subscribe(() => {
  nanoStorage.setItem('appState', store.getState());
});

// Hydrate on load
const savedState = await nanoStorage.getItem('appState');
if (savedState) {
  store.dispatch({ type: 'HYDRATE', payload: savedState });
}

---

⚠️ Important Notes

Async API

Unlike native localStorage.getItem() which is synchronous, NanoStorage uses Promises:

// ❌ Won't work
const data = nanoStorage.getItem('key');

// ✅ Correct
const data = await nanoStorage.getItem('key');

This is intentional - async operations prevent UI blocking during compression.

Data Must Be JSON-Serializable

// ✅ These work
await storage.setItem('obj', { a: 1 });
await storage.setItem('arr', [1, 2, 3]);
await storage.setItem('str', 'hello');
await storage.setItem('num', 42);
await storage.setItem('bool', true);
await storage.setItem('null', null);

// ❌ These won't work
await storage.setItem('fn', () => {}); // Functions
await storage.setItem('date', new Date()); // Dates (use .toISOString())
await storage.setItem('map', new Map()); // Map/Set (convert to array)

---

🔬 Technical Details

Compression Pipeline

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐     ┌─────────┐
│ JavaScript  │ ──► │ TextEncoder  │ ──► │ CompressionStream│ ──► │ Base64  │
│ Object      │     │ (UTF-8)      │     │ (Native GZIP)   │     │ String  │
└─────────────┘     └──────────────┘     └─────────────────┘     └─────────┘

Decompression Pipeline

┌─────────┐     ┌───────────────────┐     ┌──────────────┐     ┌─────────────┐
│ Base64  │ ──► │ DecompressionStream│ ──► │ TextDecoder  │ ──► │ JavaScript  │
│ String  │     │ (Native GZIP)     │     │ (UTF-8)      │     │ Object      │
└─────────┘     └───────────────────┘     └──────────────┘     └─────────────┘

Storage Format

Compressed data is prefixed with a marker byte:

• R - Raw (uncompressed) data
• G - GZIP compressed
• D - Deflate compressed

---

📄 License

MIT © Muhammet Ali Büyük

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

---

🔗 Links

• NPM Package
• GitHub Repository
• Issue Tracker