Persisting Models with SwiftData

// Packages/FieldNotesKit/Sources/FieldNotesModel/Note.swift (updated)
import Foundation

public struct NoteLocation: Hashable, Sendable, Codable {
    public var latitude: Double
    public var longitude: Double
    public var placeName: String?

    public init(latitude: Double, longitude: Double, placeName: String? = nil) {
        self.latitude = latitude; self.longitude = longitude; self.placeName = placeName
    }
}

/// Metadata only; the image bytes live in SwiftData external storage (`PhotoRecord.data`).
public struct PhotoAttachment: Identifiable, Hashable, Sendable {
    public var id: UUID
    public var fileName: String

    public init(id: UUID = UUID(), fileName: String) {
        self.id = id; self.fileName = fileName
    }
}

public struct Note: Identifiable, Hashable, Sendable {
    public var id: UUID
    public var title: String
    public var body: String
    public var createdAt: Date
    public var notebookID: Notebook.ID?
    public var tags: [String]
    public var isPinned: Bool
    public var location: NoteLocation? = nil
    public var attachments: [PhotoAttachment] = []

    public init(id: UUID = UUID(), title: String, body: String = "", createdAt: Date = .now,
                notebookID: Notebook.ID? = nil, tags: [String] = [], isPinned: Bool = false,
                location: NoteLocation? = nil, attachments: [PhotoAttachment] = []) {
        self.id = id; self.title = title; self.body = body; self.createdAt = createdAt
        self.notebookID = notebookID; self.tags = tags; self.isPinned = isPinned
        self.location = location; self.attachments = attachments
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Persistence/Records.swift
import Foundation
import SwiftData
import FieldNotesModel

@Model
public final class NoteRecord {
    #Index<NoteRecord>([\.createdAt], [\.isPinned, \.createdAt])

    @Attribute(.preserveValueOnDeletion) public var id: UUID = UUID()
    public var title: String = ""
    public var body: String = ""
    public var createdAt: Date = Date.now
    public var tags: [String] = []
    public var isPinned: Bool = false
    public var latitude: Double?
    public var longitude: Double?
    public var placeName: String?

    @Relationship public var notebook: NotebookRecord?
    @Relationship(deleteRule: .cascade, inverse: \PhotoRecord.note)
    public var photos: [PhotoRecord] = []

    public init(_ note: Note) {
        id = note.id
        title = note.title
        body = note.body
        createdAt = note.createdAt
        tags = note.tags
        isPinned = note.isPinned
        latitude = note.location?.latitude
        longitude = note.location?.longitude
        placeName = note.location?.placeName
    }
}

@Model
public final class NotebookRecord {
    @Attribute(.preserveValueOnDeletion) public var id: UUID = UUID()
    public var name: String = ""
    public var symbolName: String = "book.closed"

    @Relationship(deleteRule: .nullify, inverse: \NoteRecord.notebook)
    public var notes: [NoteRecord] = []

    public init(_ notebook: Notebook) {
        id = notebook.id
        name = notebook.name
        symbolName = notebook.symbolName
    }
}

@Model
public final class PhotoRecord {
    public var id: UUID = UUID()
    public var fileName: String = ""
    public var addedAt: Date = Date.now
    @Attribute(.externalStorage) public var data: Data = Data()
    public var note: NoteRecord?

    public init(id: UUID = UUID(), fileName: String, data: Data) {
        self.id = id
        self.fileName = fileName
        self.data = data
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Persistence/ModelContainer+FieldNotes.swift
import Foundation
import SwiftData

extension ModelContainer {
    /// The FieldNotes store: the App Group container, mirrored to iCloud by the main app only.
    public static func fieldNotes(inMemory: Bool = false) throws -> ModelContainer {
        let schema = Schema(versionedSchema: FieldNotesSchemaV2.self)

        if inMemory {
            let configuration = ModelConfiguration(schema: schema, isStoredInMemoryOnly: true,
                                                   groupContainer: .none, cloudKitDatabase: .none)
            return try ModelContainer(for: schema, configurations: configuration)
        }

        // Widgets, App Intents and the share extension run as app extensions and read and write the same
        // store. Every process passes the same migration plan, so whichever opens the store first after an
        // update runs the custom stage; only the main app mirrors the store to CloudKit.
        let isAppExtension = Bundle.main.bundleURL.pathExtension == "appex"
        let configuration = ModelConfiguration(
            "FieldNotes",
            schema: schema,
            groupContainer: .identifier("group.com.example.fieldnotes"),
            cloudKitDatabase: isAppExtension ? .none : .private("iCloud.com.example.fieldnotes"))
        return try ModelContainer(for: schema,
                                  migrationPlan: FieldNotesMigrationPlan.self,
                                  configurations: configuration)
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Persistence/Schema.swift
import Foundation
import SwiftData

public enum FieldNotesSchemaV1: VersionedSchema {
    public static var versionIdentifier: Schema.Version { Schema.Version(1, 0, 0) }
    public static var models: [any PersistentModel.Type] {
        [NoteRecord.self, NotebookRecord.self, PhotoRecord.self]   // the nested V1 snapshots below
    }

    @Model final class NoteRecord {
        #Index<NoteRecord>([\.createdAt], [\.isPinned, \.createdAt])
        @Attribute(.preserveValueOnDeletion) var id: UUID = UUID()
        var title: String = ""
        var body: String = ""
        var createdAt: Date = Date.now
        var tags: [String] = []
        var isPinned: Bool = false
        @Relationship var notebook: NotebookRecord?
        @Relationship(deleteRule: .cascade, inverse: \PhotoRecord.note) var photos: [PhotoRecord] = []
        init() {}
    }

    @Model final class NotebookRecord {
        @Attribute(.preserveValueOnDeletion) var id: UUID = UUID()
        var name: String = ""
        var symbolName: String = "book.closed"
        @Relationship(deleteRule: .nullify, inverse: \NoteRecord.notebook) var notes: [NoteRecord] = []
        init() {}
    }

    @Model final class PhotoRecord {
        var id: UUID = UUID()
        var fileName: String = ""
        var addedAt: Date = Date.now
        @Attribute(.externalStorage) var data: Data = Data()
        var note: NoteRecord?
        init() {}
    }
}

public enum FieldNotesSchemaV2: VersionedSchema {
    public static var versionIdentifier: Schema.Version { Schema.Version(2, 0, 0) }
    public static var models: [any PersistentModel.Type] {
        [NoteRecord.self, NotebookRecord.self, PhotoRecord.self]   // the current top-level records
    }
}

// FieldNotes/Search/RecordSearchResults.swift
import SwiftUI
import SwiftData
import FieldNotesServices
import FieldNotesUI

struct RecordSearchResults: View {
    @Query private var results: [NoteRecord]

    init(searchText: String) {
        let predicate = #Predicate<NoteRecord> { record in
            searchText.isEmpty
                || record.title.localizedStandardContains(searchText)
                || record.body.localizedStandardContains(searchText)
        }
        _results = Query(filter: predicate,
                         sort: [SortDescriptor(\NoteRecord.createdAt, order: .reverse)])
    }

    var body: some View {
        List(results) { record in
            NoteRow(note: record.note)
        }
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Persistence/SwiftDataNotePersistence+Pinned.swift
// SwiftDataNotePersistence is the model actor shown below.
import SwiftData
import FieldNotesModel

extension SwiftDataNotePersistence {
    public func pinnedNoteSummary(limit: Int) throws -> (total: Int, newest: [Note]) {
        var descriptor = FetchDescriptor<NoteRecord>(
            predicate: #Predicate { $0.isPinned },
            sortBy: [SortDescriptor(\.createdAt, order: .reverse)])
        let total = try modelContext.fetchCount(descriptor)
        descriptor.fetchLimit = limit
        descriptor.relationshipKeyPathsForPrefetching = [\.notebook]
        return (total, try modelContext.fetch(descriptor).map(\.note))
    }

    /// Pinned notes, newest first, fetched with the predicate and the index above instead of loading every note.
    public func pinnedNotes(limit: Int? = nil) throws -> [Note] {
        var descriptor = FetchDescriptor<NoteRecord>(
            predicate: #Predicate { $0.isPinned },
            sortBy: [SortDescriptor(\.createdAt, order: .reverse)])
        descriptor.fetchLimit = limit
        return try modelContext.fetch(descriptor).map(\.note)
    }

    /// One note by identifier, for intents that change a single note.
    public func note(id: Note.ID) throws -> Note? {
        try noteRecord(id: id)?.note
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Persistence/NotePersisting.swift
import FieldNotesModel

public protocol NotePersisting: Sendable {
    func fetchNotes() async throws -> [Note]
    func save(_ note: Note) async throws
    func deleteNote(id: Note.ID) async throws
    func fetchNotebooks() async throws -> [Notebook]
    func save(_ notebook: Notebook) async throws
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Persistence/SwiftDataNotePersistence.swift
import Foundation
import SwiftData
import FieldNotesModel

@ModelActor
public actor SwiftDataNotePersistence: NotePersisting {
    public func fetchNotes() async throws -> [Note] {
        let descriptor = FetchDescriptor<NoteRecord>(sortBy: [SortDescriptor(\.createdAt, order: .reverse)])
        return try modelContext.fetch(descriptor).map(\.note)
    }

    public func save(_ note: Note) async throws {
        let record: NoteRecord
        if let existing = try noteRecord(id: note.id) {
            record = existing
            record.update(from: note)
        } else {
            record = NoteRecord(note)
            modelContext.insert(record)
        }
        record.notebook = try notebookRecord(id: note.notebookID)
        try modelContext.save()
    }

    public func deleteNote(id: Note.ID) async throws {
        guard let record = try noteRecord(id: id) else { return }
        modelContext.delete(record)          // cascades to the note's photos
        try modelContext.save()
    }

    public func fetchNotebooks() async throws -> [Notebook] {
        try modelContext.fetch(FetchDescriptor<NotebookRecord>(sortBy: [SortDescriptor(\.name)])).map(\.notebook)
    }

    /// Notebooks are saved before the notes that reference them, so `save(_ note:)` can link the relationship.
    public func save(_ notebook: Notebook) async throws {
        if let existing = try notebookRecord(id: notebook.id) {
            existing.update(from: notebook)
        } else {
            modelContext.insert(NotebookRecord(notebook))
        }
        try modelContext.save()
    }

    func noteRecord(id: Note.ID) throws -> NoteRecord? {
        var descriptor = FetchDescriptor<NoteRecord>(predicate: #Predicate { $0.id == id })
        descriptor.fetchLimit = 1
        return try modelContext.fetch(descriptor).first
    }

    func notebookRecord(id: Notebook.ID?) throws -> NotebookRecord? {
        guard let id else { return nil }
        var descriptor = FetchDescriptor<NotebookRecord>(predicate: #Predicate { $0.id == id })
        descriptor.fetchLimit = 1
        return try modelContext.fetch(descriptor).first
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/NoteStore.swift (updated)
import Observation
import OSLog
import FieldNotesModel

@Observable
@MainActor
public final class NoteStore {
    public var notes: [Note]
    public var notebooks: [Notebook]

    @ObservationIgnored private let syncer: any NoteSyncing
    @ObservationIgnored private let persistence: (any NotePersisting)?
    @ObservationIgnored private var lastWrite: Task<Void, Never>?
    @ObservationIgnored private var writeCount = 0
    @ObservationIgnored private let log = Logger(subsystem: "com.example.fieldnotes", category: "persistence")

    public init(notes: [Note] = [], notebooks: [Notebook] = [],
                syncer: any NoteSyncing = NoOpNoteSyncer(),
                persistence: (any NotePersisting)? = nil) {
        self.notes = notes
        self.notebooks = notebooks
        self.syncer = syncer
        self.persistence = persistence
    }

    /// Replaces `notes` and `notebooks` with what the store holds; call at launch and after remote changes.
    public func load() async {
        guard let persistence else { return }
        while true {
            let writesBefore = writeCount
            await lastWrite?.value
            do {
                let loadedNotebooks = try await persistence.fetchNotebooks()
                let loadedNotes = try await persistence.fetchNotes()
                // A change made while the fetch ran is newer than this snapshot: read again once it has landed.
                guard writeCount == writesBefore else { continue }
                notebooks = loadedNotebooks
                notes = loadedNotes
            } catch {
                log.error("Loading notes failed: \(error.localizedDescription)")
            }
            return
        }
    }

    public func add(_ notebook: Notebook) {
        notebooks.append(notebook)
        write { try await $0.save(notebook) }
    }

    public func add(_ note: Note) {
        notes.append(note)
        write { try await $0.save(note) }
    }

    public func delete(_ note: Note) {
        notes.removeAll { $0.id == note.id }
        write { try await $0.deleteNote(id: note.id) }
    }

    public func togglePin(_ note: Note) {
        guard let index = notes.firstIndex(where: { $0.id == note.id }) else { return }
        notes[index].isPinned.toggle()
        let updated = notes[index]
        write { try await $0.save(updated) }
    }

    public func refresh() async throws {
        try await syncer.sync()
    }

    /// Returns once every queued write has reached the store, e.g. before telling a widget to reload.
    public func waitForPendingWrites() async {
        await lastWrite?.value
    }

    /// Runs writes one after another, in the order the user made them.
    private func write(_ operation: @escaping @Sendable (any NotePersisting) async throws -> Void) {
        guard let persistence else { return }
        writeCount += 1
        let previous = lastWrite
        lastWrite = Task {
            await previous?.value
            do {
                try await operation(persistence)
            } catch {
                log.error("Saving a note failed: \(error.localizedDescription)")
            }
        }
    }
}

// FieldNotesTests/PersistenceTests.swift
import Testing
import SwiftData
import FieldNotesModel
import FieldNotesServices

@MainActor
struct PersistenceTests {
    @Test func pinnedNoteSurvivesReload() async throws {
        let persistence = SwiftDataNotePersistence(modelContainer: try .fieldNotes(inMemory: true))
        let note = Note(title: "Kingfisher", location: NoteLocation(latitude: 57.3, longitude: -4.4))

        let store = NoteStore(persistence: persistence)
        store.add(note)
        store.togglePin(note)

        let reloaded = NoteStore(persistence: persistence)
        await store.load()          // waits for both writes
        await reloaded.load()
        #expect(reloaded.notes.map(\.isPinned) == [true])
        #expect(reloaded.notes.first?.location?.latitude == 57.3)
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Persistence/SwiftDataNotePersistence+History.swift
import SwiftData
import FieldNotesModel

extension SwiftDataNotePersistence {
    /// The ids of notes deleted since `token`, plus the token to pass next time.
    public func deletedNoteIDs(after token: DefaultHistoryToken?)
        throws -> (ids: [Note.ID], nextToken: DefaultHistoryToken?) {
        var descriptor = HistoryDescriptor<DefaultHistoryTransaction>()
        if let token {
            descriptor.predicate = #Predicate { $0.token > token }
        }
        let transactions = try modelContext.fetchHistory(descriptor)
        var ids: [Note.ID] = []
        for transaction in transactions {
            for change in transaction.changes {
                if case .delete(let deletion as DefaultHistoryDelete<NoteRecord>) = change,
                   let id = deletion.tombstone[\.id] as? UUID {
                    ids.append(id)
                }
            }
        }
        return (ids, transactions.last?.token ?? token)
    }

    /// Drops transactions that every consumer has already processed.
    public func trimHistory(before token: DefaultHistoryToken) throws {
        try modelContext.deleteHistory(HistoryDescriptor<DefaultHistoryTransaction>(
            predicate: #Predicate { $0.token < token }))
    }
}

// FieldNotes/Diagnostics/CloudSchemaInitializer.swift (debug builds only, run once after a model change)
#if DEBUG
import CoreData
import SwiftData
import FieldNotesServices

func initializeCloudKitDevelopmentSchema() throws {
    let configuration = ModelConfiguration("FieldNotes",
                                           groupContainer: .identifier("group.com.example.fieldnotes"))
    try autoreleasepool {
        let description = NSPersistentStoreDescription(url: configuration.url)
        description.cloudKitContainerOptions =
            NSPersistentCloudKitContainerOptions(containerIdentifier: "iCloud.com.example.fieldnotes")
        description.shouldAddStoreAsynchronously = false
        guard let model = NSManagedObjectModel.makeManagedObjectModel(
            for: [NoteRecord.self, NotebookRecord.self, PhotoRecord.self]) else { return }
        let container = NSPersistentCloudKitContainer(name: "FieldNotes", managedObjectModel: model)
        container.persistentStoreDescriptions = [description]
        container.loadPersistentStores { _, error in
            if let error { fatalError(error.localizedDescription) }
        }
        try container.initializeCloudKitSchema()
        if let store = container.persistentStoreCoordinator.persistentStores.first {
            try container.persistentStoreCoordinator.remove(store)
        }
    }
}
#endif

// QuickNotes/QuickNotesApp.swift (a separate sketch app, not FieldNotes)
import SwiftUI
import SwiftData

@Model
final class QuickNote {
    #Unique<QuickNote>([\.title, \.createdAt])        // no two notes with the same title and time
    #Index<QuickNote>([\.createdAt])

    @Attribute(.unique) var slug: String               // a single-property unique constraint
    var title: String
    var createdAt: Date
    @Transient var isExpanded = false                  // UI state, never persisted

    init(title: String, createdAt: Date = .now) {
        self.title = title
        self.createdAt = createdAt
        self.slug = "\(title.lowercased())-\(createdAt.timeIntervalSince1970)"
    }
}

struct QuickNoteList: View {
    @Environment(\.modelContext) private var modelContext
    @Query(sort: \QuickNote.createdAt, order: .reverse) private var notes: [QuickNote]

    var body: some View {
        List {
            ForEach(notes) { note in
                Text(note.title)
            }
            .onDelete { offsets in
                for index in offsets { modelContext.delete(notes[index]) }
            }
        }
        .toolbar {
            Button("Add", systemImage: "plus") {
                modelContext.insert(QuickNote(title: "Untitled"))
            }
        }
    }
}

@main
struct QuickNotesApp: App {
    var body: some Scene {
        WindowGroup {
            NavigationStack { QuickNoteList() }
        }
        .modelContainer(for: QuickNote.self, isUndoEnabled: true)
    }
}

// The shape only: a configuration names the store type that SwiftData instantiates.
import SwiftData

// final class NotesJSONStoreConfiguration: DataStoreConfiguration { typealias Store = NotesJSONStore ... }
// final class NotesJSONStore: DataStore { ... fetch(_:), save(_:) ... }
// let container = try ModelContainer(for: schema, configurations: NotesJSONStoreConfiguration(...))