DatumConfig<T extends DatumEntityInterface> class

Configuration for the Datum engine and its managers.

Implementers

Constructors

DatumConfig({Duration autoSyncInterval = const Duration(minutes: 15), bool autoStartSync = false, Duration syncTimeout = const Duration(minutes: 2), DatumConflictResolver<T>? defaultConflictResolver, UserSwitchStrategy defaultUserSwitchStrategy = UserSwitchStrategy.syncThenSwitch, Future<String?> initialUserId()?, bool enableLogging = true, SyncDirection defaultSyncDirection = SyncDirection.pushThenPull, int schemaVersion = 0, List<Migration> migrations = const [], DatumSyncExecutionStrategy syncExecutionStrategy = const SequentialStrategy(), MigrationErrorHandler? onMigrationError, DatumSyncRequestStrategy syncRequestStrategy = const SequentialRequestStrategy(), DatumErrorRecoveryStrategy errorRecoveryStrategy = const DatumErrorRecoveryStrategy(shouldRetry: _defaultShouldRetry, maxRetries: 3, backoffStrategy: ExponentialBackoff()), Duration remoteEventDebounceTime = const Duration(milliseconds: 50), Duration changeCacheDuration = const Duration(seconds: 5), DatumSyncOptions<T>? defaultSyncOptions, int maxChangeCacheSize = 1000, Duration changeCacheCleanupInterval = const Duration(seconds: 30), int remoteSyncBatchSize = 100, int remoteStreamBatchSize = 50, int progressEventFrequency = 50, LogLevel logLevel = LogLevel.info, bool enablePerformanceLogging = false, Duration performanceLogThreshold = const Duration(milliseconds: 100), Map<String, LogSampler> logSamplers = const {}, SyncDirectionResolver? syncDirectionResolver, ColdStartConfig coldStartConfig = const ColdStartConfig(), DeleteBehavior deleteBehavior = DeleteBehavior.hardDelete, Set<String> excludedSyncUserIds = const {}, bool detectRemoteDeletions = false, bool enableQueryCache = false, bool enableMetadataHashCache = true, bool enableDeltaSync = true, Duration deltaSyncOverlap = const Duration(minutes: 5), int maxQueryCacheSize = 100, int maxRelationshipQueryCacheSize = 200, int maxEntityExistenceCacheSize = 500, bool useIsolateSync = false, DatumSchema<T>? schema, bool autoMigrate = false, bool autoMigrateDropColumns = false})
const
DatumConfig.defaultConfig()
A default configuration with sensible production values.
factory

Properties

