Improve typing of the union dispatcher function

[thegedge]

What does this PR do and why?

Closes #1627

Currently, the dispatcher function for union types has two issues with the typing on the dispatcher function:

1. The input snapshot is typed as any.
2. It expects any type to be returned.

This PR improves both of these by

1. typing the input snapshot so that it's an input snapshot for the union types, and
2. it restricts the possible types returned from the dispatcher to the types specified in the union.

Steps to validate locally

As always, this is all about the typechecking, so one would just have to play around with types.union and ensure it fails when you expect it to fail, and passes when you'd expect it to pass.

I've included a test to capture two key scenarios, but let me know if there should be more!

[coolsoftwaretyler]

Thanks @thegedge! I'll take a look soon. Will you please resolve the merge conflict? On my phone right now and GitHub is not showing precisely what's in conflict.

[thegedge]

Ahh, I think master on my fork wasn't up to date, so was just a conflict on the addition of the test. Fixed!

[coolsoftwaretyler]

Thank you! Will take a look soon!

[coolsoftwaretyler]

Ooh yeah, this is great.

Before this change, if you had the same test code, snapshot on dispatcher would be any, but this code gives much much better inference.

Before:

After:

And if you mess around with the union in the _brokenUnion case, you can also see the return types. Changing line 1403 to type.string turns the @ts-expect-error into an error itself:

I love it.

I think for consistency's sake, we should push this out behind the upcoming v7 breaking version. It's definitely a "fix", but the issue has been around for so long (at least four years, by count of the issue) that I can see a lot of people ending up with broken types in a patch upgrade.

Thanks for this

[coolsoftwaretyler]

praise: @thegedge - thank you for the extra inline documentation. Very helpful.