What's a Promise?

Updating to >=0.9.7

Since 0.9.7 Hydra implements Cancellable Promises. In order to support this new feature we have slightly modified the Body signature of the Promise; in order to make your source code compatible you just need to add the third parameter along with resolve,reject: operation. operation encapsulate the logic to support Invalidation Token. It's just and object of type PromiseStatus you can query to see if a Promise is marked to be cancelled from the outside. If you are not interested in using it in your Promise declaration just mark it as _.

To sum up your code:

return Promise<Int>(in: .main, token: token, { resolve, reject in ...

needs to be:

return Promise<Int>(in: .main, token: token, { resolve, reject, operation in // or resolve, reject, _

Create a Promise

Creating a Promise is trivial; you need to specify the context (a GCD Queue) in which your async operations will be executed in and add your own async code as body of the Promise.

This is a simple async image downloader:

func getImage(url: String) -> Promise<UIImage> {
    return Promise<UIImage>(in: .background, { resolve, reject, _ in
        self.dataTask(with: request, completionHandler: { data, response, error in
            if let error = error {
                reject(error)
            } else if let data = data, let response = response as? HTTPURLResponse {
                resolve((data, response))
            } else {
                reject("Image cannot be decoded")
            }
        }).resume()
    })
}

You need to remember only few things:

How to use a Promise

Using a Promise is even easier.
You can get the result of a promise by using then function; it will be called automatically when your Promise fullfill with expected value. So:

getImage(url).then(.main, { image in
    myImageView.image = image
})

As you can see even then may specify a context (by default - if not specified - is the main thread): this represent the GCD queue in which the code of the then's block will be executed (in our case we want to update an UI control so we will need to execute it in .main thread).

But what happened if your Promise fail due to a network error or if the image is not decodable? catch func allows you to handle Promise's errors (with multiple promises you may also have a single errors entry point and reduce the complexity).

getImage(url).then(.main, { image in
    myImageView.image = image
}).catch(.main, { error in
    print("Something bad occurred: \(error)")
})

Chaining Multiple Promises

Chaining Promises is the next step thought mastering Hydra. Suppose you have defined some Promises:

func loginUser(_ name:String, _ pwd: String)->Promise<User>
func getFollowers(user: User)->Promise<[Follower]>
func unfollow(followers: [Follower])->Promise<Int>

Each promise need to use the fulfilled value of the previous; plus an error in one of these should interrupt the entire chain.
Doing it with Hydra is pretty straightforward:

loginUser(username,pass).then(getFollowers).then(unfollow).then { count in
    print("Unfollowed \(count) users")
}.catch { err in
    // Something bad occurred during these calls
}

Easy uh? (Please note: in this example context is not specified so the default .main is used instead).

Cancellable Promises

Cancellable Promises are a very sensitive task; by default Promises are not cancellable. Hydra allows you to cancel a promise from the outside by implementing the InvalidationToken. InvalidationToken is a concrete open class which is conform to the InvalidatableProtocol protocol. It must implement at least one Bool property called isCancelled.

When isCancelled is set to true it means someone outside the promise want to cancel the task.

It's your responsibility to check from inside the Promise's body the status of this variable by asking to operation.isCancelled. If true you can do all your best to cancel the operation; at the end of your operations just call cancel() and stop the workflow.

Your promise must be also initialized using this token instance.

This is a concrete example with UITableViewCell: working with table cells, often the result of a promise needs to be ignored. To do this, each cell can hold on to an InvalidationToken. An InvalidationToken is an execution context that can be invalidated. If the context is invalidated, then the block that is passed to it will be discarded and not executed.

To use this with table cells, the queue should be invalidated and reset on prepareForReuse().

class SomeTableViewCell: UITableViewCell {
    var token = InvalidationToken()

    func setImage(atURL url: URL) {
        downloadImage(url).then(in: .main, { image in
            self.imageView.image = image
        })
    }

    override func prepareForReuse() {
        super.prepareForReuse()
        token.invalidate() // stop current task and ignore result
        token = InvalidationToken() // new token
    }

    func downloadImage(url: URL) -> Promise<UIImage> {
        return Promise<Something>(in: .background, token: token, { (resolve, reject, operation) in
        // ... your async operation

        // somewhere in your Promise's body, for example in download progression
        // you should check for the status of the operation.
        if operation.isCancelled {
            // operation should be cancelled
            // do your best to cancel the promise's task
            operation.cancel() // request to mark the Promise as cancelled
            return // stop the workflow! it's important
        }
        // ... your async operation
        })
    }
}

Await & Async: async code in sync manner

Await an zip operator to resolve all promises

Await can be also used in conjuction with zip to resolve all promises from a list:

let (resultA,resultB) = Hydra.await(zip(promiseA,promiseB))
print(resultA)
print(resultB)

All Features

Because promises formalize how success and failure blocks look, it's possible to build behaviors on top of them. Hydra supports:

• always: allows you to specify a block which will be always executed both for fulfill and reject of the Promise
• validate: allows you to specify a predica block; if predicate return false the Promise fails.
• timeout: add a timeout timer to the Promise; if it does not fulfill or reject after given interval it will be marked as rejected.
• all: create a Promise that resolved when the list of passed Promises resolves (promises are resolved in parallel). Promise also reject as soon as a promise reject for any reason.
• any: create a Promise that resolves as soon as one passed from list resolves. It also reject as soon as a promise reject for any reason.
• pass: Perform an operation in the middle of a chain that does not affect the resolved value but may reject the chain.
• recover: Allows recovery of a Promise by returning another Promise if it fails.
• map: Transform items to Promises and resolve them (in paralle or in series)
• zip: Create a Promise tuple of a two promises
• defer: defer the execution of a Promise by a given time interval.
• cancel: cancel is called when a promise is marked as cancelled using operation.cancel()

always

always func is very useful if you want to execute code when the promise fulfills — regardless of whether it succeeds or fails.

showLoadingHUD("Logging in...")
loginUser(username,pass).then { user in
    print("Welcome \(user.username)")
}.catch { err in
    print("Cannot login \(err)")
}.always {
    hideLoadingHUD()
}

validate

validate is a func that takes a predicate, and rejects the promise chain if that predicate fails.

getAllUsersResponse().validate { httpResponse in
    guard let httpResponse.statusCode == 200 else {
        return false
    }
    return true
}.then { usersList in
    // do something
}.catch { error in
    // request failed, or the status code was != 200
}

timeout

timeout allows you to attach a timeout timer to a Promise; if it does not resolve before elapsed interval it will be rejected with .timeoutError.

loginUser(username,pass).timeout(.main, 10, .MyCustomTimeoutError).then { user in
    // logged in
}.catch { err in
    // an error has occurred, may be `MyCustomTimeoutError
}

all

all is a static method that waits for all the promises you give it to fulfill, and once they have, it fulfills itself with the array of all fulfilled values (in order).

If one Promise fail the chain fail with the same error.

Execution of all promises is done in parallel.

let promises = usernameList.map { return getAvatar(username: $0) }
all(promises).then { usersAvatars in
    // you will get an array of UIImage with the avatars of input
    // usernames, all in the same order of the input.
    // Download of the avatar is done in parallel in background!
}.catch { err in
    // something bad has occurred
}

If you add promise execution concurrency restriction to all operator to avoid many usage of resource, concurrency option is it.

let promises = usernameList.map { return getAvatar(username: $0) }
all(promises, concurrency: 4).then { usersAvatars in
    // results of usersAvatars is same as `all` without concurrency.
}.catch { err in
    // something bad has occurred
}

any

any easily handle race conditions: as soon as one Promise of the input list resolves the handler is called and will never be called again.

let mirror_1 = "https://mirror1.mycompany.com/file"
let mirror_2 = "https://mirror2.mycompany.com/file"

any(getFile(mirror_1), getFile(mirror_2)).then { data in
    // the first fulfilled promise also resolve the any Promise
    // handler is called exactly one time!
}

pass

pass is useful for performing an operation in the middle of a promise chain without changing the type of the Promise. You may also reject the entire chain. You can also return a Promise from the tap handler and the chain will wait for that promise to resolve (see the second then in the example below).

loginUser(user,pass).pass { userObj in 
    print("Fullname is \(user.fullname)")
}.then { userObj in
    updateLastActivity(userObj)
}.then { userObj in
    print("Login succeded!")
}

recover

recover allows you to recover a failed Promise by returning another.

let promise = Promise<Int>(in: .background, { fulfill, reject in
    reject(AnError)
}).recover({ error in
    return Promise(in: .background, { (fulfill, reject) in
        fulfill(value)
    })
})

map

Map is used to transform a list of items into promises and resolve them in parallel or serially.

[urlString1,urlString2,urlString3].map {
    return self.asyncFunc2(value: $0)
}.then(.main, { dataArray in
    // get the list of all downloaded data from urls
}).catch({
    // something bad has occurred
})

zip

zip allows you to join different promises (2,3 or 4) and return a tuple with the result of them. Promises are resolved in parallel.

zip(a: getUserProfile(user), b: getUserAvatar(user), c: getUserFriends(user))
  .then { profile, avatar, friends in
    // ... let's do something
}.catch {
    // something bad as occurred. at least one of given promises failed
}

defer

As name said, defer delays the execution of a Promise chain by some number of seconds from current time.

asyncFunc1().defer(.main, 5).then...

retry

retry operator allows you to execute source chained promise if it ends with a rejection. If reached the attempts the promise still rejected chained promise is also rejected along with the same source error.
Retry also support delay parameter which specify the number of seconds to wait before a new attempt (2.0.4+).

// try to execute myAsyncFunc(); if it fails the operator try two other times
// If there is not luck for you the promise itself fails with the last catched error.
myAsyncFunc(param).retry(3).then { value in
    print("Value \(value) got at attempt #\(currentAttempt)")
}.catch { err in
    print("Failed to get a value after \(currentAttempt) attempts with error: \(err)")
}

Conditional retry allows you to control retryable if it ends with a rejection.

// If myAsyncFunc() fails the operator execute the condition block to check retryable.
// If return false in condition block, promise state rejected with last catched error.
myAsyncFunc(param).retry(3) { (remainAttempts, error) -> Bool in
  return error.isRetryable
}.then { value in
    print("Value \(value) got at attempt #\(currentAttempt)")
}.catch { err in
    print("Failed to get a value after \(currentAttempt) attempts with error: \(err)")
}

cancel

Chaining Promises with different Value types

Sometimes you may need to chain (using one of the available operators, like all or any) promises which returns different kind of values. Due to the nature of Promise you are not able to create an array of promises with different result types. However thanks to void property you are able to transform promise instances to generic void result type. So, for example, you can execute the following Promises and return final values directly from the Promise's result property.

let op_1: Promise<User> = asyncGetCurrentUserProfile()
let op_2: Promise<UIImage> = asyncGetCurrentUserAvatar()
let op_3: Promise<[User]> = asyncGetCUrrentUserFriends()

all(op_1.void,op_2.void,op_3.void).then { _ in
    let userProfile = op_1.result
    let avatar = op_2.result
    let friends = op_3.result
}.catch { err in
    // do something
}

Installation

You can install Hydra using CocoaPods, Carthage and Swift package manager

• Swift 3.x: Latest compatible is 1.0.2 pod 'HydraAsync', ~> '1.0.2'
• Swift 4.x: 1.2.1 or later pod 'HydraAsync'

CocoaPods

use_frameworks!
pod 'HydraAsync'

Carthage

github 'malcommac/Hydra'

Swift Package Manager

Add Hydra as dependency in your Package.swift

  import PackageDescription

  let package = Package(name: "YourPackage",
    dependencies: [
      .Package(url: "https://github.com/malcommac/Hydra.git", majorVersion: 0),
    ]
  )

Requirements

Current version is compatible with:

• Swift 5.x
• iOS 9.0 or later
• tvOS 9.0 or later
• macOS 10.10 or later
• watchOS 2.0 or later
• Linux compatible environments

Contributing

• If you need help or you'd like to ask a general question, open an issue.
• If you found a bug, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, submit a pull request.

Copyright & Acknowledgements