but I understand pretty much nothing here

Then check out what is going on in #1195 … no but seriously, do you think that I should write more comments?

I don't know, better ask someone familiar with Scenes/Stages/Wizards

I don't know, better ask someone familiar with Scenes/Stages/Wizards

Who would that be?

I also had no idea about these things before I started working on this PR, so I'd appreciate it if someone with more experience than me could have a look.

@dotcypress git blame told me that you an expert on this domain—would you mind reviewing this PR?

@IMalyugin @wwwat @foodornt you all seem to be interested in having TypeScript types for Stages/Scenes.

The types are fixed now. However, I have never used that feature of telegraf, so I have quite little experience with scenes etc. Can you please pull in the code from this branch and verify that

• the types work as expected,
• the PR does not alter the behaviour of the feature, and
• you can customise the types with your own session data and context objects in order to adjust them to your needs?

This would be very helpful. We cannot merge this without other people's approval :)

Regarding the third point: I will write (UPDATE: done) some examples about how to that. This is necessary anyway, but please don't hesitate to validate the first two things already!

Some type variables are redundant. It has to be possible to infer certain variables across session, scene.session, and session.__scenes. It is annoying to type the names multiple times, and also it does not make sense to specify them differently in different positions.

This needs to be figured out before a merge.

I added a lot of example bots. They illustrate every possible way to use the type variables. It's mostly redundant stuff, so it should be enough to check out the most basic one and the most advanced one for reviewing this PR.

There is a lot of nesting of the same objects for scenes and sessions and sessions in scenes and so on. This makes it very convenient to use, so I don't think we should change it, but it also makes the types a bit annoying internally. They are pretty much fine on the surface, though.

I figured out #1194 (comment).

The problem is that ctx.scene.session is an alias for ctx.session.__scenes. It is in fact possible to add type annotations to ctx.scene: SceneContextScene that infer this correctly, however, as soon as we extend scenes and add wizards, this logic breaks. It is not possible to keep up this alias without larger restructurings of the module, which I'd like to avoid.

As a consequence, whenever the scene session under ctx.scene.session is augmented, this type has to be specified twice, once in a place that is responsible for ctx.scene.session and once for ctx.session.__scenes. I added a large number of examples that illustrate this.

It is difficult to explain to new users why type inference works correctly for scenes but not for wizards in this place. Hence, it makes sense to simply advise to consequently specify both type variables for SceneContext and WizardContext whenever the scene/wizard-specific session is extended. Nothing can go wrong here, it may just be redundant in very special cases that are too rare to care about.

Please review and test #1224, after it's merged you can merge develop here to fix the conflict and // Enable graceful stop to all the new examples. I'll review this in the meantime.

I'd still be happy to get review from someone more experienced with the stuff before I approve.

@wojpawlik For reviewing this, it helps a lot to install ts-node and run the example bots. You can

bot.use(async (c,n) => { console.log(c.session); await n(); console.log(c.session); })

to inspect that the scenes actually do their job.

#705 also helps a lot, that's what I read before getting into it.

The types are easy to check by verifying that the scenes-bot-custom-context-and-session-and-scene-and-scene-session.ts compiles, which it does.

If no one else shows up and pops a question until the end of tomorrow, I'll merge.

I have tested example bots for both scenes and wizards thoroughly and they worked without problems. Writing the other example bots made me confident that the types are correct.

Even if we missed something here, the existing types will be an order of magnitude better than the current state, so the rest is fixing bugs (and I can do that).