Implement the updated JS decorators proposal #48885

arackaf · 2022-04-29T17:30:06Z

Suggestion

Implement Decorators!

🔍 Search Terms

TypeScript Decorators

List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily and help provide feedback.

Decorators

✅ Viability Checklist

My suggestion meets these guidelines:

This wouldn't be a breaking change in existing TypeScript/JavaScript code
This wouldn't change the runtime behavior of existing JavaScript code
This could be implemented without emitting different JS based on the types of the expressions
This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
This feature would agree with the rest of TypeScript's Design Goals.

Not sure - this would be badly breaking against your legacy decorators feature, but I think it meets the goal to align TS with JS

⭐ Suggestion

The TypeScript proposal is now Stage 3!!!

https://github.com/tc39/proposal-decorators

We've all seen the issue from hell requesting better typing support for decorators

#4881

but now that the proposal is moving forward, currently at Stage 3, I thought I'd open this issue to see if there are plans to finally, fully implement (and type) the ES version of decorators.

📃 Motivating Example

N/A - just implementing new JS features, to keep JS and TS aligned.

💻 Use Cases

All the various ways decorators can be used.

DanielRosenwasser · 2022-04-29T23:34:56Z

I think the first step will be implementing decorators. We're not going to try to model the "decorators can change the types of things" portion at first, but I think we can get something good and working.

arackaf · 2022-04-30T01:01:39Z

@DanielRosenwasser that sounds perfect.

But just to be clear, annotating how a decorator change’s a type will be on the roadmap long term?

glen-84 · 2022-05-01T19:41:38Z

Shhh, don't say "long term". 😉

wycats · 2022-05-13T19:22:45Z

@DanielRosenwasser the biggest "type-related" transformation that comes up for me in the current implementation of decorators is communicating that a field decorator initializes the field's value.

I think that this would just fall out of accessor decorators (since the decorator turns into a getter, the concept of an uninitialized value no longer makes sense). Is that right?

Also, a regular field decorator might still want to communicate that the value is initialized (for example, a decorator that implements a default by returning a new initializer). Is it possible to address the issue of communicating that a decorator initializes the value on a different timeframe than arbitrary type transformation, or is it just as hard?

Jamesernator · 2022-05-14T22:45:19Z

We're not going to try to model the "decorators can change the types of things" portion at first, but I think we can get something good and working.

Simple transform decorators should be easy enough to support right?

Like:

function wrapInBox<R>(f: () => R): () => { value: R } {
    return () => { value: f() };
}

class Foo {
    @wrapInBox
    method(): number {
        return 3;
    }
}

const foo = new Foo();
foo.method(); // should be { value: number }, same as regular function wrapping

Has very little difference to (type inference wise):

class Foo {
    method = wrapInBox((): number => {
        return 3;
    });
}

(Ignoring the prototype vs own property distinction here).

Isn't it primarily the metadata-based type-mutations that are hard to actually support? (given they need to communicate types across calls)

trusktr · 2022-08-17T23:57:46Z

@DanielRosenwasser that sounds perfect.

But just to be clear, annotating how a decorator change’s a type will be on the roadmap long term?

Besides this, also picking types from a class by specific decorator would be wonderful... in the longer term. :D

trusktr · 2022-08-18T00:11:54Z

Also, a regular field decorator might still want to communicate that the value is initialized (for example, a decorator that implements a default by returning a new initializer). Is it possible to address the issue of communicating that a decorator initializes the value on a different timeframe than arbitrary type transformation, or is it just as hard?

Do you mean something like this?

class Foo {
  @alwaysString foo = 123 // initializes it to "123"
}

I think TypeScript would create the type right then and there, at class definition. The user cannot (write any code that will)
observe a moment when the value is a number instead of a string, apart from the decorators themselves.

Another thing could be that maybe decorators can augment the type of a class, but not necessarily the type of the thing they decorate directly. For example, this

class Foo {
  @withDouble count = 123
}

could add a new doubleCount variable that is always the double of count whenever count changes. The type would be { count: number, doubleCount: number } where count was not modified.

