Decorator and DecoratorBlock typings are out of sync with documentation

[Mindar]

Note by @nknapp: Unless anybody objects, this change will be made in the 4.x branch by December, 8 2019

Currently the typings and documentation for Decorator and DecoratorBlock are out of sync.

According to the documentation Decorator and DecoratorBlock should extend Statement. In the typings they extend MustacheStatement and BlockStatement. This makes it impossible to add the correct type fields for them (see #1570 and #1571 for more info ).

I assume this was done to write less code in the typings, but I think it's incorrect. I'd love to create a pull request that fixes this by making sure they extend Statement (just like they should according to the documentation) and then adding the missing fields if that's ok?

Basically I'd like to turn this

// types/index.d.ts
interface Decorator extends MustacheStatement { }

interface DecoratorBlock extends BlockStatement { }

into this

// types/index.d.ts
interface Decorator extends Statement {
    type: "Decorator";

    path: PathExpression | Literal;
    params: Expression[];
    hash: Hash;

    strip: StripFlags | null;
}

interface DecoratorBlock extends Statement {
    type: "DecoratorBlock";
    path: PathExpression | Literal;
    params: Expression[];
    hash: Hash;

    program: Program | null;

    openStrip: StripFlags | null;
    closeStrip: StripFlags | null;
}

[nknapp]

We copied the typings from DefinitelyTyped at the beginning of the year, so I'm not sure about the reasoning behind this structure.

Maybe the git history of the DefinitelyTyped repository can provide some insight. Could you have a look there? There should be a link to the latest existing version at the top of the types.ts file.

I may be able to look into this tonight (European time). Honestly, I haven't used the typings myself so far.

Are you using the decorator API yourself? Because we actually wanted to deprecate it and it would be good to know if it was actually used.

[Mindar]

I'll have a look at the history. I'm not using the decorator API myself, but I noticed the discrepancies when I added the type fields for other interfaces.

---

Edit: Seems like it's always been that way. It was added without any comment as to why it extends MustacheStatement or BlockStatement instead of Statement. Considering you want to deprecate the API anyways and considering nobody has complained about this until now, I guess we can just leave it as is.

[nknapp]

Mhm, even with deprecating this feature, it should still function correctly in 4.x versions.

I actually think, with #1571 merged, the current state is wrong (because the type for Decorators is now "MustacheStatement" (or "BlockStatement").

Your proposal will make it correct, but incompatible, because

var x: hbs.AST.MustacheStatement
var y: hbs.AST.Decorator

x = y

is not working anymore. In the end, I think we should make this change, but wait a little before doing that, unless anybody complains. A have added a note for a change by December 8, 2019 at the top of the issue. There are other possibly breaking changes that we will add at that time as well. I want to try a new approach of communicating with users (rather than "publish and wait for complaints").