supabase_flutter_ultra 0.1.0

Offline-first wrapper for Supabase Flutter with caching, offline write queue, delta sync, and conflict resolution — fully compatible with existing Supabase APIs.

Changelog

All notable changes to supabase_flutter_ultra will be documented here. This project adheres to Semantic Versioning.

---

0.1.0 — 2026-08-11 — Initial Release

Added

• UltraClient — central facade wrapping SupabaseClient with offline intelligence
• SupabaseUltra.initialize() — single-call setup, mirrors Supabase.initialize API
• Cache Layer
  • CacheManager with deterministic key building
  • SqliteCacheAdapter for persistent mobile/desktop caching
  • MemoryCacheAdapter for web and tests
  • LruEviction — Least-Recently-Used eviction tracker
  • TtlEviction — periodic TTL sweep runner
  • Five cache strategies: networkFirstWithFallback, cacheFirstThenNetwork, cacheIfFreshElseNetwork, cacheOnly, networkOnly
  • Named presets: CachePolicy.aggressive, CachePolicy.conservative, CachePolicy.offlineOnly
• Queue Layer
  • OperationQueue — persistent FIFO queue for offline writes
  • QueuePersistence — SQLite-backed queue storage surviving app restarts
  • QueueProcessor — sequential operation replay with retry logic
  • RetryStrategy — fixedDelay, exponentialBackoff, exponentialBackoffWithJitter, noRetry
• Sync Layer
  • SyncEngine — orchestrates queue drain + delta sync
  • DeltaSync — updated_at > lastSyncAt delta queries (no full-table downloads)
  • SyncManifest — per-table checkpoint tracking
  • SyncScheduler — configurable periodic background sync
  • SyncState stream — reactive status updates for UI
• Conflict Resolution Layer
  • ConflictResolver — dispatches to the correct strategy
  • Five strategies: serverWins, clientWins, lastWriteWins, fieldLevelMerge, custom
  • VectorClock — causal conflict detection for advanced use cases
  • FieldLevelMergeStrategy — three-way merge with configurable field-conflict winner
• Network Layer
  • ConnectivityMonitor — combines connectivity_plus with endpoint reachability
  • NetworkState enum: online, offline, reachabilityFailed, weak
  • onReconnect stream — fires once on every offline→online transition
• Realtime Layer
  • UltraRealtime — offline-aware realtime wrapper
  • EventBuffer — stores events during offline periods (configurable TTL + capacity)
  • RealtimeReconciler — replays buffered events into cache on reconnect
• Query Layer
  • UltraQueryBuilder — offline-aware query builder mirroring Supabase API
  • UltraFilterBuilder — filter chain with offline-aware fetch()
  • QueryInterceptor — pure read-strategy dispatcher
  • UltraWriteResult — reports whether a write was executed or queued
• Models & Utils
  • SyncMetadata, LocalRecord, ConflictRecord — rich data models
  • IdGenerator — UUID v4/v7 for offline-safe primary keys
  • TimestampUtils, SerializationHelper — shared utility functions
• Tests
  • Full unit test suite for cache, queue, and conflict layers
  • Integration tests for offline scenarios without a live network
• Example App
  • Complete offline-first Todo app with sync status screen

---

[Unreleased]

Planned

• HiveCacheAdapter — alternative Hive-based cache backend
• UltraStorage — offline-first wrapper for Supabase Storage
• UltraRPC — offline-queued RPC (Edge Functions) support
• ConflictInspector — UI widget for manual conflict resolution
• Drift ORM integration for richer local schema management
• Web platform support via IndexedDB adapter