FAQ

Why not just use SwiftData directly? Do that if you're happy modeling your data as @Model classes. SwiftLocalStorage is for apps whose model is already a set of Codable DTOs and who want caching semantics (expiration, metadata) without a parallel entity layer.

Why not UserDefaults or files? UserDefaults is meant for small preferences, and hand-rolled file caches need their own indexing, expiry and concurrency control. SwiftLocalStorage gives you both entity and key-value storage behind one API, with transactions and concurrency safety.

Why does fetch return an optional instead of throwing notFound? For a cache, a miss is normal control flow. Errors are reserved for things that actually went wrong.

Can I use my own storage engine? Not yet. The engine protocol is internal while its shape settles. It will be considered for public API before 1.0.

What happens to data already on devices when I update the package? It's kept. The store schema upgrades itself when the store opens: stores from 0.1 to 0.2.2 (V1) and 0.2.3 to 0.5 (V2) move to the current V3 in place. Records written before indexes existed are re-indexed on the first indexed query. Changes to your own DTOs are yours to migrate; see Migrating stored DTOs.

Does it work with SwiftUI? Yes. updates(of:) is a live query built for .task { for try await ... }, and changes(of:) gives typed events for view models. See Observation and SwiftUI.

Known limitations

• Closure filters run in memory. fetch(_:where:) decodes values 500 at a time until it has enough matches. Use indexed fields for filters and sorts that must scale. Indexed queries support AND only (plus oneOf within one string index), with up to three indexes per type; string matching is case-sensitive.
• Change events are per instance. Only writes made through the same LocalStorage instance are observed. Share one instance per store.
• Key-value entries aren't observable. Live queries (updates) refetch once per burst of writes to the type, even when the write doesn't affect the result.
• Migrations go forward only. An older app build reading a newer record gets migrationFailed with storedVersionNewer.
• Apple platforms only, because SwiftData is Apple-only.
• No encryption at rest beyond the platform's data protection.