Docs: Decorators for class decorator needs to either be explicit about the type or note that new interface isn't inferred

[orta]

Page URL: https://www.typescriptlang.org/docs/handbook/decorators.html

Issue:

function classDecorator<T extends { new(...args: any[] ) : {} }>(constructor: T) {
    return class extends constructor {
        newProperty = "new property";
        hello = "override";
    }
}

@classDecorator
class Greeter {
    property = "property";
    hello: string;
    constructor(m: string) {
        this.hello = m;
    }
}

const a = new Greeter("world")
a.newProperty

a.newProperty errors because a isn't inferred to have newProperty from the classDecorator.

Recommended Fix: Either explicitly add the type in the code sample, or state in the docs

re microsoft/TypeScript#4881

[zackdotcomputer]

I wound up here because I encountered this issue IRL - the example on the website led me to misunderstand the capabilities of the class decorator. Agree this example should be corrected so that it doesn't imply that decorators can define new properties on the object since that is not exactly the case right now (at least not in a way that typescript's compiler is happy about).

[jmar777]

Bumping this issue, as the docs continue to suggest that class decorators can reshape the target in a TypeScript-aware way. Given the number of related GitHub issues / StackOverflow questions, there seems to be a lot of avoidable wheel-spinning if the documentation were clearer on this point.

I would suggest a new "NOTE" along the lines of:

NOTE TypeScript supports the runtime semantics of the decorator proposal, but does not currently track changes to the shape of the target. Adding or removing methods and properties, for example, will not be tracked by the type system.

Likewise, it may be best to remove the following line from the code example, as TypeScript will be unaware of newProperty:

    newProperty = "new property";

[typescript-bot]

Hello! As per #2804, we are automatically closing all open issues. Please see #2804 for a description of what issues and PRs can be accepted going forward.