Local mutated bookmarks persistence & The new bookmarks persistence

Data/MutatedPageBookmarkPersistence/Sources/GRDBMutatedPageBookmarkPersistence.swift

@@ -0,0 +1,192 @@
+//
+//  GRDBMutatedPageBookmarkPersistence.swift
+//  QuranEngine
+//
+//  Created by Mohannad Hassan on 10/02/2025.
+//
+
+import Combine
+import Foundation
+import GRDB
+import SQLitePersistence
+import VLogging
+
+public struct GRDBMutatedPageBookmarkPersistence: MutatedPageBookmarkPersistence {
+    // MARK: Lifecycle
+
+    init(db: DatabaseConnection) {
+        self.db = db
+        do {
+            try migrator.migrate(db)
+        } catch {
+            logger.error("Failed to to do Mutated Page Bookmarks migration: \(error)")
+        }
+    }
+
+    public init(directory: URL) {
+        let fileURL = directory.appendingPathComponent("local_pagebookmarks_mutations.db", isDirectory: false)
+        self.init(db: DatabaseConnection(url: fileURL, readonly: false))
+    }
+
+    // MARK: Public
+
+    public func bookmarksPublisher() throws -> AnyPublisher<[MutatedPageBookmarkModel], Never> {
+        try db.readPublisher { db in
+            try GRDBMutatedPageBookmark.fetchAll(db)
+                .map { $0.toMutatedBookmarkModel() }
+        }
+        .catch { error in
+            logger.error("Error in page bookmarks publisher: \(error)")
+            return Empty<[MutatedPageBookmarkModel], Never>()
+        }
+        .eraseToAnyPublisher()
+    }
+
+    public func bookmarkMutations(page: Int) async throws -> [MutatedPageBookmarkModel] {
+        try await db.read { db in
+            try GRDBMutatedPageBookmark.fetchAll(
+                db.makeStatement(sql: "SELECT * FROM \(GRDBMutatedPageBookmark.databaseTableName) WHERE page = ?"),
+                arguments: [page]
+            )
+            .map { $0.toMutatedBookmarkModel() }
+        }
+    }
+
+    public func bookmarks() async throws -> [MutatedPageBookmarkModel] {
+        try await db.read { db in
+            try GRDBMutatedPageBookmark.fetchAll(db)
+                .map { $0.toMutatedBookmarkModel() }
+        }
+    }
+
+    public func createBookmark(page: Int) async throws {
+        let persisted = try await fetchCreatedBookmark(forPage: page)
+        if persisted?.deleted == false {
+            logger.error("[PageBookamrksMutatiosn] Adding a duplicate page bookmark.")
+            throw MutatedPageBookmarkPersistenceError.bookmarkAlreadyExists(page: page)
+        }
+
+        // If `persisted` is still not nil, then it's been deleted, and it was a synced one.
+        // In this case, it's safe to create a new unsynced bookmark, as a way to update
+        // the bookmark's modification date.
+        // The other case for this code branch is that `persisted` is nil.
+        try await db.write { db in
+            var instance = GRDBMutatedPageBookmark(page: page)
+            try instance.insert(db)
+        }
+    }
+
+    public func removeBookmark(page: Int, remoteID: String?) async throws {
+        let hasCreatedRecord = try await fetchCreatedBookmark(forPage: page) != nil
+
+        if hasCreatedRecord && remoteID != nil {
+            logger.error("[PageBookamrksMutatiosn] Illegal state: Deleting a bookmark on page, while there's an unsynced bookmark on the same page.")
+            let reason = "Deleting a synced bookmark on a page, after creating an unsynced one."
+            throw MutatedPageBookmarkPersistenceError.illegalState(reason: reason, page: page)
+        } else if hasCreatedRecord && remoteID == nil {
+            logger.trace("[PageBookamrksMutatiosn] Removing records for a page bookmark, after deleting an unsynced bookmark.")
+            try await deleteAll(forPage: page)
+        } else if remoteID != nil {
+            logger.trace("[PageBookamrksMutatiosn] Adding a delete record for a synced page bookmark.")
+            try await createBookamrkMarkedForDelete(for: page, remoteID: remoteID!)
+        } else {
+            logger.error("[PageBookamrksMutatiosn] Illegal state: Deleting an unsynced page bookmark, while there's no record for it.")
+            let reason = "Deleting an unsynced bookmark on a page with no record of being created."
+            throw MutatedPageBookmarkPersistenceError.illegalState(reason: reason, page: page)
+        }
+    }
+
+    public func clear() async throws {
+        try await db.write { db in
+            let cnt = try GRDBMutatedPageBookmark.deleteAll(db)
+            logger.info("[PageBookmarkMutationsPersistence] Cleared \(cnt) bookmark records.")
+        }
+    }
+
+    // MARK: Private
+
+    private let db: DatabaseConnection
+
+    private var migrator: DatabaseMigrator {
+        var migrator = DatabaseMigrator()
+        migrator.registerMigration("createPageBookmarks") { db in
+            try db.create(table: GRDBMutatedPageBookmark.databaseTableName, options: .ifNotExists) { table in
+                table.column("page", .integer).notNull()
+                table.column("remote_id", .text)
+                table.column("deleted", .boolean).notNull().defaults(to: false)
+                table.column("modification_date", .datetime).notNull()
+                // See the documentation on GRDBMutatedPageBookmark.
+                table.column("id", .integer).primaryKey(autoincrement: true)
+            }
+        }
+        return migrator
+    }
+
+    /// Fetches a bookmark for the given page that isn't marked for deletion.
+    private func fetchCreatedBookmark(forPage page: Int) async throws -> GRDBMutatedPageBookmark? {
+        try await db.read { db in
+            try GRDBMutatedPageBookmark.fetchOne(db.makeStatement(sql: "SELECT * from \(GRDBMutatedPageBookmark.databaseTableName) WHERE page=? AND deleted=false"), arguments: ["\(page)"])
+        }
+    }
+
+    private func createBookamrkMarkedForDelete(for page: Int, remoteID: String) async throws {
+        try await db.write { db in
+            var instance = GRDBMutatedPageBookmark(
+                remoteID: remoteID,
+                page: page,
+                modificationDate: Date(),
+                deleted: true
+            )
+            try instance.insert(db)
+        }
+    }
+
+    private func deleteAll(forPage page: Int) async throws {
+        try await db.write { db in
+            try db.execute(sql: "DELETE FROM \(GRDBMutatedPageBookmark.databaseTableName) WHERE page = ?", arguments: [page])
+        }
+    }
+}
+
+/// Imperatives:
+/// - If remote ID is not nil, then `deleted` must be true.
+/// - If remote ID is nil, then `deleted` can't be true
+/// - If there are two records with the same `page`, then the first must be a deletion for a synced bookmark, so the remote
+///   ID must be nil, and the second must be a new unsynced one.
+/// - Otherwise, there can't be two records for the same `page`.
+private struct GRDBMutatedPageBookmark: Identifiable, Codable, FetchableRecord, MutablePersistableRecord {
+    enum CodingKeys: String, CodingKey {
+        case id
+        case remoteID = "remote_id"
+        case page
+        case modificationDate = "modification_date"
+        case deleted
+    }
+
+    static var databaseTableName: String { "mutated_page_bookmarks" }
+
+    var id: Int64?
+    var remoteID: String?
+    var page: Int
+    var modificationDate: Date
+    var deleted: Bool
+}
+
+private extension GRDBMutatedPageBookmark {
+    init(page: Int) {
+        self.init(page: page, modificationDate: Date(), deleted: false)
+    }
+
+    func toMutatedBookmarkModel() -> MutatedPageBookmarkModel {
+        .init(
+            remoteID: remoteID,
+            page: page,
+            modificationDate: modificationDate,
+            mutation: remoteID == nil ? .created : .deleted
+        )
+    }
+}
+
+private extension MutatedPageBookmarkModel {
+    var isSynced: Bool { remoteID != nil }
+}

