pocketbase_drift 0.3.4

pocketbase_drift: ^0.3.4 copied to clipboard

New Features #

• Cache TTL & Expiration - Added configurable time-to-live (TTL) for cached data. Old synced records and cached responses are automatically cleaned up when runMaintenance() is called.
  • Configurable cacheTtl parameter in $PocketBase.database() (default: 60 days)
  • New runMaintenance() method to clean up expired cache data
  • Returns MaintenanceResult with counts of deleted items
  • Only removes synced data - unsynced local changes are always preserved
  • Cleans up expired file blobs automatically

New Features #

• Filter-aware sync for deleted records - Added syncLocal method that intelligently syncs deletions from the server to local cache. When fetching data with getFullList, the system now detects and removes records that were deleted on the server while offline, even when using filtered queries. This ensures local cache stays in sync with server state.
  • Works with both filtered and unfiltered queries
  • Only deletes records within the filter scope
  • Preserves unsynced local changes, local-only records, and pending deletions
  • Includes safety check to prevent mass deletion on server errors

Improvements #

• Enhanced getFullList behavior - Now automatically calls syncLocal after fetching all pages, ensuring deleted records are cleaned up from local cache
• Added comprehensive test coverage - New test suite (sync_local_test.dart) with 7 tests covering all edge cases for filter-aware deletion
• PocketBase-compatible ID generation - Local IDs are now generated using PocketBase's exact format ([a-z0-9]{15}). This eliminates the need for ID remapping during sync, simplifying the offline-first flow:
  • Records created offline now sync with the same ID they were created with
  • Removed shortid dependency in favor of a built-in secure random generator
  • Exported newId() function for use by consuming applications

Bug Fixes #

• Fixed partial update validation for offline scenarios - Partial updates now correctly merge with existing record data before validation, allowing updates with only changed fields when using cacheFirst or cacheOnly policies
• Fixed SQLite quote semantics in filters - Added automatic quote normalization in filter parser to convert double quotes to single quotes for string literals, preventing SQLite from misinterpreting values as identifiers. Both 'id = "$id"' and "id = '$id'" now produce correct SQL

Bug Fixes #

• Critical: Fixed pending sync execution on app restart - Resolved a critical issue where pending changes would not sync when the app was completely closed and reopened. The sync mechanism now queries the database to identify services with pending records instead of relying on an in-memory cache that gets cleared on app restart. This ensures that all offline changes are reliably synced when connectivity is restored, even after a complete app restart.

• Resolved pub.dev issue

BREAKING CHANGES: Added new RequestPolicy options for more explicit control over caching and network behavior.

New Features #

• New RequestPolicy options: Added RequestPolicy.cacheFirst and RequestPolicy.networkFirst for more explicit control over data fetching and synchronization behavior
  • cacheFirst: Returns cache immediately, fetches network in background to update cache
  • networkFirst: Tries network first, falls back to cache on failure (replaces old cacheAndNetwork behavior for reads)
  • cacheAndNetwork: Now has distinct behavior - for reads it behaves like networkFirst, but for writes it provides resilient offline-first synchronization with automatic retry

Improvements #

• Refactored write operations (create/update/delete): Split monolithic methods into smaller, policy-specific implementations for better maintainability
• Enhanced documentation: Comprehensive guide on choosing the right RequestPolicy for different scenarios
• Better error messages: More descriptive error messages that indicate which policy was used when operations fail

Write Operation Behavior Changes #

• networkFirst (new strict mode): Writes to server first, updates cache on success, throws error on failure (NO cache fallback)
• cacheFirst (new optimistic mode): Writes to cache first, attempts server sync in background
• cacheAndNetwork (enhanced): Tries server first, falls back to cache with pending sync on failure (maintains backward compatibility for offline-first apps)

Migration Guide #

Existing code continues to work - the default RequestPolicy.cacheAndNetwork maintains backward compatibility for most use cases.

However, if you were relying on specific behavior:

• If you want strict server-first writes with no offline fallback, use RequestPolicy.networkFirst
• If you want instant UI feedback with background sync, use RequestPolicy.cacheFirst
• If you want resilient offline-first behavior (old default), continue using RequestPolicy.cacheAndNetwork

Exclude certain API paths from caching in send method

• Add a list of non-cacheable path segments to exclude specific API endpoints from being cached.
• Modify the send method to bypass cache if the request path contains any of these segments.

This prevents caching sensitive or system data like backups, settings, and logs.

Refactor file download methods to use consistent getFileData & Implement auto-generation of file token

• Change token parameter from bool to String?
• Add autoGenerateToken parameter to automatically generate tokens when needed
• Refactor file download methods to use consistent getFileData API across platforms
• Improve file service architecture to better handle token-based file downloads

• Update Documentation.

• Resolve pub.dev score issues e.g outdated plugin dependencies.

• Initial release.

This is the first version of pocketbase_drift, a powerful offline-first client for the PocketBase backend, built on top of the reactive persistence library Drift.

Features #

• Offline-First Architecture: Read, create, update, and delete records even without a network connection. The client seamlessly uses the local database as the source of truth.
• Automatic Synchronization: Changes made while offline are automatically queued and retried when network connectivity is restored.
• Reactive Data & UI: Build reactive user interfaces with streams that automatically update when underlying data changes, whether from a server push or a local mutation.
• Local Caching with Drift: All collections and records are cached in a local SQLite database, providing fast, offline access to your data.
• Powerful Local Querying: Full support for local querying, mirroring the PocketBase API. This includes:
  • Filtering: Complex filter strings are parsed into SQLite WHERE clauses.
  • Sorting: Sort results by any field with sort (e.g., -created,name).
  • Field Selection: Limit the returned fields with fields for improved performance.
  • Pagination: limit and offset are fully supported for local data.
• Relation Expansion: Support for expanding single and multi-level relations (e.g., post.author) directly from the local cache.
• Full-Text Search: Integrated Full-Text Search (FTS5) for performing fast, local searches across all your cached record data.
• Authentication Persistence: User and admin authentication state is persisted locally using shared_preferences, keeping users logged in across app sessions.
• Cross-Platform Support: Works across all Flutter-supported platforms, including mobile (iOS, Android), web, and desktop (macOS, Windows, Linux).
• Basic File & Image Caching: Includes a PocketBaseImageProvider that caches images in the local database for offline display.
• Custom API Route Caching: Added support for offline caching of custom API routes accessed via the send method. This allows GET requests to custom endpoints to be cached and available offline, improving performance and reliability for custom integrations.
• Robust & Performant: Includes optimizations for batching queries and file streaming on all platforms to handle large files efficiently.

Improvements #

• Improved maintainability by refactoring the large create and update methods in the internal ServiceMixin into smaller, more manageable helper methods.
• Improved web performance by switching from a full http.get() to a streaming download for file fetching, aligning it with the more memory-efficient native implementation.