{ "componentChunkName": "component---src-templates-blog-post-tsx", "path": "/blog/2017-06-01-one-helpful-way-to-think-about-javascript-decorators/", "result": {"data":{"blogPost":{"title":"One Helpful Way to Think About JavaScript Decorators","slug":"/blog/2017-06-01-one-helpful-way-to-think-about-javascript-decorators/","authorNodes":[{"name":"Charles Lowell","slug":"/people/charles-lowell/"}],"markdown":{"html":"

Why Decorators?

\n

It is an important question; one many tutorials rush past in their hurry to talk about the what and how. Of course, after being exposed to enough doses of what and how, you can usually piece together why, but in my experience it saves time to just hear it up front. I'd like to share one of the ways I've come to think about decorators and how it's helped me think about when to use them.

\n

So like every good meta-discussion of JavaScript, let's start by\ntalking about Clojure. Don't sweat it if you don't know Clojure,\nthat's totally ok. The examples are very simple and only there to\nillustrate a bigger point.

\n

Anyway, back to Clojure...

\n

In Clojure, one way to associate a name with a value is to use the def form:

\n
(def message \"hello computer\")
\n

After that declaration, subsequent code can refer to the string \"hello computer\" just by using the symbol message instead.

\n

The ability to associate names and values is a pretty handy thing in programmming, and it turns out you can do something very similar in JavaScript too. You might write something like this:

\n
const message = \"hello computer\";
\n

Another thing that Clojure has support for is function values:\nfunctions that can be passed as either an argument to, or the return\nvalue from, another function. You can declare a function value that\nadds its operands together with the following syntax.

\n
(fn [x y] (+ x y))
\n

Not to be outdone though, JavaScript also has support for first class functions, and it's syntax is even a little more concise than Clojure's too! This is it here.

\n
(x, y) => { return x + y; }
\n

Both of these are examples of anonymous functions. Function values that can be passed around as one-offs to other functions. It's handy, but sometimes it's not enough.

\n

Often what we want is to associate a name with a function so that we\ncan call it again and again. In the same way we associated the name\nmessage with the string value \"hello computer\" so that we could\naccess it repeatedly just by referring to message, we can associate\na function value with a symbol so that we can reach for it over and\nover just by remembering its name. To do that, we use the two\nconstructs just introduced (def and fn):

\n
;; associate the symbol `add` with the function to add\n(def add (fn [x y] (+ x y)))\n\n;; and now we can call it by name.\n(add 1 1) ;;=> 2\n(add 4 3) ;;=> 7
\n

Just like before, a parallel construct exists in JavaScript. No suprises there.

\n
// associate the symbol `add` with the function to add\nconst add = (x, y) => { return x + y; };\n\n// and now we can call it by name.\nadd(1, 1) //=> 2\nadd(4, 3) //=> 7
\n

But of course, this pattern of associating a name with a function is so prevalent that both Clojure and JavaScript have a special syntax to both declare a function and associate it with a name in one fell swoop. In Clojure you use defn (literally the conjuction of def + fn)

\n
(defn add [x y] (+ x y))
\n

And you're probably already familiar with how it's done in JavaScript with a function declaration.

\n
function add(x, y) { return x + y; }
\n

There's a point to this. I promise.

\n

So I just explained named functions in both Clojure and JavaScript. Big\nwhoop.

\n

It's such a simple idea and an equally simple mechanism. And on the surface they seem equivalent in both languages, but there's one key difference between the way the named function syntax works in JavaScript and the way it works in Clojure. Both syntaxes declare a function value, and both associate that function value with a name so that it can be referred to later.

\n

The difference is that in JavaScript the syntax is implemented by the JavaScript parser and interpreter, whereas in Clojure the syntax is implemented in Clojure.

\n

A Macro Says What?

\n

That bears repeating. In JavaScript, the syntax is implemented by the\nJavaScript parser and interpreter. More than likely that means baked\nin with some C or C++ code somewhere. Beyond the implementation, it\nmeans that there needs to be a\nspecification for the syntax as part ECMA standard\nso that any of the multiple engines can be sure to get it right.

\n
\n \n
Figure 1: Put this in your C++ and smoke it\n
\n

Contrast this to Clojure in which the named function syntax is nothing but more Clojure code. It's easy to understand not only for programmers, but also for any alternative implementation of Clojure (such as clojurescript). It's a nifty trick that saves time, adds clarity and eliminates ambiguity. How does it work? The answer is macros.

\n

Macros are powerful, but they aren't fancy. A macro is just a function like any other function, and if you can work with functions, then you can work with macros.

\n

There are two things that make a macro function special though. The\nfirst is that the type of its arguments and the type it returns are\nnot general values but source code. That means it takes code in as\nits input, and returns code as it's output. Here's a couple of\nfamiliar functions along with their (pseudo) types for comparison. map takes an array as its input, and returns another array. sum takes an array as input, and returns a number. defn takes code input and returns more code.

\n
map :: Array -> Array\nsum :: Array -> Number\ndefn :: Code -> Code
\n

The second thing that makes a macro function special is that it doesn't run when the rest of your program does; it runs when your program is being compiled. When the compiler encounters a macro, it calls it, and then replaces the macro with the code that got returned.

\n
\n \n
Figure 2: The arguments to a macro function are unevaluated source code\n
\n

In fact, this is how the defn macro works. It literally replaces

\n
(defn add [x y] (+ xy))
\n

with

\n
(def add (fn [x y] (+ x y)))
\n
\n \n
Figure 3:\n The defn macro takes code as arguments and returns more code\n
\n

The point here is not to geek out too hard on Clojure macros, but to\nshow just how much more you can do with so much less when your\nlanguage has first class support for transforming code into other\ncode. Large swaths of what we think of as Clojure syntax is actually\ndefined with Clojure. The syntax it does have baked in works\nharder. There's no need to change the way the compiler works, and\ncertainly no slog through a potentially contentious\nspecification by committee.

\n

Wouldn't it be nice if JavaScript let us do something similar? Wouldn't it be nice if we could extend JavaScript syntax with just a few lines of JavaScript code instead of years spent shit-posting on the internet?

\n

Decorators to the rescue

\n

The answer is that with decorators we can... almost. To be clear, decorators are not lisp macros. They're less powerful and they operate in a much smaller niche. But even so, they're an exciting development because there is just enough overlap with macros to make them helpful in the same kinds of situations.

\n

That's because, like a macro, a decorator is also just a function. And also like a macro, it's a function that operates on code before the rest of your program sees it.

\n
@decorator :: Code -> Code
\n

Like a macro, we can use this to add the new syntax we always wanted to our JavaScript classes.

\n

For example, I've often wished that there were an immutable keyword in JavaScript that made it impossible to change member data of an instance once it was constructed. Wouldn't it be great if you write a class like this?

\n
immutable class Circle {\n  constructor(radius) {\n    this.radius = radius;\n  }\n\n  get area () { return Math.PI * this.radius * this.radius; }\n}\n\nlet circle = new Circle(5);\ncircle.area //=> 25π\n\n// can't do this!\ncircle.radius = 10 //=> Error!
\n

I think that would be awesome, and if you feel the way I do, then you've got two options:

\n

A. Begin your submission to the TC39 (you'd better get on it if you\nwant to hit your deadline in three weeks!)

\n

B. Do it now with decorators.

\n

Decorators can help us get the syntax we want today because they let\nyou transparently transform the code that you see into the code that\nyou want. In the case of our immutable keyword, the code is a\nclass. In other words, we want to take the class that we see\n(mutation allowed) and convert it into the class we want (no\nmutation allowed)

\n

The class we see has this constructor:

\n
class Circle {\n  constructor(radius) {\n    this.radius = radius;\n  }\n}
\n

But the class we want has this constructor:

\n
class Circle {\n  constructor(radius) {\n    this.radius = radius;\n    Object.freeze(this);\n  }\n}
\n

If we can write a function that takes the former and returns the latter, then we're in business. Luckily, this is pretty straightforward. In order to make an immutable version of any given class, we can extend it, and then make a call to Object.freeze after invoking the original constructor.

\n
// @immutable :: Class -> Class\nfunction immutable(Class) {\n  class ImmutableVersion extends Class {\n    constructor(...args) {\n      super(...args);\n      Object.freeze(this);\n    }\n  };\n  return ImmutableVersion;\n}
\n

We now have a function that returns an immutable version of any class, and so now we can just use it as a decorator; almost like we were creating our own syntax.

\n
@immutable class Circle {\n  constructor(radius) {\n    this.radius = radius;\n  }\n\n  get area () { return Math.PI * this.radius * this.radius; }\n}
\n

Our JavaScript interpreter will see this and transparently convert the Circle class that we see into a different one; one that prohibits any mutation of its member data after construction.

\n

Decorators aren't just for entire classes. They can be used to enhance individual members of as class as well and transform them transparently into something more powerful. For example, since the area of the circle is a computed property, it won't be enumerable by default.

\n
Object.keys(new Circle(5)) //=> ['radius']
\n

That doesn't seem quite right. Shouldn't area be in there too?

\n

What would be really nice if if JavaScript had a keyword to make any property enumerable. E.g.

\n
{\n  enumerable get area() { return Math.PI * this.radius * this.radius; }\n}
\n

It doesn't of course, but with decorators we can change that. We'll\njust write a member decorator: a decorator that operates on\nproperty descriptors\ninstead of classes. We can write an enumerable function to take the property descriptor we see (non-enumerable) and return the property descriptor we want (enumerable). This is accomplished simply enough by returning a new descriptor exactly like the old one, except with the enumerable key of the descriptor set to true.

\n
// @enumerable :: Property -> Property\n\nfunction enumerable(target, key, descriptor) {\n  return {...descriptor, enumerable: true};\n}
\n

With this in hand, we can mark the area property as enumerable, just as though the syntax had existed the whole time.

\n
@immutable class Circle {\n  constructor(radius) {\n    this.radius = radius;\n  }\n  @enumerable get area() { return Math.PI * this.radius * this.radius; }\n}
\n

Declared this way, circles will let you know that they have an area in addition to a radius:

\n
Object.keys(new Circle(5)) //=> ['radius', 'area']
\n

Easy!

\n

Decorators FTW

\n

And that's it! My goal with this brief tour of decorators isn't to\nshow you the ins and outs of how they work, but to share a helpful way\nto think about them and when they might be the right tool to reach\nfor. While decorators are not lisp macros, it's useful to think about\nthem as a spiritual grandchild in the sense that their biggest power\nis to transform the primary artifacts of your code before the rest of\nyour program sees them. Rather being locked into a given syntax, the\ninterpreter is open to extension, and you can negotiate with it for a\nnew set of semantics.

\n

In a way, by including decorators and allowing them to stand in for\nmany of the use-cases where a new syntax might otherwise be desirable,\nthe ECMAScript specification is firing itself from its primary\nresponsibility of evolving the core language. What previously might\nhave taken months or years, can now be done in a matter of minutes or\nhours; a huge roadblock gone that has historically stood in the way of progress.

\n

For individual developers, decorators let us work with a lighter touch; applying just a little bit of new syntax to make big transformations, but all the while preserving the core intent and readability of our code.

\n
\n

I’m Charles Lowell (@cowboyd on twitter), and I build UI for a\nliving at Frontside. If you enjoyed this, I’d love to hear\nfrom you. We're always hiring and\nlooking for exciting new work

","frontmatter":{"date":"June 01, 2017","description":"JavaScript decorators are coming, but what are the class of problems which they're useful for? In this brief tour of decorators, we'll try to answer that question by contrasting them with comparable technology from other languages.","tags":["javascript","clojure","macros","decorators"],"img":{"childImageSharp":{"fixed":{"src":"/static/5bdaef2c99b94bac1ebfbfce229c49b9/a6352/2017-06-01-one-helpful-way-to-think-about-javascript-decorators_russian-dolls.jpg"}}}}}}},"pageContext":{"id":"9bc500f9-d2ce-5648-946e-1ef27bdbac02"}}, "staticQueryHashes": ["1241260443"]}