Data/MutatedPageBookmarkPersistence/Sources/MutatedPageBookmarkModel.swift

@@ -0,0 +1,36 @@
+//
+//  MutatedPageBookmarkModel.swift
+//  QuranEngine
+//
+//  Created by Mohannad Hassan on 10/02/2025.
+//
+
+import Foundation
+
+/// Represents a page bookmark with mutation information.
+///
+/// This model is used to represent a bookmark that has been created or mutated locally. The model
+/// may reference a remote bookmark that has been synced with the upstream server, in which case,
+/// `remoteID` will be the ID of that bookmark. This means that the bookmark has been deleted
+/// locally, but the deletion hasn't been marked as synced yet.
+///
+/// See `MutatedPageBookmarkPersistence` for more information regarding
+/// the relationship between the local mutated bookmarks and the upstream-synced bookmarks.
+public struct MutatedPageBookmarkModel {
+    public enum Mutation {
+        case created
+        case deleted
+    }
+
+    /// If `nil`, then this is a local bookmark that hasn't been synced upstream. Otherwise, this
+    /// is the remote ID of the upstream bookmark.
+    public let remoteID: String?
+    public let page: Int
+    public let modificationDate: Date
+
+    /// Represents the kind of mutation that casued this bookmark's current state.
+    ///
+    /// If `remoteID` is `nil`, then this will be `.created`. For remote bookmarks, this will be
+    /// `.deleted`.
+    public let mutation: Mutation
+}

