coldbrew

Easy to use Clojure wrappers for Caffeine

Usage

(require '[fmnoise.coldbrew :refer [cached defcached]])

The main building block is cached function which accepts function and returns cached version of it. Cache options are passed as meta attached to function. Supported options are:

• :expire : expiration time (in seconds), uses expireAfterWrite
• :refresh : refresh time (in seconds), uses refreshAfterWrite
• :when : function for performing conditional caching (value is cached only if function returns truthy value)

Let's create a cached function with expiration time 1 hour (3600 sec):

(defn fetch-customer [base-url id]
  (http/get (str base-url "/customers/" id)))

(def cached-customer-fetch
  (cached (with-meta fetch-customer {:expire 3600})))

We can achieve same result using anonymous function:

(def cached-customer-fetch
  (cached
    (with-meta
     (fn [base-url id]
       (http/get (str base-url "/customers/" id))
     {:expire 3600})))

We can also configure that value should be cached only when it satisfied condition:

;; tasks can be only added to worker and capacity can only decrease
;; so it makes sense to cache value when capacity reaches 0
(def worker-tasks-capacity
  (cached
    (with-meta
    (fn [db worker-id date]
      (some-expensive-query db worker-id date)
      {:when zero?})))

There's also more flexible defcached macro which uses cached under the hood. The main purpose of it is ability to build cache key from function agruments:

(defcached fetch-customer ;; function name
  [{:keys [base-url timeout]} id] ;; function args
  ^{:expire 3600} ;; cache options passed as meta attached to cache key
  [id] ;; cache key - a vector which will become args for internal caching function
  ;; function body
  (let [result (deref (http/get (str base-url "/customer/" id)) timeout ::timeout)]
    (if (= result ::timeout)
      (throw (ex-info "Request timed out" {:id id}))
      result))

All meta passed to function name is preserved, so we can have private cached function and add docstring:

(defcached
  ^{:private true
    :doc "Fetches customer with given id"}
  fetch-customer-impl [{:keys [base-url timeout]} id]
  ^{:expire 3600}
  [id]
  (let [result (deref (http/get (str base-url "/customer/" id)) timeout ::timeout)]
    (if (= result ::timeout)
      (throw (ex-info "Request timed out" {:id id}))
      result)))

NB: Docstring is only supported as meta

Due to defn-like declaration it's very easy to refactor existing defn to cached function using defcached macro:

1. Change defn to defcached
2. Add cache key vector before function body (names should correspond with function args) with optional meta for expiration/refreshing
3. That's it! :tada:

NB: If you later decide to return back to defn and forget to remove cache key, nothing will break.

Disclaimer

Same as consuming cold brew coffee, make sure you don't exceed recommended caffeine amount, as each call to cached creates separate Caffeine Loading Cache instance. Also make sure you understand the risk of memory leaks when caching large objects or collections.

Status

Early adopting. Breaking changes are possible.

Credits

Coldbrew icon made by Freepik from Flaticon

License

Copyright © 2021 fmnoise

Distributed under the Eclipse Public License 2.0