com.ben-allred.vow.core — com.ben-allred/vow 0.6.0

A library to wrap core.async channels with chainable left/right (or success/failure) handling.

all clj/s

(all promises)

Takes a sequence of promises and returns a promise that resolves when all promises resolve, or rejects if any promise rejects. promises can be a map or sequential collection.

(-> {:foo (resolve :bar) :baz (resolve :quux)} (all) (then println)) ;; {:foo :bar :baz :quux}

always clj/s macro

(always promise & body)

A macro that always executes a body, regardless of the result of the promise. Evaluates forms in order and returns the last one.

(always my-promise (println "I always happen") 17)

and clj/s macro

(and promise & forms)

Continues the promise chain by executing each form in order until one throws or results in a rejected promise. Returns the last success or the first rejection.

any clj/s

(any promises)

Takes a sequence of promises and returns a promise that resolves to the first success or rejects with all errors if everything fails. promises can be a map or sequential collection.

(-> {:foo (resolve :bar) :baz (sleep :quux 100)} any (then println)) ;; :bar

attempt clj/s macro

(attempt & forms)

A macro to imitate try/catch/finally behavior with promises.

(begin (reject "some error") (catch ^Number num [:number num]) (catch any [:any any]) (catch ^String str [:string str]) (finally (println "finally"))) ;; [:success [:any "some error"]]

await clj/s macro

(await bindings & body)

A lexical binding macro that coerces it's expressions into promises and binds their results accordingly. Any thrown exception or attempt to bind to a rejected promise results in a rejected promise, otherwise it resolves the body with the expressions bound.

(v/await [foo (v/sleep :foo 100) _ (println "this will print after 100 ms") bar (v/or (v/reject :error) (v/resolve :baz))] [foo bar]) ;; [:success [:foo :bar]]

catch clj/s

(catch promise cb)

Handles the failure path of a promise. If the handler fn returns an IPromise, it will be hoisted. If the handler fn throws, it will produce a rejected promise.

ch->prom clj/s

(ch->prom ch)

(ch->prom ch success?)

Given a core.async channel and an optional success? predicate, creates a promise with the first value pulled off the channel. The promise will resolve or reject according to the result of (success? (async/<! ch)). Defaults to always resolving.

create clj/s

(create cb)

Creates a promise that resolves or rejects at the discretion of cb. cb should be a two arg function accepting resolve and reject that will "resolve" or "reject" the promise respectively.

(create (fn [resolve reject] (let [default (gensym) result (deref (future (do-something)) 1000 default)] (if (= default result) (reject (ex-info "Took too long" {})) (resolve result)))))

deref! clj/s

(deref! prom)

(deref! prom timeout-ms timeout-value)

Deref a promise into a value, or cause it to throw an exception - Clojure only.

first clj/s

(first promises)

Takes a sequence of promises and resolves or rejects whichever finishes first.

(-> [(resolve :foo) (sleep :bar 10)] first (v/peek println)) ;; [:success :foo]

native->prom clj/s≠

clj

(native->prom prom)

(native->prom prom success?)

cljs

(native->prom prom)

Given a "native" promise (js/Promise in cljs and anything that implements IDeref in clj), creates a promise that resolves or rejects. In cljs it follows js/Promise semantics for resolving and rejecting. In clj you can pass an optional success? predicate that determines whether to resolve or reject the value which always resolves by default.

or clj/s macro

(or promise & forms)

Continues the promise chain by executing each form in order until one returns a value or a resolved promise. Returns the first success or the last rejection.

peek clj/s

(peek promise cb)

(peek promise on-success on-error)

Access the success and/or failure path of a promise chain at a specific point in processing. Can be used for side effects (or debugging) only. Does not effect the value to be resolved or rejected. If you only want to handle one of success/failure path, pass nil for the other handler.

(peek promise nil println)

promise? clj/s

(promise? x)

Returns true if x satisfies IPromise.

reject clj/s

(reject)

(reject err)

Creates a promise that rejects with err.

resolve clj/s

(resolve)

(resolve val)

Creates a promise that resolves with val.

sleep clj/s

(sleep ms)

(sleep value ms)

Creates a promise that resolves after the specified amount of time (in milliseconds).

then clj/s

(then promise on-success)

(then promise on-success on-error)

Handles the success path (or success and failure path) of a promise. If the handler fn returns an IPromise, it will be hoisted. If the handler fn throws, it will produce a rejected promise.

then-> clj/s macro

(then-> promise & forms)

A macro for handing the success path thread via ->.

(-> (resolve 3) (then-> inc (* 2) (as-> $ (repeat $ $)) (->> (map dec))) (peek println nil)) ;; (7 7 7 7 7 7 7 7)

vow clj/s macro

(vow & body)

A macro for creating a promise out of an expression

(peek (vow (println "starting") (/ 17 0)) println)