Skip to content

State Management

Manajemen state di modul Search ditangani oleh SearchViewModel, yang dioptimalkan dengan makro @Observable (Swift 5.9+) untuk integrasi reaktif dengan antarmuka SwiftUI maupun binding data ke UIKit dan AppKit (melalui Combine atau Observation).

Komponen SearchViewModel

ViewModel ini mengoordinasikan antrean multithread dari SearchEngine, menyangga hasil melalui SearchResultBuffer, dan menyiapkannya untuk dikonsumsi oleh lapisan presentasi (UI) secara lazy menggunakan SearchHitResolver.

State Utama

  • query: Teks atau kata kunci yang dicari.
  • searchMode: Mode pencarian (Frasa, Mengandung, OR, Jarak/Near).
  • nearDistance: Jarak maksimal kata untuk mode Near.
  • results: Kumpulan data SearchResultItem yang dipancarkan ke antarmuka pengguna.
  • isSearching & isPaused: Indikator status siklus hidup (lifecycle) pencarian yang sedang aktif.
  • Indikator Progress: Properti totalTables, completedTables, totalRowsInTable, dan completedRowsInTable digunakan untuk memandu bilah kemajuan (progress bar). Pada mode Unified FTS, completedRowsInTable / totalRowsInTable merefleksikan alur streaming baris hasil secara adaptif dengan animasi reaktif (SearchProgressView di iOS dan progressTable di macOS).

Komponen Penyangga & Resolusi Viewport

1. SearchResultBuffer (Class)

Untuk mencegah freezing antarmuka pengguna saat kueri FTS menghasilkan ribuan hingga ratusan ribu kecocokan dalam hitungan milidetik, SearchResultBuffer bertindak sebagai penyangga (buffer) adaptif dengan perlindungan Mutex:

final class SearchResultBuffer: Sendable {
    private let state = Mutex(BufferState())
    private let batchSize: Int // Nilai bawaan: 50 item
    private let flushInterval: Duration // Nilai bawaan: 100ms
    private let onFlush: @Sendable ([SearchResultItem]) -> Void
}
  • Mekanisme Adaptive Flush: Item hasil pencarian ditampung di dalam memori penyangga. Pengiriman hasil ke SearchViewModel (onFlush) dipicu ketika salah satu dari dua kondisi terpenuhi:
  • Jumlah item yang tertampung mencapai ambang batas batchSize (50 item).
  • Interval waktu flushInterval (100 ms) berakhir.
  • Pendekatan ini meratakan beban main-thread render sehingga antarmuka tetap berjalan mulus pada 60/120 fps.

2. SearchHitResolver (Class)

Merupakan singleton berstatus @MainActor yang bertugas menyelesaikan cuplikan teks berformat (NSAttributedString) secara lazy (sesuai kebutuhan sel tabel yang sedang terlihat di layar):

@MainActor
final class SearchHitResolver {
    static let shared = SearchHitResolver()
    private let cache = NSCache<NSString, NSAttributedString>() // Batas kapasitas: 1000 entri

    func resolveSnippet(
        for item: SearchResultItem,
        keywords: [String],
        mode: SearchMode,
        nearDistance: Int
    ) async -> NSAttributedString?
}
  • Alur Resolusi:
  • Memeriksa cache NSCache menggunakan kunci unik item.id.
  • Jika belum tersedia, membaca baris teks spesifik secara langsung dari basis data arsip melalui LibraryDataManager.shared.fetchSingleContent.
  • Membersihkan teks Arab (cleaningLineBreaks, stripSpanTags), menormalisasi angka (convertToArabicDigits), dan mencari rentang kata kunci.
  • Menyimpan hasil NSAttributedString yang telah disorot warnanya ke dalam cache 1000 item.

Sub-Komponen (Ekstensi)

Fungsionalitas SearchViewModel didistribusikan ke dalam beberapa berkas ekstensi untuk memelihara prinsip Separation of Concerns:

1. Execution (Search+Execution.swift)

Menangani siklus pencarian seperti eksekusi awal (startSearch), jeda/lanjutkan (pause/resume), dan penghentian task (stopSearch). Eksekusi dialihkan ke background thread melalui Task.detached dengan penguncian Mutex pada referensi Task untuk mencegah akses konkuren ganda. Di AppKit (macOS), ekstensi ini memanfaatkan Combine Publishers seperti searchDidInitialize atau searchProgressDidUpdate.

  • Sentralisasi Cooldown Penyelesaian (handleSearchCompletion): Penutupan indikator pencarian dan pengiriman sinyal selesai disentralisasi ke dalam view model dengan jeda waktu terukur (0.5 detik di iOS dan 1.0 detik di macOS via completionDismissTask yang diproteksi Mutex). Mekanisme ini mengeliminasi race condition pada OptionSearchVC saat kueri menghasilkan 0 baris kecocokan, memastikan bilah progres ditutup dan tombol pencarian di-reset secara konsisten.

2. Library (Search+Library.swift)

Bertindak sebagai adapter dan delegator menuju LibraryDataManager untuk melacak tabel SQLite (resolve) terhadap pustaka kitab terkait.

3. Observers (Search+Observers.swift)

Memantau siaran internal (NotificationCenter). Jika direktori penyimpanan basis data perpustakaan diubah, modul ini mereset dan memuat ulang instrumen pencarian secara mandiri.

4. Restoration (Search+Restoration.swift)

Membaca dan menyimpan cadangan sesi pencarian (ReaderState). Mekanisme ini memulihkan hasil pencarian terakhir ketika pengguna membuka kembali kotak dialog tanpa harus melakukan komputasi ulang.

5. Saved Results (Search+SavedResults.swift)

Menyediakan utilitas pemrosesan teks sorotan (cuplikan rentang kata kunci NSAttributedString). Ketika riwayat hasil tersimpan (Saved Results) diakses, modul memanfaatkan ResultBuffer (batching) untuk memuat fragmen secara efisien.

6. Ekstensi Spesifik Platform

Memuat abstraksi terisolasi bagi masing-masing platform:

  • iOS (Search+iOS.swift): Penerapan debounce filter (melalui Combine), pencatatan histori pencarian (search history), serta penyesuaian hierarki kategori perpustakaan.
  • macOS (Search+macOS.swift): Penyesuaian sinkronisasi pemuatan data ke dalam manajer pustaka macOS.