clojure-donut-system

donut.party/​system

Component lifecycle and dependency injection library for Clojure applications. Helps organize applications as systems of components with managed dependencies and lifecycle.

Setup

deps.edn:

party.donut/​system {:mvn/​version "1.0.257"}

Require:

(require '[donut.system :as ds])

See https://clojars.org/party.donut/system for the latest version.

Quick Start

Define components with ::ds/​start and ::ds/​stop handlers:

(def system
  {::ds/​defs
   {:app
    {:server #::ds{:start (fn [{:keys [::ds/​config]}]
                            (start-server (:port config)))
                   :stop  (fn [{:keys [::ds/​instance]}]
                            (stop-server instance))
                   :config {:port 8080}}}}})

;; Start the system
(def running-system (ds/​signal system ::ds/​start))

;; Stop the system
(ds/​signal running-system ::ds/​stop)

Core Concepts

System Map Structure

{::ds/​defs          ; component definitions go here
 ::ds/​instances     ; runtime instances (created by signals)
 ::ds/​signals       ; custom signal definitions (optional)
 ::ds/​plugins       ; plugins to extend functionality (optional)}

Component Definition

Components are maps with signal handlers:

#::ds{:start  (fn [arg] ...)  ; creates instance
      :stop   (fn [arg] ...)  ; cleans up instance
      :config {...}}          ; configuration data

Component Organization

Components are organized into groups (2-level structure):

{::ds/​defs
 {:group-name         ; first level: component group
  {:component-name    ; second level: component
   #::ds{:start ...}}}}

Signal Handler Arguments

Signal handlers receive a map with:

• ::ds/​instance - component instance (if exists)
• ::ds/​config - component config with refs resolved
• ::ds/​system - entire system map
• ::ds/​component-id - e.g. [:group :component]

Common Patterns

References Between Components

Use ds/​ref to reference other components:

(def system
  {::ds/​defs
   {:services
    {:db #::ds{:start (fn [_] (create-db-pool))}}

    :app
    {:handler #::ds{:start  (fn [{:keys [::ds/​config]}]
                              (make-handler (:db config)))
                    :config {:db (ds/​ref [:services :db])}}}}})

Refs determine startup order - dependencies start first.

Local Refs (within same group)

Use ds/​local-ref to reference components in the same group:

(def HTTPServer
  #::ds{:start  (fn [{:keys [::ds/​config]}]
                  (start-server (:handler config) (:port config)))
        :config {:handler (ds/​local-ref [:handler])
                 :port    (ds/​local-ref [:port])}})

(def system
  {::ds/​defs
   {:http-1 {:server  HTTPServer
             :handler (fn [req] {:status 200 :body "Server 1"})
             :port    8080}

    :http-2 {:server  HTTPServer
             :handler (fn [req] {:status 200 :body "Server 2"})
             :port    9090}}})

System Data (non-component values)

Maps without ::ds/​start are treated as data and can be referenced:

{::ds/​defs
 {:env {:db-url "jdbc:postgresql://localhost/​mydb"
        :port 8080}

  :services
  {:db #::ds{:start  (fn [{:keys [::ds/​config]}]
                       (connect (:url config)))
             :config {:url (ds/​ref [:env :db-url])}}}}}

Named Systems (environment-specific config)

Define systems by environment:

(defmethod ds/​named-system :dev
  [_]
  {::ds/​defs {:env {:port 8080}
              :app {...}}})

(defmethod ds/​named-system :test
  [_]
  {::ds/​defs {:env {:port 9999}
              :app {...}}})

;; Start with overrides
(ds/​start :dev {[:env :port] 3000})

REPL Workflow

Use donut.system.repl for development:

(require '[donut.system.repl :as dsr])

;; Define default REPL system
(defmethod ds/​named-system :donut.system/​repl
  [_]
  (ds/​system :dev))

;; REPL commands
(dsr/​start)   ; start system
(dsr/​stop)    ; stop system
(dsr/​restart) ; stop, reload namespaces, start

Built-in Signals

• ::ds/​start - create/​start component instances (reverse-topsort order)
• ::ds/​stop - stop/​cleanup component instances (topsort order)
• ::ds/​suspend - pause without full teardown
• ::ds/​resume - resume suspended components

Convenience functions: ds/​start, ds/​stop, ds/​suspend, ds/​resume

Gotchas / Caveats

1. Component Organization: Components must be direct children of groups. This won't work:

   {::ds/​defs
    {:group {:subgroup {:component ...}}}}  ; TOO NESTED!
   

2. Refs Must Be Reachable: Refs must be in the data structure, not hidden in functions:

   ;; BAD - ref inside function, not reachable
   #::ds{:start (fn [_] (ds/​ref [:services :db]))}
   
   ;; GOOD - ref in config
   #::ds{:start  (fn [{:keys [::ds/​config]}] (:db config))
         :config {:db (ds/​ref [:services :db])}}
   

3. Deep Refs: Can reference into component instances:

   (ds/​ref [:group :component :level-1 :level-2])
   

4. Idempotent Start Handlers: If you signal the same system multiple times, make start handlers idempotent:

   (fn [{::ds/​keys [instance config]}]
     (or instance (create-component config)))
   

Testing

Test System Fixtures

(use-fixtures :each (ds/​system-fixture ::test))

(deftest my-test
  (is (= expected-value
         @(ds/​instance ds/​*system* [:group :component]))))

Mocking Components

Override components in tests:

(ds/​start ::test
  {[:services :external-api] mock-api
   [:services :email] mock-email-sender})

Advanced Features

• Custom signals with ::ds/​signals
• Lifecycle hooks: ::ds/​pre-start, ::ds/​post-start, etc.
• Component selection: (ds/​start system {} #{[:group :component]})
• Plugins: extend system functionality
• Validation plugin: malli schemas for config and instances
• Subsystems: compose systems from other systems

References

• Clojars: https://clojars.org/party.donut/system
• GitHub: https://github.com/donut-party/system
• Full Docs: https://github.com/donut-party/system#readme
• Tutorial: https://donut.party/docs/system/tutorial/
• cljdoc: https://cljdoc.org/d/party.donut/system/