desiderata

Things wanted or needed but missing from clojure.core.

This is not just a collection of utility functions, but more significant features (and maybe some utility functions). Maybe it's best to just poke around in the documentation? Otherwise, I've attempted to provide details below.

Baseline versions

• JVM: 21
• Clojure: 1.12.0

defrecord

You can use systems.thoughtfull.desiderata/defrecord as a drop-in replacement for clojure.core/defrecord and what you get are five new features. The first (minor) feature is the factory function (i.e. map->...) takes keyword arguments.

Metadata propagation

Metadata attached to the name symbol of systems.thoughtfull.desiderata/defrecord will get propagated to the factory functions. So, for example, if you deprecate the defrecord, then its factory functions will also be deprecated.

Docstring

systems.thoughtfull.desiderata/defrecord takes a docstring that it appends to the end of both the factory and positional factory functions.

user> (require '[systems.thoughtfull.desiderata :as desiderata])
nil

user> (desiderata/defrecord Widget
"A widget for frobbing gizmos.

width and height are in metric."
[width height])
user.Widget

user> (doc map->Widget)
-------------------------
user/map->Widget
([& {:keys [width height]}])
  Factory function for class user.Widget, taking a map of keywords to field values.

  A widget for frobbing gizmos.
  
  width and height are in metric.
nil

user> (doc ->Widget)
-------------------------
user/->Widget
([width height])
  Positional factory function for class user.Widget.

  A widget for frobbing gizmos.
  
  width and height are in metric.
nil

Defaults

You can specify a map of default values for fields (and non-fields) with the systems.thoughtfull.desiderata/defaults option. Values given to the factory or positional factory functions will override defaults.

user> (desiderata/defrecord Gizmo
[name]
::desiderata/defaults
{:name "Gizmo"
 :color :blue})
user.Gizmo

user> (->Gizmo "the Great")
{:name "the Great", :color :blue}

user> (map->Gizmo :texture :bumpy)
{:name "Gizmo", :color :blue, :texture :bumpy}

Initializer

A method with the same name as the defrecord is an initializer method called from both the factory and positional factory functions. The initializer runs after the defaults and arguments have merged and the factory function has executed.

As a sanity check, the initializer must return an instance of the defrecord, otherwise an IllegalStateException is thrown.

user> (desiderata/defrecord Company
[debt equity]
(Company
  [this]
  (assoc this :gearing-ratio (/ debt equity))))
user.Company

user> (->Company 100 1000)
{:debt 100, :equity 1000, :gearing-ratio 1/10}

Thread.UncaughtExceptionHandler

There are two convenience functions for working with Thread.UncaughtExceptionHandler. uncaught-exception-handler will adapt a two argument function to a Thread.UncaughtExceptionHandler.

set-default-uncaught-exception-handler-fn! will set the default Thread.UncaughtExceptionHandler after adapting the given two argument function to a Thread.UncaughtExceptionHandler. The default handler is used if there is no handler defined for a Thread and its ThreadGroup (see Thread/setDefaultUncaughtExceptionHandler).

thread-factory

thread-factory creates a java.util.concurrent.ThreadFactory for use particularly with executors. It passes options to Threads as it creates them, however, a notable feature is it takes an uncaught-exception-handler-fn that it will set as a Thread.UncaughtExceptionHandler on each thread it creates. It adapts the uncaught-exception-handler-fn into a Thread.UncaughtExceptionHandler using uncaught-exception-handler, and conveys to the uncaught-exception-handler-fn the bindings established at the time the thread factory is created.

Another notable and Clojure-specific feature is the ThreadFactory can convey to created threads the bindings established when the thread factory was created. You can enable this by passing :convey-bindings? true, but by default it is disabled.

It will also take a name which is used as a prefix to the names of threads it creates.

clj-kondo

To import custom clj-kondo hooks for systems.thoughtfull.desiderata/defrecord use

clj-kondo --lint "$(clojure -Spath)" --copy-configs --skip-lint

License

Copyright © technosophist

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

This Source Code Form is "Incompatible With Secondary Licenses", as defined by the Mozilla Public License, v. 2.0.