DatumManager<T extends DatumEntityInterface> class

Mixed-in types
Available extensions

Constructors

DatumManager({required LocalAdapter<T> localAdapter, required RemoteAdapter<T> remoteAdapter, DatumConflictResolver<T>? conflictResolver, required DatumConnectivityChecker connectivity, DatumConfig<T>? datumConfig, DatumLogger? logger, List<DatumObserver<T>>? localObservers, List<DatumMiddleware<T>>? middlewares, List<GlobalDatumObserver>? globalObservers, DatumSyncRequestStrategy? syncRequestStrategy, String? deviceId, DatumPersistence? persistence, Stream<String?>? userChangeStream})

Properties

coldStartManager → ColdStartManager
Exposes the cold start manager for testing purposes.
no setter
config → DatumConfig<T>
final
currentStatus → DatumSyncStatusSnapshot
The most recent snapshot of the manager's sync status.
no setter
deviceId → String?
final
eventStream → Stream<DatumSyncEvent<T>>
Public event streams
no setter
hashCode → int
The hash code for this object.
no setterinherited
health → Stream<DatumHealth>
A stream of the manager's current health status.
no setter
isDisposed → bool
Returns true if the object has been disposed.
no setterinherited
isInitialized → bool
no setter
isSubscribedToRemoteChanges → bool
Whether the manager is currently subscribed to remote change events.
no setter
localAdapter → LocalAdapter<T>
final
onConflict → Stream<ConflictDetectedEvent<T>>
no setter
onDataChange → Stream<DataChangeEvent<T>>
no setter
onNextSyncTimeChanged → Stream<DateTime?>
no setter
onSyncCompleted → Stream<DatumSyncCompletedEvent<T>>
no setter
onSyncError → Stream<DatumSyncErrorEvent<T>>
no setter
onSyncProgress → Stream<DatumSyncProgressEvent<T>>
no setter
onSyncStarted → Stream<DatumSyncStartedEvent<T>>
no setter
onUserChanged → Stream<String?>
A stream that emits when the active user changes for this manager. Reactive queries can listen to this to refresh their data when users switch.
no setter
onUserSwitched → Stream<UserSwitchedEvent<T>>
no setter
persistence → DatumPersistence?
final
queueManager → QueueManager<T>
Exposes the queue manager for central orchestration.
no setter
remoteAdapter → RemoteAdapter<T>
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
statusStream → Stream<DatumSyncStatusSnapshot>
A stream of the manager's sync status snapshots.
no setter
watchNextSyncDuration → Stream<Duration?>
A stream that emits the Duration until the next scheduled auto-sync.
no setter
watchNextSyncTime → Stream<DateTime?>
The most recent snapshot of the manager's sync status.
no setter

Methods

