ClojureScript Unraveled (3rd edition)

In ClojureScript, numbers include both integers and floating points. Keeping in mind that ClojureScript is a guest language that compiles to JavaScript, integers are actually JavaScript’s native floating points under the hood.

As in any other language, numbers in ClojureScript are represented in the following ways:

Keywords in ClojureScript are objects that always evaluate to themselves. They are usually used in map data structures to efficiently represent the keys.

As you can see, the keywords are all prefixed with :, but this character is only part of the literal syntax and is not part of the name of the object.

You can also create a keyword by calling the keyword function. Don’t worry if you don’t understand or are unclear about anything in the following example; functions are discussed in a later section.

In the end, keywords are a special case of Symbols which will be explained later.

Symbols in ClojureScript are very, very similar to keywords (which you now know about). But instead of evaluating to themselves, symbols are evaluated to something that they refer to, which can be functions, variables, etc.

Symbols start with a non numeric character and can contain alphanumeric characters as well as *, +, !, -, _, ', and ? such as :

The symbols themselves are not usually used as data but are used by the language to resolve function calls. In other words, let’s use this example:

In this case, the println symbol is telling the compiler to look in its resolution table to see if it has a bound implementation of a function that prints data to standard output.

And by wrapping the symbol in parentheses, you are telling the compiler that what you want is to execute that function. All elements other than the println symbol, which is in the first place, are considered parameters.

There is almost nothing new we can explain about strings that you don’t already know. In ClojureScript, they work the same as in any other language. One point of interest, however, is that they are immutable.

In this case they are the same as in JavaScript:

One peculiar aspect of strings in ClojureScript is due to the language’s Lisp syntax: single and multiline strings have the same syntax:

ClojureScript also lets you write single characters using Clojure’s character literal syntax.

Since the host language doesn’t contain character literals, ClojureScript characters are transformed behind the scenes into single character JavaScript strings.

The same for booleans:

The really interesting part of the booleans is the concepts of logical booleans. Is a concept in which we assign a boolean meaning to an expression (if it is falsy or truthy even if it is not of boolean type).

This is the aspect where each language has its own semantics (mostly wrongly in my opinion). The majority of languages consider empty collections, the integer 0, and other things like this to be false. In ClojureScript, unlike in other languages, only two values are considered as logical false: nil and false. Everything else is treated as logical true.

Another big step in explaining a language is to explain its collections and collection abstractions. ClojureScript is not an exception to this rule.

ClojureScript comes with many types of collections. The main difference between ClojureScript collections and collections in other languages is that they are persistent and immutable.

Before moving on to these (possibly) unknown concepts, we’ll present a high-level overview of existing collection types in ClojureScript.

It’s time to make things happen. ClojureScript has what are known as first class functions. They behave like any other type; you can pass them as parameters and you can return them as values, always respecting the lexical scope. ClojureScript also has some features of dynamic scoping, but this will be discussed in another section.

If you want to know more about scopes, this Wikipedia article is very extensive and explains different types of scoping.

As ClojureScript is a Lisp dialect, it uses the prefix notation for calling a function:

In the example above, inc is a function and is part of the ClojureScript runtime (standard library), and 1 is the first argument for the inc function.

The + symbol represents an add function. It allows multiple parameters, whereas in ALGOL-type languages, + is an operator and only allows two parameters.

The prefix notation has huge advantages, some of them not always obvious. ClojureScript does not make a distinction between a function and an operator; everything is a function. The immediate advantage is that the prefix notation allows an arbitrary number of arguments per "operator". It also completely eliminates the problem of operator precedence.

You can define an unnamed (anonymous) function with the fn special form. This is one type of function definition; in the following example, the function takes two parameters and returns their average.

You can define a function and call it at the same time (in a single expression):

Let’s start creating named functions. But what does a named function really mean? It is very simple; in ClojureScript, functions are first-class and behave like any other value, so naming a function is done by simply binding the function to a symbol:

ClojureScript also offers the defn macro as a little syntactic sugar for making function definition more idiomatic:

The string that comes between the function name and the parameter vector is called a docstring (documentation string); programs that automatically create web documentation from your source files will use these docstrings.

