Swift Actors para Persistência Thread-Safe

Padrões para construir camadas de persistência de dados thread-safe usando actors do Swift. Combina cache em memória com armazenamento em arquivo, aproveitando o modelo de actors para eliminar data races em tempo de compilação.

Quando Ativar

• Construindo uma camada de persistência de dados em Swift 5.5+
• Necessidade de acesso thread-safe a estado mutável compartilhado
• Desejo de eliminar sincronização manual (locks, DispatchQueues)
• Construindo apps offline-first com armazenamento local

Padrão Central

Repositório Baseado em Actor

O modelo de actors garante acesso serializado — sem data races, imposto pelo compilador.

public actor LocalRepository<T: Codable & Identifiable> where T.ID == String {
    private var cache: [String: T] = [:]
    private let fileURL: URL

    public init(directory: URL = .documentsDirectory, filename: String = "data.json") {
        self.fileURL = directory.appendingPathComponent(filename)
        // Synchronous load during init (actor isolation not yet active)
        self.cache = Self.loadSynchronously(from: fileURL)
    }

    // MARK: - Public API

    public func save(_ item: T) throws {
        cache[item.id] = item
        try persistToFile()
    }

    public func delete(_ id: String) throws {
        cache[id] = nil
        try persistToFile()
    }

    public func find(by id: String) -> T? {
        cache[id]
    }

    public func loadAll() -> [T] {
        Array(cache.values)
    }

    // MARK: - Private

    private func persistToFile() throws {
        let data = try JSONEncoder().encode(Array(cache.values))
        try data.write(to: fileURL, options: .atomic)
    }

    private static func loadSynchronously(from url: URL) -> [String: T] {
        guard let data = try? Data(contentsOf: url),
              let items = try? JSONDecoder().decode([T].self, from: data) else {
            return [:]
        }
        return Dictionary(uniqueKeysWithValues: items.map { ($0.id, $0) })
    }
}

Uso

Todas as chamadas são automaticamente async devido ao isolamento do actor:

let repository = LocalRepository<Question>()

// Read — fast O(1) lookup from in-memory cache
let question = await repository.find(by: "q-001")
let allQuestions = await repository.loadAll()

// Write — updates cache and persists to file atomically
try await repository.save(newQuestion)
try await repository.delete("q-001")

Combinando com ViewModel @Observable

@Observable
final class QuestionListViewModel {
    private(set) var questions: [Question] = []
    private let repository: LocalRepository<Question>

    init(repository: LocalRepository<Question> = LocalRepository()) {
        self.repository = repository
    }

    func load() async {
        questions = await repository.loadAll()
    }

    func add(_ question: Question) async throws {
        try await repository.save(question)
        questions = await repository.loadAll()
    }
}

Principais Decisões de Design

Melhores Práticas

• Use tipos Sendable para todos os dados que cruzam limites de actors
• Mantenha a API pública do actor mínima — exponha apenas operações de domínio, não detalhes de persistência
• Use escritas .atomic para prevenir corrupção de dados se o app travar no meio de uma escrita
• Carregue síncronamente em init — inicializadores async adicionam complexidade com benefício mínimo para arquivos locais
• Combine com ViewModels @Observable para atualizações reativas da UI

Anti-Padrões a Evitar

• Usar DispatchQueue ou NSLock em vez de actors para novo código de concorrência Swift
• Expor o dicionário de cache interno para chamadores externos
• Tornar o URL do arquivo configurável sem validação
• Esquecer que todas as chamadas de método de actor são await — os chamadores devem lidar com o contexto async
• Usar nonisolated para contornar o isolamento do actor (anula o propósito)

Quando Usar

• Armazenamento de dados local em apps iOS/macOS (dados do usuário, configurações, conteúdo em cache)
• Arquiteturas offline-first que sincronizam com um servidor posteriormente

…