Compile Time Type Checking

NOTE: This page documents on-going development on the ClojureScript master branch.

ClojureScript can easily leverage Google Closure for compile time type checking. This is done simply via ClojureScript docstrings which are compiled into JSDoc style comment blocks. Google Closure supports many useful kinds of type annotation. For example you can write a function that takes non-nullable Object.

(defn foo 
  "@param {!Object} x
  [x] x)

If Closure can infer that some invoke may pass null, this will result in a compile time type error.

Type checking can be enabled for :simple or :advanced optimization builds:

(require '[cljs.build.api :as b])

(b/build "src"
  {:main 'my.ns
   :output-to "app.js"
   :optimizations :simple
   :verbose true
   :closure-warnings
   {:check-types :error ;; << ADD THIS
    :undefined-names :off
    :externs-validation :off
    :missing-properties :off}})

(System/exit 0)

The other :closure-warnings options here are to disable noisier checks that are less relevant for ClojureScript projects.

Type Resolution

ClojureScript supports unqualified type names in @param and @return annotations. These will automatically be expanded based on the vars currently in scope.

(defn bar
  "@param {!IVector} v
   @return {!IMap}"
  [v] {})

Both IVector and IMap will be resolved to cljs.core where they are defined.

Protocols

Programs written around concrete types are not idiomatic. ClojureScript itself is written in terms of a rich set of protocols. Therefore it is important to support type checking on protocols rather than particular types.

Protocols all emit an @interface annotation. Any deftype or defrecord that implements some protocol will have its JSDoc annotation extended with @implements for that protocol.

(defn bar
  "@param {IVector} x"
  [x] x)

Future Enhancements

Pre & Post conditions

It would be interesting to generate @param and @return automatically. For example the following:

(defn foo [x y]
  {:pre  [(map? x) (or (number? y) (string? y))]
   :post [vector?]}
  ; ...
  )

Could be made equivalent to:

(defn foo
  "@param {!IMap} x
   @param {number|string} y
   @return {!IVector}"
  [x y]
  ; ...
  )

Nullability

The following is a common idiom:

(if-let [v (:foo m)]
  (non-nullable-fn v))

In master this would still generate a type error since Closure doesn't know that if-let prevents v from ever being null.

We could change if-let to emit a (goog.asserts/assert v) as the first statement of the successful branch. This would inform the type checker that v can never be null.