Promises for Swift & ObjC.
Promises simplify asynchronous programming, freeing you up to focus on the more
important things. They are easy to learn, easy to master and result in clearer,
more readable code. Your co-workers will thank you.
UIApplication.shared.isNetworkActivityIndicatorVisible = true
let fetchImage = URLSession.shared.dataTask(.promise, with: url).compactMap{ UIImage(data: $0.data) }
let fetchLocation = CLLocationManager.requestLocation().lastValue
firstly {
when(fulfilled: fetchImage, fetchLocation)
}.done { image, location in
self.imageView.image = image
self.label.text = "\(location)"
}.ensure {
UIApplication.shared.isNetworkActivityIndicatorVisible = false
}.catch { error in
self.show(UIAlertController(for: error), sender: self)
}
PromiseKit is a thoughtful and complete implementation of promises for any
platform that has a swiftc. It has excellent Objective-C bridging and
delightful specializations for iOS, macOS, tvOS and watchOS. It is a top-100
pod used in many of the most popular apps in the world.
Quick Start
In your Podfile:
use_frameworks!
target "Change Me!" do
pod "PromiseKit", "~> 8"
end
PromiseKit 8 supports recent Xcodes (13+). Some Podspecs were
dropped as a result.
Pull requests are welcome.
PromiseKit 6, 5 and 4 support Xcode 8.3, 9.x and 10.0; Swift 3.1,
3.2, 3.3, 3.4, 4.0, 4.1, 4.2, 4.3 and 5.0 (development snapshots); iOS, macOS,
tvOS, watchOS, Linux and Android; CocoaPods, Carthage and SwiftPM;
(CI Matrix).
For Carthage, SwiftPM, Accio, etc., or for instructions when using older Swifts or Xcodes, see our Installation Guide. We recommend
Carthage or
Accio.
PromiseKit and Swift 5.5+ Async/Await
As of Swift 5.5, the Swift language now offers support for built-in concurrency with async / await. See Async+ for a port of PromiseKit’s most useful patterns to this new paradigm.
Professionally Supported PromiseKit is Now Available
TideLift gives software development teams a single source for purchasing
and maintaining their software, with professional grade assurances from
the experts who know it best, while seamlessly integrating with existing
tools.
Get Professional Support for PromiseKit with TideLift.
Documentation
- Handbook
- Manual
- Installation Guide
- Objective-C Guide
- Troubleshooting (e.g., solutions to common compile errors)
- Appendix
- API Reference
Extensions
Promises are only as useful as the asynchronous tasks they represent. Thus, we
have converted (almost) all of Apple’s APIs to promises. The default CocoaPod
provides Promises and the extensions for Foundation and UIKit. The other
extensions are available by specifying additional subspecs in your Podfile,
e.g.:
pod "PromiseKit/MapKit" # MKDirections().calculate().then { /*…*/ }
pod "PromiseKit/CoreLocation" # CLLocationManager.requestLocation().then { /*…*/ }
All our extensions are separate repositories at the PromiseKit organization.
I don’t want the extensions!
Then don’t have them:
pod "PromiseKit/CorePromise", "~> 8"
Note: Carthage installations come with no extensions by default.
Networking
Promise chains commonly start with a network operation. Thus, we offer
extensions for URLSession:
// pod 'PromiseKit/Foundation' # https://github.com/PromiseKit/Foundation
firstly {
URLSession.shared.dataTask(.promise, with: try makeUrlRequest()).validate()
// ^^ we provide `.validate()` so that eg. 404s get converted to errors
}.map {
try JSONDecoder().decode(Foo.self, with: $0.data)
}.done { foo in
//…
}.catch { error in
//…
}
func makeUrlRequest() throws -> URLRequest {
var rq = URLRequest(url: url)
rq.httpMethod = "POST"
rq.addValue("application/json", forHTTPHeaderField: "Content-Type")
rq.addValue("application/json", forHTTPHeaderField: "Accept")
rq.httpBody = try JSONEncoder().encode(obj)
return rq
}
Support for Alamofire is welcome, please submit a PR.
Support
Please check our Troubleshooting Guide, and
if after that you still have a question, ask at our Gitter chat channel or on our bug tracker.