@suaveplan/cache-storage - AbstractCache backend that bridges any @suaveplan/storage AbstractStorage into a typed cache via a 32-byte fixed-width TTL header and pluggable Codec (JSON default, identity for Uint8Array).

AbstractCache<T> backend that bridges any @suaveplan/storage AbstractStorage into a typed cache via a 32-byte fixed-width TTL header and pluggable Codec<T> (JSON default, identity for Uint8Array).

Documentation tree

identity — IdentityCodec is the Codec<Uint8Array> implementation that passes bytes through without encoding overhead. Use it w…
json — JsonCodec<T> is the default codec for StorageCache. It serialises arbitrary JSON-compatible values to UTF-8 bytes v…
errors — Defines the structured error surface for @suaveplan/cache-storage. Every failure path inside the package — corrupt bl…
- errors — Defines the structured error surface for @suaveplan/cache-storage. Every failure path inside the package — corrupt bl…
header — Defines the 32-byte fixed-width metadata header that StorageCache prepends to every cached value. The header carries…
- header — Defines the 32-byte fixed-width metadata header that StorageCache prepends to every cached value. The header carries…
registry-augment — Augments the CacheProviderRegistry type exported by @suaveplan/cache with a storage entry, and side-effect-regist…
- registry-augment — Augments the CacheProviderRegistry type exported by @suaveplan/cache with a storage entry, and side-effect-regist…
storage-cache — StorageCache<T> extends AbstractCache<T> from @suaveplan/cache and turns any AbstractStorage (from `@suaveplan/…
- storage-cache — StorageCache<T> extends AbstractCache<T> from @suaveplan/cache and turns any AbstractStorage (from `@suaveplan/…

Summary

@suaveplan/cache-storage is the universal cache backend for the cache family. It composes any byte-oriented storage adapter — MemoryStorage, storage-browser-localstorage, storage-browser-indexeddb, storage-browser-opfs, storage-file, storage-s3, storage-cdn-* — into a typed cache with TTL, lifecycle events, namespacing, and structured errors. The package subsumes the upstream cache-browser package by composition: pick the storage adapter that matches your environment, and the cache surface is identical to MemoryCache. Side-effect import auto-registers StorageCache as the "storage" provider on CacheFactory, so createCache("storage", { storage }) works after a single import.

Installation

bun add @suaveplan/cache-storage

Quick Start

import { StorageCache } from "@suaveplan/cache-storage";
import { MemoryStorage } from "@suaveplan/storage/memory";

const cache = new StorageCache<{ id: string; email: string }>({
  storage: new MemoryStorage(),
  defaultTtl: 5 * 60_000,
});

await cache.set("user:1", { id: "1", email: "alice@example.com" });
const user = await cache.get("user:1");

Modules

errors — CACHE_STORAGE_CODES, StorageCacheError.
header — 32-byte fixed-width metadata header codec.
codec/identity — IdentityCodec for Uint8Array values.
codec/json — JsonCodec<T> default codec.
storage-cache — StorageCache<T> class.
registry-augment — CacheProviderRegistry augmentation + auto-registration.

Browser-side caching (replaces `cache-browser`)

import { StorageCache } from "@suaveplan/cache-storage";
import { LocalStorageStorage } from "@suaveplan/storage-browser-localstorage";

const cache = new StorageCache<string>({
  storage: new LocalStorageStorage(),
  namespace: "ui:preferences",
  defaultTtl: 7 * 24 * 60 * 60_000,
});

The same pattern works over storage-browser-indexeddb (larger payloads) and storage-browser-opfs (file-grade durability).

Factory registration

import "@suaveplan/cache-storage"; // side-effect: register provider
import { createCache } from "@suaveplan/cache";
import { MemoryStorage } from "@suaveplan/storage/memory";

const cache = createCache("storage", { storage: new MemoryStorage() });

Dependencies

Dependency	Purpose
`@suaveplan/cache`	`AbstractCache<T>`, `CacheFactory`, `CacheProviderRegistry`, `CacheEvents`, `CacheSetOptions`.
`@suaveplan/error`	`defineCodes`, `SuaveplanError`.
`@suaveplan/storage`	`AbstractStorage` contract.
`@suaveplan/types`	`EventBusLike`.
`tslib`	TypeScript helpers.

5.0 KiB Raw Blame History