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.

Install

dependencies:
  blossom_cache: ^0.1.0
  idb_shim: ^2.9.2

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);

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

Each blob has a pinned flag. BoundedBlossomCache will not auto-evict pinned blobs. Manual delete ignores the flag and always removes the blob.

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

// Important file, never auto-evicted
await cache.put(fileBytes, type: 'application/pdf', pinned: true);

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, list.