Guardrails is intended to make it possible (and easy) to use specs as a loose but informative (even advisory) type system during development so you can better see where you are making mistakes as you make them, without affecting production build size or performance.

Guardrails can now have a much smaller impact on your dev-time performance!

I realized that most of the time in dev mode you’re just running bits of code here and there in fits and starts. Most people rarely run super high numbers of iterations without some kind of pause. Even then: if you’re running such a computation there is still a high probability that you’ll see problems even if some of the checks are silently dropped.

As a result, guardrails now has an asynchronous checking mode (which mainly benefits Clojure)!

When this mode is enabled it pushes spec checking into a core.async channel with a dropping buffer (size 10,000). The overhead for the put is just a few microseconds. This allows an alternate thread to run the checks, and as long as you don’t have large sustained computations this can give you nearly full-production performance of your code, while an alternate core in your computer handles the checks.

Benefits:

• Much faster dev performance (Clojure only. The option works in CLJS, but there’s not a second thread so there is no benefit).

• High performance algorithms can use guardrails with a tolerable cost.

Costs:

• Checking results are queued. If a lot of slow checks get in the queue you might have to wait some time before you see the problems. This could cause confusion (you might be running your next expression in the REPL and see an error from the prior one).

• Not all checks will run in a CPU-intensive task that queues checks rapidly.

• Async mode is incompatible with the :throw? true option.

To enable the async mode, just add :async? true in your guardrails.edn file.

1. Add this library to your dependencies

2. Create a guardrails.edn with {} in it in your project root.

3. When you run a REPL or CLJS compiler, include the JVM option -Dguardrails.enabled.

   • Optionally: If you’re using CLJS, set your compiler options to include {:external-config {:guardrails {}}}

And code as follows:

then when the function is misused you’ll at least get a log error:

You can control if spec failures are advisory or fatal by editing guardrails.edn and setting the :throw? option. See Configuration for more details.

I use shadow-cljs as the build tool for all of my projects, and highly recommend it. Version 0.0.11 of Guardrails checks the compiler optimizations and refuses to output guardrails checks except in development mode (no optimizations). This prevents you from accidentally releasing a CLJS project with big runtime performance penalties due to spec checking at every function call.

The recommended approach for using guardrails in your project is to make a separate :dev and :release section of your shadow-cljs config, like so:

Doing so will prevent you from accidentally generating a release build with guardrails enabled in case you had a shadow-cljs server running in dev mode (which would cache that guardrails was enabled) and built a release target:

In this scenario Guardrails will detect that you have accidentally enabled it on a production build and will throw an exception. The only way to get guardrails to build into a CLJS release build is to explicitly set the JVM property "guardrails.enabled" to "production" (NOTE: any truthy value will enable it in CLJ).

You can set JVM options in shadow-cljs using the :jvm-opts key:

but this is highly discouraged.

Dead Code Elimination

Clojure spec’s instrument (and Orchestra’s outstrument) have a number of disadvantages when trying to use them for this purpose. Specifically, they are side-effecting after-calls that do not play particularly well with hot code reload, and always throw when there is a failed spec. Furthermore, management of the accidental inclusion of specs in your cljs builds (which increase build size) is a constant pain when writing separate specs for functions (the specs end up in a whole other file, inclusion needs to be via a development ns, and things easily get out of date).

This library is a middle ground between the features of raw Clojure spec and George Lipov’s Ghostwheel. Much of the source code in this library is directly from Ghostwheel.

This library’s goals are:

• The ability to use a simple DSL to declare the spec with a function (taken from Ghostwheel). See that library’s docs for syntax of >defn, >defn, etc.

• The ability to support dead-code elimination in cljs.

• No reliance on generative testing facilities/checkers. No orchestra/instrument stuff.

• Good output when a function receives or emits an incorrect value.

• The ability to control if a spec failure causes a throw (instrument always throws), because a lot of the time during development your spec is just wrong, and crashing your program is very inconvenient. You just want a log message to make you aware.

without the extra overhead of Ghostwheel’s support for:

• Automatic generative testing stuff.

• Tracing.

• Side-effect detection/warning.

[arg-specs* (| arg-preds+)? => ret-spec (| fn-preds+)? (<- generator-fn)?]

| = :st – such that
=> = :ret – return value, same as in fspec

The number of arg-specs must match the number of function arguments, including a possible variadic argument – Guardrails will shout at you if it doesn’t.

Single/Multiple Arities

(>defn myf
  ([x]
   [int? => number?]
   ...)
  ([x y]
   [int? int? => int?]
   ...))

Variadic Argument Lists

(>fdef clojure.core/max
  [x & more]
  [number? (s/* number?) => number?])

Such That

(>defn f
  [i]
  [int? | #(< 0 i 10) => int? | #(pos-int? %)]
  ...)

Nilable

(>fdef clojure.core/empty?
  [coll]
  [(? seqable?) => boolean?])

Nested Specs

(>fdef clojure.core/map-indexed
  ([f]
   [[nat-int? any? => any?] => fn?])
  ([f coll]
   [[nat-int? any? => any?] (? seqable?) => seq?]))

(>fdef clojure.core/set-validator!
  [a f]
  [atom? [? [any? => any?]] => any?])

The JVM option -Dguardrails.enabled=true should be used to turn on guardrails. When not defined >defn will emit exactly what defn would.

You may also enable it in cljs in your shadow-cljs config (see Configuration…​adding even an empty config map will enable it).

The default config goes in top of project as guardrails.edn:

You can override the config file name using JVM option -Dguardrails.config=filename. In your shadow-cljs config file you can override settings via the [:compiler-options :external-config :guardrails] config path of a build:

The code and documentation taken from Ghostwheel is by George Lipov and follows the ownership/copyright of that library. The modifications in this library are copyrighted by Fulcrologic, LLC.

This library follows Ghostwheel’s original license: Eclipse public license version 2.0.