bloom_data library

Client-side data, caching, query, and offline synchronization layer for Bloom applications.

Exports BloomData, BloomQuery, BloomMutation, BloomStorage, the offline mutation queue, HTTP client wrapper, and repository interfaces.

Note: This barrel builds on the reactive Signal type from package:signals_flutter (via src/state/signals.dart), so importing this barrel pulls in package:flutter. It is designed as a dedicated, focused alternative to bloom.dart for client data layers without routing or UI widgets. For Flutter-free server entrypoints, use bloom_server.dart or bloom_core.dart.

Example:

import 'package:bloom_framework/bloom_data.dart';

final userQuery = BloomData.query<User>(
  key: 'user:123',
  fetcher: () => fetchUser(123),
);

Classes

BloomCrudRepository<T, ID>
Generic CRUD repository interface for typed entities composing read and write contracts.
BloomData
Global query cache manager for Bloom Data with automated periodic TTL garbage collection and request deduplication.
BloomHttpClient
HTTP client with environment base URL resolution, JSON codecs, Bearer auth token injection, DevTools tracing, and simulation hooks.
BloomJsonStorage
JSON object storage with optional TTL expiration.
BloomMutation<T, P>
Asynchronous mutation manager with automated optimistic updates, automatic rollback, and cache invalidation.
BloomQuery<T>
A reactive asynchronous query with automatic caching, stale-while-revalidate, and deduplication.
BloomReadOnlyRepository<T, ID>
Lean read-only repository interface for query-only data access (Interface Segregation Principle).
BloomRepository
Base repository pattern class for encapsulating API communication.
BloomStorageAdapter
Abstract storage adapter contract for key-value persistence.
BloomWriteRepository<T, ID>
Lean write-only/mutation repository interface (Interface Segregation Principle).
FileStorageAdapter
File-based storage adapter providing real persistence on disk across application restarts.
InMemoryStorageAdapter
In-memory storage adapter for testing and rapid prototyping.
OfflineMutationQueue
Persistent offline mutation buffer and replay engine.
QueryCacheEntry<T>
A single cached query record containing fetched data, timestamps, and TTL settings.
QueuedMutation
A persisted mutation entry stored in the offline queue waiting to be synced with the server.

Enums

ConflictPolicy
Conflict resolution strategy when replaying offline mutations against the server.
MutationStatus
Lifecycle execution status of a BloomMutation.
QueryStatus
Execution status of a BloomQuery.

Functions

mutation<T, P>({required MutationFn<T, P> mutate, List? optimisticKey, OptimisticUpdater<T, P>? optimisticData, List<List> invalidateKeys = const [], OnMutateCallback<P>? onMutate, OnSuccessCallback<T, P>? onSuccess, OnErrorCallback<P>? onError, OnSettledCallback<T, P>? onSettled}) → BloomMutation<T, P>
Creates a declarative mutation with optional automated optimistic rollback and cache invalidation.
query<T>({required List key, required QueryFetcher<T> fetch, Duration staleTime = const Duration(minutes: 5), Duration cacheTime = const Duration(minutes: 30), bool enabled = true, int retry = 2, Duration retryDelay = const Duration(milliseconds: 500)}) → BloomQuery<T>
Creates a declarative, cached asynchronous query.

Typedefs

CustomConflictResolver = FutureOr<Map<String, dynamic>?> Function(Map<String, dynamic> clientPayload, Object serverError)
Custom conflict resolution handler resolving differences between client payload and server error.
MutationExecutor = Future Function(Map<String, dynamic> payload)
Execution function that sends an offline mutation payload to the server.
MutationFn<T, P> = Future<T> Function(P params)
The asynchronous execution function that performs the mutation operation.
OnErrorCallback<P> = FutureOr<void> Function(Object error, P params, dynamic context)
Hook called when a mutation throws an error.
OnMutateCallback<P> = FutureOr Function(P params)
Hook called immediately prior to executing the mutation, returning an optional context object.
OnSettledCallback<T, P> = FutureOr<void> Function(T? data, Object? error, P params, dynamic context)
Hook called after mutation settled (either succeeded or failed).
OnSuccessCallback<T, P> = FutureOr<void> Function(T data, P params, dynamic context)
Hook called upon successful mutation completion.
OptimisticUpdater<T, P> = T? Function(P params, T? oldData)
Optimistic update transformation function updating cached data prior to network response.
QueryFetcher<T> = Future<T> Function()
Asynchronous data fetcher function for a query.
RequestInterceptor = FutureOr<BaseRequest> Function(BaseRequest request)
Interceptor callback that transforms an outgoing http.BaseRequest before sending.
ResponseInterceptor = FutureOr<Response> Function(Response response)
Interceptor callback that transforms an incoming http.Response before returning to callers.