However, I think that with this new decorator API, decorator functions can be completely generic, with their input and output types completely known by TypeScript. So, this should be possible:

function alwaysString<T, C extends ...>(_: T, context: C): (initial: T) => string {
  if (context.kind !== 'field') return // type narrowing based on union of string values for `kind`

  return initial => initial.toString()
}

and based on something like this, I imagine it totally possible for TypeScript to look at the return type and determine that the final type of the property should always be a string (or to always have any setter, string getter).

But a version with class types not modifiable would still be totally usable!

ruojianll · 2022-08-19T15:30:15Z

I suggest implement decorators first, then add type support. The current legacy class decorator could return a non-class constructor value, and it won't be recognized by ts type system, but it is still easy to use.

Or we just use legacy version until stage 4 published, but maybe they are waiting us to do something to verify their design in stage 3.

wycats · 2022-08-25T00:25:59Z

I suggest implement decorators first, then add type support

As long as @dec accessor foo understands that you don't need to explicitly initialize foo, I think I can live with that.

wycats · 2022-08-25T00:26:45Z

I wonder if the narrow case of initializer mapping might be more doable than other kinds of changes caused by decorators.

DanielRosenwasser · 2022-08-25T00:42:40Z

This is kind of what I've been thinking recently. I can imagine a world where

decorators can return a more-derived type than the initializer of a field
the type returned by the decorator needs to be assignable to the annotated type of the field - though the initializer doesn't necessarily need to be

It's enough to help with auto-initialization (which is just removing undefined from a type) and creating more-specialized types (which is turning something like [1, 2, 3] into a WatchedArray<number>/ReactiveArray<number> instead of an Array<number).

The reason for the latter bullet is being able to support something along the lines of #47947, along with some other precedent we have (e.g. async functions need to say they return a Promise<ThingBeingReturned> rather than ThingBeingReturned, and the wishful thinking some of us have in the behavior of --exactOptionalProperties).

trusktr · 2022-08-26T16:54:01Z

decorators can return a more-derived type than the initializer of a field

This part works:

class Foo {
  @reactive array = [1, 2, 3] // converts to ReactiveArray<number> for example
}

But what about this?

const f = new Foo

f.array = [4, 5, 6] // Should also accept a plain array and convert to a (or map to the) `ReactiveArray<number>`
f.array // `ReactiveArray<number>`

trusktr · 2022-08-26T16:57:55Z

Also what about the case of a totally different but valid type? The following is based on real-world examples, namely for attribute processing with custom elements:

import {numberArray} from 'some-custom-element-lib'

class MyEl extends HTMLElement {
  // also accepts strings (f.e. from HTML attributes)
  @numberArray coords = "1 2 3" // converts to ReactiveArray<number> for example
}

customElements.define('my-el', MyEl)

const el = new MyEL

el.array = [4, 5, 6] // Should also accept a plain array and convert to a (or map to the) `ReactiveArray<number>`
el.array = "7 8 9" // Should also accept a string with space-separate list of numbers and convert to a (or map to the) `ReactiveArray<number>`
el.array // `ReactiveArray<number>`

trusktr · 2022-08-26T17:14:03Z

Hmm, now that I think about it, maybe an accessor is all that is needed, because the decorator would then receive an object with get and set functions. The decorator could define each one of those to have separate types, just like class getters/setters currently can.

Example:

// some-custom-element-lib
export function numberAttribute() {
  return {
      get(): ReactiveArrayTriplet<number> {
        // ...
      },

      set(val: `${number} ${number} ${number}` | [number, number, number] | ReactiveArrayTriplet<number>) {
        // ...
      },
  }
}

import {numberArray} from 'some-custom-element-lib'

class MyEl extends HTMLElement {
  // also accepts strings (f.e. from HTML attributes)
  @numberArray accessor coords = "1 2 3" // converts to ReactiveArray<number> for example
}

In this case, the type of the implied getter/setter can be determined from the decorator return value.

There's actually a way to write the above without using the accessor keyword in plain JavaScript, like so:

import {element, numberArray} from 'some-custom-element-lib'

@element // this added decorator is needed for creating reactive accessors in a returned subclass based on decorated fields
class MyEl extends HTMLElement {
  @numberArray coords = "1 2 3"
}

