{"id":3381,"date":"2024-08-09T13:54:47","date_gmt":"2024-08-09T18:54:47","guid":{"rendered":"https:\/\/frontendmasters.com\/blog\/?p=3381"},"modified":"2024-08-09T13:54:48","modified_gmt":"2024-08-09T18:54:48","slug":"exploring-the-possibilities-of-native-javascript-decorators","status":"publish","type":"post","link":"https:\/\/frontendmasters.com\/blog\/exploring-the-possibilities-of-native-javascript-decorators\/","title":{"rendered":"Exploring the Possibilities of Native JavaScript Decorators"},"content":{"rendered":"\n

We’ve known it for a while now, but JavaScript is eventually getting native support for decorators. The proposal is in stage 3<\/a> \u2014 it\u2019s inevitable! I’m just coming around to explore the feature, and I’m kinda kicking myself for waiting so long, because I\u2019m finding it to be tremendously helpful. Let\u2019s spend some time exploring it.<\/p>\n\n\n\n

The Pattern vs The Feature<\/h2>\n\n\n\n

It’s probably worth clarifying what’s meant by a “decorator.” Most of the time, people are talking about one of two things:<\/p>\n\n\n\n

The decorator<\/strong> design pattern<\/strong><\/em><\/h3>\n\n\n\n

This is the higher-level concept<\/a> of augmenting or extending a function’s behavior by “decorating” it. Logging is a common example. You might want to know when<\/em> and with what<\/em> parameters it’s called, so you wrap it with another function:<\/p>\n\n\n

function<\/span> add<\/span>(a, b<\/span>) <\/span>{\n  return<\/span> a + b;\n}\n\nfunction<\/span> log<\/span>(func<\/span>) <\/span>{\n  return<\/span> function<\/span> (...args<\/span>) <\/span>{\n    console<\/span>.log(\n      `method: ${func.name}<\/span> | `<\/span>,\n      `arguments: ${[...args].join(\", \"<\/span>)}<\/span>`<\/span>\n    );\n    return<\/span> func.call(this<\/span>, ...args);\n  };\n}\n\nconst<\/span> addWithLogging = log(add);\n\naddWithLogging(1<\/span>, 2<\/span>);\n\/\/ adding 1 2<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
There’s no new language-specific feature here. One function simply accepts another as an argument and returns a new, souped-up version. The original function has been decorated<\/em>.<\/p>\n\n\n\n
Decorators as a<\/strong> feature of the language<\/strong><\/em><\/h3>\n\n\n\n
The decorator feature is a more tangible manifestation of the pattern. It’s possible you’ve seen an older, unofficial version of this before. We’ll keep using the logging example from above, but we’ll first need to refactor a bit because language-level decorators can only be used on class methods, fields, and on classes themselves.<\/p>\n\n\n
\/\/ The \"old\" decorator API:<\/span>\n<\/span><\/span>\n<\/span><\/span>function<\/span> log<\/span>(target, key, descriptor<\/span>) <\/span>{\n<\/span><\/span>  const<\/span> originalMethod = descriptor.value;\n<\/span><\/span>\n<\/span><\/span>  descriptor.value = function<\/span> (...args<\/span>) <\/span>{\n<\/span><\/span>    console<\/span>.log(\n<\/span><\/span>      `method: ${originalMethod.name}<\/span> | `<\/span>,\n<\/span><\/span>      `arguments: ${[...args].join(\", \"<\/span>)}<\/span>`<\/span>\n<\/span><\/span>    );\n<\/span><\/span>\n<\/span><\/span>    return<\/span> originalMethod.apply(this<\/span>, args);\n<\/span><\/span>  };\n<\/span><\/span>\n<\/span><\/span>  return<\/span> descriptor;\n<\/span><\/span>}\n<\/span><\/span>\n<\/span><\/span>class<\/span> Calculator<\/span> <\/span>{\n<\/span><\/span>  @log \/\/ <-- Decorator applied here.<\/span>\n<\/span><\/mark>  add(a, b) {\n<\/span><\/span>    return<\/span> a + b;\n<\/span><\/span>  }\n<\/span><\/span>}\n<\/span><\/span>\n<\/span><\/span>new<\/span> Calculator().add(1<\/span>, 2<\/span>); \/\/ method: add | arguments: 1, 2<\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
But because it’s non-standard, it could become problematic. For example, there’s some nuance<\/a> between how it\u2019s implemented by Babel and TypeScript, which probably caused frustration for engineers moving between applications with different build tooling. Standardization would serve them well.<\/p>\n\n\n\n
The Slightly Different Official API<\/h2>\n\n\n\n
Fortunately, both TypeScript (as of v5<\/a>) and Babel (via plugin<\/a>) now support the TC39 version of the API, which is even simpler:<\/p>\n\n\n
function<\/span> log<\/span>(func, context<\/span>) <\/span>{\n  return<\/span> function<\/span> (...args<\/span>) <\/span>{\n    console<\/span>.log(\n      `method: ${func.name}<\/span> | `<\/span>,\n      `arguments: ${[...args].join(\", \"<\/span>)}<\/span>`<\/span>\n    );\n\n    func.call(this<\/span>, ...args);\n  };\n}\n\nclass<\/span> Calculator<\/span> <\/span>{\n  @log\n  add(a, b) {\n    return<\/span> a + b;\n  }\n}\n\nnew<\/span> Calculator().add(1<\/span>, 2<\/span>); \/\/ method: add | arguments: 1, 2<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
As you can see, there\u2019s much less of a learning curve, and it’s fully interchangeable with many functions that have been used as decorators until now. The only difference is that it\u2019s implemented with new syntax.<\/p>\n\n\n\n
Exploring the Use Cases<\/h2>\n\n\n\n
There\u2019s no shortage of scenarios in which this feature will be handy, but let\u2019s try out a couple that come to mind.<\/p>\n\n\n\n
Debouncing & Throttling<\/strong><\/h3>\n\n\n\n
Limiting the number of times an action occurs in a given amount of time is an age-old need on the web. Typically, that\u2019s meant reaching for a Lodash utility or rolling an implementation yourself.<\/p>\n\n\n\n
Think of a live search box. To prevent user experience issues and network load, you want to debounce<\/em> those searches, only firing a request when the user has stopped typing for a period of time:<\/p>\n\n\n
function<\/span> debounce<\/span>(func<\/span>) <\/span>{\n  let<\/span> timeout = null<\/span>;\n\n  return<\/span> function<\/span> (...args<\/span>) <\/span>{\n    clearTimeout(timeout);\n\n    timeout = setTimeout(()<\/span> =><\/span> {\n      func.apply(this<\/span>, args);\n    }, 500<\/span>);\n  };\n}\n\nconst<\/span> debouncedSearch = debounce(search);\n\ndocument<\/span>.addEventListener('keyup'<\/span>, function<\/span>(e<\/span>) <\/span>{\n  \/\/ Will only fire after typing has stopped for 500ms.<\/span>\n  debouncedSearch(e.target.value);\n});  <\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
But decorators can only be used on a class or its members, so let’s flesh out a better example. You’ve got a ViewController<\/code> class with a method for handling keyup<\/code> events:<\/p>\n\n\n
class<\/span> ViewController<\/span> <\/span>{\n  async<\/span> handleSearch(query) {\n    const<\/span> results = await<\/span> search(query);\n\n    console<\/span>.log(`Update UI with:`<\/span>, results);\n  }\n}\n\nconst<\/span> controller = new<\/span> ViewController();\n\ninput.addEventListener('keyup'<\/span>, function<\/span> (e<\/span>) <\/span>{\n  controller.handleSearch(e.target.value);\n});<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Using the debounce()<\/code> method we wrote above, implementation would be clunky. Focusing in on the ViewController<\/code> class itself:<\/p>\n\n\n
class<\/span> ViewController<\/span> <\/span>{\n  handleSearch = debounce(async<\/span> function<\/span> (query<\/span>) <\/span>{\n    const<\/span> results = await<\/span> search(query);\n\n    console<\/span>.log(`Got results!`<\/span>, results);\n  });\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
You not only need to wrap your entire<\/em> method, but you also need to switch from defining a class method to an instance property set to the debounced version of that method. It\u2019s a little invasive.<\/p>\n\n\n\n
Updating to a Native Decorator<\/h3>\n\n\n\n
Turning that debounce()<\/code> function into an official decorator won’t take much. In fact, the way it’s already written fits the API perfectly: it accepts the original function and spits out the augmented version. So, all we need to do is apply it with the @<\/code> syntax:<\/p>\n\n\n
class<\/span> ViewController<\/span> <\/span>{\n<\/span><\/span>  @debounce\n<\/span><\/mark>  async<\/span> handleSearch(query) {\n<\/span><\/span>    const<\/span> results = await<\/span> search(query);\n<\/span><\/span>\n<\/span><\/span>    console<\/span>.log(`Got results!`<\/span>, results);\n<\/span><\/span>  }\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
That’s all it takes \u2014 a single line \u2014 for the exact same result.<\/p>\n\n\n\n
We can also make the debouncing delay configurable by making debounce()<\/code> accept a delay<\/code> value and return a decorator itself:<\/p>\n\n\n
\/\/ Accept a delay:<\/span>\nfunction<\/span> debounce<\/span>(delay<\/span>) <\/span>{\n  let<\/span> timeout = null<\/span>;\n\n  \/\/ Return the configurable decorator:<\/span>\n  return<\/span> function<\/span> (value<\/span>) <\/span>{\n    return<\/span> function<\/span> (...args<\/span>) <\/span>{\n      clearTimeout(timeout);\n\n      timeout = setTimeout(()<\/span> =><\/span> {\n        value.call(this<\/span>, ...args);\n      }, delay);\n    };\n  };\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Using it just means calling our decorator wrapper as a function and passing the value:<\/p>\n\n\n
class<\/span> ViewController<\/span> <\/span>{\n<\/span><\/span>  @debounce(500<\/span>)\n<\/span><\/mark>  async<\/span> handleSearch(query) {\n<\/span><\/span>    const<\/span> results = await<\/span> search(query);\n<\/span><\/span>\n<\/span><\/span>    console<\/span>.log(`Got results!`<\/span>, results);\n<\/span><\/span>  }\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
That\u2019s a lot of value for minimal code wrangling, especially support being provided by TypeScript and Babel \u2014 tools already well-integrated in our build processes.<\/p>\n\n\n\n
Memoization<\/strong><\/h3>\n\n\n\n
Whenever I think of great memoization that’s syntactically beautiful, Ruby first comes to mind. I’ve written about how elegant it is<\/a> in the past; the ||=<\/code> operator is all you really need:<\/p>\n\n\n
def<\/span> results<\/span><\/span>\n  @results ||<\/span>= calculate_results\nend<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
But with decorators, JavaScript’s making solid strides. Here\u2019s a simple implementation that caches the result of a method, and uses that value for any future invocations:<\/p>\n\n\n
function<\/span> memoize<\/span>(func<\/span>) <\/span>{\n  let<\/span> cachedValue;\n\n  return<\/span> function<\/span> (...args<\/span>) <\/span>{\n    \/\/ If it's been run before, return from cache.<\/span>\n    if<\/span> (cachedValue) {\n      return<\/span> cachedValue;\n    }\n\n    cachedValue = func.call(this<\/span>, ...args);\n\n    return<\/span> cachedValue;\n  };\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
The nice thing about this is that each invocation of a decorator declares its own scope, meaning you can reuse it without risk of the cachedValue<\/code> being overwritten with an unexpected value.<\/p>\n\n\n
class<\/span> Student<\/span> <\/span>{\n  @memoize\n  calculateGPA() {\n    \/\/ Expensive computation...<\/span>\n    return<\/span> 3.9<\/span>;\n  }\n\n  @memoize\n  calculateACT() {\n    \/\/ Expensive computation...<\/span>\n    return<\/span> 34<\/span>;\n  }\n}\n\nconst<\/span> bart = new<\/span> Student();\n\nbart.calculateGPA();\nconsole<\/span>.log(bart.calculateGPA()); \/\/ from cache: 3.9<\/span>\n\nbart.calculateACT();\nconsole<\/span>.log(bart.calculateACT()); \/\/ from cache: 34<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Going further, we could also memoize based on the parameters passed to a method:<\/p>\n\n\n
function<\/span> memoize<\/span>(func<\/span>) <\/span>{\n  \/\/ A place for each distinct set of parameters.<\/span>\n  let<\/span> cache = new<\/span> Map<\/span>();\n\n  return<\/span> function<\/span> (...args<\/span>) <\/span>{\n    const<\/span> key = JSON<\/span>.stringify(args);\n\n    \/\/ This set of parameters has a cached value.<\/span>\n    if<\/span> (cache.has(key)) {\n      return<\/span> cache.get(key);\n    }\n\n    const<\/span> value = func.call(this<\/span>, ...args);\n\n    cache.set(key, value);\n\n    return<\/span> value;\n  };\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Now, regardless of parameter usage, memoization can become even more flexible:<\/p>\n\n\n
class<\/span> Student<\/span> <\/span>{\n  @memoize\n  calculateRank(otherGPAs) {\n    const<\/span> sorted = [...otherGPAs].sort().reverse();\n\n    for<\/span> (let<\/span> i = 0<\/span>; i <= sorted.length; i++) {\n      if<\/span> (this<\/span>.calculateGPA() > sorted[i]) {\n        return<\/span> i + 1<\/span>;\n      }\n    }\n\n    return<\/span> 1<\/span>;\n  }\n\n  @memoize\n  calculateGPA() {\n    \/\/ Expensive computation...<\/span>\n    return<\/span> 3.4<\/span>;\n  }\n}\n\nconst<\/span> bart = new<\/span> Student();\n\nbart.calculateRank([3.5<\/span>, 3.7<\/span>, 3.1<\/span>]); \/\/ fresh<\/span>\nbart.calculateRank([3.5<\/span>, 3.7<\/span>, 3.1<\/span>]); \/\/ cached<\/span>\nbart.calculateRank([3.5<\/span>]); \/\/ fresh<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
That\u2019s cool, but it\u2019s also worth noting that you could run into issues if you’re dealing with parameters that can’t be serialized (undefined<\/code>, objects with circular references, etc.). So, use it with some caution.<\/p>\n\n\n\n
Memoizing Getters<\/strong><\/h3>\n\n\n\n
Since decorators can be used on more than just methods, a slight adjustment means we can memoize getters too. We just need to use context.name<\/code> (the name of the getter) as the cache key:<\/p>\n\n\n
function<\/span> memoize<\/span>(func, context<\/span>) <\/span>{\n  let<\/span> cache = new<\/span> Map<\/span>();\n\n  return<\/span> function<\/span> (<\/span>) <\/span>{\n    if<\/span> (cache.has(context.name)) {\n      return<\/span> cache.get(context.name);\n    }\n\n    const<\/span> value = func.call(this<\/span>);\n\n    cache.set(context.name, value);\n\n    return<\/span> value;\n  };\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Implementation would look the same:<\/p>\n\n\n
class<\/span> Student<\/span> <\/span>{\n  @memoize\n  get<\/span> gpa() {\n    \/\/ Expensive computation...<\/span>\n    return<\/span> 4.0<\/span>;\n  }\n}\n\nconst<\/span> milton = new<\/span> Student();\n\nmilton.gpa \/\/ fresh<\/span>\nmilton.gpa \/\/ from the cache<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
That context object contains some useful bits of information, by the way. One of those is the “kind” of field being decorated. That means we could even take this a step further by memoizing the getters and<\/em> methods with the same decorator:<\/p>\n\n\n
function<\/span> memoize<\/span>(func, context<\/span>) <\/span>{\n  const<\/span> cache = new<\/span> Map<\/span>();\n\n  return<\/span> function<\/span> (...args<\/span>) <\/span>{\n    const<\/span> { kind, name } = context;\n\n    \/\/ Use different cache key based on \"kind.\"<\/span>\n    const<\/span> cacheKey = kind === 'getter'<\/span> ? name : JSON<\/span>.stringify(args);\n\n    if<\/span> (cache.has(cacheKey)) {\n      return<\/span> cache.get(cacheKey);\n    }\n\n    const<\/span> value = func.call(this<\/span>, ...args);\n\n    cache.set(cacheKey, value);\n\n    return<\/span> value;\n  };\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
You could take this much further, but we’ll draw the line there for now, and instead shift to something a little more complex.<\/p>\n\n\n\n
Dependency Injection<\/h2>\n\n\n\n
If you’ve worked with a framework like Laravel or Spring Boot, you’re familiar with dependency injection and the “inversion of control (IoC) container” for an application. It’s a useful feature, enabling you to write components more loosely coupled and easily testable. With native decorators, it’s possible to bring that core concept to vanilla JavaScript as well. No framework needed.<\/p>\n\n\n\n
Let’s say we’re building an application needing to send messages to various third-parties. Triggering an email, sending an analytics event, firing a push notification, etc. Each of these are abstracted into their own service classes:<\/p>\n\n\n
class<\/span> EmailService<\/span> <\/span>{\n  constructor<\/span>() {\n    this<\/span>.emailKey = process.env.EMAIL_KEY;\n  }\n}\n\nclass<\/span> AnalyticsService<\/span> <\/span>{\n  constructor<\/span>(analyticsKey) {\n    this<\/span>.analyticsKey = analyticsKey;\n  }\n}\n\nclass<\/span> PushNotificationService<\/span> <\/span>{\n  constructor<\/span>() {\n    this<\/span>.pushNotificationKey = process.env.PUSH_NOTIFICATION_KEY;\n  }\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Without decorators, it’s not difficult to instantiate those yourself. It might look something like this:<\/p>\n\n\n
class<\/span> MyApp<\/span> <\/span>{\n  constructor<\/span>(\n    emailService = new EmailService(),\n    analyticsService = new AnalyticsService(),\n    pushNotificationService = new PushNotificationService()\n  ) {\n    this<\/span>.emailService = emailService;\n    this<\/span>.analyticsService = analyticsService;\n    this<\/span>.pushNotificationService = pushNotificationService;\n\n    \/\/ Do stuff...<\/span>\n  }\n}\n\nconst<\/span> app = new<\/span> MyApp();<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
But now you’ve cluttered your constructor with parameters that’ll never otherwise be used during runtime, and you\u2019re taking on full responsibility for instantiating those classes. There are workable solutions out there (like relying on separate modules to create singletons), but it’s not ergonomically great. And as complexity grows, this approach will become more cumbersome, especially as you attempt to maintain testability and stick to good inversion of control.<\/p>\n\n\n\n
Dependency Injection with Decorators<\/h2>\n\n\n\n
Now, let’s create a basic dependency injection mechanism with decorators. It\u2019ll be in charge of registering dependencies, instantiating them when necessary, and storing references to them in a centralized container.<\/p>\n\n\n\n
In a separate file (container.js<\/code>), we’ll build a simple decorator used to register any classes we want to make available to the container.<\/p>\n\n\n
const<\/span> registry = new<\/span> Map<\/span>();\n\nexport<\/span> function<\/span> register<\/span>(args = []<\/span>) <\/span>{\n  return<\/span> function<\/span> (clazz<\/span>) <\/span>{\n    registry.set(clazz, args);\n  };\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
There’s not much to it. We’re accepting the class itself and optional constructor arguments needed to spin it up. Next up, we’ll create a container to hold the instances we create, as well as an inject()<\/code> decorator.<\/p>\n\n\n
const<\/span> container = new<\/span> Map<\/span>();\n\nexport<\/span> function<\/span> inject<\/span>(clazz<\/span>) <\/span>{\n  return<\/span> function<\/span> (_value, context<\/span>) <\/span>{\n    context.addInitializer(function<\/span> (<\/span>) <\/span>{\n      let<\/span> instance = container.get(clazz);\n\n      if<\/span> (!instance) {\n        instance = Reflect<\/span>.construct(clazz, registry.get(clazz));\n        container.set(clazz, instance);\n      }\n\n      this<\/span>[context.name] = instance;\n    });\n  };\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
You’ll notice we’re using something else from the decorator specification. The addInitializer()<\/code> method will fire a callback only after the decorated property has been defined. That means we\u2019ll be able to lazily instantiate our injected dependencies, rather than booting up every registered class all at once. It\u2019s a slight performance benefit. If a class uses the EmailService<\/code> for example, but it’s never actually instantiated, we won\u2019t unnecessarily boot up an instance of EmailService<\/code> either.<\/p>\n\n\n\n
That said, here’s what’s going on when the decorator is invoked:<\/p>\n\n\n\n
Despite being non-standard, there are a number of popular, mature libraries out there that have used this implementation. TypeORM<\/a>, Angular<\/a>, and NestJS<\/a> are just a few of the big ones. And I’m glad they have. It’s made building applications with them feel cleaner, more expressive, and easier to maintain.<\/p>\n\n\n\n