feat(@jest/expect): Expose type of actual to Matchers

[benjaminjkraft]

Summary

Matchers isn't as typed as some users would like (see #13334, #13812). For users who want to customize it by extending the Matchers interface, it's useful to have access to the type of actual (the argument of expect) so you can do, say,

interface Matchers<R, T> {
    toTypedEqual(expected: T): R
}

This commit exposes it. The first-party matchers still have the same types as before.

Test Plan

typecheck

[mrazauskas]

Thanks! I think this is useful for custom matchers in general. For example, the inferred type of actual is used in snapshot matchers through @jest/expect. I think user of expect should be allowed to have similar functionality for a custom matcher.

Also because this was allowed before #12404 and still works with @types/jest. That's why I see this PR as a fix of a regression.

---

Could you add:

type N = Matchers<void, string>;

Under this line:

https://github.com/facebook/jest/blob/836157f4807893bb23a4758a60998fbd61cb184c/packages/expect/__typetests__/expect.test.ts#L21

Also please add a type test with your example of toTypedEqual here (simply to prevent regression):

https://github.com/facebook/jest/blob/836157f4807893bb23a4758a60998fbd61cb184c/packages/expect/__typetests__/expect.test.ts#L108-L109

[mrazauskas]

I think this can go under fixes as well.

Suggested change

	- `[@jest/expect]` provide type of `actual` as a generic argument to `Matchers` to allow better-typed extensions (#TBD)
	- `[expect, @jest/expect]` Provide type of `actual` as a generic argument to `Matchers` to allow better-typed extensions ([#13848](https://github.com/facebook/jest/pull/13848))

[benjaminjkraft]

Thanks for all the helpful comments! I think I've addressed all of them. A couple notes:

• I can't rename the variable to _T because if there are multiple declarations of an interface the type parameters get matched by name (so users would have to do Matchers<R, _T>). Sadly that means we need a ts-ignore as well as an eslint-ingore :( . Other ideas welcome.
• I put the expect type tests in a different file to show that users can declare either Matchers<R> or Matchers<R, T> (but typescript requires they are consistent within a file), and also added some to jest-expect since it has its own copy of the wiring

[mrazauskas]

What about this:

Suggested change

	// @ts-expect-error unused variable T (can't use _T since users redeclare Matchers)
	// eslint-disable-next-line @typescript-eslint/no-unused-vars
	export interface Matchers<R extends void | Promise<void>, T = unknown> {
	export interface Matchers<R extends void | Promise<void>, T = unknown> {
	/** @internal */
	_doKeepT(expect: T): R;

[mrazauskas]

Could have some longer comment, but seems to be working. Or?

stripInternal documentation: https://www.typescriptlang.org/tsconfig#stripInternal

[benjaminjkraft]

Ah, great! I thought of adding a fake method but didn't realize I could hide it like that.

[mrazauskas]

Two last details from my side. The rest looks good.

Type tests are passing, because emitted types keep T as expected:

It is marked as unused in this screenshot of .d.ts file. So I went checking if that is not a problem for a user having "skipLibCheck": true in a tsconfig.json. TypeScript did not complain. Seems to be fine.

[benjaminjkraft]

It is marked as unused in this screenshot of .d.ts file. So I went checking if that is not a problem for a user having "skipLibCheck": true in a tsconfig.json. TypeScript did not complain. Seems to be fine.

Thanks for checking, I looked at the .d.ts but didn't think to check if it could cause upstream errors. Just to confirm, this works even if they also have noUnusedParameters enabled?

[mrazauskas]

Just to confirm, this works even if they also have noUnusedParameters enabled?

Yes, noUnusedParameters was enabled and in general it was rather strict TS configuration.

[SimenB]

skipLibCheck: false I assume?

[mrazauskas]

Right, false it was. I had in mind that it was enabled, so fingers typed true (;

[SimenB]

thanks!

[SimenB]

https://github.com/facebook/jest/releases/tag/v29.4.2

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.