Quick Start Guide

Installation

npm install tiered-storage
# or
bun add tiered-storage

Basic Usage

import { TieredStorage, MemoryStorageTier, DiskStorageTier, S3StorageTier } from 'tiered-storage';

const storage = new TieredStorage({
  tiers: {
    hot: new MemoryStorageTier({ maxSizeBytes: 100 * 1024 * 1024 }),
    warm: new DiskStorageTier({ directory: './cache' }),
    cold: new S3StorageTier({
      bucket: 'my-bucket',
      region: 'us-east-1',
    }),
  },
  compression: true,
  defaultTTL: 14 * 24 * 60 * 60 * 1000, // 14 days
});

// Store data
await storage.set('user:123', { name: 'Alice' });

// Retrieve data
const user = await storage.get('user:123');

// Invalidate by prefix
await storage.invalidate('user:');

Selective Tier Placement

Control which tiers receive specific files:

// Critical file - store in all tiers
await storage.set('index.html', htmlContent);

// Large file - skip hot tier to save memory
await storage.set('video.mp4', videoData, {
  skipTiers: ['hot']
});

Bootstrap on Startup

// Warm up hot tier from warm tier
await storage.bootstrapHot(1000); // Load top 1000 items

// Warm up warm tier from cold tier
await storage.bootstrapWarm({
  sinceDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
  limit: 10000,
});

Statistics & Monitoring

const stats = await storage.getStats();
console.log('Hot tier:', stats.hot);
console.log('Warm tier:', stats.warm);
console.log('Cold tier:', stats.cold);
console.log('Hit rate:', stats.hitRate);

API Reference