Reason - Example - Documentation - Installation
fetchUserId().then { id in
print("UserID : \(id)")
}.onError { e in
print("An error occured : \(e)")
}.finally {
print("Everything is Done :)")
}
let userId = try! await(fetchUserId())
Because async code is hard to write, hard to read, hard to reason about. A pain to maintain
then is part of freshOS iOS toolset. Try it in an example App ! Download Starter Project
By using a then keyword that enables you to write aSync code that reads like an English sentence
Async code is now concise, flexible and maintainable β€οΈ
- Based on the popular
Promise
/Future
concept -
Async
/Await
-
progress
race
recover
validate
retry
bridgeError
chain
noMatterWhat
... - Strongly Typed
- Pure Swift & Lightweight
fetchUserId({ id in
fetchUserNameFromId(id, success: { name in
fetchUserFollowStatusFromName(name, success: { isFollowed in
// The three calls in a row succeeded YAY!
reloadList()
}, failure: { error in
// Fetching user ID failed
reloadList()
})
}, failure: { error in
// Fetching user name failed
reloadList()
})
}) { error in
// Fetching user follow status failed
reloadList()
}
πππ#callbackHell
fetchUserId()
.then(fetchUserNameFromId)
.then(fetchUserFollowStatusFromName)
.then(updateFollowStatus)
.onError(showErrorPopup)
.finally(reloadList)
fetchUserId().then { id in
print("UserID : \(id)")
}.onError { e in
print("An error occured : \(e)")
}.finally {
print("Everything is Done :)")
}
If we want this to be maintainable, it should read like an English sentence
We can do this by extracting our blocks into separate functions:
fetchUserId()
.then(printUserID)
.onError(showErrorPopup)
.finally(reloadList)
This is now concise, flexible, maintainable, and it reads like an English sentence <3
Mental sanity saved
// #goodbyeCallbackHell
- Writing your own Promise
- Progress
- Registering a block for later
- Returning a rejecting promise
- Common Helpers
- race
- recover
- validate
- retry
- bridgeError
- whenAll
- chain
- noMatterWhat
- unwrap
- AsyncTask
- Async/Await
Wondering what fetchUserId() is?
It is a simple function that returns a strongly typed promise :
func fetchUserId() -> Promise<Int> {
return Promise { resolve, reject in
print("fetching user Id ...")
wait { resolve(1234) }
}
}
Here you would typically replace the dummy wait function by your network request <3
As for then
and onError
, you can also call a progress
block for things like uploading an avatar for example.
uploadAvatar().progress { p in
// Here update progressView for example
}
.then(doSomething)
.onError(showErrorPopup)
.finally(doSomething)
Our implementation slightly differs from the original javascript Promises. Indeed, they do not start right away, on purpose. Calling then
, onError
, or finally
will start them automatically.
Calling then
starts a promise if it is not already started.
In some cases, we only want to register some code for later.
For instance, in the case of JSON to Swift model parsing, we often want to attach parsing blocks to JSON promises, but without starting them.
In order to do that we need to use registerThen
instead. It's the exact same thing as then
without starting the promise right away.
let fetchUsers:Promise<[User]> = fetchUsersJSON().registerThen(parseUsersJSON)
// Here promise is not launched yet \o/
// later...
fetchUsers.then { users in
// YAY
}
Note that onError
and finally
also have their non-starting counterparts : registerOnError
and registerFinally
.
Oftetimes we need to return a rejecting promise as such :
return Promise { _, reject in
reject(anError)
}
This can be written with the following shortcut :
return Promise.reject(error:anError)
With race
, you can send multiple tasks and get the result of the first one coming back :
race(task1, task2, task3).then { work in
// The first result !
}
With .recover
, you can provide a fallback value for a failed Promise.
You can :
- Recover with a value
- Recover with a value for a specific Error type
- Return a value from a block, enabling you to test the type of error and return distinct values.
- Recover with another Promise with the same Type
.recover(with: 12)
.recover(MyError.defaultError, with: 12)
.recover { e in
if e == x { return 32 }
if e == y { return 143 }
throw MyError.defaultError
}
.recover { e -> Promise<Int> in
// Deal with the error then
return Promise<Int>.resolve(56)
// Or
return Promise<Int>.reject(e)
}
}
.recover(with: Promise<Int>.resolve(56))
Note that in the block version you can also throw your own error \o/
With .validate
, you can break the promise chain with an assertion block.
You can:
- Insert assertion in Promise chain
- Insert assertion and return you own Error
For instance checking if a user is allowed to drink alcohol :
fetchUserAge()
.validate { $0 > 18 }
.then { age in
// Offer a drink
}
.validate(withError: MyError.defaultError, { $0 > 18 })`
A failed validation will retrun a PromiseError.validationFailed
by default.
With retry
, you can restart a failed Promise X number of times.
doSomething()
.retry(10)
.then { v in
// YAY!
}.onError { e in
// Failed 10 times in a row
}
With .bridgeError
, you can intercept a low-level Error and return your own high level error.
The classic use-case is when you receive an api error and you bridge it to your own domain error.
You can:
- Catch all errors and use your own Error type
- Catch only a specific error
.bridgeError(to: MyError.defaultError)
.bridgeError(SomeError, to: MyError.defaultError)
With .whenAll
, you can combine multiple calls and get all the results when all the promises are fulfilled :
whenAll(fetchUsersA(),fetchUsersB(), fetchUsersC()).then { allUsers in
// All the promises came back
}
With chain
, you can add behaviours without changing the chain of Promises.
A common use-case is for adding Analytics tracking like so:
extension Photo {
public func post() -> Async<Photo> {
return api.post(self).chain { _ in
Tracker.trackEvent(.postPicture)
}
}
}
With noMatterWhat
you can add code to be executed in the middle of a promise chain, no matter what happens.
func fetchNext() -> Promise<[T]> {
isLoading = true
call.params["page"] = page + 1
return call.fetch()
.registerThen(parseResponse)
.resolveOnMainThread()
.noMatterWhat {
self.isLoading = false
}
}
With unwrap
you can transform an optional into a promise :
func fetch(userId: String?) -> Promise<Void> {
return unwrap(userId).then {
network.get("/user/\($0)")
}
}
Unwrap will fail the promise chain with unwrappingFailed
error in case of a nil value :)
AsyncTask
and Async<T>
typealisases are provided for those of us who think that Async can be clearer than Promise
.
Feel free to replace Promise<Void>
by AsyncTask
and Promise<T>
by Async<T>
wherever needed.
This is purely for the eyes :)
await
waits for a promise to complete synchronously and yields the result :
let photos = try! await(getPhotos())
async
takes a block and wraps it in a background Promise.
async {
let photos = try await(getPhotos())
}
Notice how we don't need the !
anymore because async
will catch the errors.
Together, async
/await
enable us to write asynchronous code in a synchronous manner :
async {
let userId = try await(fetchUserId())
let userName = try await(fetchUserNameFromId(userId))
let isFollowed = try await(fetchUserFollowStatusFromName(userName))
return isFollowed
}.then { isFollowed in
print(isFollowed)
}.onError { e in
// handle errors
}
Await comes with ..
shorthand operator. The ..?
will fallback to a nil value instead of throwing.
let userId = try await(fetchUserId())
Can be written like this:
let userId = try ..fetchUserId()
target 'MyApp'
pod 'thenPromise'
use_frameworks!
github "freshOS/then"
Simply Copy and Paste .swift
files in your Xcode Project :)
Grab this repository and build the Framework target on the example project. Then Link against this framework.
S4cha, Max Konovalov, YannickDot, Damien, piterlouis
- Swift 2 -> version 1.4.2
- Swift 3 -> version 2.2.5
- Swift 4 -> version 3.1.0
- Swift 4.1 -> version 4.0.0
Like the project? Offer coffee or support us with a monthly donation and help us continue our activities :)
Become a sponsor and get your logo on our README on Github with a link to your site :)