PromiseKit README

The project's README from github.com/mxcl/PromiseKit. As one markdown file: README.md.

PromiseKit

badge-pod badge-languages badge-pms badge-platforms codecov

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.

codecov

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

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.

Security & Vulnerability Reporting or Disclosure

https://tidelift.com/security

PromiseKit (mxcl/PromiseKit)

swift-package-manager
Searching Database…

14.2K ·GitHub
PromiseKit
What is this?PromiseKit is a complete promises implementation for Swift and Objective-C that simplifies asynchronous programming, so your async code ends up clearer, more readable and easier to master.
Is this a library I add to my app, or a separate tool I run?It is a library: you add it to your Swift or Objective-C project through a package manager and it runs inside your app. It works on any platform that has a Swift compiler.
How do I add it to my project?Add it to your Podfile with CocoaPods, or install via Carthage, SwiftPM or Accio — the README recommends Carthage or Accio. PromiseKit 8 needs Xcode 13 or newer.
Will it work with my version of Xcode and Swift?PromiseKit 8 supports recent Xcodes (13+), and some podspecs were dropped for that. Older lines 6, 5 and 4 cover Xcode 8.3-10.0 and Swift 3.1 through 5.0.
Swift has async/await built in now — is PromiseKit still worth adding?The README itself points to Async+, a port of PromiseKit's most useful patterns to the new async/await paradigm, as the modern counterpart for Swift 5.5+ code.
Does it work outside Apple platforms, or is it iOS-only?It has delightful specializations for iOS, macOS, tvOS and watchOS, but any platform with a swiftc works, including Linux — older versions 4-6 even listed Android.
What do the extensions add?PromiseKit has converted almost all of Apple's APIs to return promises. The default CocoaPod ships extensions for Foundation and UIKit; other extensions are separate subspecs (including URLSession for networking), and Carthage installs come with none by default.
Is PromiseKit used in real production apps?Yes — it is a top-100 CocoaPod used in many of the most popular apps in the world.
Can I use it from Objective-C?Yes — PromiseKit has excellent Objective-C bridging, and the documentation includes a dedicated Objective-C guide.
Is professional support available for teams?Yes — PromiseKit is offered through TideLift, which gives development teams professional-grade assurances and maintenance from the experts who know it best.
What are similar projects?AFNetworking, CocoaLumberjack, Alamofire, SDWebImage, Mantle, firebase-ios-sdk, SwifterSwift, swift-composable-architecture
Which topics is it in?swift-package-manager, watchos, tvos, objective-c, concurrency, async, apple, swift, ios, android, library, cross-platform
Creator
mxcl
Size
10.4 MB
Stars
14.2K
Updated
CommitJun 03Release8.2.0Jan 16
Age
12y
Commits · 90 Days