Introduction

A promise library for Clojure and ClojureScript.

On the JVM paltform promesa is built on top of completable futures (requires jdk8). On JS engines it is built on top of the bluebird promise library.

Project Maturity

Since promesa is a young project there may be some API breakage.

Install

Just include the following lines in your dependency vector on project.clj:

[funcool/promesa "1.9.0"]

This package requires JDK8 if you are using it on the JVM and all environments that the bluebird library supports on JS engines.

User guide

Introduction

A promise is an abstraction that represents the result of an asynchronous operation that has the notion of error.

This is a list of all possible states for a promise:

  • resolved: means that the promise contains a value.

  • rejected: means that the promise contains an error.

  • pending: means that the promise does not have value.

The promise can be considered done when it is resolved or rejected.

Creating a promise

There are several different ways to create a promise instance:

Example creating already resolved promise instances from plain values.
(require '[promesa.core :as p])

;; Create a fulfilled promise
(p/promise 1)
;; => #<Promise [1]>

If a promise function receives a plain value, it returns a resolved promise with the provided plain value. If it receives an instance of Error, it returns a rejected promise.

Also, it accepts a factory callback that receives two callable parameters: resolve and reject. So you can use one or other to resolve or reject the promise respectively.

Example creating promise instance using a factory.
(p/promise (fn [resolve reject]
             (resolve 1)))

An other way to create a promise is using the do* macro which works similar to the factory callback with the exception that to resolve the promise instead of calling the resolve callback we just need to return the value:

(p/do*
  (let [a (rand-int 10)
        b (rand-int 10)]
    (+ a b)))

do* blocks work similarly to clojure’s do block, so you can put any expression but only the last one will be returned and that expression can be a plain value or an other promise.

If an exception is raised inside the do* block, it will return the rejected promise instead of re-raising the exception on the stack.

Note

In both platforms the promise factory function is executed synchronously and making it blocking or not blocking is the user’s responsibility.

Promise Chaining

The most common way to apply a function to a promise (or in other words, to chain its execution) is using the well known map function:

(def result (->> (p/promise 1)
                 (p/map inc)))

@result     ; only on the jvm
;; => 2

For people coming from the JS world, there is also the then function that works in the same way as map but with the parameters inverted:

(def result (-> (p/promise 1)
                (p/then inc)))

@result     ; only on the jvm
;; => 2

If you want to apply multiple functions instead of using multiple then or map`s, you can use the `chain function:

(def result (-> (p/promise 1)
                (p/chain inc inc inc))

@result     ; only on the jvm
;; => 4

There is also the mapcat function that removes one level of nesting when dealing with multiple promises. It is specially useful if the function that you want to apply to also returns a promise instead of a value:

(def incp #(p/resolved (inc %)))

(def result (->> (p/promise 1)
                 (p/mapcat incp)))

@result     ; only on the jvm
;; => 2

Important: The mapcat function is only useful in the JVM platform. In JS engines, the map function already flattens the result magically (because the underlying implementation does that).

Async/Await Syntax

alet macro (async let)

The promesa library comes with convenient syntax-sugar that allows you to create a compositions that looks like synchronous code while using the clojure’s familiar let syntax:

(require '[promesa.core :as p])

(defn sleep-promise
  [wait]
  (p/promise (fn [resolve reject]
               (p/schedule wait #(resolve wait)))))

(def result
  (p/alet [x (p/await (sleep-promise 42))
           y (p/await (sleep-promise 41))
           z 2]
    (+ x y z)))

@result     ; only on the jvm
;; => 85

The alet macro behaves identical to the let with the exception that it always return a promise and allows you to mark async operations with the await placeholder making it looks like a synchronous operation.

If an error occurs at any step the entire composition will be short-circuited, returning exceptionally resolved promise.

async macro (general purpose)

In contrast to the alet macro, the async macro is more general purpose and enables the usage of await in any place (not only on the let bindings). Let see an example:

(def p (async
         (dotimes [i 3]
           (p/await (p/delay 100))
           (println "i=" i))
         10))

@p
;; i=0
;; i=1
;; i=2
;; => 10

As expected, it returns a promise which will be resolved with result of the body when completed.

If you are familiar with core.async go macro, async macro works in the same way (in fact, it uses core.async machinery to archive that).

Note

Because of some differences in the macro implementation in clj and cljs, the clojure version of macro is available in promesa.async namespace and ClojureScript version of macro in promesa.async-cljs namespace.

Example importing async macro in Clojure
(require '[promesa.async :refer [async]])
Example importing async macro in ClojureScript
(require '[promesa.async-cljs :refer-macros [async]])

If you are not familiar with async/await syntax, you can read more about it here.

Warning
 experimental

Error handling

One of the advantages of using promise abstraction is that it natively has a notion of error, so you don’t need reinvent it. If some of the computations of the composed promise chain/pipeline raises an exception, that one is automatically propagated to the last promise making the effect of short-circuiting.

Let see an example:

(-> (p/promise (ex-info "error" nil))
    (p/catch (fn [error]
               (.log js/console error))))

The catch function adds a new handler to the promise chain that will be called when any of the previous promises in the chain are rejected or an exception is raised. The catch function also returns a promise that will be resolved or rejected depending on that will happen inside the catch hanlder.

If you prefer map like parameters order, it there err function (and error alias) that works in same way as catch but has the parameters like map:

(->> (p/promise (ex-info "error" nil))
     (p/error (fn [error]
                (.log js/console error))))
Note

On the JVM platform the reject value is mandatory to be an instance of Throwable but in JS platform it can by any value.

Branching

For adding both success and error handlers to a promise at the same time you can use the branch function:

(p/branch a-promise
          (fn [v]
            (println "Ok" v))
          (fn [err]
            (println err)))

Working with collections

In some circumstances you will want wait a completion of few promises at same time, and promesa also provides helpers for that.

Imagine that you have a collection of promises and you want to wait until all of them are resolved. This can be done using the all combinator:

(let [p (p/all [(do-some-io)
                (do-some-other-io)])]
  (p/then p (fn [[result1 result2]]
              (do-something-with-results result1 result2))))

It there are also circumstances where you only want arbitrary select of the first resolved promise. For this case, you can use the any combinator:

(let [p (p/any [(p/delay 100 1)
                (p/delay 200 2)
                (p/delay 120 3)])]
  (p/then p (fn [x]
              (.log js/console "The first one finished: " x))))

Delays and timeouts.

JavaScript due its nature, does not allow you to block or sleep. But with promises you can emulate the functionality using delay like so:

(-> (p/delay 1000 "foobar")
    (p/then (fn [v]
              (println "Received:" v))))

;; After 1 second it will print the message
;; to the console: "Received: foobar"

The promise library offers the ability to add a timeout to async operations thanks to the timeout function:

(-> (some-async-task)
    (p/timeout 200)
    (p/then #(println "Task finished" %))
    (p/catch #(println "Timeout" %)))

In case the async task is slow, in the example more that 200ms, the promise will be rejected with timeout error and successfully captured with the catch handler.

Scheduling Tasks

Additionally to the promise abstraction, this library also comes with lightweight abstraction for scheduling task to be executed at some time in future:

Example using a schedule function.
(p/schedule 1000 (fn []
                   (println "hello world")))

This example shows you how you can schedule a function call to be executed 1 second in the future. It works in the same way for both plaforms (clj and cljs).

The tasks can be cancelled using its return value:

(def task (p/schedule 1000 #(do-stuff)))

(p/cancel! task)

FAQ

Why bluebird instead of es6 promise?

Because it is the state of the art and the most performant promise implementation.

Let see some home made benchmarks:

lib=promesa number=500
promesa: 25.144ms

lib=promesa-raw number=500
promesa-raw: 15.646ms

lib=es6 number=500
es6: 2426.458ms

lib=zousan number=500
zousan: 114.634ms

lib=goog number=500
goog: 239.821ms

The promesa-raw lib refers to the raw usage of bluebird library and as you can observe, promesa has some overhead. But it is nothing important if you compare it with the rest of libraries.

Developers Guide

Contributing

Unlike Clojure and other Clojure contrib libs, does not have many restrictions for contributions. Just open a issue or pull request.

Get the Code

promesa is open source and can be found on github.

You can clone the public repository with this command:

git clone https://github.com/funcool/promesa

Run tests

To run the tests execute the following:

For the JVM platform:

lein test

And for JS platform:

./scripts/build
node out/tests.js

You will need to have nodejs installed on your system.

License

promesa is licensed under BSD (2-Clause) license:

Copyright (c) 2015-2016 Andrey Antukh <niwi@niwi.nz>

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.