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, uses expireAfterWrite
• :refresh, uses refreshAfterWrite

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})))

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

Alpha. Not used in production yet. Breaking changes are possible.

Credits

Coldbrew icon made by Freepik from Flaticon

License

Copyright © 2021 fmnoise

Distributed under the Eclipse Public License 2.0