datum library

Classes

AdapterPair
AdapterPairImpl<T extends DatumEntity>
BelongsTo
Represents a one-to-one or one-to-many relationship.
CompositeFilter
Represents a composite filter with AND/OR logic.
ConflictDetectedEvent<T extends DatumEntity>
Event emitted when the engine detects a conflict between local and remote data.
ConflictResolvedEvent<T extends DatumEntity>
Event emitted after a conflict has been successfully resolved.
CustomBackoff
Implements a custom backoff strategy defined by a function. Useful for testing or complex retry logic.
DataChangeEvent<T extends DatumEntity>
Event emitted whenever local or remote data changes.
Datum
DatumBackoffStrategy
Abstract base class for retry backoff strategies.
DatumChangeDetail<T extends DatumEntity>
Represents a change that occurred in a data source. This is used by adapters to notify the engine about external changes.
DatumConfig<T extends DatumEntity>
Configuration for the Datum engine and its managers.
DatumConflictContext
Context information describing a synchronization conflict.
DatumConflictDetector<T extends DatumEntity>
Detects conflicts between local and remote versions of an entity.
DatumConflictResolution<T extends DatumEntity>
Result of a conflict resolution attempt.
DatumConflictResolver<T extends DatumEntity>
Base interface for components that resolve synchronization conflicts.
DatumConnectivityChecker
An abstract interface for checking network connectivity.
DatumCustomFieldQuery<T>
Helper class for building complex queries with custom field definitions.
DatumEntity
Base class for all entities managed by Datum.
DatumEntitySyncDetails
Describes the synchronization state for a single entity type.
DatumErrorRecoveryStrategy
Defines a strategy for how the sync engine should behave on errors.
DatumHashGenerator
Utility for generating consistent hashes for data integrity checks.
DatumHealth
Represents the operational health of a sync manager.
DatumIndexConfig<T extends DatumEntity>
Configuration for database indexes on syncable entities.
DatumLogger
A simple logger for the Datum package.
DatumManager<T extends DatumEntity>
DatumMetrics
An immutable snapshot of key synchronization statistics.
DatumMiddleware<T extends DatumEntity>
Middleware for intercepting and transforming data during CRUD operations.
DatumObserver<T extends DatumEntity>
An observer class to monitor operations within DatumManager.
DatumQuery
Defines a query for filtering and sorting items from a data source.
DatumQueryBuilder<T>
A fluent builder for creating DatumQuery objects with type-safe field access.
DatumRegistration<T extends DatumEntity>
A helper class to encapsulate the registration details for a single entity type.
DatumSyncCompletedEvent<T extends DatumEntity>
Event fired when a synchronization cycle completes.
DatumSyncConflictSummary<T extends DatumEntity>
Description of a conflict encountered during a sync.
DatumSyncEngine<T extends DatumEntity>
The core engine that orchestrates the synchronization process.
DatumSyncErrorEvent<T extends DatumEntity>
Event fired when an error occurs during synchronization.
DatumSyncEvent<T extends DatumEntity>
Base class for all synchronization-related events.
DatumSyncExecutionStrategy
Defines the execution strategy for processing the sync queue.
DatumSyncMetadata
Metadata describing the synchronization state for a specific user.
DatumSyncOperation<T extends DatumEntity>
Represents a single pending operation to be synchronized.
DatumSyncOptions<T extends DatumEntity>
Configuration passed when triggering a manual synchronization via Datum.sync().
DatumSyncProgressEvent<T extends DatumEntity>
Event fired to report synchronization progress.
DatumSyncResult<T extends DatumEntity>
Represents the outcome of a synchronization cycle.
DatumSyncScope
Defines a scope for a synchronization operation, allowing for partial syncs.
DatumSyncStartedEvent<T extends DatumEntity>
Event fired when a synchronization cycle starts.
DatumSyncStatistics
Aggregated statistics about multiple sync cycles.
DatumSyncStatusSnapshot
An immutable snapshot describing the current sync state for a user.
DatumUserSwitchResult
Result of a user switching operation.
ExcludableEntity
An example entity with fields that can be excluded from local/remote storage.
ExponentialBackoff
Implements an exponential backoff retry strategy.
Filter
Represents a single filter condition in a DatumQuery.
FilterCondition
Represents a filter condition (can be simple or composite).
FixedBackoff
Implements a fixed backoff retry strategy where the delay is always the same.
GlobalDatumObserver
A specialized observer that can handle any entity type. This is used for global observers registered on the main Datum instance.
HasMany
Represents a one-to-many relationship from the "one" side.
HasOne
Represents a one-to-one relationship from the "one" side.
InitialSyncEvent<T extends DatumEntity>
Event emitted when event listeners are attached for a user and the full dataset snapshot needs to be delivered.
IsolateHelper
Helper for offloading work to a background isolate.
IsolateStrategy
A strategy that executes another DatumSyncExecutionStrategy in a background isolate. This is ideal for long-running syncs to prevent UI jank.
LastWriteWinsResolver<T extends DatumEntity>
A simple conflict resolver that chooses the entity with the later modifiedAt timestamp.
LinearBackoff
Implements a linear backoff retry strategy where the delay increases by a fixed amount.
LocalAdapter<T extends DatumEntity>
Local storage adapter abstraction that provides access to offline data.
LocalPriorityResolver<T extends DatumEntity>
Resolves conflicts by always preferring the local version of the entity. If the local version does not exist, it will use the remote version.
ManyToMany
Represents a many-to-many relationship.
MergeResolver<T extends DatumEntity>
A resolver that uses a provided function to merge conflicting entities.
Migration
Represents a single migration step from one schema version to another.
MigrationExecutor
Orchestrates the execution of schema migrations.
PaginatedResult<T extends DatumEntity>
Result of a paginated query.
PaginationConfig
Configuration for paginated queries.
ParallelStrategy
Processes pending operations in parallel batches.
QueueManager<T extends DatumEntity>
Manages the queue of pending synchronization operations.
Relation
A sealed class representing the different types of relationships between entities.
RelationalDatumEntity
An extension of DatumEntity that includes support for defining relationships.
RemoteAdapter<T extends DatumEntity>
Remote storage adapter abstraction for cloud data sources.
RemotePriorityResolver<T extends DatumEntity>
Resolves conflicts by always preferring the remote version of the entity. If the remote version does not exist, it will use the local version.
SequentialStrategy
Processes pending operations one by one. This is safer and less resource-intensive.
SortDescriptor
Defines sorting for a field in a DatumQuery.
UserPromptResolver<T extends DatumEntity>
A resolver that delegates the conflict decision to the user via a prompt.
UserSwitchedEvent<T extends DatumEntity>
Event emitted when the active user is changed in the manager.

Enums

AdapterHealthStatus
Describes the health of an individual adapter.
ChangeType
Type of data change.
DataSource
Source of data change.
DatumConflictType
Types of conflicts detected between local and remote representations.
DatumOperationType
Defines the type of a synchronization or data manipulation operation.
DatumResolutionStrategy
Strategies used when resolving conflicts.
DatumSyncHealth
Describes the overall health of a synchronization process.
DatumSyncStatus
High-level states for the synchronization process.
DatumSyncTrigger
Defines the scope of a synchronization operation triggered after a local change.
FilterOperator
Defines the available comparison operators for filters.
LogicalOperator
Defines logical operators for combining filters.
MapTarget
The target for serialization, allowing different fields for local vs. remote.
NullSortOrder
Defines how null values are sorted.
SqlDialect
Defines the SQL dialect to be used for generating queries.
SyncDirection
Defines the direction of a synchronization operation. Defines the order of operations during a synchronization cycle.
UserSwitchStrategy
Defines the strategy to use when switching between users.

Mixins

Disposable
A mixin to provide disposable behavior to a class.

Extensions

DatumManagerAutoSyncInfo on DatumManager<T>
DatumManagerSyncControl on DatumManager<T>
DatumQuerySqlConverter on DatumQuery
An extension on DatumQuery to provide SQL conversion capabilities.

Properties

isTest → bool
A flag to determine if the code is running in a test environment.
final

Functions

formatDuration(Duration d) → String
Formats a Duration into a more human-readable string.

Typedefs

DatumCustomSqlBuilder = String? Function(Filter filter, String getPlaceholder(), List<Object?> params)
A builder function for custom SQL operator logic.
DatumMergeFunction<T extends DatumEntity> = FutureOr<T?> Function(T local, T remote, DatumConflictContext context)
A function that defines how to merge a local and remote entity.
DatumPlaceholderBuilder = String Function(int index)
A builder function for custom SQL placeholder logic.
DatumSqlQueryResult = ({List<Object?> params, String sql})
A record holding the generated SQL string and its corresponding parameters.
MigrationErrorHandler = Future<void> Function(Object error, StackTrace stackTrace)
A handler for migration errors.

Exceptions / Errors

AdapterException
Exception thrown by adapters during their operations.
DatumException
Base exception for all Datum related errors.
EntityNotFoundException
Exception thrown when an entity is not found, typically during an update or delete operation on a remote data source.
MigrationException
Exception thrown when a schema migration fails.
NetworkException
Exception thrown for network-related issues.
SyncExceptionWithEvents<T extends DatumEntity>
A special exception to carry events back up the call stack on failure.
UserSwitchException<T extends DatumEntity>
Exception thrown when a user switch operation is rejected by a strategy.