darkleaf.di.core — org.clojars.darkleaf/di 3.2.1

*next-id* clj

(*next-id*)

add-side-dependency clj

(add-side-dependency dep-key)

A registry middleware for adding side dependencies. Use it for migrations or other side effects.

(defn flyway [{url "DATABASE_URL"}]
  (.. (Flyway/configure)
      ...))

(di/start ::root (di/add-side-dependency `flyway))

combine-dependencies clj

(combine-dependencies)

(combine-dependencies a b)

Combines dependencies. Use it with reduce. Dependencies are a hash map of a key and a dependency type.

derive clj

(derive key f & args)

Applies f to an object built from key.

(def port (-> (di/derive "PORT" (fnil parse-long "8080"))))

See ref, template.

env-parsing clj

(env-parsing & {:as cmap})

A registry middleware for parsing environment variables. You can define a dependency of env as a string key like "PORT", and its value will be a string. With this middleware, you can define it as a qualified keyword like :env.long/PORT, and its value will be a number. cmap is a map of prefixes and parsers.

(defn root [{port :env.long/PORT}]
  ...)

(di/start `root (di/env-parsing :env.long parse-long
                                :env.edn  edn/read-string
                                :env.json json/read-value))

inspect clj

(inspect key & middlewares)

Collects and returns a vector of keys along with their dependencies. Useful for inspecting enabled components and services. Evaluates all registries with middlewares applied.

Expects the same arguments as start and returns a vector of keys with dependencies e.g.:

[{:key `root :dependencies {`foo :required `bar :optional}}
 {:key `foo}
 {:key `bar}]

log clj

(log &
     {:keys [after-build! after-demolish!]
      :or {after-build! (fn no-op [_]) after-demolish! (fn no-op [_])}})

A logging middleware. Calls :after-build! and :after-demolish! during di/start. Must be the last one in the middleware chain. Both callbacks are expected to accept the following arg {:keys [key object]}.

ns-publics clj

(ns-publics)

A registry middleware that interprets a whole namespace as a component. A component will be a map of var names to corresponding components.

The key of a component is a keyword with the namespace :ns-publics and a name containing the name of a target ns. For example :ns-publics/io.gihub.my.ns.

This enables access to all public components, which is useful for testing.

See the test darkleaf.di.tutorial.x-ns-publics-test.

(di/start :ns-publics/io.gihub.my.ns (di/ns-publics))

opt-ref clj

(opt-ref key)

Returns a factory referencing to a possible undefined key. Produces nil in that case.

See template, ref, derive.

ref clj

(ref key)

Returns a factory referencing to a key.

(def port (di/ref "PORT"))
(defn server [{port `port}] ...)

(def routes (di/template [["/posts" (di/ref `handler)]]))

(di/start `root {::my-abstraction (di/ref `my-implementation)})

See template, opt-ref, derive, p/build.

start clj

(start key & middlewares)

Starts a system of dependent objects.

key is a name of the system root. Use symbols for var names, keywords for abstract dependencies, and strings for environments variables.

key is looked up in a registry. By default registry uses Clojure namespaces and system env to resolve symbols and strings, respectively.

You can extend it with registry middlewares. Each middleware can be one of the following form:

• a function registry -> key -> Factory
• a map of key and p/Factory instance
• nil, as no-op middleware
• a sequence of the previous forms

Middlewares also allows you to instrument built objects. It's useful for logging, schema validation, AOP, etc. See update-key.

(di/start `root
          {:my-abstraction implemntation
           `some-key replacement
           "LOG_LEVEL" "info"}
          [dev-middlwares test-middlewares]
          (if dev-routes?
            (di/update-key `route-data conj `dev-route-data)
          (di/instrument `log))

Returns a container contains started root of the system. The container implements AutoCloseable, IDeref, IFn, Indexed and ILookup.

Use with-open in tests to stop the system reliably.

You can pass a vector as the key argument to start many keys:

(with-open [root (di/start [`handler `helper])]
  (let [[handler helper] root]
     ...))

See the tests for use cases. See update-key.

stop clj

(stop root)

Stops the root of a system

template clj

(template form)

Returns a factory for templating a data-structure. Replaces ref or opt-ref instances with built objects.

(def routes (di/template [["/posts" (di/ref `handler)]]))

See ref and opt-ref.

update-key clj

(update-key target f & args)

A registry middleware for updating built objects.

target is a key to update. f and args are intances of p/Factory. For example, a factory can be a regular object or (di/ref key).

(def routes [])
(def subsystem-routes (di/template [["/posts" (di/ref `handler)]]))

(di/start ::root (di/update-key `routes conj (di/ref `subsystem-routes)))

See start, derive.

with-open clj macro

(with-open bindings & body)

A c/with-open variant that supports destructuring in bindings.

bindings => [name init ...] Evaluates body in a try expression with names bound to the values of the inits, and a finally clause that calls (.close name) on each name in reverse order.