persistência-em-atores-swift

Atores Swift para Persistência Thread-Safe

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

Quando Ativar

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

Padrão Principal

Repositório Baseado em Ator

O modelo de ator garante acesso serializado — sem condições de corrida, 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)
        // Carregamento síncrono durante init (isolamento do ator ainda não ativo)
        self.cache = Self.loadSynchronously(from: fileURL)
    }

    // MARK: - API Pública

    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: - Privado

    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 assíncronas devido ao isolamento do ator:

let repository = LocalRepository<Question>()

// Leitura — consulta O(1) rápida do cache em memória
let question = await repository.find(by: "q-001")
let allQuestions = await repository.loadAll()

// Escrita — atualiza o cache e persiste no arquivo atomicamente
try await repository.save(newQuestion)
try await repository.delete("q-001")

Combinando com @Observable ViewModel

@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

Decisão	Justificativa
Ator (não classe + lock)	Segurança de thread imposta pelo compilador, sem sincronização manual
Cache em memória + persistência em arquivo	Leituras rápidas do cache, escritas duráveis no disco
Carregamento síncrono no init	Evita complexidade de inicialização assíncrona
Dicionário chaveado por ID	Consultas O(1) por identificador
Genérico sobre Codable & Identifiable	Reutilizável em qualquer tipo de modelo
Escritas atômicas (.atomic)	Previne escritas parciais em caso de falha

Melhores Práticas

• Use tipos Sendable para todos os dados que cruzam fronteiras do ator
• Mantenha a API pública do ator 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 aplicativo falhar no meio da escrita
• Carregue sincronamente no init — inicializadores assíncronos adicionam complexidade com benefício mínimo para arquivos locais
• Combine com ViewModels @Observable para atualizações reativas da interface

Anti-Padrões a Evitar

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

Quando Usar

• Armazenamento local de dados em aplicativos iOS/macOS (dados do usuário, configurações, conteúdo em cache)
• Arquiteturas offline-first que sincronizam com um servidor posteriormente
• Qualquer estado mutável compartilhado que múltiplas partes do aplicativo acessam concorrentemente
• Substituir segurança de thread legada baseada em DispatchQueue por concorrência Swift moderna