but then I don't see how TypeScript would be able to determine differing get/set types for coords.

ruojianll · 2022-08-28T15:04:06Z

@trusktr Maybe that should be write in grouped accessors.

class Foo {
accessor coords{
  get():ReactiveArrayTriplet<number>{
    //...
  };
  set(data:`${number} ${number} ${number}` | [number, number, number] | ReactiveArrayTriplet<number>){
    //...
  };
}
}

ruojianll · 2022-08-28T15:22:06Z

@wycats In my opinion, the accessor type should be declared in the class. Decorators should be compatible with accessor type.

class Foo{
  @Dec accessor bar?:string //not allowed, bar must be instialized
  @Dec accessor bar2:string|undefined//allowed
}

Decorators shouldn't break the type defined in class. That's also a typescript way to implement.

uasan · 2022-09-05T17:22:37Z

Is there any information about TS plans to implement decorator extensions?
https://github.com/tc39/proposal-decorators/blob/master/EXTENSIONS.md

Many real use cases require exactly the extended capabilities of decorators.
Thanks.

justinfagnani · 2022-09-06T01:32:51Z

@uasan I'm sure TypeScript wouldn't implement them before they're standardized, so it's really a question for TC39 and the decorators proposal champions.

trusktr · 2022-09-14T21:17:32Z

@trusktr Maybe that should be write in grouped accessors.

That defeats the purpose of having decorators: to write concise code and not repeat that pattern on every property. We are here in this thread to use decorators!

trusktr · 2022-09-14T21:22:32Z

For the time being, it would be great to have an option to not compile decorators (just like we can leave JSX untouched), so that we can pass output code along to other tools like Babel. This would be a lot simpler to implement, and still useful even after TypeScript gets updated decorators.

trusktr · 2022-09-15T00:02:50Z

Along with a decorators: "preserve" or similar option, export needs to be allowed before @decorator. Then we're fully off to the races without TS needing full support yet!

trusktr · 2022-09-15T00:28:11Z

Currently we can make this work using @babel/typescript (type check code with tsc separately) by splitting exports from class definitions to avoid errors that tsc currently gives.

This does not work:

export // export is required before stage-3 decorators, currently an error in TS
@stage3Decorator
class Foo {}

This works:

@stage3Decorator
class Foo {}
export {Foo}

Your babel config plugins will look something like this:

	plugins: [
		['@babel/plugin-transform-typescript', {...}],
		['@babel/plugin-proposal-decorators', {version: '2022-03'}],
		['@babel/plugin-proposal-class-static-block'], // needed, or decorator output will currently not work in Safari.
	],

and off to the races! 🐎

trusktr · 2022-09-15T00:55:56Z

For now, here's what the signature of a stage 3 decorator may look like to avoid type errors:

export function someDecorator(...args: any[]): any {
	const [value, {kind, ...etc}] = args as [DecoratedValue, DecoratorContext]
	console.log('stage 3!', value, kind, etc)

	if (kind === 'class') {
		// ...
	} else if (kind === 'field') {
		// ...
	} else (/*...etc...*/) {
		// ...
	}

	// ...
}

interface DecoratorContext {
	kind: 'class' | 'method' | 'getter' | 'setter' | 'field' | 'accessor'
	name: string | symbol
	access: Accessor
	private?: boolean
	static?: boolean
	addInitializer?(initializer: () => void): void
}

interface Accessor { 
    get?(): unknown
    set?(value: unknown): void
}

type Constructor<T = object, A extends any[] = any[], Static = {}> = (new (...a: A) => T) & Static

type DecoratedValue = Constructor | Function | Accessor | undefined

pokatomnik · 2022-11-09T13:17:37Z

Sorry for the offtopic question, but what will happen to stage3 decorators? Will they be removed from Typescript?

rbuckton · 2022-11-09T20:16:13Z

Sorry for the offtopic question, but what will happen to stage3 decorators? Will they be removed from Typescript?

I assume you mean the Stage 1 "experimental" decorators that are already in TypeScript? That will remain behind --experimentalDecorators for the foreseeable future as there are a number of decorator features that are not yet covered by the current Decorators proposal:

Metadata (https://github.com/tc39/proposal-decorator-metadata)
Parameter Decorators (Parameter decorators tc39/proposal-decorators#47)
A way to decorate a getter/setter pair via { get, set } (https://github.com/tc39/proposal-grouped-and-auto-accessors). While this does exist for the new accessor fields, there is no easy alternative for normal getters and setters.

We also do not currently support decorated declare fields with Stage 3 decorators, as that would introduce significant additional complexity due to the timing of decorator application.

rbuckton · 2022-11-09T20:26:02Z

For now, here's what the signature of a stage 3 decorator may look like to avoid type errors:

[...]

The built-in lib definitions in #50820 contain types that will hopefully be able to help:

// class decorator
function MyClassDecorator<T extends new (...args: any) => any>(target: T, context: ClassDecoratorContext<T>) {
};

// method decorator
function MyMethodDecorator<T extends (...args: any) => any>(target: T, context: ClassMethodDecorator<unknown, T>) {
};

// or, a catch-all decorator
function MyDecorator(target: unknown, context: DecoratorContext) {
  switch (context.kind) {
    case "class": ...
    case "method": ...
    ...
  }
}

pokatomnik · 2022-11-09T20:39:32Z

@rbuckton, thank you, I mean ES decorators reached stage 3. And because of that, I believe they'll be implemented in the Typescript as well. And correct me if I'm wrong, but the newest decorators are not compatible with the good old "experimental". So I thought, Typescript will have to support them since a lot of frameworks are relying on them.
In other words, my question is "should I write a new code with the experimental decorators or will they be deprecated in about 3 years?"
Thanks in advance!

ruojianll · 2022-11-10T05:58:49Z

"should I write a new code with the experimental decorators or will they be deprecated in about 3 years?"

Hope there is adapter to update experimental decorators to stage 3 automatic.

trusktr · 2022-11-12T17:57:42Z

@pokatomnik while experimental stage 1 decorators will be supported for some unknown amount of time, I believe we can assume that eventually non-experimental stage 3 decorators will land and we'll be able to rely on those.

If you want to prepare for this future, the best way to do that currently is to use tsc only for type checking, and use babel for transpiling stage 3 decorators today. Then it should be minimal effort later to switch to using just tsc for type checking and compiling.

I'm betting on stage 3 decorators with a setup like I mentioned in the above comment.

trusktr · 2022-11-12T18:00:10Z

Hope there is adapter to update experimental decorators to stage 3 automatic.

I don't think TypeScript will do that (I don't think it has ever been done for any feature). Experimental stage 1 decorators and stage 3 decorators are highly incompatible. Start migrating!

ruojianll · 2022-11-15T07:39:20Z

Hope there is adapter to update experimental decorators to stage 3 automatic.

I don't think TypeScript will do that (I don't think it has ever been done for any feature). Experimental stage 1 decorators and stage 3 decorators are highly incompatible. Start migrating!

I will try, but it is a terrible work especially for package creators to update their user's code.

jithujoshyjy · 2022-11-15T18:22:19Z

Metadata (https://github.com/tc39/proposal-decorator-metadata)

A little nod about the metadata in decorators. tc39/proposal-type-annotations#159 can this be done in typescript?

rbuckton · 2022-11-15T19:22:09Z

Hope there is adapter to update experimental decorators to stage 3 automatic.

I don't think TypeScript will do that (I don't think it has ever been done for any feature). Experimental stage 1 decorators and stage 3 decorators are highly incompatible. Start migrating!

No, we won't automatically adapt legacy decorators as that would require type-directed emit. Also, there is not 1:1 parity between legacy decorators and ECMAScript decorators, which I mentioned above.

It's possible to write a custom decorator adapter, though that would entail varying degrees of complexity depending on the decorator you are adapting. An adapter that provided full backwards compatibility with legacy decorators would likely incur a performance penalty, though it would be feasible:

// legacy.ts
@foo
@bar({ x: 1 })
class C {
  @baz method() {}
  @quxx field;
}

// native.ts
import { createDecoratorAdapter } from "./adapter";

const _ = createDecoratorAdapter();

@_ // <- last applied decorator
@_(foo)
@_(bar({ x: 1 })
class C {
  @_(baz) method() {}
  @_(quxx) field;
}

// adapter.ts
export function createDecoratorAdapter() {
  // TODO: returns a function that queues up each legacy decorator application
  // and performs legacy decorator evaluation at the end as part of a
  // final class decorator.
}

rbuckton · 2022-11-15T21:12:22Z

Here's a rough implementation of a comprehensive createDecoratorAdapter(): https://gist.github.com/rbuckton/a464d1a0997bd3dab36c8b0caef0959a

NOTE: It's not designed to be intermingled with native decorators, as all decorator applications are queued until an adapted class decorator runs (or the adapter itself is used as a class decorator).

DanielRosenwasser added this to the TypeScript 4.8.0 milestone Apr 29, 2022

DanielRosenwasser added the Suggestion An idea for TypeScript label Apr 29, 2022

DanielRosenwasser assigned DanielRosenwasser and rbuckton Apr 29, 2022

DanielRosenwasser added In Discussion Not yet reached consensus Committed The team has roadmapped this issue labels Apr 29, 2022

DanielRosenwasser mentioned this issue May 11, 2022

TypeScript 4.8 Iteration Plan #49074

Closed

Agapurnis mentioned this issue May 27, 2022

[Bug]: When using legacy decorators, accessing a class in a static method of said class gives the non-decorated class babel/babel#14245

Closed

1 task

L2jLiga mentioned this issue Jul 19, 2022

upgrading to 4.0.0 L2jLiga/fastify-decorators#738

Open

jkrems mentioned this issue Jul 20, 2022

Implementation Status tc39/proposal-decorators#476

Open

6 tasks

MartinJohns mentioned this issue Jul 22, 2022

Decorator is in stage3 now. #49997

Closed

DanielRosenwasser mentioned this issue Aug 25, 2022

TypeScript 4.9 Iteration Plan #50457

Closed

Jamesernator mentioned this issue Sep 2, 2022

Sharp notation do not allow decorator .. #50602

Closed

rbuckton mentioned this issue Sep 17, 2022

Implement the Stage 3 Decorators Proposal #50820

Merged

typescript-bot added the Fix Available A PR has been opened for this issue label Sep 17, 2022

DanielRosenwasser mentioned this issue Oct 28, 2022

Types for Decorators Design Sync, 10/28/2022 #51347

Closed

DanielRosenwasser modified the milestones: TypeScript 4.8.0, TypeScript 5.0.0 Oct 31, 2022

DanielRosenwasser mentioned this issue Oct 31, 2022

TypeScript 5.0 Iteration Plan #51362

Closed

azu mentioned this issue Nov 2, 2022

2022-11-02のJS: Node.js 18.12.0 LTS、Babel 7.20.0、TypeScript 4.9 RC jser/jser.github.io#1016

Merged

zkulbeda mentioned this issue Nov 3, 2022

[feature] class properties that are "readonly in public, writable in private" or other permutations #37487

Open

5 tasks

qufei1993 mentioned this issue Dec 31, 2022

JavaScript 装饰器进入 stage 3，是时候了解了 qufei1993/blog#48

Open

rbuckton closed this as completed in #50820 Jan 19, 2023

This was referenced Mar 2, 2023

📎 TypeScript 5.0 rome/tools#4227

Closed

📎 EcmaScript @decorators rome/tools#4252

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement the updated JS decorators proposal #48885

Implement the updated JS decorators proposal #48885

arackaf commented Apr 29, 2022

DanielRosenwasser commented Apr 29, 2022

arackaf commented Apr 30, 2022

glen-84 commented May 1, 2022

wycats commented May 13, 2022

Jamesernator commented May 14, 2022 •

edited

Loading

trusktr commented Aug 17, 2022

trusktr commented Aug 18, 2022 •

edited

Loading

ruojianll commented Aug 19, 2022 •

edited

Loading

wycats commented Aug 25, 2022

wycats commented Aug 25, 2022

DanielRosenwasser commented Aug 25, 2022 •

edited

Loading

trusktr commented Aug 26, 2022 •

edited

Loading

trusktr commented Aug 26, 2022 •

edited

Loading

trusktr commented Aug 26, 2022

ruojianll commented Aug 28, 2022 •

edited

Loading

ruojianll commented Aug 28, 2022

uasan commented Sep 5, 2022

justinfagnani commented Sep 6, 2022

trusktr commented Sep 14, 2022 •

edited

Loading

trusktr commented Sep 14, 2022 •

edited

Loading

trusktr commented Sep 15, 2022 •

edited

Loading

trusktr commented Sep 15, 2022

trusktr commented Sep 15, 2022

pokatomnik commented Nov 9, 2022

rbuckton commented Nov 9, 2022

rbuckton commented Nov 9, 2022 •

edited

Loading

pokatomnik commented Nov 9, 2022

ruojianll commented Nov 10, 2022

trusktr commented Nov 12, 2022 •

edited

Loading

trusktr commented Nov 12, 2022 •

edited

Loading

ruojianll commented Nov 15, 2022

jithujoshyjy commented Nov 15, 2022 •

edited

Loading

rbuckton commented Nov 15, 2022

rbuckton commented Nov 15, 2022

Implement the updated JS decorators proposal #48885

Implement the updated JS decorators proposal #48885

Comments

arackaf commented Apr 29, 2022

Suggestion

🔍 Search Terms

✅ Viability Checklist

⭐ Suggestion

📃 Motivating Example

💻 Use Cases

DanielRosenwasser commented Apr 29, 2022

arackaf commented Apr 30, 2022

glen-84 commented May 1, 2022

wycats commented May 13, 2022

Jamesernator commented May 14, 2022 • edited Loading

trusktr commented Aug 17, 2022

trusktr commented Aug 18, 2022 • edited Loading

ruojianll commented Aug 19, 2022 • edited Loading

wycats commented Aug 25, 2022

wycats commented Aug 25, 2022

DanielRosenwasser commented Aug 25, 2022 • edited Loading

trusktr commented Aug 26, 2022 • edited Loading

trusktr commented Aug 26, 2022 • edited Loading

trusktr commented Aug 26, 2022

ruojianll commented Aug 28, 2022 • edited Loading

ruojianll commented Aug 28, 2022

uasan commented Sep 5, 2022

justinfagnani commented Sep 6, 2022

trusktr commented Sep 14, 2022 • edited Loading

trusktr commented Sep 14, 2022 • edited Loading

trusktr commented Sep 15, 2022 • edited Loading

trusktr commented Sep 15, 2022

trusktr commented Sep 15, 2022

pokatomnik commented Nov 9, 2022

rbuckton commented Nov 9, 2022

rbuckton commented Nov 9, 2022 • edited Loading

pokatomnik commented Nov 9, 2022

ruojianll commented Nov 10, 2022

trusktr commented Nov 12, 2022 • edited Loading

trusktr commented Nov 12, 2022 • edited Loading

ruojianll commented Nov 15, 2022

jithujoshyjy commented Nov 15, 2022 • edited Loading

rbuckton commented Nov 15, 2022

rbuckton commented Nov 15, 2022

Jamesernator commented May 14, 2022 •

edited

Loading

trusktr commented Aug 18, 2022 •

edited

Loading

ruojianll commented Aug 19, 2022 •

edited

Loading

DanielRosenwasser commented Aug 25, 2022 •

edited

Loading

trusktr commented Aug 26, 2022 •

edited

Loading

trusktr commented Aug 26, 2022 •

edited

Loading

ruojianll commented Aug 28, 2022 •

edited

Loading

trusktr commented Sep 14, 2022 •

edited

Loading

trusktr commented Sep 14, 2022 •

edited

Loading

trusktr commented Sep 15, 2022 •

edited

Loading

rbuckton commented Nov 9, 2022 •

edited

Loading

trusktr commented Nov 12, 2022 •

edited

Loading

trusktr commented Nov 12, 2022 •

edited

Loading

jithujoshyjy commented Nov 15, 2022 •

edited

Loading