cascadeDelete({required String id, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false}) → Future<CascadeDeleteResult<T>>
Deletes an entity with cascading behavior based on relationship configurations.
checkHealth() → Future<DatumHealth>
Performs a health check on the local and remote adapters and updates the health stream with the result.
clearCaches() → void
Clears all caches. Useful for testing or when data consistency is critical.
clearRelationshipCacheForType(Type entityType) → void
Clears relationship caches for a specific entity type.
count({DatumQuery? query, DataSource source = DataSource.local, String? userId}) → Future<int>
Counts entities matching an optional query.
delete({required String id, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false, DeleteBehavior? behavior}) → Future<bool>
Deletes an entity by its ID from all local and remote adapters.
deleteAndSync({required String id, required String userId, DatumSyncOptions<T>? syncOptions, DeleteBehavior? behavior}) → Future<(bool, DatumSyncResult<T>)>
Deletes an entity locally and immediately triggers a synchronization.
deleteCascade(String entityId) → CascadeDeleteBuilder<T>
Creates a fluent API builder for cascade delete operations.
deleteMany(List<String> ids, {required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false, DeleteBehavior? behavior}) → Future<List<String>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Deletes multiple entities by ids in one call, returning the ids that were actually removed (a batch convenience over delete).
dispose() → Future<void>
Releases all resources held by the manager and its adapters.
override
ensureNotDisposed() → void
Throws a StateError if the object has been disposed.
inherited
executeCascadeDeleteWithOptions(String entityId, String userId, CascadeOptions options) → Future<CascadeResult<T>>
Executes cascade delete with enhanced options (dry-run, progress, etc.).
exists(String id, {String? userId}) → Future<bool>
Returns whether an entity with id exists in local storage.
fetch(DatumQuery query, {DataFetchStrategy strategy = DataFetchStrategy.localFirst, String? userId, bool persistRemoteResults = false}) → Future<List<T>>
Runs query using a DataFetchStrategy, removing the repetitive "try local, then fall back to remote" boilerplate (#17).
fetchById(String id, {DataFetchStrategy strategy = DataFetchStrategy.localFirst, String? userId, List<String> withRelated = const [], bool persistRemoteResults = false}) → Future<T?>
Reads a single entity by id using a DataFetchStrategy.
fetchRelated<R extends DatumEntityInterface>(T parent, String relationName, {DataSource source = DataSource.local}) → Future<List<R>>
DEPRECATED: This method will be removed in a future version. Use the withRelated parameter in the query method for eager loading, or the fetch() method on the relation object for lazy loading. Fetches related entities for a given parent entity.
getCacheStats() → Map<String, int>
Gets cache statistics for monitoring and debugging.
getDeletePlan(String id, {String? userId}) → Future<CascadeDeletePreview?>
Returns a visualization of the delete plan for the given entity. This is useful for previewing what will happen before deleting.
getLastSyncResult(String userId) → Future<DatumSyncResult<T>?>
Retrieves the result of the last synchronization for a user from local storage.
getNextSyncDuration() → Future<Duration?>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Gets the Duration until the next scheduled auto-sync as a Future.
getNextSyncTime() → Future<DateTime?>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Gets the DateTime of the next scheduled auto-sync as a Future.
getPendingCount(String userId) → Future<int>
Returns the number of pending synchronization operations for the user.
getPendingOperations(String userId) → Future<List<DatumSyncOperation<T>>>
Returns a list of pending synchronization operations for the user.
getRemoteSyncMetadata(String userId) → Future<DatumSyncMetadata?>
Fetches sync metadata from the remote server for this entity type.
getStorageSize({String? userId}) → Future<int>
Gets the current storage size in bytes from the local adapter.
initialize() → Future<void>
Initializes the manager and its adapters. Must be called before any other methods.
invalidateMetadataHash(String userId) → void
Invalidates the cached sync-metadata content hash for userId.
manageController(StreamController controller) → void
Registers a StreamController to be automatically closed on dispose.
inherited
manageSubscription(StreamSubscription subscription) → void
Registers a StreamSubscription to be automatically cancelled on dispose.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pauseSync() → void
Pauses all synchronization activity for this manager.
performDeleteWithoutEvents({required String id, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false}) → Future<bool>
Performs a delete without firing events (used internally for cascading).
push({required T item, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false}) → Future<T>
pushAndSync({required T item, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false, DatumSyncOptions<T>? syncOptions, DatumSyncScope? scope}) → Future<(T, DatumSyncResult<T>)>
Saves an entity locally and immediately triggers a synchronization.
query(DatumQuery query, {DataSource source = DataSource.local, String? userId, bool includeDeleted = false}) → Future<List<T>>
rawQuery(DatumRawQuery query, {DataSource source = DataSource.local, String? userId}) → Future<List<DatumRawRow>>
Executes an adapter-aware raw query for projections/aggregations without hydrating entities (#11), dispatching to the local or remote adapter.
read(String id, {String? userId, List<String> withRelated = const [], bool includeDeleted = false}) → Future<T?>
Reads a single entity by its ID from the primary local adapter. Reads a single entity by its ID from the primary local adapter.
readAll({String? userId, List<String> withRelated = const [], bool includeDeleted = false}) → Future<List<T>>
Reads all entities from the primary local adapter.
refreshStreams() → Future<void>
Refreshes all reactive streams by clearing caches and forcing streams to re-evaluate their data. This is useful when external state changes (like user switches) require all streams to refresh their data.
resubscribeToRemoteChanges() → Future<void>
Re-subscribes to remote change events.
resumeSync() → void
Resumes synchronization activity for this manager.
saveMany({required List<T> items, required String userId, bool andSync = false, DataSource source = DataSource.local, bool forceRemoteSync = false, DatumSyncOptions<T>? syncOptions, DatumSyncScope? scope}) → Future<List<T>>
startAutoSync(String userId, {Duration? interval}) → void
Starts automatic periodic synchronization for the specified user.
stopAutoSync({String? userId}) → void
Stops automatic synchronization for one or all users.
switchUser({required String? oldUserId, required String newUserId, UserSwitchStrategy? strategy}) → Future<DatumUserSwitchResult>
Switches the active user with configurable handling of unsynced data.
synchronize(String userId, {DatumSyncOptions<DatumEntityInterface>? options, DatumSyncScope? scope}) → Future<DatumSyncResult<T>>
toString() → String
A string representation of this object.
inherited
transaction<R>(Future<R> action()) → Future<R>
Executes a block of code within a single atomic transaction.
tryCascadeDelete({required String id, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false}) → Future<DatumEither<DatumError, CascadeDeleteResult<T>>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of cascadeDelete.
tryDelete({required String id, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false, DeleteBehavior? behavior}) → Future<DatumEither<DatumError, bool>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of delete.
tryPush({required T item, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false}) → Future<DatumEither<DatumError, T>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of push.
tryQuery(DatumQuery query, {required DataSource source, String? userId}) → Future<DatumEither<DatumError, List<T>>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of query.
tryRead(String id, {String? userId, List<String> withRelated = const []}) → Future<DatumEither<DatumError, T?>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of read. Returns Success(null) when the entity is simply absent, and Failure only on an actual error (storage, network…).
tryReadAll({String? userId, List<String> withRelated = const []}) → Future<DatumEither<DatumError, List<T>>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of readAll.
trySaveMany({required List<T> items, required String userId, bool andSync = false, DataSource source = DataSource.local, bool forceRemoteSync = false, DatumSyncOptions<T>? syncOptions, DatumSyncScope? scope}) → Future<DatumEither<DatumError, List<T>>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of saveMany.
trySwitchUser({required String? oldUserId, required String newUserId, UserSwitchStrategy? strategy}) → Future<DatumEither<DatumError, DatumUserSwitchResult>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of switchUser.
trySynchronize(String userId, {DatumSyncOptions<DatumEntityInterface>? options, DatumSyncScope? scope}) → Future<DatumEither<DatumError, DatumSyncResult<T>>>

Available on DatumManager<T>, provided by the DatumManagerAutoSyncInfo extension

Non-throwing variant of synchronize.
unsubscribeFromRemoteChanges() → Future<void>
Unsubscribes from remote change events.
updateAndSync({required T item, required String userId, DataSource source = DataSource.local, bool forceRemoteSync = false, DatumSyncOptions<T>? syncOptions, DatumSyncScope? scope}) → Future<(T, DatumSyncResult<T>)>
Updates an entity locally and immediately triggers a synchronization.
watchAll({String? userId, bool includeInitialData = true, List<String> withRelated = const [], bool includeDeleted = false}) → Stream<List<T>>
Watches all entities from the local adapter, emitting a new list on any change.
watchAllPaginated(PaginationConfig config, {String? userId}) → Stream<PaginatedResult<T>>
Watches a paginated list of items. Emits an empty stream if the adapter does not support reactive queries.
watchById(String id, String? userId, {bool includeDeleted = false}) → Stream<T?>
Watches a single entity by its ID, emitting the item on change or null if deleted. A soft-delete tombstone emits null like a hard delete would, unless includeDeleted is true. Returns null if the adapter does not support reactive queries.
watchQuery(DatumQuery query, {String? userId, List<String> withRelated = const [], bool includeDeleted = false}) → Stream<List<T>>
Watches a subset of items matching a query. Emits an empty stream if the adapter does not support reactive queries.
watchRelated<R extends DatumEntityInterface>(T parent, String relationName) → Stream<List<R>>?
DEPRECATED: This method will be removed in a future version. Use the withRelated parameter in the query method for eager loading, or the fetch() method on the relation object for lazy loading. Reactively watches related entities for a given parent entity.
watchStorageSize({String? userId}) → Stream<int>
Reactively watches the storage size in bytes from the local adapter.

Operators

operator ==(Object other) → bool
The equality operator.
inherited