datum library

Classes

AdapterPair
AdapterPairImpl<T extends DatumEntityInterface>
BelongsTo<T extends DatumEntityInterface>
CompositeFilter
Represents a composite filter with AND/OR logic.
ConflictDetectedEvent<T extends DatumEntityInterface>
Event emitted when the engine detects a conflict between local and remote data.
ConflictResolvedEvent<T extends DatumEntityInterface>
Event emitted after a conflict has been successfully resolved.
CountBasedSampler
Count-based sampler that logs every Nth occurrence.
CustomBackoff
Implements a custom backoff strategy defined by a function. Useful for testing or complex retry logic.
CustomManagerConfig<T extends DatumEntityInterface>
A testing-only config to smuggle a mock manager into the creation process.
DataChangeEvent<T extends DatumEntityInterface>
Event emitted whenever local or remote data changes.
Datum
DatumBackoffStrategy
Abstract base class for retry backoff strategies.
DatumChangeDetail<T extends DatumEntityInterface>
Represents a change that occurred in a data source. This is used by adapters to notify the engine about external changes.
DatumConfig<T extends DatumEntityInterface>
Configuration for the Datum engine and its managers.
DatumConflictContext
Context information describing a synchronization conflict.
DatumConflictDetector<T extends DatumEntityInterface>
Detects conflicts between local and remote versions of an entity.
DatumConflictResolution<T extends DatumEntityInterface>
Result of a conflict resolution attempt.
DatumConflictResolver<T extends DatumEntityInterface>
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
The base abstract class for all entities managed by Datum without built-in relationship handling.
DatumEntityBase
The base sealed class for all entities managed by the Datum framework.
DatumEntityInterface
Interface for all Datum entities, allowing both inheritance and mixin approaches.
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 DatumEntityInterface>
Configuration for database indexes on syncable entities.
DatumLogger
Enhanced logger for the Datum package with structured logging and performance optimizations.
DatumManager<T extends DatumEntityInterface>
DatumMetrics
An immutable snapshot of key synchronization statistics.
DatumMiddleware<T extends DatumEntityInterface>
Middleware for intercepting and transforming data during CRUD operations.
DatumObserver<T extends DatumEntityInterface>
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 DatumEntityInterface>
A helper class to encapsulate the registration details for a single entity type.
DatumSyncCompletedEvent<T extends DatumEntityInterface>
Event fired when a synchronization cycle completes.
DatumSyncConflictSummary<T extends DatumEntityInterface>
Description of a conflict encountered during a sync.
DatumSyncEngine<T extends DatumEntityInterface>
The core engine that orchestrates the synchronization process.
DatumSyncErrorEvent<T extends DatumEntityInterface>
Event fired when an error occurs during synchronization.
DatumSyncEvent<T extends DatumEntityInterface>
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 DatumEntityInterface>
Represents a single pending operation to be synchronized.
DatumSyncOptions<T extends DatumEntityInterface>
Configuration passed when triggering a manual synchronization via Datum.sync().
DatumSyncProgressEvent<T extends DatumEntityInterface>
Event fired to report synchronization progress.
DatumSyncRequestStrategy
Defines the strategy for handling concurrent calls to the synchronize method.
DatumSyncResult<T extends DatumEntityInterface>
Represents the outcome of a synchronization cycle.
DatumSyncScope
Defines a scope for a synchronization operation, allowing for partial syncs.
DatumSyncStartedEvent<T extends DatumEntityInterface>
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<T extends DatumEntityInterface>
HasOne<T extends DatumEntityInterface>
InitialSyncEvent<T extends DatumEntityInterface>
Event emitted when event listeners are attached for a user and the full dataset snapshot needs to be delivered.
IsolateHelper
LastWriteWinsResolver<T extends DatumEntityInterface>
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 DatumEntityInterface>
Local storage adapter abstraction that provides access to offline data.
LocalPriorityResolver<T extends DatumEntityInterface>
Resolves conflicts by always preferring the local version of the entity. If the local version does not exist, it will use the remote version.
LogEntry
Structured log entry with metadata for better debugging and monitoring.
LogSampler
Sampling strategy for high-frequency log operations.
ManyToMany<T extends DatumEntityInterface>
MergeResolver<T extends DatumEntityInterface>
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 DatumEntityInterface>
Orchestrates the execution of schema migrations.
PaginatedResult<T extends DatumEntityInterface>
Result of a paginated query.
PaginationConfig
Configuration for paginated queries.
ParallelStrategy
Processes pending operations in parallel batches.
QueueManager<T extends DatumEntityInterface>
Manages the queue of pending synchronization operations for a specific entity type T.
RateLimitingSampler
Time-based sampler that limits logs to a maximum rate.
Relation<T extends DatumEntityInterface>
RelationalDatumEntity
An extension of DatumEntity that includes support for defining relationships.
RemoteAdapter<T extends DatumEntityInterface>
Remote storage adapter abstraction for cloud data sources.
RemotePriorityResolver<T extends DatumEntityInterface>
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.
TypeSafeManagerRegistry
A type-safe registry for storing and retrieving managers.
UserPromptResolver<T extends DatumEntityInterface>
A resolver that delegates the conflict decision to the user via a prompt.
UserSwitchedEvent<T extends DatumEntityInterface>
Event emitted when the active user is changed in the manager.

