blossom_cache

A network-free local Blossom blob store for Dart. Same code runs on web, native, and server.

Blobs are addressed by their sha256 hash. The cache computes the hash from the bytes by default; callers that already have one (e.g. from a Blossom server response, or from a faster platform digest like crypto.subtle.digest on web) can pass it via the sha256: parameter to skip the computation. Supplied hashes are trusted as-is and not verified.

Usage

Pick the IdbFactory for your target, then open the cache:

import 'dart:typed_data';
import 'package:blossom_cache/blossom_cache.dart';

// Web
import 'package:idb_shim/idb_browser.dart';
final cache = await IdbBlossomCache.open(factory: idbFactoryBrowser);

// Native / server (persistent on disk via sembast)
import 'package:idb_shim/idb_io.dart';
final cache = await IdbBlossomCache.open(factory: idbFactorySembastIo);

// Tests / ephemeral
import 'package:idb_shim/idb_client_memory.dart';
final cache = await IdbBlossomCache.open(factory: newIdbFactoryMemory());

Then:

// Hash computed by the cache:
final descriptor = await cache.put(bytes, type: 'image/png');
final sha = descriptor.sha256;

// Or, when you already have it:
await cache.put(bytes, sha256: sha, type: 'image/png');

final read = await cache.get(sha);    // Uint8List?, updates lastAccessedAt
final meta = await cache.head(sha);   // BlobDescriptor?, metadata only
final all  = await cache.list();      // List<BlobDescriptor>
await cache.delete(sha);              // bool, manual delete

await cache.pin(sha);                 // protect from future auto-eviction
await cache.unpin(sha);
await cache.pin(sha, by: 'chat');     // pin on behalf of a holder
await cache.unpinAll('chat');         // release every pin that holder has

await cache.clearAllLocalData();      // wipe everything, pinned included

clearAllLocalData leaves the cache open and usable, so it fits a "clear cache" button or a logout flow:

Future<void> logout() async {
  await cache.clearAllLocalData();
  // ... then the rest of your session cleanup
}

Bounded cache (LRU eviction)

Wrap any BlossomCache in a BoundedBlossomCache to cap total size. When a put would exceed the limit, the decorator evicts blobs by lastAccessedAt ascending (LRU), skipping pinned blobs:

final cache = BoundedBlossomCache(
  inner: await IdbBlossomCache.open(factory: idbFactoryBrowser),
  maxSize: 500 * 1024 * 1024, // 500 MB
);

If the cache cannot make enough room (a single blob is bigger than maxSize, or every remaining blob is pinned), put throws BlossomCacheOverflowException and the cache is left unchanged.

Pinning

A blob can be pinned by several holders. BoundedBlossomCache will not auto-evict a blob while at least one holder pins it. Manual delete ignores pins and always removes the blob.

A holder is any string you choose: a feature name, an account pubkey, etc. pin and unpin use BlossomCache.defaultHolder when none is given, which is enough for a single consumer.

// Avatar, evictable
await cache.put(avatarBytes, type: 'image/png');

// Important file, never auto-evicted while 'chat' holds it
await cache.put(fileBytes, type: 'application/pdf', pinBy: 'chat');

// Another feature needs it too
await cache.pin(fileSha, by: 'drafts');

// 'chat' lets go, the blob stays pinned by 'drafts'
await cache.unpin(fileSha, by: 'chat');

Holders make per-account logout possible without touching other accounts:

Future<void> logout(String pubkey) async {
  await cache.unpinAll(pubkey); // blobs no one else pins become evictable
}

Re-putting a blob keeps its existing holders. BlobDescriptor.pinnedBy lists them and BlobDescriptor.pinned is true when that set is not empty.

Custom backends

BlossomCache is an abstract class. Implement it against any storage you like (disk, OPFS, S3, ...). The interface is intentionally small: put, get, head, delete, pin, unpin, unpinAll, list, clearAllLocalData.