Run downloadImage completion closure with .placeholder error if thumbnail preview

README.md

@@ -184,13 +184,24 @@ Images are stored in the disk cache the same way as data. The image-specific fun
 
 #### Thumbnail preview
 
-If there are already cached thumbnails for the image you are trying to fetch, you can use the `preview` parameter to specify that you would like to get that thumbnail first while the full-size image is downloading.
+If there are already cached thumbnails for the image you are trying to fetch, you can use the `preview` parameter to specify that you would like to get that thumbnail first while the full-size image is downloading. When you do this, the completion closure will run with a `.placeholder` error on the call with the thumbnail.
 
 ```swift
 webDAV.downloadImage(path: imagePath, account: account, password: password, preview: .memoryOnly) { image, error in
-    // Display the image.
-    // This will run once on the largest cached thumbnail (if there are any)
-    // and again with the full-size image.
+    switch error {
+    case .none, .placeholder:
+        // .none is the full-size image.
+        // .placeholder is the thumbnail.
+        // The completion closure will not be run with the thumbnail after
+        // it is run with the full-size image, so assuming you don't have
+        // a use for the thumbnail after the full-size image loads, you
+        // shouldn't need to check which it is before displaying.
+        break
+    case .some(let unexpectedError):
+        // Log the error
+    }
+    
+    // Display the image
 }
 ```
 

Sources/WebDAV/WebDAV+Images.swift

@@ -89,8 +89,9 @@ public extension WebDAV {
     ///   Note that `.diskAllowed` will load all thumbnails for the given image which can be an expensive process.
     ///   `.memoryOnly` and `.specific()` are recommended unless you do not know what thumbnails exist.
     ///   - completion: If account properties are invalid, this will run immediately on the same thread with an error.
-    ///   Otherwise, it will run on a utility thread with a preview (if available and a `preview` mode is provided),
-    ///   then runs on a background thread when the network call finishes.
+    ///   Otherwise, it will run on a utility thread with a preview (if available and a `preview` mode is provided) with a `.placeholder` error,
+    ///   then run on a background thread when the network call finishes.
+    ///   This will not be called with the thumbnail after being called with the full-size image.
     ///   - image: The image downloaded, if successful.
     ///   The cached image if it has already been downloaded.
     ///   - cachedImageURL: The URL of the cached image.

Sources/WebDAV/WebDAV.swift

@@ -418,7 +418,7 @@ extension WebDAV {
         
         let placeholderTask = DispatchWorkItem {
             if let placeholderValue = placeholder?() {
-                completion(placeholderValue, nil)
+                completion(placeholderValue, .placeholder)
             }
         }
         DispatchQueue.global(qos: .utility).async(execute: placeholderTask)

Sources/WebDAV/WebDAVError.swift

@@ -19,6 +19,8 @@ public enum WebDAVError: Error {
     case unsupported
     /// Another unspecified Error occurred.
     case nsError(Error)
+    /// The returned value is simply a placeholder.
+    case placeholder
     
     static func getError(statusCode: Int?, error: Error?) -> WebDAVError? {
         if let statusCode = statusCode {

Tests/WebDAVTests/WebDAVTests.swift

@@ -634,22 +634,26 @@ final class WebDAVTests: XCTestCase {
             return XCTFail("You need to set the image_path in the environment.")
         }
         
-        let expectation = XCTestExpectation(description: "Fetch image")
-        // Check that the completion closure is run first
-        // on the preview then again for the image itself.
-        expectation.expectedFulfillmentCount = 2
+        let thumbnailExpectation = XCTestExpectation(description: "Get the cached thumbnail")
+        let imageExpectation = XCTestExpectation(description: "Fetch image")
         
         downloadThumbnail(imagePath: imagePath, account: account, password: password)
         
         try? webDAV.deleteCachedData(forItemAtPath: imagePath, account: account)
         webDAV.downloadImage(path: imagePath, account: account, password: password, preview: .memoryOnly) { image, error in
-            XCTAssertNil(error)
+            switch error {
+            case .placeholder:
+                thumbnailExpectation.fulfill()
+            case .none:
+                imageExpectation.fulfill()
+            case .some(let unexpectedError):
+                XCTFail("\(unexpectedError)")
+            }
             XCTAssertNotNil(image)
-            expectation.fulfill()
         }
         try? webDAV.deleteCachedData(forItemAtPath: imagePath, account: account)
         
-        wait(for: [expectation], timeout: 10.0)
+        wait(for: [thumbnailExpectation, imageExpectation], timeout: 10.0)
     }
     
     //MARK: OCS