ClojureScript also comes with the ability to define functions with an arbitrary number of arguments. (The term arity means the number of arguments that a function takes.) The syntax is almost the same as for defining an ordinary function, with the difference that it has more than one body.

Let’s see an example, which will explain it better:

This line: ([x] (myinc x 1)) says that if there is only one argument, call the function myinc with that argument and the number 1 as the second argument. The other function body ([x increment] (+ x increment)) says that if there are two arguments, return the result of adding them.

Here are some examples using the previously defined multi-arity function. Observe that if you call a function with the wrong number of arguments, the compiler will emit an error message.

Another way to accept multiple parameters is defining variadic functions. Variadic functions are functions that accept an arbitrary number of arguments:

The way to denote a variadic function is using the & symbol prefix on its arguments vector.

The variadic function can also be combined with multiple arities:

You may wonder why I really need this syntax and define all that arities. Well, sometimes it is for documentation, since it prefers to name the first required parameters and leave the rest in a sequence. It is also a performance issue, since calling an arity with fixed variables will always be faster than calling a variadic function.

In the function parameters you can apply destructuring, which is explained in detail later.

Parameters by name in ClojureScript is nothing more than a special case of destructuring. See the destructuring section to better understand all the concepts.

There are times when we want to pass optional parameters to a function, something like options and it is better to give those options a name to be concise:

When you call this function, you just can omit the options, and the default will be used:

Then, provide a different prefix using named parameters:

The good part is that the name parameters do not impose a fixed calling convention. Nothing really prevents you from calling that function with a map as a second parameter with all the options you want to pass.

ClojureScript provides a shorter syntax for defining anonymous functions using the #() reader macro (usually leads to one-liners). Reader macros are "special" expressions that will be transformed to the appropriate language form at compile time; in this case, to some expression that uses the fn special form.

The preceding definition is shorthand for:

The %1, %2…​ %N are simple markers for parameter positions that are implicitly declared when the reader macro will be interpreted and converted to a fn expression.

If a function only accepts one argument, you can omit the number after the % symbol, e.g., a function that squares a number: #(* %1 %1)) can be written #(* % %)).

Additionally, this syntax also supports the variadic form with the %& symbol:

This way of defining functions is generally useful for defining single line functions.

Let’s start with a basic one: if. In ClojureScript, the if is an expression and not a statement, and it has three parameters: the first one is the condition expression, the second one is an expression that will be evaluated if the condition expression evaluates to logical true, and the third expression will be evaluated otherwise. The else part is optional.

The block expression do can be used to have multiple expressions in an if branch. do is explained in the next section.

Sometimes, the if expression can be slightly limiting because it does not have the "else if" part to add more than one condition. The cond macro comes to the rescue.

With the cond expression, you can define multiple conditions:

The :else keyword has no special meaning in cond. It just a truthy value and in reallity can be any keyword os anything that evaluates to a logical true.

Also, cond has another form, called condp, that works very similarly to the simple cond but looks cleaner when the condition (also called a predicate) is the same for all conditions:

The line condp = (keyword code) means that, in each of the following lines, ClojureScript will apply the = function to the result of evaluating (keyword code).

The case branching expression has a similar use as our previous example with condp. The main differences are that case always uses the = predicate/function and its branching values are evaluated at compile time. This results in a more performant form than cond or condp but has the disadvantage that the condition value must be static.

Here is the previous example rewritten to use case:

In JavaScript, braces { and } delimit a block of code that “belongs together”. Blocks in ClojureScript are created using the do expression and are usually used for side effects, like printing something to the console or writing a log in a logger.

A side effect is something that is not necessary for the return value.

The do expression accepts as its parameter an arbitrary number of other expressions, but it returns the return value only from the last one:

ClojureScript does not have the concept of variables as in ALGOL-like languages, but it does have locals. Locals, as per usual, are immutable, and if you try to mutate them, the compiler will throw an error.

Locals are defined with the let expression. The expression starts with a vector as the first parameter followed by an arbitrary number of expressions. The first parameter (the vector) should contain an arbitrary number of pairs that give a binding form (usually a symbol) followed by an expression whose value will be bound to this new local for the remainder of the let expression.