autoMigrate → bool
Whether to reconcile the store's shape with schema during initialize() — after the manual migrations chain runs. Missing declared columns are added (renames honored via DatumFieldSpec.renamedFrom hints); undeclared columns are kept and warned about unless autoMigrateDropColumns is on.
final
autoMigrateDropColumns → bool
Whether auto-migration may drop stored columns that are not in schema. Off by default — destructive changes are opt-in.
final
autoStartSync → bool
Whether to automatically start auto-sync for all users with local data upon initialization.
final
autoSyncInterval → Duration
The interval for any automatic background synchronization.
final
changeCacheCleanupInterval → Duration
The interval for periodic cleanup of the change cache. This is in addition to the immediate cleanup based on changeCacheDuration.
final
changeCacheDuration → Duration
The duration to keep a change ID in the cache to prevent duplicate processing.
final
coldStartConfig → ColdStartConfig
Configuration for cold start synchronization behavior. Determines how the system handles sync when the app is fully closed and reopened.
final
defaultConflictResolver → DatumConflictResolver<T>?
The default conflict resolver to use if none is provided per-operation. If null, LastWriteWinsResolver is used.
final
defaultSyncDirection → SyncDirection
The default direction for synchronization.
final
defaultSyncOptions → DatumSyncOptions<T>?
Default sync options to use when none are provided to synchronize(). These options will be merged with any options passed to individual sync calls.
final
defaultUserSwitchStrategy → UserSwitchStrategy
The default strategy to use when switching users.
final
deleteBehavior → DeleteBehavior
Defines the behavior for delete operations. Defaults to DeleteBehavior.hardDelete.
final
deltaSyncOverlap → Duration
Clock-skew tolerance subtracted from the watermark passed to DeltaSyncCapable.readSince. Re-delivered rows in the overlap window are skipped by the strictly-newer check, so a generous overlap is safe.
final
detectRemoteDeletions → bool
Whether a full pull should treat entities that exist locally but are absent remotely as remote deletions, routing each through the conflict resolver (as a DatumConflictType.deletionConflict with a null remote).
final
enableDeltaSync → bool
Whether the pull phase may use incremental pulls when the remote adapter mixes in DeltaSyncCapable — fetching only entities modified since the last sync watermark instead of the full dataset.
final
enableLogging → bool
Whether to enable detailed logging from the Datum engine.
final
enableMetadataHashCache → bool
Whether to cache the per-user content hash used when stamping sync metadata, so an idle sync cycle skips an O(n) readAll + rehash of the whole local dataset.
final
enablePerformanceLogging → bool
Whether to enable performance logging for operations exceeding thresholds.
final
enableQueryCache → bool
Whether to cache the results of local DatumManager.query calls.
final
errorRecoveryStrategy → DatumErrorRecoveryStrategy
The strategy for handling errors and retries during synchronization.
final
excludedSyncUserIds → Set<String>
User IDs that must never be auto-discovered for synchronization.
final
hashCode → int
The hash code for this object.
no setterinherited
initialUserId → Future<String?> Function()?
The user ID to target for the initial auto-sync if autoStartSync is true. A function that returns a Future<String?> to get the current user ID. If the function returns null, DatumManager will discover all users with local data. If null, DatumManager will discover all users with local data.
final
logLevel → LogLevel
The minimum log level for logging output.
final
logSamplers → Map<String, LogSampler>
Sampling strategies for high-frequency log operations.
final
maxChangeCacheSize → int
The maximum number of entries to keep in the change cache. When exceeded, older entries are removed to prevent unbounded memory growth.
final
maxEntityExistenceCacheSize → int
The maximum size of the entity existence cache.
final
maxQueryCacheSize → int
The maximum size of the query cache.
final
maxRelationshipQueryCacheSize → int
The maximum size of the relationship query cache.
final
migrations → List<Migration>
A list of Migration classes to be run when the schemaVersion is incremented.
final
onMigrationError → MigrationErrorHandler?
A callback to handle failures during schema migration.
final
performanceLogThreshold → Duration
The duration threshold for performance logging.
final
progressEventFrequency → int
The frequency of progress event emissions during sync operations. Progress events are emitted every N items processed.
final
props → List<Object?>
The list of properties that will be used to determine whether two instances are equal.
no setter
remoteEventDebounceTime → Duration
The duration to buffer remote changes before processing a batch. Helps to group rapid-fire updates from a server push into a single operation.
final
remoteStreamBatchSize → int
The batch size for streaming remote items from adapters. Smaller batches reduce memory usage but may increase processing overhead.
final
remoteSyncBatchSize → int
The batch size for processing remote changes during sync operations. Larger batches reduce memory overhead but may increase latency.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
schema → DatumSchema<T>?
The declared runtime schema for this entity — powers typed reads and, with autoMigrate, schema reconciliation at initialize.
final
schemaVersion → int
The current version of the data schema for migration purposes.
final
stringify → bool?
If set to true, the toString method will be overridden to output this instance's props.
no setterinherited
syncDirectionResolver → SyncDirectionResolver?
A callback that allows customizing the sync direction based on pending operations.
final
syncExecutionStrategy → DatumSyncExecutionStrategy
The execution strategy for processing the sync queue.
final
syncRequestStrategy → DatumSyncRequestStrategy
The strategy for handling concurrent calls to the synchronize method. Defaults to SequentialRequestStrategy.
final
syncTimeout → Duration
The maximum duration for a single sync cycle before it times out.
final
useIsolateSync → bool
Whether to offload the entire synchronization process to a background isolate.
final

Methods

copyWith<E extends DatumEntityInterface>({Duration? autoSyncInterval, bool? autoStartSync, Duration? syncTimeout, DatumConflictResolver<E>? defaultConflictResolver, UserSwitchStrategy? defaultUserSwitchStrategy, Future<String?> initialUserId()?, bool? enableLogging, SyncDirection? defaultSyncDirection, int? schemaVersion, List<Migration>? migrations, DatumSyncExecutionStrategy? syncExecutionStrategy, MigrationErrorHandler? onMigrationError, DatumSyncRequestStrategy? syncRequestStrategy, DatumErrorRecoveryStrategy? errorRecoveryStrategy, Duration? remoteEventDebounceTime, Duration? changeCacheDuration, DatumSyncOptions<E>? defaultSyncOptions, int? maxChangeCacheSize, Duration? changeCacheCleanupInterval, int? remoteSyncBatchSize, int? remoteStreamBatchSize, int? progressEventFrequency, LogLevel? logLevel, bool? enablePerformanceLogging, Duration? performanceLogThreshold, Map<String, LogSampler>? logSamplers, SyncDirectionResolver? syncDirectionResolver, ColdStartConfig? coldStartConfig, DeleteBehavior? deleteBehavior, Set<String>? excludedSyncUserIds, bool? detectRemoteDeletions, bool? enableQueryCache, bool? enableMetadataHashCache, bool? enableDeltaSync, Duration? deltaSyncOverlap, int? maxQueryCacheSize, int? maxRelationshipQueryCacheSize, int? maxEntityExistenceCacheSize, bool? useIsolateSync, DatumSchema<E>? schema, bool? autoMigrate, bool? autoMigrateDropColumns}) → DatumConfig<E>
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
sanitizedForIsolate<E extends DatumEntityInterface>() → DatumConfig<E>
Returns a copy of this config with the callback fields that commonly capture unsendable state (initialUserId, onMigrationError, syncDirectionResolver) removed, re-typed for entity type E.
toString() → String
A string representation of this object.

Operators

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