Improve errors. Add actual and expected types to MismatchArgs

[trevorade]

Updates MismatchArgs to, rather than create the tuple [never], creates a tuple with an object literal containing the Actual type and the expected type.

How the expected type is shown depends on the specific match. I will most likely post screenshots showing the errors for the various matchers in the PR conversation.

I left toBeCallableWith and toBeConstructibleWith alone as these do not use MismatchArgs and I couldn't work out how to use Variadic Tuple Types to make it work. These error messages are easier to understand anyways.

If microsoft/TypeScript#40468 is merged, we could drop MismatchArgs in favor of having a return that, rather than return true, uses a type throw if the type does not match.

[trevorade]

When hovering over an error in VSCode, you get a legible message showing the actual and expected type:

This also works with .not:

More complicated types work with toEqualTypeOf as well:

As well as toMatchTypeOf:

All matcher functions which make use of MismatchArgs are supported:

---

Known issues

For toEqualTypeOf and toMatchTypeOf, if you pass a param rather than explicitly specifying the type, the overload at times prevents the useful error message from showing:

The error message can still be seen in a flat manner if you try to enter a second param:

Similarly, sometimes the passed-in param clobbers the mismatch args:

Again, the error message can be seen if you try to enter a second param:

So, as seen, this improves the situation for error messages in expect-type but does not solve it. Having throw be supported for types is really what this library needs.

[mmkal]

This is nice! DX looks nicer here. I haven't run this locally yet, and I have the same question that was raised on the type-fest PR: this doesn't help with CLI error messages, right? Not a blocker, it would still be an improvement.

Some other questions/comments:

Can we build something into MismatchArgs and its first typearg so that we don't have to repeat the "core" type? e.g.

toBeNumber: (...MISMATCH: MismatchArgs<Extends<Actual, number>, ExpectedResult, Actual, {extends: number}>)

Would be nicer something like this:

toBeNumber: (...MISMATCH: MismatchArgs<ShouldExtend<Actual, number>, ExpectedResult>)

Where ShouldExtend could be a wrapper for Extend which adds the extra info for these errors.

Another thing worth noting, esp if the CLI errors aren't improved - you can get intellisense to show you the types on hover, but by hovering on the method, not in the error message. I'll share a screenshot when I can.

Also, in the previous repo this library lived in, I had a PR for throw types, worth taking a look if you're interested: mmkal/ts#152. There are also some other template string type tricks in there that maybe we could borrow from.

[trevorade]

Can we build something into MismatchArgs and its first typearg so that we don't have to repeat the "core" type?

Here's what that implementation looks like (based on my version anyways):

(Note: MismatchArgsNew would be named MismatchArgs as expected. I only implemented the change for toBeAny as a proof of concept)

This pattern necessitates writing new types. That is, we can't really directly use IsAny anymore as that is used elsewhere and is exported, we need to add a new CheckIsAny that resolves to a CheckResult type.

This has the advantage of keeping interface ExpectTypeOf a bit cleaner at the cost of more indirection and more lines of checks (probably 6 or 7 CheckXyz types). CheckExtends will be re-used a fair amount so that should reduce code duplication a bit.

I'm happy to fully implement this update but I'd like to make sure we're satisfied with this implementation pattern before committing to it.

[mmkal]

@trevorade thanks again for this. I do like the idea of another helper type here, especially because I think it'd be good to be able to play around a bit with the { actual: ...; expected: ... } structure.

The discussion on your type-fest PR got me thinking more generally about whether there wasn't some semi-low-hanging fruit where a bit more effort/complexity on the library side could improve the DX fairly significantly. And I also wanted to capture exactly what error messages looked like so it wasn't as necessary to share screenshots about what they looked like. And the existing tests only have valid code - so I added a file errors.test.ts which uses the typescript compiler API and does a jest snapshot of what the errors for some invalid code look like. If you could merge from main, I'd be interested to see if this branch improves them at all, or if it would when combined with #16 - also, it would be great to get your feedback on that if you have any. Sorry to say that it looks like there are some conflicts now - let me know if you need any help resolving them.

[mmkal]

Oh also I invited you to be a collaborator on this repo, so if you'd like to create a branch here instead of on your fork, feel free.

[trevorade]

Thx for the collaborator invite! I appreciate it.

I like the idea of capturing error messages in errors.test.ts! I'll utilize that for this PR where it makes sense.

I'll get a chance to work on this more tomorrow.

[mmkal]

@trevorade now that #16 is merged I think this is out of date. But if there's an improvement on top of #16 you'd like to make, let me know. It should probably be in a new PR though since this is conflicted now, so I'll close for now.

Note - I will aim to cut a 1.0.0 release this week if all goes well, so ideally any changes that don't happen before then are non-breaking so I don't have to go to 2.0.0 embarrassingly quickly!