Singleton-Like Resources and Global State in Clojure

The singleton pattern promises one shared instance and a global access path. In Clojure, that idea deserves extra scrutiny because global state is one of the fastest ways to make otherwise clear functional code harder to test and harder to reason about.

That does not mean the problem never exists. Some resources really are shared:

• a connection pool
• a metrics registry
• a cache
• a lazily initialized expensive client

The practical question is not, “How do I recreate the classic singleton?” It is, “Do I truly need one shared runtime resource, and if so, how can I make its ownership explicit and safe?”

Why Singletons Are Often A Smell In Clojure

Many singleton requests are really symptoms of one of these design problems:

• dependencies are not being passed explicitly
• initialization is happening in the wrong place
• global mutable state is being used as a convenience shortcut

Once a value becomes globally reachable, tests start depending on execution order, reload behavior becomes trickier, and local reasoning gets weaker. That is especially costly in Clojure, where the language otherwise makes explicit data flow easy.

The Legitimate Case

A shared resource is legitimate when all of these are true:

• there is a real cost or coordination reason to create it once
• multiple parts of the application use the same instance
• the resource has one clear owner at runtime
• the program can still test or replace it intentionally

That is closer to “shared runtime resource” than to “magic global object.”

Prefer defonce And delay Over Ad-Hoc Global Mutation

If you really need one lazily created resource per running process, defonce plus delay is often clearer than a hand-rolled atom-based singleton.

 1(ns app.db)
 2
 3(defn connect-db []
 4  {:pool :connected})
 5
 6(defonce db-pool
 7  (delay (connect-db)))
 8
 9(defn get-db-pool []
10  @db-pool)

This works well because:

• defonce avoids recreating the root var on normal reloads
• delay guarantees lazy, at-most-once realization per process
• callers can still see that they are using a shared runtime value

That is usually cleaner than:

• an atom plus manual nil? checks
• a var with hidden rebinding logic
• a function that silently memoizes expensive state without making the lifecycle obvious

When An Atom Makes Sense

Use an atom only when the shared value itself must change over time and that is part of the design, not just part of initialization.

1(defonce current-config
2  (atom {:log-level :info
3         :feature-flags #{}}))

That is no longer just a singleton. It is a shared mutable reference with all the trade-offs that implies. Make that distinction explicit in naming and design review.

Prefer Injection For Most Business Code

Even if the program has one shared resource, most business functions should still receive that resource explicitly rather than reaching for a global.

1(defn find-user [db user-id]
2  ;; query using db
3  {:user/id user-id})
4
5(defn handle-request [db request]
6  (find-user db (:user-id request)))

That keeps the shared resource at the system edge while preserving testable, local business logic in the middle.

Common Mistakes

The first mistake is treating any widely used value as a singleton candidate. Frequency of use is not a sufficient reason for global access.

The second mistake is using defonce to hide mutable state that should have stayed explicit.

The third mistake is assuming “only one instance” automatically means “best accessed globally.” Those are separate decisions.

Better Alternatives

Before using a singleton-style pattern, consider:

• passing the dependency explicitly
• using a system map assembled at startup
• using delay for one-time lazy creation
• keeping mutable references confined to a small boundary namespace

In Clojure, these options usually produce clearer code than a traditional global singleton port.

Design Review Questions

Ask these before accepting singleton-style code:

• Is the resource truly shared, or just convenient to access globally?
• Would explicit injection make tests and reuse easier?
• Does delay solve the problem more cleanly than an atom or var?
• Is the lifecycle obvious to the next reader?

If the answers are weak, you probably do not need a singleton at all.