Data/MutatedPageBookmarkPersistence/Sources/MutatedPageBookmarkPersistence.swift

@@ -0,0 +1,53 @@
+//
+//  MutatedPageBookmarkPersistence.swift
+//  QuranEngine
+//
+//  Created by Mohannad Hassan on 10/02/2025.
+//
+
+import Combine
+import Foundation
+
+public enum MutatedPageBookmarkPersistenceError: Error {
+    case bookmarkAlreadyExists(page: Int)
+    case illegalState(reason: String, page: Int)
+}
+
+/// Provides access for a mutable page bookmark persistence.
+///
+/// This persistence layer is aware of the difference between downstream and upstream-synced bookmarks. It can mark
+/// a mutation record for an upstream-synced bookmark, while providing access to create and remove local-unsynced
+/// bookmarks. If used in an unconnected state, this persistence can be can be seen as an local bookmarks persistence,
+/// without reference to upstream resources.
+///
+/// The repository guarantees that it can only hold a single *created* bookmark for a page. It may hold a record of a
+/// deleted upstream bookmark for a page holding a record for a created local unsynced bookmark. It's the responsibility
+/// of the client of this persistence to guarantee any further data requirements with the upstream resources.
+///
+/// See `MutatedPageBookmarkModel` for more information on the state of the returend objects.
+public protocol MutatedPageBookmarkPersistence {
+    func bookmarksPublisher() throws -> AnyPublisher<[MutatedPageBookmarkModel], Never>
+
+    func bookmarks() async throws -> [MutatedPageBookmarkModel]
+
+    func bookmarkMutations(page: Int) async throws -> [MutatedPageBookmarkModel]
+
+    /// Creates a new local bookmark for the given page.
+    ///
+    /// - throws `MutatedPageBookmarkPersistenceError.bookmarkAlreadyExists`
+    func createBookmark(page: Int) async throws
+
+    /// Signals the removal of the bookmark for the given page.
+    ///
+    /// If `remoteID` is given, this marks the record for deletion on the associated upstream resource.
+    /// If `remoteID` is `nil`, this will remove the records of the bookmark of the given page.
+    ///
+    /// - throws `MutatedPageBookmarkPersistenceError.illegalState` if
+    /// `remoteID` is nil, and there's no local  bookmark for that page.
+    func removeBookmark(page: Int, remoteID: String?) async throws
+
+    /// Clears all records.
+    ///
+    /// Should only be called after a sync operation with the upstream source is done.
+    func clear() async throws
+}