In the preceding example, the symbol x is bound to the value of executing the (inc 1) expression, which comes out to 2, and the symbol y is bound to the sum of x and 1, which comes out to 3. Given those bindings, the expressions (println "Simple message from the body of a let") and (* x y) are evaluated.

The body of the let expression has an implicit do, so you can put there multiple expressions, where the last one will be used as return value.

The functional approach of ClojureScript means that it does not have standard, well-known, statement-based loops such as for in JavaScript. The loops in ClojureScript are handled using recursion. Recursion sometimes requires additional thinking about how to model your problem in a slightly different way than imperative languages.

Many of the common patterns for which for is used in other languages are achieved through higher-order functions - functions that accept other functions as parameters.

We mentioned before that ClojureScript collections are persistent and immutable, but we didn’t explain what that meant.

An immutable data structure, as its name suggests, is a data structure that cannot be changed. In-place updates are not allowed in immutable data structures.

Let’s illustrate that with an example: appending values to a vector using the conj (conjoin) operation.

As you can see, we derived a new version of the xs vector appending an element to it and got a new vector ys with the element added. However, the xs vector remained unchanged because it is immutable.

A persistent data structure is a data structure that returns a new version of itself when transforming it, leaving the original unmodified. ClojureScript makes this memory and time efficient using an implementation technique called structural sharing, where most of the data shared between two versions of a value is not duplicated and transformations of a value are implemented by copying the minimal amount of data required.

If you want to see an example of how structural sharing works, read on. If you’re not interested in more details you can skip over to the next section.

For illustrating the structural sharing of ClojureScript data structures, let’s compare whether some parts of the old and new versions of a data structure are actually the same object with the identical? predicate. We’ll use the list data type for this purpose:

As you can see in the example, we used cons (construct) to prepend a value to the xs list and we got a new list ys with the element added. The rest of the ys list (all the values but the first) are the same object in memory as the xs list, thus xs and ys share structure.

One of the central ClojureScript abstractions is the sequence which can be thought of as a list and can be derived from any of the collection types. It is persistent and immutable like all collection types, and many of the core ClojureScript functions return sequences.

The types that can be used to generate a sequence are called "seqables"; we can call seq on them and get a sequence back. Sequences support two basic operations: first and rest. They both call seq on the argument we provide them:

Calling seq on a seqable can yield different results if the seqable is empty or not. It will return nil when empty and a sequence otherwise:

next is a similar sequence operation to rest, but it differs from the latter in that it yields a nil value when called with a sequence with one or zero elements. Note that, when given one of the aforementioned sequences, the empty sequence returned by rest will evaluate as a boolean true whereas the nil value returned by next will evaluate as false (see the section on booleans and truthiness).

Now that we’re acquainted with ClojureScript’s sequence abstraction and some of the generic sequence manipulating functions, it’s time to dive into the concrete collection types and the operations they support.

This is called thread first because it threads the first argument throught the different expressions as first arguments.

Using a more concrete example, this is how the code looks without using threading macros:

We can rewrite that code to use the -> threading macro:

This threading macro is especially useful for transforming data structures, because ClojureScript (and Clojure) functions for data structures transformations consistently uses the first argument to receive the data structure.

The main difference between the thread-last and thread-first macros is that instead of threading the first argument given as the first argument on the following expresions, it threads it as the last argument.

Let’s look at an example:

The same code written using ->> threading macro:

This threading macro is especially useful for transforming sequences or collections of data because ClojureScript functions that work with sequences and collections consistently use the last argument position to receive them.

Finally, there are cases where neither -> nor ->> are applicable. In these cases, you’ll need to use as->, the more flexible alternative, that allows you to thread into any argument position, not just the first or last.

It expects two fixed arguments and an arbitrary number of expressions. As with ->, the first argument is a value to be threaded through the following forms. The second argument is the name of a binding. In each of the subsequent forms, the bound name can be used for the prior expression’s result.

Let’s see an example:

