decorators.deno.dev - Reference to Stage 3 Decorators in TypeScript with Deno

Welcome to decorators.deno.dev, a micro-site by Nicholas Berlette, entirely dedicated to helping you implement Stage 3 Decorators in Deno projects.

Stage 3 Decorators... in Deno?

You've got that right - Deno just rolled out experimental support for the new decorators syntax in v1.40.0, and it's now enabled by default in all projects using that version or higher. To disable it in favor of the legacy decorators (yuck), you must explicitly set the experimentalDecorators flag to false in your deno.json or deno.jsonc file.

Preamble

The new decorators syntax took 5 years to flesh out, and many of us in the JavaScript community have been eagerly waiting (some more patiently than others) for widespread support to happen. Deno rolling out support on their runtime is a huge step in the right direction in this regard.

Feature Highlights

The latest iteration of decorators brings a suite of powerful enhancements to improve the developer's experience and type safety. Here are some of the standouts:

Significantly stronger type safety and definitions than before.
Integrated with Decorator Metadata capabilities
Fully-typed context object for each type of decorator.
All decorators accept exactly 2 arguments. The second one is always an object. Pro Tip: This invariant can be used to differentiate between legacy decorators and the new ES Decorator syntax.

Syntax and Compatibility

The new style decorators bring with them an entirely new way of decorating classes and class members - therefore, it is 100% incompatible with the signatures of all previous decorator formats.

Decorator Types

There are six (6) different decorator types, each of which serves a different purpose. Each decorator type is only allowed to decorate a specific type of code, known as the decorator target. You should never try to apply a decorator to a target type other than what it is compatible with.

Class Decorators

Applied at the outermost scope to the class itself.

This type of decorator receives the actual class (constructor) being decorated as its first argument.

@decorator class Person {
	constructor(
		public readonly name: string,
		public readonly age: number,
	) {}
}

Field Decorators

Applied to static, instance, and private class fields (properties).

This type of decorator will always receive undefined for its first argument.

class Person {
	@observable name: string;
	@observable #hiddenAge: number;
}

Method Decorators

Applied to static, instance, and private methods.

This type of decorator receives the actual method function being decorated as its first argument.

class Person {
	@bound greet(): string {
		return `Hello, ${this.name}!`;
	}

	@bound static kind(): string {
		return this.name;
	}
}

Getter Decorators

Applied to static, instance, and private getters.

This type of decorator receives the actual getter method being decorated as its first argument.

class Person {
	#age: number;
	@lazy get age(): number {
		return this.#age;
	}
}

Setter Decorators

Applied to static, instance, and private setters.

This type of decorator receives the actual setter method being decorated as its first argument. Its context.kind value will be "setter".

If the decorator returns a value, it must be a function with the same signature as the one received in the target. The returned function will replace the original setter in the final form of the class.

class Person {
	#age: number;
	@log set age(newAge: number) {
		this.#age = newAge;
	}
}

Accessor Decorators

Applied to static, instance, and private auto-accessors, defined with the accessor modifier keyword.

This type of decorator receives a special target object for its first argument, which contains a get method and a set method.

If an accessor decorator returns a value, it must be an object with a get method and a set method, just like the target object it received. It may also optionally have an init method, which allows you to override the accessor's initial value.

class Person {
	@log accessor age: number = 30;
}

Limitations and Caveats

Caveat: Parameter decorators are currently not supported.

Synopsis: the TC39 Proposal Process

When it comes to new features, there is an established approval process through which potential features are proposed, accepted, reviewed/refined, and (eventually) either rejected or ratified and added to the specification. This is known as the TC39 Proposal process, and it has 4 distinctive stages. I'm not going to get into much detail here, but I'll point out a few parts that I feel are most relevant to the decorators topic. To start is something probably quite obvious to you: the higher the stage number, the closer a feature is to implementation.

Stage 3 essentialy means the blueprint for runtime implementations have more or less reached their final form. It takes quite a bit of effort, and the reasoning must be very persuasive, to roll back a proposal once it's reached Stage 3. It also takes a non-trivial amount of work for the agreed-upon design plan to be modified or updated once at this stage.

Therefore, when a proposal reaches Stage 3, it's usually a strong indicator that we can expect to see the feature ship in the near future. Typically it will start appearing in canary (pre-release/beta) channels of the major runtimes while their engineers flesh out the intricacies of getting the feature to behave as expected.

Stage 4 means the feature has been added to the specification, and is probably already implemented in most major browsers and runtimes.

So where are the decorators in all this?

In April of 2022, the TC39 Decorators Proposal finally graduated to Stage 3 of the proposal process, after nearly 5 years painstaking revisions and rewrites.

While it still hasn't been implemented by any major runtimes or browsers yet, the TypeScript Team threw us a bone by implementing support for this new decorators API in their TypeScript 5.0 release in January 2023. The Deno team released Deno v1.40 in January 2024, which finally provided support for decorators through its built-in TypeScript compiler.

The significance of Deno v1.40

Deno's implementation is really significant because of how Deno itself works in comparison to Node/TypeScript: unlike the traditional Node.js + TypeScript setup, Deno supports TypeScript and TSX syntax right out of the box, without worrying build steps to enjoy static type analysis in the world's most popular programming language.

The Deno implementation of this new decorators proposal keeps with the aforementioned design points, allowing it to almost feel like the proposal has already hit Stage 4 and achieved widespread implementation. Don't take my word for it though, try it out yourself: open up the Deno REPL with a one word command - deno - and drop in a class thats been thoroughly decorated. Watch with glee as it just... works.

🦖 decorators.deno.dev