datum library

Classes

AdapterPair
AdapterPairImpl<T extends DatumEntityBase>
BelongsTo
Represents a one-to-one or one-to-many relationship.
CompositeFilter
Represents a composite filter with AND/OR logic.
ConflictDetectedEvent<T extends DatumEntityBase>
Event emitted when the engine detects a conflict between local and remote data.
ConflictResolvedEvent<T extends DatumEntityBase>
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.
CustomManagerConfig<T extends DatumEntityBase>
A testing-only config to smuggle a mock manager into the creation process.
DataChangeEvent<T extends DatumEntityBase>
Event emitted whenever local or remote data changes.
Datum
DatumBackoffStrategy
Abstract base class for retry backoff strategies.
DatumChangeDetail<T extends DatumEntityBase>
Represents a change that occurred in a data source. This is used by adapters to notify the engine about external changes.
DatumConfig<T extends DatumEntityBase>
Configuration for the Datum engine and its managers.
DatumConflictContext
Context information describing a synchronization conflict.
DatumConflictDetector<T extends DatumEntityBase>
Detects conflicts between local and remote versions of an entity.
DatumConflictResolution<T extends DatumEntityBase>
Result of a conflict resolution attempt.
DatumConflictResolver<T extends DatumEntityBase>
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.
DatumEntityBase
Base sealed class for all Datum entities
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 DatumEntityBase>
Configuration for database indexes on syncable entities.
DatumLogger
A simple logger for the Datum package.
DatumManager<T extends DatumEntityBase>
DatumMetrics
An immutable snapshot of key synchronization statistics.
DatumMiddleware<T extends DatumEntityBase>
Middleware for intercepting and transforming data during CRUD operations.
DatumObserver<T extends DatumEntityBase>
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 DatumEntityBase>
A helper class to encapsulate the registration details for a single entity type.
DatumSyncCompletedEvent<T extends DatumEntityBase>
Event fired when a synchronization cycle completes.
DatumSyncConflictSummary<T extends DatumEntityBase>
Description of a conflict encountered during a sync.
DatumSyncEngine<T extends DatumEntityBase>
The core engine that orchestrates the synchronization process.
DatumSyncErrorEvent<T extends DatumEntityBase>
Event fired when an error occurs during synchronization.
DatumSyncEvent<T extends DatumEntityBase>
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 DatumEntityBase>
Represents a single pending operation to be synchronized.
DatumSyncOptions<T extends DatumEntityBase>
Configuration passed when triggering a manual synchronization via Datum.sync().
DatumSyncProgressEvent<T extends DatumEntityBase>
Event fired to report synchronization progress.
DatumSyncRequestStrategy
Defines the strategy for handling concurrent calls to the synchronize method.
DatumSyncResult<T extends DatumEntityBase>
Represents the outcome of a synchronization cycle.
DatumSyncScope
Defines a scope for a synchronization operation, allowing for partial syncs.
DatumSyncStartedEvent<T extends DatumEntityBase>
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 DatumEntityBase>
Event emitted when event listeners are attached for a user and the full dataset snapshot needs to be delivered.
IsolateHelper
LastWriteWinsResolver<T extends DatumEntityBase>
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 DatumEntityBase>
Local storage adapter abstraction that provides access to offline data.
LocalPriorityResolver<T extends DatumEntityBase>
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 DatumEntityBase>
A resolver that uses a provided function to merge conflicting entities.
Migration
Represents a single migration step from one schema version to another.
MigrationExecutor<T extends DatumEntityBase>
Orchestrates the execution of schema migrations.
PaginatedResult<T extends DatumEntityBase>
Result of a paginated query.
PaginationConfig
Configuration for paginated queries.
ParallelStrategy
Processes pending operations in parallel batches.
QueueManager<T extends DatumEntityBase>
Manages the queue of pending synchronization operations for a specific entity type T.
Relation
A sealed class representing the different types of relationships between entities.
RelationalDatumEntity
Entity with relationships
RemoteAdapter<T extends DatumEntityBase>
Remote storage adapter abstraction for cloud data sources.
RemotePriorityResolver<T extends DatumEntityBase>
Resolves conflicts by always preferring the remote version of the entity. If the remote version does not exist, it will use the local version.
SequentialRequestStrategy
A strategy that queues new sync requests if one is already in progress.
SequentialStrategy
Processes pending operations one by one. This is safer and less resource-intensive.
SkipConcurrentStrategy
A strategy that skips new sync requests if one is already in progress. This prevents re-entrant sync calls.
SortDescriptor
Defines sorting for a field in a DatumQuery.
UserPromptResolver<T extends DatumEntityBase>
A resolver that delegates the conflict decision to the user via a prompt.
UserSwitchedEvent<T extends DatumEntityBase>
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>
DatumQuerySqlConverter on DatumQuery
An extension on DatumQuery to provide SQL conversion capabilities.

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 DatumEntityBase> = 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.
MigrationResult = ({Object? migrationError, StackTrace? migrationStack, bool success})
A record representing the outcome of a migration execution.

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 DatumEntityBase>
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.