Two of the more specialized threading macros that ClojureScript comes with. They work in the same way as their analagous -> and ->> macros with the additional support for short-circuiting the expression if one of the expresions evaluates to nil.

Let’s see another example:

This is an easy way avoid null pointer exceptions.

The cond-> and cond->> macros are analogous to -> and ->> that offers the ability to conditionally skip some steps from the pipeline. Let see an example:

The value threading only happens when the corresponding condition evaluates to logical true.

The namespace is ClojureScript’s fundamental unit of code modularity. Namespaces are analogous to Java packages or Ruby and Python modules and can be defined with the ns macro. If you have ever looked at a little bit of ClojureScript source, you may have noticed something like this at the beginning of the file:

Namespaces are dynamic, meaning you can create one at any time. However, the convention is to have one namespace per file. Naturally, a namespace definition is usually at the beginning of the file, followed by an optional docstring.

Previously we have explained vars and symbols. Every var that you define will be associated with its namespace. If you do not define a concrete namespace, then the default one called "cljs.user" will be used:

Defining a namespace and the vars in it is really easy, but it’s not very useful if we can’t use symbols from other namespaces. For this purpose, the ns macro offers a simple way to load other namespaces.

Observe the following:

As you can observe, we are using fully qualified names (namespace + var name) to access vars and functions from different namespaces.

While this will let you access other namespaces, it’s also repetitive and overly verbose. It will be especially uncomfortable if the name of a namespace is very long. To solve that, you can use the :as directive to create an additional (usually shorter) alias to the namespace. This is how it can be done:

One peculiarity of the namespace aliases, is that they can be used to obtain namespaced keywords from a specific namespace:

In the same way, you can namespace all the keys on the moment of creation of a map:

Additionally, ClojureScript offers a simple way to refer to specific vars or functions from a concrete namespace using the :refer directive, followed by a sequence of symbols that will refer to vars in the namespace. Effectively, it’s as if those vars and functions are now part of your namespace, and you do not need to qualify them at all.

And finally, you should know that everything located in the cljs.core namespace is automatically loaded and you should not require it explicitly. Sometimes you may want to declare vars that will clash with some others defined in the cljs.core namespace. To do this, the ns macro offers another directive that allows you to exclude specific symbols and prevent them from being automatically loaded.

Observe the following:

The ns macro also has other directives for loading host classes (with :import) and macros (with :refer-macros), but these are explained in other sections.

When you have a namespace like myapp.core, the code must be in a file named core.cljs inside the myapp directory. So, the preceding examples with namespaces myapp.core and myapp.main would be found in project with a file structure like this:

The ClojureScript primitive for defining "interfaces" is called a protocol. A protocol consists of a name and set of functions. All the functions have at least one argument corresponding to the this in JavaScript or self in Python.

Protocols provide a type-based polymorphism, and the dispatch is always done by the first argument (equivalent to JavaScript’s this, as previously mentioned).

A protocol looks like this:

From the user perspective, protocol functions are simply plain functions defined in the namespace where the protocol is defined. This enables an easy and simple approach for avoiding conflicts between different protocols implemented for the same type that have conflicting function names.

Here’s an example. Let’s create a protocol called IInvertible for data that can be "inverted". It will have a single method named invert.

We have previously talked about protocols which solve a very common use case of polymorphism: dispatch by type. But in some circumstances, the protocol approach can be limiting. And here, multimethods come to the rescue.

These multimethods are not limited to type dispatch only; instead, they also offer dispatch by types of multiple arguments and by value. They also allow ad-hoc hierarchies to be defined. Also, like protocols, multimethods are an "Open System", so you or any third parties can extend a multimethod for new types.

The basic constructions of multimethods are the defmulti and defmethod forms. The defmulti form is used to create the multimethod with an initial dispatch function. This is a model of what it looks like:

The anonymous function defined within the defmulti form is a dispatch function. It will be called in every call to the say-hello function and should return some kind of marker object that will be used for dispatch. In our example, it returns the contents of the :locale key of the first argument.

And finally, you should add implementations. That is done with the defmethod form:

