# Kovenant cheat sheet

Promises are awesome. They remove a lot of the complexity of dealing with asynchronous code, and ever since I started using them in Javascript I’ve never gone back to callbacks. When it comes to Android development I’ve done a bit of experimenting with RxKotlin, but it was a bit overcomplicated for my needs. Recently I’ve been using the Kovenant library for Kotlin which adds pretty good Promise support with a nice and simple API.

Some interesting points about the way Kovenant works:

• All operations are done in background threads, unless you use successUi, failUi, or promiseOnUi.
• The success and fail blocks are not directly part of the promise chain, so any errors thrown inside won’t be passed down to the next fail block. Block types which handle throw correctly: promiseOnUi, task, then, bind
• Nested promises are not handled by default. If a then block returns another promise, use bind instead or else the promise itself will be passed to the next block.
• If you know Rx: then is like .map, and bind is like .flatMap.

Here is a list of Kovenant snippets which I have found extremely useful.

## Android specific

Add both the Kovenant core library and the Android extensions to your build.gradle.

Start and stop Kovenant along with your application. This can be done easily in a custom Application class.

When performing actions based on the user’s intent (button press etc), it’s good to show them the progress. Kovenant makes it really easy.

## Nested promises

Use bind instead of then if the block is returning a promise. bind unwraps the promise in the following block.

If you have a nested promise and can’t use bind like above, you can unwrap it by calling bind afterwards.

## Error handling

Kovenant doesn’t come with a block for recovering from errors, but it’s easy to extend it to include one. Get Kovenant+Recover.kt

The recover block from above can be used to transform error messages as well, since it handles throw correctly.

## Wrapping non-promise based functions

You can easily wrap non-Promise functions by using Deferred.

Wrapping operations that use delegate callbacks are easy too, just store the Deferred promise until you can resolve or reject it later.

## Synchronization and queueing

You can easily chain multiple promises. When doing it this way, you can ignore all errors and only have one fail block right at the end for catching any error in the entire chain.

It’s possible to create a “queue” of promises which ensures that operations always are executed in order, and that the next promise only starts when the previous one is entirely completed. Get PromiseQueue.kt

PromiseQueue.add handles throw correctly as well, so errors thrown inside the block will be passed on to the next fail or recover handler.

Using the PromiseQueue class above, it’s possible to create “synchronized” functions, which ensure they don’t run at the same time.

This was very useful for me when creating a Bluetooth library, since GATT characteristic read/write operations cannot be done simultaneously. This allows users of the library to call write() as many times as they want, without having to worry about previous writes still in progress.

## Result value

If you don’t want to return a value from a promise, use Unit as the value type. You can also return Unit from your then block.

Unit is Kotlin’s equivalent of void in Java.

You can use a then block to convert the output of a promise.