Expose clearAmbientCache method (#2367)

Author: OdNairy

CHANGELOG.md

@@ -16,6 +16,7 @@ In order to continue use them use the following import `@_spi(Experimental) impo
 * Fix a crash on calling `LocationIndicatorLayer/location(coordinate:) function` due to missing 0 altitude value.
 * Add a new Expression initializer `init(_ operator: Operator, _ arguments: ExpressionArgumentConvertible...)` to simplify the creation of expressions with multiple arguments.
 That initializer doesn't require to wrap arguments in `Argument` cases. For example, `Exp(.eq, Exp(.get, "extrude"), "true")`.
+* Expose a `TileStore/clearAmbientCache()` method to clear ambient cache.
 * Add new experimental `radius` parameter to `TapInteraction`, `LongPressInteraction` and interaction managers to control the radius of a tappable area.
 
 ## 11.8.0 - 11 November, 2024

Sources/MapboxMaps/Documentation.docc/API Catalogs/TileStore APIs.md

@@ -35,6 +35,7 @@
 - ``MapboxCommon/TileRegionEstimateProgressCallback``
 - ``MapboxCommon/CacheClearingError``
 - ``MapboxCommon/CacheClearingErrorType``
+- ``ClearCacheError``
 
 ### Style pack
 

Sources/MapboxMaps/Offline/ClearCacheError.swift

@@ -0,0 +1,17 @@
+/// Describes the reason for a cache clearing failure.
+public enum ClearCacheError: Error, Equatable, Sendable, CoreErrorRepresentable {
+
+    /// There was an issue accessing the database
+    case database(String)
+
+    /// There was an uncategorised error, check the associated message
+    case other(String)
+
+    init(coreError: MapboxCommon.CacheClearingError) {
+        switch coreError.type {
+        case .databaseError: self = .database(coreError.message)
+        case .otherError: fallthrough
+        @unknown default: self = .other(coreError.message)
+        }
+    }
+}

Sources/MapboxMaps/Offline/TileStore+MapboxMaps.swift

@@ -241,6 +241,32 @@ extension TileStore: TileStoreProtocol {
     public func removeRegion(forId id: String, completion: @escaping (Result<TileRegion, Error>) -> Void) {
         __removeTileRegion(forId: id, callback: tileStoreClosureAdapter(for: completion, type: TileRegion.self))
     }
+
+    /// Clears the ambient cache data.
+    ///
+    /// Ambient cache data is anything not associated with an offline region or a stylepack,
+    /// including predictively cached data. Use to quickly clear data e.g. for a system update.
+    ///
+    /// Note: Do not use this method to clear cache data unless strictly
+    /// necessary as previously cached data will need to be re-downloaded,
+    /// leading to increased network usage.
+    /// If you want general control of the size of the Tile Store.
+    ///
+    /// - Note: This function is blocking the Tile Store until completed.
+    /// - Parameter completion: The `UInt32` value represents how many bytes were cleared from the cache.
+    public func clearAmbientCache(
+        completion: @escaping (Result<UInt32, any Error>) -> Void
+    ) {
+        clearAmbientCache(
+            forCallback: coreAPIClosureAdapter(
+                for: completion,
+                type: NSNumber.self,
+                concreteErrorType: ClearCacheError.self,
+                converter: { $0.uint32Value }
+            )
+        )
+    }
+
 }
 
 private func tileStoreClosureAdapter<T, ObjCType>(