State Management & Asynchronous Workflows
Dokumentasi ini membedah arsitektur logika bisnis, alur kerja reaktif, manajemen konkurensi, dan perluasan modular yang dikelola oleh ResultsViewModel pada direktori Source/Features/Bookmarks/ViewModel/.
1. ResultsViewModel (Class)
ResultsViewModel dirancang sebagai class singleton yang mengadopsi makro Swift Observation @Observable dan diikat secara mutlak ke antrean utama (@MainActor). Pendekatan ini menjamin bahwa seluruh mutasi properti yang diamati oleh SwiftUI maupun AppKit selalu terjadi secara aman di main thread.
@Observable @MainActor
class ResultsViewModel {
static let shared: ResultsViewModel = .init()
let db: ResultsHandler = .shared
// Sumber Data Utama
var folderRoots: [FolderNode] = []
var folderResults: [Int64?: [ResultNode]] = [:] // Key nil = berada di root
// Cache Struktural (Index untuk operasi O(1))
var folderById: [Int64: FolderNode] = [:]
var parentById: [Int64: Int64?] = [:]
var resultById: [Int64: ResultNode] = [:]
var onTreeChange: ((BookmarkTreeChange) -> Void)?
// ...
}
Properti Sumber Data & Cache Struktural
folderRoots: Array node tingkat atas (root level folders).folderResults: Kamus (dictionary) yang memetakan ID folder induk (Int64?, di mananilmewakili hasil di root) ke daftar node[ResultNode]yang terkandung di dalamnya.folderById: Indeks hash map untuk menemukan instanceFolderNodedalam kompleksitas waktu $O(1)$ tanpa perlu menjelajahi seluruh hierarki secara rekursif.parentById: Indeks pemetaan hubungan hierarki child-to-parent. NilaiparentById[childId] = parentId.resultById: Indeks hash map untuk mengambilResultNodeberdasarkan kunci unikid.
2. Manajemen Konkurensi & Siklus Notifikasi
Untuk mencegah freeze antarmuka pengguna pada basis data yang memiliki ribuan markah tersimpan, proses pembacaan berat dan pengurutan dialihkan ke background thread.
Pola Eksekusi Task.detached
Pada metode getFolders() dan dbLoadAllResults(), kalkulasi hierarki dan sorting dieksekusi di luar MainActor menggunakan Task.detached:
func getFolders() async {
let roots = await Task.detached {
var roots = ResultsHandler.shared.fetchFolderTree()
roots.sort { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
func localSortTree(_ nodes: [FolderNode]) {
for node in nodes {
node.children.sort { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
localSortTree(node.children)
}
}
localSortTree(roots)
return roots
}.value
folderRoots = roots
rebuildFolderIndex()
notifyChange(.fullReload)
}
Reaktivitas via NotificationCenter
flowchart TD
CK["CloudKitSyncManager"] -->|"post(.savedResultsTreeDidUpdate)"| NC["NotificationCenter"]
NC -->|"handleSavedResultsTreeDidUpdate()"| VM["ResultsViewModel"]
VM ~~~ TASKS
subgraph TASKS ["Detached Tasks & In-Memory Index"]
FETCH["fetchFolderTree() & fetchResults()"]
REBUILD["rebuildFolderIndex() & rebuildResultIndex()"]
end
VM --> FETCH
FETCH --> REBUILD
REBUILD --> NOTIFY(["notifyChange(.fullReload)"])
NOTIFY --> UI["UI Layer (NSOutlineView / NavigationStack)"]
classDef ui fill:#e040fb26,stroke:#c026d3,stroke-width:2px;
classDef vm fill:#3b82f626,stroke:#2563eb,stroke-width:2px;
classDef store fill:#22c55e26,stroke:#16a34a,stroke-width:2px;
classDef db fill:#f9731626,stroke:#ea580c,stroke-width:2px;
classDef event fill:#be185d26,stroke:#9d174d,stroke-width:2px,color:#9d174d;
class UI ui;
class VM vm;
class CK,NC,FETCH,REBUILD store;
class NOTIFY event;
sequenceDiagram
participant CloudKit as CloudKitSyncManager
participant NC as NotificationCenter
participant VM as ResultsViewModel
participant UI as macOS / iOS UI
CloudKit->>NC: post(.savedResultsTreeDidUpdate)
NC->>VM: handleSavedResultsTreeDidUpdate()
activate VM
VM->>VM: Task.detached { fetchFolderTree() }
VM->>VM: Task.detached { fetchResults() }
VM->>VM: rebuildFolderIndex() & rebuildResultIndex()
VM-->>UI: notifyChange(.fullReload)
deactivate VM
.savedResultsTreeDidUpdate: Dipicu saat sinkronisasi CloudKit selesai menyerap perubahan dari server. ViewModel memuat ulang seluruh hierarki secara asinkron lalu membangun ulang indeks..bookIdMigrated: Dipicu saat modul katalog memperbarui skema ID buku internal, memastikan referensi markah diperbarui seketika.
3. Dekonstruksi Ekstensi Modular (ViewModel/Extensions/)
Logika bisnis dibagi menjadi beberapa modul fungsional di bawah folder ViewModel/Extensions/:
ViewModel/Extensions/
├── Results+Load.swift # Pemuatan data & pembangunan indeks lookup
├── Results+Tree.swift # Utilitas penelusuran hierarki & breadcrumb
├── Results+FolderOps.swift # Operasi CRUD dan pemindahan folder
├── Results+ResultOps.swift # Operasi CRUD dan pemindahan hasil pencarian
└── Results+Search.swift # Mesin pencari markah dalam memori
Results+Load.swift
Menangani fase inisialisasi data dan pemulihan konsistensi indeks:
getFolders(): Mengambil struktur hierarki folder dari basis data, mengurutkan secara rekursif berbasis lokalitas teks, dan memperbaruifolderRoots.dbLoadAllResults(): Mengambil seluruh hasil pencarian secara massal viaResultsHandler.shared.fetchAllResultsGroupedByFolder()dalam satu kueri terisolasi di background, bebas dari risiko data race traversal referensiFolderNode.rebuildFolderIndex(): Mengisi ulang kamusfolderByIddanparentByIdmelalui penelusuran mendalam (depth-first walk).rebuildResultIndex(): Mengisi ulangresultByIddan memastikan integritas nilaiparentIddi setiap child node.
Results+Tree.swift
Menyediakan fungsi pembantu operasi hierarki (tree operations):
isDescendant(_ node: FolderNode, of ancestor: FolderNode) -> Bool:- Mencegah bahaya infinite circular loop saat pengguna memindahkan folder ke dalam dirinya sendiri atau ke dalam subfoldernya.
folderPath(for folderId: Int64?) -> String:- Membangun jalur navigasi (breadcrumb trail), misalnya:
"Hadits / Shahih Bukhari / Kitab Iman". Menggunakan penelusuran balik ke atas (bottom-up traversal) viaparentByIddengan kompleksitas $O(d)$ di mana $d$ adalah kedalaman hierarki, dilengkapi guardvisited: Set<Int64>untuk memotong siklus anomali.
- Membangun jalur navigasi (breadcrumb trail), misalnya:
removeNodeFromTree(_ node: FolderNode):- Menghapus referensi node secara tepat dari array induknya tanpa merusak struktur cabang lainnya.
Results+FolderOps.swift
Mengelola alur kerja transaksi pembuatan, modifikasi, dan pemindahan folder:
addRootFolder(name: String) throws:- Menyimpan folder baru ke SQLite via
db.insertRootFolder, memperbaruifolderRoots, mendaftarkan ke indeks cache, dan memicu.insertFolderuntuk animasi antarmuka pengguna.
- Menyimpan folder baru ke SQLite via
addSubFolder(parentNode: FolderNode, name: String) throws:- Membuat subfolder di bawah node yang ditentukan, menyortir node sejajar (siblings), dan memancarkan notifikasi perubahan.
updateFolderName(id: Int64, newName: String) throws:- Mengubah nama pada basis data lokal, menyortir ulang posisi folder di antara siblings, serta memicu notifikasi
.moveFolderjika posisinya bergeser secara alfabetis.
- Mengubah nama pada basis data lokal, menyortir ulang posisi folder di antara siblings, serta memicu notifikasi
deleteFolder(node: FolderNode):- Menghapus folder beserta seluruh sub-hierarki di bawahnya secara kaskade (
allDescendantIds), membersihkan hasil terkait dari memori dan indeks pencarian.
- Menghapus folder beserta seluruh sub-hierarki di bawahnya secara kaskade (
moveNode(draggedNode: FolderNode, newParent: FolderNode?) throws:- Memvalidasi batasan hierarki, memperbarui basis data, mereposisi node dalam hierarki memori, dan mengabarkan perubahan indeks ke
NSOutlineView.
- Memvalidasi batasan hierarki, memperbarui basis data, mereposisi node dalam hierarki memori, dan mengabarkan perubahan indeks ke
Results+ResultOps.swift
Mengatur siklus hidup leaf node hasil pencarian:
saveSearchResults(results: [SearchResultItem], query: String, ...):- Mengelompokkan baris hasil pencarian berdasarkan kombinasi arsip dan kitab menggunakan
GroupedResult, lalu menyimpannya ke basis data dalam satu transaksi terpadu.
- Mengelompokkan baris hasil pencarian berdasarkan kombinasi arsip dan kitab menggunakan
updateResultQueryName(id: Int64, newName: String) throws:- Mengubah nama node hasil pencarian dan mengurutkan ulang posisinya pada folder yang bersangkutan.
deleteResult(_ parentFolderId: Int64?, name: String):- Menghapus hasil pencarian dari basis data dan memangkas entri dari memori dari urutan indeks belakang ke depan (reverse iteration) agar stabilitas indeks array tetap terjaga.
moveResult(_ resultId: Int64, to newFolderId: Int64?) throws:- Memindahkan satu result node ke folder penampung yang berbeda.
Results+Search.swift
Menyediakan pencarian instan dalam memori (in-memory filtering):
searchFoldersInMemory(_ query: String) -> [FolderNode]:- Memfilter seluruh nilai pada
folderByIdmenggunakanlocalizedStandardContains.
- Memfilter seluruh nilai pada
searchResultsInMemory(_ query: String) -> [ResultNode]:- Menyaring seluruh node pada
resultById.
- Menyaring seluruh node pada
searchResultsWithFolderPath(_ query: String) -> [SearchResultWithPath]:- Menggabungkan hasil pencarian dengan teks representasi jalur direktori (
folderPath) untuk disajikan pada daftar pencarian global di macOS maupun iOS.
- Menggabungkan hasil pencarian dengan teks representasi jalur direktori (