Swift Actor Persistence

1---2name: swift-actor-persistence3description: Thread-safe data persistence in Swift using actors — in-memory cache with file-backed storage, eliminating data races by design.4origin: ECC5---6 7# Swift Actors for Thread-Safe Persistence8 9Patterns for building thread-safe data persistence layers using Swift actors. Combines in-memory caching with file-backed storage, leveraging the actor model to eliminate data races at compile time.10 11## When to Activate12 13- Building a data persistence layer in Swift 5.5+14- Need thread-safe access to shared mutable state15- Want to eliminate manual synchronization (locks, DispatchQueues)16- Building offline-first apps with local storage17 18## Core Pattern19 20### Actor-Based Repository21 22The actor model guarantees serialized access — no data races, enforced by the compiler.23 24```swift25public actor LocalRepository<T: Codable & Identifiable> where T.ID == String {26    private var cache: [String: T] = [:]27    private let fileURL: URL28 29    public init(directory: URL = .documentsDirectory, filename: String = "data.json") {30        self.fileURL = directory.appendingPathComponent(filename)31        // Synchronous load during init (actor isolation not yet active)32        self.cache = Self.loadSynchronously(from: fileURL)33    }34 35    // MARK: - Public API36 37    public func save(_ item: T) throws {38        cache[item.id] = item39        try persistToFile()40    }41 42    public func delete(_ id: String) throws {43        cache[id] = nil44        try persistToFile()45    }46 47    public func find(by id: String) -> T? {48        cache[id]49    }50 51    public func loadAll() -> [T] {52        Array(cache.values)53    }54 55    // MARK: - Private56 57    private func persistToFile() throws {58        let data = try JSONEncoder().encode(Array(cache.values))59        try data.write(to: fileURL, options: .atomic)60    }61 62    private static func loadSynchronously(from url: URL) -> [String: T] {63        guard let data = try? Data(contentsOf: url),64              let items = try? JSONDecoder().decode([T].self, from: data) else {65            return [:]66        }67        return Dictionary(uniqueKeysWithValues: items.map { ($0.id, $0) })68    }69}70```71 72### Usage73 74All calls are automatically async due to actor isolation:75 76```swift77let repository = LocalRepository<Question>()78 79// Read — fast O(1) lookup from in-memory cache80let question = await repository.find(by: "q-001")81let allQuestions = await repository.loadAll()82 83// Write — updates cache and persists to file atomically84try await repository.save(newQuestion)85try await repository.delete("q-001")86```87 88### Combining with @Observable ViewModel89 90```swift91@Observable92final class QuestionListViewModel {93    private(set) var questions: [Question] = []94    private let repository: LocalRepository<Question>95 96    init(repository: LocalRepository<Question> = LocalRepository()) {97        self.repository = repository98    }99 100    func load() async {101        questions = await repository.loadAll()102    }103 104    func add(_ question: Question) async throws {105        try await repository.save(question)106        questions = await repository.loadAll()107    }108}109```110 111## Key Design Decisions112 113| Decision | Rationale |114|----------|-----------|115| Actor (not class + lock) | Compiler-enforced thread safety, no manual synchronization |116| In-memory cache + file persistence | Fast reads from cache, durable writes to disk |117| Synchronous init loading | Avoids async initialization complexity |118| Dictionary keyed by ID | O(1) lookups by identifier |119| Generic over `Codable & Identifiable` | Reusable across any model type |120| Atomic file writes (`.atomic`) | Prevents partial writes on crash |121 122## Best Practices123 124- **Use `Sendable` types** for all data crossing actor boundaries125- **Keep the actor's public API minimal** — only expose domain operations, not persistence details126- **Use `.atomic` writes** to prevent data corruption if the app crashes mid-write127- **Load synchronously in `init`** — async initializers add complexity with minimal benefit for local files128- **Combine with `@Observable`** ViewModels for reactive UI updates129 130## Anti-Patterns to Avoid131 132- Using `DispatchQueue` or `NSLock` instead of actors for new Swift concurrency code133- Exposing the internal cache dictionary to external callers134- Making the file URL configurable without validation135- Forgetting that all actor method calls are `await` — callers must handle async context136- Using `nonisolated` to bypass actor isolation (defeats the purpose)137 138## When to Use139 140- Local data storage in iOS/macOS apps (user data, settings, cached content)141- Offline-first architectures that sync to a server later142- Any shared mutable state that multiple parts of the app access concurrently143- Replacing legacy `DispatchQueue`-based thread safety with modern Swift concurrency