Enums

AdapterHealthStatus
Describes the health of an individual adapter.
CascadeDeleteBehavior
Defines the cascading behavior for delete operations on relationships.
ChangeType
Type of data change.
DataSource
Source of data change.
DatumConflictType
Types of conflicts detected between local and remote representations.
DatumExceptionCode
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.
DeleteBehavior
Defines how delete operations are handled by the DatumManager.
FilterOperator
Defines the available comparison operators for filters.
LogicalOperator
Defines logical operators for combining filters.
LogLevel
Log levels for structured logging with performance awareness.
MapTarget
The target for serialization, allowing different fields to be included or excluded based on whether the data is going to a local or remote data source.
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.
SyncStatus
Sync status enumeration.
UserSwitchStrategy
Defines the strategy to use when switching between users.

Mixins

DatumEntityMixin
A mixin that provides the base functionality for Datum entities.
Disposable
A mixin to provide disposable behavior to a class.
RelationalDatumEntityMixin
A mixin that provides relational functionality for Datum entities.

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.
isSubtype<S, T>() → bool
The central engine for the Datum framework, managing data synchronization, entity registration, and communication between local and remote sources.
sameTypes<S, V>() → bool

Typedefs

DatumCustomSqlBuilder = String? Function(Filter filter, String getPlaceholder(), List<Object?> params)
A builder function for custom SQL operator logic.
DatumMergeFunction<T extends DatumEntityInterface> = 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.
SyncDirectionResolver = SyncDirection? Function(int pendingCount, SyncDirection defaultDirection)
A callback that allows customizing the sync direction based on pending operations.

Exceptions / Errors

AdapterException
Exception thrown when an error occurs within an adapter implementation.
AuthenticationException
Exception thrown when authentication fails.
AuthorizationException
Exception thrown when authorization fails.
BadRequestException
Exception thrown when the client makes a bad request.
CancellationException
Exception thrown when an operation is cancelled.
ConflictException
Exception thrown when a conflict is detected during synchronization.
DatumException
Base exception class for all errors originating from the Datum library.
EntityNotFoundException
Exception thrown when an entity with the specified ID is not found.
MigrationException
NetworkException
Exception thrown when a network-related error occurs.
PreconditionFailedException
Exception thrown when a precondition for an operation is not met.
SerializationException
Exception thrown when an error occurs during data serialization or deserialization.
ServerException
Exception thrown when the server responds with an error.
SyncExceptionWithEvents<T extends DatumEntityInterface>
A special exception to carry events back up the call stack on failure.
TimeoutException
Exception thrown when an operation times out.
UnavailableException
Exception thrown when the requested resource is unavailable.
UnknownException
Exception thrown when original exception unknown
UserSwitchException
ValidationException
Exception thrown when a validation error occurs.