So, if you execute that function over a hash map containing the :locale and optionally the :name key, the multimethod will first call the dispatch function to determine the dispatch value, then it will search for an implementation for that value. If an implementation is found, the dispatcher will execute it. Otherwise, the dispatch will search for a default implementation (if one is specified) and execute it.

If the default implementation is not specified, an exception will be raised notifying you that some value does not have an implementation for that multimethod.

Hierarchies are ClojureScript’s way to let you build whatever relations that your domain may require. Hierarchies are defined in term of relations between named objects, such as symbols, keywords, or types.

Hierarchies can be defined globally or locally, depending on your needs. Like multimethods, hierarchies are not limited to a single namespace. You can extend a hierarchy from any namespace, not only from the one in which it is defined.

The global namespace is more limited, for good reasons. Keywords or symbols that are not namespaced can not be used in the global hierarchy. That behavior helps prevent unexpected situations when two or more third party libraries use the same symbol for different semantics.

The most low-level construction in ClojureScript for creating your own types is the deftype macro. As a demonstration, we will define a type called User:

Once the type has been defined, we can create an instance of our User. In the following example, the . after User indicates that we are calling a constructor.

Its fields can be accessed using the prefix dot notation:

Types defined with deftype (and defrecord, which we will see later) create a host-backed class-like object associated with the current namespace. For convenience, ClojureScript also defines a constructor function called →User that can be imported using the :require directive.

We personally do not like this type of function, and we prefer to define our own constructors with more idiomatic names:

We use this in our code instead of →User.

The record is a slightly higher-level abstraction for defining types in ClojureScript and should be the preferred way to do it.

As we know, ClojureScript tends to use plain data types such as maps, but in most cases we need a named type to represent the entities of our application. Here come the records.

A record is a data type that implements the map protocol and therefore can be used like any other map. And since records are also proper types, they support type-based polymorphism through protocols.

In summary: with records, we have the best of both worlds, maps that can play in different abstractions.

Let’s start defining the User type but using records:

It looks really similar to the deftype syntax; in fact, it uses deftype behind the scenes as a low-level primitive for defining types.

Now, look at the difference with raw types for access to its fields:

As we mentioned previously, records are maps and act like them:

And like maps, they support extra fields that are not initially defined:

As we can see, the assoc function works as expected and returns a new instance of the same type but with new key-value pair. But take care with dissoc! Its behavior with records is slightly different than with maps; it will return a new record if the field being dissociated is an optional field, but it will return a plain map if you dissociate a mandatory field.

Another difference with maps is that records do not act like functions:

For convenience, the defrecord macro, like deftype, exposes a →User function, as well as an additional map→User constructor function. We have the same opinion about that constructor as with deftype defined ones: we recommend defining your own instead of using the other ones. But as they exist, let’s see how they can be used:

Both type definition primitives that we have seen so far allow inline implementations for protocols (explained in a previous section). Let’s define one for example purposes:

Now, you can define a type with inline implementation for an abstraction, in our case the IUser:

The reify macro is an ad hoc constructor you can use to create objects without pre-defining a type. Protocol implementations are supplied the same as deftype and defrecord, but in contrast, reify does not have accessible fields.

This is how we can emulate an instance of the user type that plays well with the IUser abstraction:

specify! is an advanced alternative to reify, allowing you to add protocol implementations to an existing JavaScript object. This can be useful if you want to graft protocols onto a JavaScript library’s components.

specify is an immutable version of specify! that can be used on immutable, copyable values implementing ICloneable (e.g. ClojureScript collections).

ClojureScript, unlike what you might expect, tries to take advantage of every type that the platform provides. This is a (perhaps incomplete) list of things that ClojureScript inherits and reuses from the underlying platform:

On top of it, ClojureScript builds its own abstractions and types that do not exist in the platform, such as Vectors, Maps, Sets, and others that are explained in preceding sections of this chapter.

ClojureScript comes with a little set of special forms that allows it to interact with platform types such as calling object methods, creating new instances, and accessing object properties.

Vars can be redefined at will inside a namespace but there is no way to know when they change. The inability to redefine vars from other namespaces is a bit limiting; also, if we are modifying state, we’re probably interested in knowing when it occurs.

