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} m"
  [v] {})

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

Protocols

Programs written around concrete types is not idiomatic. ClojureScript itself is written in terms of a rich set of protocols. There 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 it's JSDoc annotation extended with @implement for that protocol.

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