promesa

To use promesa in your Clojure or ClojureScript project, add it to your deps.edn file. You can use the Maven central version or pull directly from GitHub using a specific SHA or tag.

;; Using Maven central
funcool/promesa {:mvn/version "12.0.1"}

;; Using Git
funcool/promesa
{:git/sha "7d841fc"
 :git/tag "12.0.1"
 :git/url "https://github.com/funcool/promesa"}

By default, channels use virtual threads (on JVM) or the common pool for internal dispatching. You can override this by providing a custom executor via the :exc option in the sp/chan constructor.

(require '[promesa.exec :as px])

(def executor (px/cached-executor))

;; Create a channel using the custom executor
(def ch (sp/chan :exc executor))

Promesa provides syntactic abstractions for working with promises, similar to async/await in JavaScript. You can create promises using p/promise and transform them using functional operators like p/map.

Note: The following example using deref requires a JVM environment, as the JavaScript runtime lacks equivalent blocking primitives.

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

(->> (p/promise 1)
     (p/map inc)
     (deref))
;; => 2

Use these functions to manage the lifecycle of a promise chain regardless of success or failure.

• handle: Combines resolved and rejected callbacks into a single function. The callback receives [result error]. If the handler returns a promise, it is automatically unwrapped.
• finally: Executes a callback regardless of whether the promise was resolved or rejected. The return value of the finally callback is ignored, and a new promise is returned that mirrors the original promise's state.

;; handle: [result error]
(-> (p/promise 1)
    (p/handle (fn [result error]
                (if error :rejected :resolved))))

;; finally: always runs
(-> (p/promise 1)
    (p/finally (fn [_ _]
                (println "finally"))))

Use p/timeout to prevent an asynchronous task from running indefinitely. If the task takes longer than the specified duration, the promise will be rejected with a timeout error.

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

In Promesa, go blocks are not macro-transformed code; they are simply executed within a virtual thread (on JVM) or a standard thread.

Key behaviors:

• Return Value: Unlike core.async where go returns a channel, Promesa's go returns a promise (CompletableFuture). This allows the block to represent a computation that can fail.
• go-chan: If you specifically need a go block to return a channel, use the go-chan macro.
• go-loop: Use go-loop for recursive go blocks (combining go with loop/recur).

Example:

(sp/go
  (sp/<! ch 1000 :timeout))

;; Returns a promise (CompletableFuture)
@(sp/go
   (sp/<! ch 1000 :timeout))

On the JVM, the default execution model for promise chains executes callbacks in the same thread that resolved the previous promise. While efficient for small chains, large or computationally heavy chains can block the thread pool.

To prevent this, use p/fmap with an executor keyword to schedule callbacks as separate tasks:

• :default: Uses px/*default-executor* (a ForkJoinPool optimized for small tasks).
• :vthread: Uses px/*vthread-executor* (Virtual Threads, available on JDK 21+ or JDK 19 with preview enabled).

(require '[promesa.exec :as px])

@(->> (p/delay 100 1)
      (p/fmap :default inc)
      (p/fmap :default inc))
;; => 3

To implement pub/sub or multiple readers for the same data, use multiplexers.

• sp/mult: Creates a new multiplexer. The returned object implements the channel API, so you can put values into it directly.
• sp/mult*: Used when you already have an existing channel that you want to multiplex.
• sp/tap: Attaches a channel to a multiplexer.
• sp/untap: Removes a channel from a multiplexer.

Closed channels are automatically removed from the multiplexer.

(def mx (sp/mult))

(sp/go
  (let [ch (sp/chan)]
    (sp/tap mx ch)
    (println "go 1:" (sp/<! ch))
    (sp/close ch)))

(sp/go
  (let [ch (sp/chan)]
    (sp/tap mx ch)
    (println "go 2:" (sp/<! ch))
    (sp/close ch)))

(sp/>! mx :a)