ClojureScript gives us the Atom type, which is an object containing a value that can be altered at will. Besides altering its value, it also supports observation through watcher functions that can be attached and detached from it and validation for ensuring that the value contained in the atom is always valid.

If we were to model an identity corresponding to a person called Ciri, we could wrap an immutable value containing Ciri’s data in an atom. Note that we can get the atom’s value with the deref function or using its shorthand @ notation:

We can use the swap! function on an atom to alter its value with a function. Since Ciri’s birthday is today, let’s increment her age count:

The reset! functions replaces the value contained in the atom with a new one:

Volatiles, like atoms, are objects containing a value that can be altered. However, they don’t provide the observation and validation capabilities that atoms provide. This makes them slightly more performant and a more suitable mutable container to use inside stateful functions that don’t need observation nor validation.

Their API closely resembles that of atoms. They can be dereferenced to grab the value they contain and support swapping and resetting with vswap! and vreset! respectively:

Note that another difference with atoms is that the constructor of volatiles uses a bang at the end. You create volatiles with volatile! and atoms with atom.

What is an execution environment? An execution environment is an engine where JavaScript can be executed. For example, the most popular execution environment is a browser (Chrome, Firefox, …​) followed by the second most popular - nodejs.

There are others, such as Rhino (JDK 6+), Nashorn (JDK 8+), QtQuick (QT),…​ but none of them have significant differences from the first two. So, ClojureScript at the moment may compile code to run in the browser or in nodejs-like environments out of the box.

This chapter supposes you have a properly installed nodejs (v20.10.0) and JVM (JDK21). Other versions probably work but all this is tested under specified versions.

It also will be nice to have the rlwrap tool, which can be installed this way on a debian like linux distributions:

So, lets create our directory stucture and the first package.json file:

Then, lets define our package.json content:

And execute the npm install for correctly install shadow-cljs dependency

Then, setup the basic shadow-cljs.edn confguration:

And finally, put the following content on the mynodeapp/main.cljs file:

Now it’s time to compile the project:

And when it finishes, execute the result using node binary:

The shadow-cljs guide is very extensive, and you can read more detailed documentation here: https://shadow-cljs.github.io/docs/UsersGuide.html#target-node

In this section we are going to create an application similar to the "hello world" example from the previous section to run in the browser environment. The minimal requirement for this application is just a browser that can execute JavaScript.

The process is almost the same, and the directory structure is very similar, with few additions.

Set setup the package.json file:

Execute the npm install for correctly install the shadow-cljs dependency.

Then, setup shadow-cljs configuration on shadow-cljs.edn file:

Write new content to the src/mywebapp/main.cljs file:

Once all this is ready, instead of just compiling it, we start a watch process:

The watch also starts a development http server at http://localhost:8888 for access our brand new web application. But we still need a last step: we need to create an index.html where we’re going to load our recently compiled js.

So, open the browser on http://localhost:8888 and open the devconsole with F12 key and see the Hello World printed on the console tab.

The shadow-cljs guide is very extensive, and you can read more detailed documentation here: https://shadow-cljs.github.io/docs/UsersGuide.html#target-browser

Although you can create a source file and compile it every time you want to try something out in ClojureScript, it’s easier to use the REPL. REPL stands for:

In other words, the REPL lets you try out ClojureScript concepts and get immediate feedback.

ClojureScript comes with support for executing the REPL in different execution environments, each of which has its own advantages and disadvantages. For example, you can run a REPL in nodejs but in that environment you don’t have any access to the DOM. Which REPL environment is best for you depends on your specific needs and requirements.

The node-repl and browser-repl work without any specific build configuration. That means they will only do whatever you tell them to do but nothing on their own.

But there is also an option to connect to a build specific repl, for which to work correctly you need 2 things:

Once you have both you can connect to the CLJS REPL via the command line or from the Clojure REPL.

In this example we will use the Cuerdas (a string manipulation library build especifically for Clojure(Script)) for improve the previous functionality of the mywebapp.

Let’s update our shadow-cljs.edn file with the dependency:

And the following modifications to the src/mywebapp/main.cljs file: