cellar library

Cross-platform object storage for Flutter.

Construct a Cellar, open it, use it. The same API works on every platform — native filesystem on mobile/desktop, IndexedDB on web — and your app code never branches on platform.

import 'package:cellar/cellar.dart';

final cellar = Cellar(name: 'my_app');
await cellar.open();

await cellar.write('photos/sunset', bytes);
final stream = cellar.readStream('photos/sunset');

// Need a path/URL to hand to non-Dart code? Materialize it.
final handle = await cellar.materialize('photos/sunset');
// handle.localPath: filesystem path on native, blob URL on web
await handle.release();

await cellar.close();

Multi-partition + lifecycle

final cellar = Cellar(
  name: 'my_app',
  partitions: {
    'main': PartitionConfig(),
    'image_cache': PartitionConfig(
      lifecycle: Lifecycle.cache(maxBytes: 100 * 1024 * 1024),
    ),
    'pending_uploads': PartitionConfig(
      lifecycle: Lifecycle.scratch(),
    ),
  },
  defaultPartition: 'main',
  keyPrefix: 'user/$uid',
  encryption: CellarEncryption(encryptor: myEncryptor),
);
await cellar.open();

await cellar.write('thumb/x', smallBytes, partition: 'image_cache');

Custom native path

Use Cellar.atPath when you need a path the standard constructor doesn't resolve itself (Downloads, external storage, iOS Library). Native-only — throws on web.

Custom backend stacks

import 'package:cellar/cellar_lowlevel.dart'; exposes the raw backends and decorators (FileSystemBackend, EncryptedBackend, ChunkedBackend, StorageScope). Compose your own stack and pass it to Cellar.withBackends.

Classes

Cellar
Cross-platform object storage.
CellarEncryption
Encryption configuration for a Cellar.
EncryptionKeyResolver
Resolves encryption keys for file operations.
FileEncryptor
Bring-your-own encryption interface for EncryptedBackend.
Lifecycle
Lifecycle policy attached to a partition.
MaterializedFile
A handle to a stored object made available for non-Dart consumers.
ObjectInfo
Metadata about a stored object.
PartitionConfig
Configuration for a partition in Cellar.
StorageRoots
The two native directories a default-constructed Cellar places partitions under, resolved once per cellar.

Constants

defaultPartitionName → const String
Default partition name used when Cellar is constructed without a partitions: map. Apps that don't need multi-partition storage just use this implicitly.

Functions

validateKey(String key) → void
Validate a storage key.
validatePrefix(String prefix) → void
Validate a prefix used for listing/deleting.

Typedefs

EvictionErrorCallback = void Function(String partition, String? key, Object error)
Callback for eviction failures. key is the victim that could not be deleted, or null when the partition pass itself failed (e.g. the listing errored). Without an observer, a permanently failing delete retries forever with zero visibility.

Exceptions / Errors

ChunkVerificationError
Per-chunk MAC verification failed — chunk has been tampered with or the wrong key was used.
CorruptedFileError
File is corrupted — cannot be read or decrypted.
CorruptedMetadataError
Sidecar metadata is corrupted or unreadable.
EncryptionKeyMissingError
Encryption was requested but no key could be resolved.
FileNotFoundError
File/object not found at the given key.
InvalidHeaderError
The encrypted file header is invalid or from an unsupported version.
InvalidKeyError
The storage key contains invalid characters or structure.
StorageError
Typed error hierarchy for storage operations.
WriteError
A write operation failed (disk full, permission denied, etc.).