flutter_universal_sync_core 0.3.0

Core contracts for the flutter_universal_sync offline-first sync package family. Defines the SyncEntity, adapter interfaces, conflict resolver, schema constants, and error hierarchy shared by every ad [...]

Changelog

0.3.0 — 2026-06-21

Added

• PaginatedAdapter — optional capability for keyset (seek) pagination of the local store: getPage(table, {limit, orderBy, descending, after, includeDeleted}) returns a PageResult (rows + nextCursor). Keyset anchoring is stable under concurrent inserts/deletes — no offset drift, so no duplicated/skipped rows ("stale reads"). InMemoryAdapter implements it.
• PageResult / PageCursor value types and the shared paginateRows helper (used by stores without a query engine).
• NetworkState (offline / metered / unmetered) and ReachabilityMonitor — refines a raw OS connectivity stream into a confirmed one, optionally verifying real internet with an injected probe (catches captive portals) and de-duplicating. Lets callers defer heavy transfers on metered links.
• SubmitGuard — prevents duplicate submissions ("triple-tap Save"): keyed single-flight coalescing plus a post-success cooldown. Failures don't cool down, so a failed submit retries immediately.
• SchemaMigrator / SchemaMigration — versioned local-schema migrations. Runs pending migrations in ascending order, each inside the adapter's transaction with the version bump (stored in the meta KV), so a failed step rolls back and re-runs next launch.
• SyncPushException gains isConflict + serverState so adapters can report a version conflict (HTTP 409) with the server's current row, enabling push-side conflict resolution in the engine.
• rowFreshness + StalenessPolicy (freshness) — classify a cached row as synced/pending and decide whether table data is too old to trust.
• runRemoteSyncAdapterContract + RemoteAdapterHarness (in testing.dart) — a shared behavioural contract for remote adapters, mirroring runLocalDatabaseAdapterContract. Lets a custom RemoteSyncAdapter prove it conforms (pull empty/seeded, push insert/update/round-trip/delete).

0.2.1 — 2026-06-21

Added

• PurgeableAdapter — optional capability interface for cache eviction, separate from the core adapter contract so adapters opt in without breaking the others. purgeSynced(table, {olderThan, keepLatest}) hard-removes synced rows only (never pending), returning the count removed.
• CacheEvictor — runs a maxAge/maxRows eviction policy across tables on a PurgeableAdapter (injectable now for tests).
• InMemoryAdapter now implements PurgeableAdapter.

0.2.0 — 2026-04-30

Engine-support contract bumps. Required for flutter_universal_sync_engine 0.1.0.

Added

• SyncQueueEntry.nextRetryAt field; round-trips through toMap/fromMap, participates in equality.
• SyncColumns.nextRetryAt constant + SyncColumns.queueTypes reference SQL.
• SyncMetaColumns (table _sync_meta, columns key, value).
• LocalDatabaseAdapter.upsert(table, data) — pull-pipeline write.
• LocalDatabaseAdapter.getMeta(key) / setMeta(key, value) / deleteMeta(key).
• LocalDatabaseAdapter.pendingForEntity(table, entityId).
• LocalDatabaseAdapter.rewriteQueuePayload(entryId, payload).
• LocalDatabaseAdapter.pendingSyncEntries(...) gains a readyAt parameter (back-compat with the existing {int? limit} form).
• Contract-suite groups for every addition above; reusable by every adapter.
• InMemoryAdapter is now exported from package:flutter_universal_sync_core/testing.dart so downstream packages (e.g. the sync engine) can reuse it as a local-store test double.

Changed

• LocalDatabaseAdapter.recordSyncFailure(...) now increments retry_count and accepts nextRetryAt. Pass incrementRetryCount: false and omit nextRetryAt to retain 0.1.0 "just store the error" behaviour.

Migration (for 0.1.0 adapters; none published yet)

• Add next_retry_at INTEGER to your sync queue table.
• Create _sync_meta(key TEXT PRIMARY KEY, value TEXT NOT NULL).
• Implement the seven new / amended methods above.
• The shared contract suite exercises every new method — run it.

0.1.0 — 2026-04-24

Initial release. Contracts layer for the flutter_universal_sync family.

Added

• SyncEntity abstract base class with the six sync-metadata fields.
• SyncQueueEntry data class with copyWith, toMap/fromMap, and structural equality.
• SyncOperation (insert / update / delete) and SyncStatus (pending / syncing / synced / failed) enums.
• LocalDatabaseAdapter interface covering domain CRUD, sync queue, atomic transactions, and schema validation.
• RemoteSyncAdapter interface for per-op push and delta pull.
• ConflictResolver interface plus three built-in strategies: LastWriteWinsResolver, ServerPriorityResolver, ClientPriorityResolver.
• SyncColumns schema constants.
• SyncException sealed hierarchy (SchemaValidationException, SyncPushException, SyncPullException, ConflictResolutionException).
• IdGenerator / UuidV4Generator.
• Shared runLocalDatabaseAdapterContract test suite for downstream adapter packages (exported via package:flutter_universal_sync_core/testing.dart).

Known limitations

See README "Known v1 limitations" for the list of accepted 0.1.0 trade-offs.