//
//  PreferenceStoring.swift
//
//  Copyright 2026 Brendan Szymanski <hello@bscubed.dev>
//
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
//  SPDX-License-Identifier: GPL-3.0-or-later
//

/// An ordered, asynchronous backend for scalar application preferences.
package protocol PreferenceStoring: Sendable {
    /// Every persisted row, read once at open. The UI serves synchronous reads from this snapshot.
    nonisolated var initialSnapshot: [String: StoredPreference] { get }

    /// Queues a write without blocking or performing I/O on the caller's thread.
    ///
    /// - Parameters:
    ///   - key: The stable preference row key.
    ///   - value: The new scalar value, or `nil` to delete the row.
    nonisolated func enqueue(_ key: String, _ value: StoredPreference?)

    /// Returns after every write queued before this call has been applied.
    ///
    /// - Throws: The first backend failure recorded since the previous flush, then clears that
    ///   retained failure.
    func flush() async throws
}

/// One queued mutation, or a barrier that reports the queue has drained to this point.
package enum PreferenceWrite: Sendable {
    case set(key: String, value: StoredPreference?)
    case barrier(@Sendable (PreferenceStoreError?) -> Void)
}