Add firstValue(where:)

Sources/Error.swift

@@ -2,7 +2,7 @@ import Foundation
 
 public enum PMKError: Error {
     /**
-     The completionHandler with form (T?, ErrorType?) was called with (nil, nil)
+     The completionHandler with form `(T?, Error?)` was called with `(nil, nil)`.
      This is invalid as per Cocoa/Apple calling conventions.
      */
     case invalidCallingConvention
@@ -26,7 +26,11 @@ public enum PMKError: Error {
     /// `nil` was returned from `compactMap`
     case compactMap(Any, Any.Type)
 
-    /// the lastValue or firstValue of a sequence was requested but the sequence was empty
+    /**
+     The lastValue or firstValue of a sequence was requested but the sequence was empty.
+
+     Also used if all values of this collection failed the test passed to `firstValue(where:)`.
+     */
     case emptySequence
 }
 

Sources/Thenable.swift

@@ -372,6 +372,15 @@ public extension Thenable where T: Collection {
         }
     }
 
+    func firstValue(on: DispatchQueue? = conf.Q.map, flags: DispatchWorkItemFlags? = nil, where test: @escaping (T.Iterator.Element) -> Bool) -> Promise<T.Iterator.Element> {
+        return map(on: on, flags: flags) {
+            for x in $0 where test(x) {
+                return x
+            }
+            throw PMKError.emptySequence
+        }
+    }
+
     /// - Returns: a promise fulfilled with the last value of this `Collection` or, if empty, a promise rejected with PMKError.emptySequence.
     var lastValue: Promise<T.Iterator.Element> {
         return map(on: nil) { aa in