Storage

Storage adapters persist cache data across sessions via the StorageManager.

StorageAdapter Interface

All storage adapters must implement this interface:

interface StorageAdapter {
  readonly name: string;
 
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  delete(key: string): Promise<void>;
  clear(): Promise<void>;
  has(key: string): Promise<boolean>;
 
  keys(): Promise<string[]>;
  getSize(): Promise<number>;
  getUsage(): Promise<StorageUsage>;
 
  initialize(): Promise<void>;
  dispose(): Promise<void>;
  isReady(): boolean;
}

Usage

import { StorageManager, createMemoryAdapter } from '@soulcache/core';
 
const storage = new StorageManager({
  adapter: createMemoryAdapter(),
  prefix: 'soulcache',
});
 
await storage.initialize();

Built-in Adapters

Adapter	Description
`MemoryAdapter`	Default in-memory storage, suitable for most use cases

Custom Adapters

Implement the StorageAdapter interface to create custom adapters:

import type { StorageAdapter } from '@soulcache/core';
 
const customAdapter: StorageAdapter = {
  name: 'custom',
  async get(key) { /* ... */ },
  async set(key, value) { /* ... */ },
  async delete(key) { /* ... */ },
  async clear() { /* ... */ },
  async has(key) { /* ... */ },
  async keys() { /* ... */ },
  async getSize() { /* ... */ },
  async getUsage() { /* ... */ },
  async initialize() { /* ... */ },
  async dispose() { /* ... */ },
  isReady() { return true; },
};

Features

Pluggable Backends

Swap storage adapters without changing application code

Automatic Serialization

Data is automatically serialized/deserialized for storage

Error Handling

Graceful fallback when storage is unavailable

Quota Management

Automatic monitoring and management of storage limits

Best Practices

Storage Guidelines

Choose the right adapter — Consider performance and persistence needs
Handle errors — Storage may be unavailable in some environments
Monitor quota — Avoid exceeding storage limits
Use compression — For large datasets