syncache library

An offline-first cache and sync engine for Dart applications.

This library exports the complete public API: Syncache (the engine), Store implementations (MemoryStore, SharedMemoryStore), caching Policy variants, reactive streams, optimistic Mutation with a durable MutationOutbox, typed entries (SyncacheEntry), stats (SyncacheStats), and debug tooling (SyncacheDebug).

Flutter integration lives in syncache_flutter; persistent backends in syncache_hive and syncache_drift.

Classes

AlwaysOnline
A Network implementation that always reports online status.
AppendOperation<T>
Appends an item to the end of the list.
BoundedStore<T>
Extended store interface for caches with a bounded capacity.
CacheResult<T>
A cache result containing a value and its metadata.
CacheResultMeta
Metadata about a cache result's source and freshness.
CancellationToken
A token that can be used to cancel asynchronous operations.
ConflictResolver<T>
Decides the final value of a mutation whose Mutation.send threw a SyncacheConflictException (typically an HTTP 409 with the server's current state).
FetchResult<T>
Result of a fetch operation that supports HTTP caching semantics.
InsertOperation<T>
Inserts an item at a specific index.
IterableStore<T>
Extended store interface for stores that can enumerate their keys.
ListOperation<T>
Describes an operation on a cached list.
LoggingObserver
A SyncacheObserver that logs cache operations.
MemoryMutationOutbox
In-memory MutationOutbox shipped with core syncache.
MemoryStore<T>
An in-memory implementation of Store that supports tagging.
Metadata
Metadata associated with a cached entry.
Mutation<T>
Describes an optimistic mutation operation.
MutationDiscarded<T>
The mutation was removed from the queue before the server confirmed it: via Syncache.clearPendingMutations, Syncache.removePendingMutation, or Syncache.dispose.
MutationFailure<T>
The mutation exhausted its retry attempts and was removed from the queue. The optimistic value remains in the cache until the entry is refetched or invalidated.
MutationHandle<T>
A handle for awaiting the server-side outcome of one specific mutation.
MutationOutbox
Persistence backend for pending mutations.
MutationOutcome<T>
The terminal outcome of a submitted optimistic mutation.
MutationResolved<T>
The mutation hit a server-side conflict (SyncacheConflictException thrown from Mutation.send) and the configured ConflictResolver produced the final value.
MutationRetryConfig
Configuration for mutation retry behavior.
MutationSuccess<T>
The server accepted the mutation.
Network
Abstract interface for checking network connectivity status.
PagedViewState<T>
An immutable snapshot of a PaginatedCache's window and fetch state.
PageResult<T>
The result of fetching one page for a PaginatedCache.
PaginatedCache<T>
Infinite-list cache over a Syncache: fetches pages one at a time, accumulates them into a windowed list stored as a normal cached value under key, and exposes it as reactive watch state.
PendingMutationInfo
Information about a pending mutation in the sync queue.
PendingMutationRecord
A persisted, serializable description of a pending mutation.
PrefetchGraphOptions
Options for controlling prefetch graph execution.
PrefetchGraphResult
Result of a prefetch graph execution.
PrefetchNode<T>
A node in a prefetch dependency graph.
PrefetchNodeResult
Result of a single node in a prefetch graph.
PrefetchRequest<T>
A request to prefetch a cache entry.
PrefetchResult
Result of a single prefetch operation.
PrependOperation<T>
Prepends an item to the beginning of the list.
QueryKey
A structured cache key with encoded parameters.
ReactiveNetwork
A Network that also reports connectivity changes.
RemoveWhereOperation<T>
Removes items from the list that match a predicate.
RetryConfig
Configuration for retry behavior on transient failures.
ScopedSyncache<T>
A scoped view of a Syncache instance.
SharedMemoryStore<T>
A Store that shares data across instances with the same namespace.
Store<T>
Abstract interface for cache storage backends.
Stored<T>
A cached value with its associated metadata.
Syncache<T>
An offline-first cache and sync engine for Dart applications.
SyncacheDebug<T>
A debug facade over a Syncache instance for inspecting live cache state in a running app.
SyncacheEntry<T>
A typed view of a single cache key, bound to its fetcher and default cache parameters.
SyncacheObserver
Observer interface for monitoring Syncache operations.
SyncacheRequest
Contains request metadata for fetch operations.
SyncacheStats
An immutable snapshot of Syncache health counters.
TaggableStore<T>
Extended store interface that supports tagging entries.
UpdateWhereOperation<T>
Updates items in the list that match a predicate.

Enums

PendingMutationStatus
Status of a pending mutation.
Policy
Caching policies that determine how Syncache.get retrieves data.
PrefetchNodeStatus
SyncacheCounter
An individual stats counter that can be reset on its own via Syncache.resetStats.

Extensions

QueryKeyStringExtension on String
Extension on String to create QueryKey from string.
SyncacheListExtension on Syncache<List<T>>
Extension providing list-specific mutation helpers for Syncache<List<T>>.

Functions

clientWins<T>() → ConflictResolver<T>
A ConflictResolver that keeps the client's optimistic value: the local unsynced intent wins and is stored over the server's state.
serverWins<T>() → ConflictResolver<T>
A ConflictResolver that keeps the server's value: the local optimistic write is dropped and the cache is refreshed with ConflictResolver.resolve's serverValue.

Typedefs

ConditionalFetcher<T> = Future<FetchResult<T>> Function(SyncacheRequest request)
A fetcher that can return FetchResult to support HTTP 304 Not Modified.
Fetcher<T> = Future<T> Function(SyncacheRequest request)
A function that fetches data of type T from a remote source.

Exceptions / Errors

CacheMissException
Thrown when a cache lookup fails to find a value for the requested key.
CacheMissForConditionalException
Thrown when a conditional fetch returns 304 but no cached value exists.
CancelledException
Exception thrown when an operation is cancelled via CancellationToken.
SyncacheConflictException<T>
Thrown by a mutation's Mutation.send when the server reports that the resource changed concurrently — typically an HTTP 409, or any response that carries the server's current state alongside a version/etag mismatch.
SyncacheException
Base exception class for all Syncache-related errors.