TopDogLabs/LocalData
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs Proposal

Browse Source 
Summary:
- Docs: Proposal

Stats:
- 1 file changed, 14 insertions(+)
This commit is contained in:
Matt Bruce 2026-01-16 16:59:58 -06:00
parent fb90270d9f
commit efb740e291
1 changed files with 14 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
Proposal.md
View File

@ -18,6 +18,7 @@ Create a single, typed, discoverable namespace for persisted app data with consi
### Core Components ### Core Components
- **StorageKey** protocol - Defines storage configuration for each data type - **StorageKey** protocol - Defines storage configuration for each data type
- **StorageKey.migration** - Optional protocol-based migration attached to a key
- **StorageRouter** actor - Main entry point coordinating all storage operations - **StorageRouter** actor - Main entry point coordinating all storage operations
- **StorageProviding** protocol - Abstraction for storage operations - **StorageProviding** protocol - Abstraction for storage operations
- **StorageKeyCatalog** protocol - Catalog of keys for auditing/validation - **StorageKeyCatalog** protocol - Catalog of keys for auditing/validation
@ -47,6 +48,10 @@ Each helper is a dedicated actor providing thread-safe access to a specific stor
- **AnyStorageKey** - Type-erased storage key for catalogs - **AnyStorageKey** - Type-erased storage key for catalogs
- **AnyStorageMigration** - Type-erased migration for protocol-based workflows - **AnyStorageMigration** - Type-erased migration for protocol-based workflows
- **AnyCodable** - Type-erased Codable for mixed-type payloads - **AnyCodable** - Type-erased Codable for mixed-type payloads
- **MigrationContext** - Context for conditional migrations (app version, device, system info)
- **MigrationResult** - Migration outcome with errors and metadata
- **MigrationError** - Error types for migration failures
- **DeviceInfo / SystemInfo** - Device and system metrics used by migrations
## Usage Pattern ## Usage Pattern
Apps extend StorageKeys with their own key types and use StorageRouter.shared. This follows the Notification.Name pattern for discoverable keys. Apps extend StorageKeys with their own key types and use StorageRouter.shared. This follows the Notification.Name pattern for discoverable keys.
@ -62,6 +67,14 @@ The `StorageRouter` provides discovery APIs to retrieve all registered keys for
## Sync Behavior ## Sync Behavior
StorageRouter can call WCSession.updateApplicationContext for manual or automaticSmall sync policies when availability allows it. Session activation and receiving data are owned by the app. StorageRouter can call WCSession.updateApplicationContext for manual or automaticSmall sync policies when availability allows it. Session activation and receiving data are owned by the app.
### Bootstrapping and Watch Requests
LocalData exposes helper APIs to make watch sync reliable after relaunch or reconnection:
- `StorageRouter.syncRegisteredKeysIfNeeded()` re-sends stored values for eligible keys.
- `StorageRouter.syncSnapshot()` returns a payload snapshot for replying to watch requests.
Apps should call `syncRegisteredKeysIfNeeded()` on launch and on WatchConnectivity reachability changes, and reply to watch-initiated requests with `syncSnapshot()` to avoid launch-order issues.
## Platforms ## Platforms
- iOS 17+ - iOS 17+
- watchOS 10+ - watchOS 10+
@ -69,5 +82,6 @@ StorageRouter can call WCSession.updateApplicationContext for manual or automati
## Future Ideas (Not Implemented) ## Future Ideas (Not Implemented)
- Key rotation strategies for encrypted data - Key rotation strategies for encrypted data
- Watch-optimized data representations - Watch-optimized data representations
- Persistent storage for sync policy overrides
Any future changes should keep LocalData documentation in sync with code changes. Any future changes should keep LocalData documentation in sync with code changes.