swift-persistence

Swift Persistence

Instructions

Step 1: Choose the framework

Ask if not already specified:

SwiftData or CoreData?

	SwiftData	CoreData
Min iOS	iOS 17+	iOS 8+
Syntax	@Model macro, Swift-native	NSManagedObject, Objective-C roots
Recommended for	New projects on iOS 17+	Legacy projects, complex migration needs

Then load the matching reference:

• SwiftData → references/swiftdata.md
• CoreData → references/coredata.md

Step 2: Define the models

Ask: what entities are needed? For each entity:

• Name (singular, UpperCamelCase: Task, UserProfile, Transaction)
• Properties and their types
• Relationships to other entities (one-to-one, one-to-many, many-to-many)
• Any computed properties needed

Step 3: Generate the model layer

Models go in Core/Models/ — they are plain data types, framework-agnostic where possible.

Persistence infrastructure goes in Services/Storage/:

• PersistenceController.swift — container setup, in-memory preview/test variant
• [Entity]Repository.swift — CRUD operations for each entity
• [Entity]RepositoryProtocol.swift — protocol for testability

Rule: ViewModels inject a repository protocol. They never touch ModelContext or NSManagedObjectContext directly.

Services/Storage/
├── PersistenceController.swift
├── TaskRepository.swift
└── TaskRepositoryProtocol.swift

Step 4: Generate the repository protocol

Always define a protocol first so ViewModels can be tested with a mock:

// Services/Storage/TaskRepositoryProtocol.swift
protocol TaskRepositoryProtocol {
    func fetchAll() throws -> [Task]
    func save(_ task: Task) throws
    func delete(_ task: Task) throws
}

Step 5: Wire into the ViewModel

ViewModels receive the repository via init:

@MainActor
@Observable
final class TaskListViewModel {
    private(set) var tasks: [Task] = []
    private let repository: TaskRepositoryProtocol

    init(repository: TaskRepositoryProtocol = TaskRepository()) {
        self.repository = repository
    }

    func loadTasks() {
        tasks = (try? repository.fetchAll()) ?? []
    }
}