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.

PromiseKit 6 has been released; read the release notes and migration guide.

In your Podfile:

use_frameworks!

target "Change Me!" do
  pod "PromiseKit", "~> 6.0"
end

PromiseKit 6, 5, and 4 support Xcode 8.3, 9.x, and 10.0; Swift 3.1, 3.2, 3.3, 4.0, 4.1, and 4.2 ; iOS, macOS, tvOS, watchOS, Linux, and Android; CocoaPods, Carthage, and SwiftPM; (CI Matrix).

For Carthage, SwiftPM, etc., or for instructions when using older Swifts or Xcodes, see our Installation Guide. We recommend Carthage.

• Handbook
  • Getting Started
  • Promises: Common Patterns
  • Frequently Asked Questions
• Manual
  • Installation Guide
  • Objective-C Guide
  • Troubleshooting (e.g., solutions to common compile errors)
  • Appendix
• API Reference

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.

Then don’t have them:

pod "PromiseKit/CorePromise", "~> 6.0"

Note: Carthage installations come with no extensions by default.

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())
}.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
}

Alamofire:

// pod 'PromiseKit/Alamofire'  # https://github.com/PromiseKit/Alamofire-

firstly {
    Alamofire
        .request("http://example.com", method: .post, parameters: params)
        .responseDecodable(Foo.self)
}.done { foo in
    //…
}.catch { error in
    //…
}

And OMGHTTPURLRQ:

// pod 'PromiseKit/OMGHTTPURLRQ'  # https://github.com/PromiseKit/OMGHTTPURLRQ

firstly {
    URLSession.shared.POST("http://example.com", JSON: params)
}.map {
    try JSONDecoder().decoder(Foo.self, with: $0.data)
}.done { foo in
    //…
}.catch { error in
    //…
}

Nowadays, considering that:

• We almost always POST JSON
• We now have JSONDecoder
• PromiseKit now has map and other functional primitives

We recommend vanilla URLSession. It uses fewer black boxes and sticks closer to the metal. Alamofire was essential until the three bulletpoints above became true, but nowadays it isn’t really necessary. OMGHTTPURLRQ was developed before JSON was the modern standard and thus REST requests were hard, but these days you rarely need to speak any format but JSON.

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.