Swift Actor Persistence
Thread-safe data persistence in Swift using actors — in-memory cache with file-backed storage, eliminating data races by design. Use when persisting data in Swift and a data race or thread-safety problem needs designing out.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Swift Actor Persistence when an AI agent needs a reusable SKILL.md workflow for this job: Thread-safe data persistence in Swift using actors — in-memory cache with file-backed storage, eliminating data races by design. Use when persisting data in Swift and a data race or thread-safety problem needs designing out.
When not to use it
Skip Swift Actor Persistence when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/swift-actor-persistence # Save SKILL.md to ~/.claude/skills/swift-actor-persistence/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/swift-actor-persistence/SKILL.md. For a shared project, commit the folder at .claude/skills/swift-actor-persistence/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Swift Actor Persistence skill for this task: Local data storage in iOS/macOS apps (user data, settings, cached content). Confirm any required inputs or files before making changes.
What supports this recommendation?
88/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 100/100
- Practical detail
- 100/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Swift Actors for Thread-Safe Persistence
Patterns 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.
## When to Activate
- Building a data persistence layer in Swift 5.5+ - Need thread-safe access to shared mutable state - Want to eliminate manual synchronization (locks, DispatchQueues) - Building offline-first apps with local storage
## Core Pattern
### Actor-Based Repository
The actor model guarantees serialized access — no data races, enforced by the compiler.
```swift 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) }) } } ```
### Usage
All calls are automatically async due to actor isolation:
```swift 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") ```
### Combining with @Observable ViewModel
```swift @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() } } ```
## Key Design Decisions
| Decision | Rationale | |----------|-----------| | Actor (not class + lock) | Compiler-enforced thread safety, no manual synchronization | | In-memory cache + file persistence | Fast reads from cache, durable writes to disk | | Synchronous init loading | Avoids async initialization complexity | | Dictionary keyed by ID | O(1) lookups by identifier | | Generic over `Codable & Identifiable` | Reusable across any model type | | Atomic file writes (`.atomic`) | Prevents partial writes on crash |
## Best Practices
- **Use `Sendable` types** for all data crossing actor boundaries - **Keep the actor's public API minimal** — only expose domain operations, not persistence details - **Use `.atomic` writes** to prevent data corruption if the app crashes mid-write - **Load synchronously in `init`** — async initializers add complexity with minimal benefit for local files - **Combine with `@Observable`** ViewModels for reactive UI updates
## Anti-Patterns to Avoid
- Using `DispatchQueue` or `NSLock` instead of actors for new Swift concurrency code - Exposing the internal cache dictionary to external callers - Making the file URL configurable without validation - Forgetting that all actor method calls are `await` — callers must handle async context - Using `nonisolated` to bypass actor isolation (defeats the purpose)
## When to Use
- Local data storage in iOS/macOS apps (user data, settings, cached content) - Offline-first architectures that sync to a server later - Any shared mutable state that multiple parts of the app access concurrently - Replacing legacy `DispatchQueue`-based thread safety with modern Swift concurrency
Intended uses
- Local data storage in iOS/macOS apps (user data, settings, cached content)
- Offline-first architectures that sync to a server later
- Any shared mutable state that multiple parts of the app access concurrently
- Replacing legacy DispatchQueue-based thread safety with modern Swift concurrency
Implementation notes
- Use Sendable types for all data crossing actor boundaries
- Keep the actor's public API minimal — only expose domain operations, not persistence details
- Use .atomic writes to prevent data corruption if the app crashes mid-write
- Load synchronously in init — async initializers add complexity with minimal benefit for local files
- Combine with @Observable ViewModels for reactive UI updates
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.