[tile_store] Export TileStore.estimateTileRegion API (#2079)

CHANGELOG.md

@@ -4,6 +4,8 @@ Mapbox welcomes participation and contributions from everyone.
 
 ## main
 
+[tile store] Expose API for estimating Tile Region downloads and storage size.
+
 # 11.3.0-beta.1 - 14 March, 2024
 
 * Update the minimum Xcode version to 15.2 (Swift 5.9).

Sources/MapboxMaps/Offline/TileStore+MapboxMaps.swift

@@ -94,6 +94,49 @@ extension TileStore: TileStoreProtocol {
         }
     }
 
+    /// Estimates the storage and transfer size of a tile region.
+    ///
+    /// - Parameters:
+    ///  - id The tile region identifier.
+    ///  - loadOptions The tile region load options.
+    ///  - estimateOptions The options for the estimate operation. Optional, default values will be aplied if nil.
+    ///  - onProgress Invoked multiple times to report progess of the estimate operation.
+    ///  - onFinished Invoked only once upon success, failure, or cancelation of the estimate operation.
+    /// - Returns: a `Cancelable` object to cancel the estimate request
+    ///
+    /// This can be used for estimating existing or new tile regions. For new tile
+    /// regions, both geometry and tileset descriptors need to be provided to the
+    /// given load options.  If a tile region with the given id already exists, its
+    /// geometry and tileset descriptors are reused unless a different value is
+    /// provided in the region load options.
+    ///
+    /// Estimating a tile region does not mutate exising tile regions on the tile store.
+    ///
+    /// - Note:
+    ///     The user-provided callbacks will be executed on a TileStore-controlled worker thread;
+    ///     it is the responsibility of the user to dispatch to a user-controlled thread.
+    @discardableResult
+    public func estimateTileRegion(forId id: String,
+                                   loadOptions: TileRegionLoadOptions,
+                                   estimateOptions: TileRegionEstimateOptions? = nil,
+                                   progress: @escaping TileRegionEstimateProgressCallback,
+                                   completion: @escaping (Result<TileRegionEstimateResult, Error>) -> Void) -> Cancelable {
+        if let estimateOptions = estimateOptions {
+            return __estimateTileRegion(forId: id,
+                                        loadOptions: loadOptions,
+                                        estimateOptions: estimateOptions,
+                                        onProgress: progress,
+                                        onFinished: tileStoreClosureAdapter(for: completion, type: TileRegionEstimateResult.self))
+        }
+        // Use overloaded version
+        else {
+            return __estimateTileRegion(forId: id,
+                                        options: loadOptions,
+                                        onProgress: progress,
+                                        onFinished: tileStoreClosureAdapter(for: completion, type: TileRegionEstimateResult.self))
+        }
+    }
+
     /// Checks if a tile region with the given id contains all tilesets from all
     /// of the given tileset descriptors.
     ///

Tests/MapboxMapsTests/Offline/TileRegionEstimateOptions_MapboxMapTests.swift

@@ -0,0 +1,29 @@
+import XCTest
+@testable import MapboxMaps
+
+class TileRegionEstimateOptionsTests: XCTestCase {
+
+    func testInitilization() throws {
+        let extraOptions: [Int]? = .random(Array.random(withLength: 5, generator: { Int.random(in: 0...9) }))
+
+        let tileRegionEstimateOptions = try XCTUnwrap(TileRegionEstimateOptions(
+            errorMargin: 0.1,
+            preciseEstimationTimeout: 1000,
+            timeout: 10,
+            extraOptions: extraOptions))
+
+        XCTAssertEqual(tileRegionEstimateOptions.errorMargin, 0.1)
+        XCTAssertEqual(tileRegionEstimateOptions.preciseEstimationTimeout, 1000)
+        XCTAssertEqual(tileRegionEstimateOptions.timeout, 10)
+        XCTAssertEqual(tileRegionEstimateOptions.extraOptions as? [Int], extraOptions)
+    }
+
+    func testInitializationDefaultValues() throws {
+        let tileRegionEstimateOptions = try XCTUnwrap(TileRegionEstimateOptions(extraOptions: nil))
+
+        XCTAssertEqual(tileRegionEstimateOptions.errorMargin, 0.05)
+        XCTAssertEqual(tileRegionEstimateOptions.preciseEstimationTimeout, 5)
+        XCTAssertEqual(tileRegionEstimateOptions.timeout, 0)
+        XCTAssertNil(tileRegionEstimateOptions.extraOptions)
+    }
+}