Experimental

Now, let’s get into the weird and wonderful world of making decorators actually useful. You see, the basic decorators we just covered are like getting a fancy new power tool… without the battery. They let you see that a class or method is being decorated, but they don’t give you the runtime information about that class or method to do anything truly intelligent. You know target is a constructor function, but what are the names and types of its properties? Good luck.

Alright, let’s settle this. For years, you’ve been using decorators in TypeScript or Babel, and I’ve been right there with you, grumbling about the absurdly complex incantations needed to make them work. That was the legacy decorator proposal, a weird, unofficial draft that got stuck in committee purgatory for so long that everyone just started using it anyway. It was the house guest who overstayed their welcome by about seven years.

Now, let’s talk about the black sheep of the decorator family: parameter decorators. You’ve probably seen them lurking in Angular or other DI-heavy frameworks, looking cryptic and a bit magical. Their entire job is to let you attach metadata to a function’s parameters. That’s it. They don’t do anything on their own. They just whisper, “Hey, when you’re constructing this class later, you should probably pass 'database' for this first parameter, okay?” They are the ultimate backseat drivers of the JavaScript world.

Right, decorators. You’ve probably heard the hype, seen the @ symbols littering frameworks, and wondered if it’s just magic glitter someone sprinkled on JavaScript. It’s not. It’s a structured, powerful, and frankly, a bit awkward way to metaprogram your classes. We’re going to focus on the ones that finally made it into the official spec: property and accessor decorators. Forget the old, weird, wildly-incompatible-between-Babel-and-TypeScript versions. ES2023 is the real deal, and it’s about time.

Alright, let’s get our hands dirty with method decorators. Forget the dry theory—you want to know what these things do. At their core, a method decorator is a function that gets to wrap another function, specifically a method on a class. It can intercept the call, mess with the inputs, mess with the output, or even replace the entire method. It’s like having a universal middleware system for your class methods, and it’s incredibly powerful for things like logging, validation, or access control without cluttering your actual business logic.

Alright, let’s get our hands dirty with the two main flavors of class decorators: wrapping and replacing. This is where the magic happens, and also where you can spectacularly blow your own foot off if you’re not careful. I’m here to make sure you keep all your toes. The core idea is simple: a class decorator receives the entire class constructor as its target and can either return a new constructor (wrapping or replacing) or mutate the original one. We’re going to focus on the non-mutating, return-a-new-constructor approach because it’s cleaner, more powerful, and frankly, less likely to cause weird side-effects that make you question your life choices.

Alright, let’s talk about the weird, liminal space decorators have occupied for the last decade. If you’ve dabbled in TypeScript or modern frameworks, you’ve used them. @Component, @observable, you name it. But here’s the kicker: for years, the decorators you were using were a complete fiction. Well, not a complete fiction. They were based on a very real, very old Stage 2 proposal from… checks notes… 2014. A proposal that was essentially a draft scribbled on a napkin, which the TC39 committee then spent the next several years completely rewriting. This left us all in a state of Schrödinger’s decorator: both standardized and experimental at the same time.