@types/jest Use Mock in MockedFunction

[jacksteamdev]

This change allows MockedFunction to be used where Mock can be used. I don't think this fundamentally changes MockedFunction, just makes it more robust. This would resolve issues where an extended expect method takes a Mock type, but the mocking library uses MockedFunction.

Related issues:
extend-chrome/jest-chrome#9
jest-community/jest-extended#292

Please fill in this template.

• Use a meaningful title for the pull request. Include the name of the package modified.
• Test the change in your own code. (Compile and run.)
• Add or edit tests to reflect the change.
• Follow the advice from the readme.
• Avoid common mistakes.
• Run npm test <package to test>.

Select one of these and delete the others:

If changing an existing definition:

• Provide a URL to documentation or source code which provides context for the suggested changes: <Fix toHaveBeenCalledBefore/toHaveBeenCalledAfter type definition jest-community/jest-extended#292>
• If this PR brings the type definitions up to date with a new version of the JS library, update the version number in the header.

[typescript-bot]

👋 Hi there! I’ve run some quick measurements against master and your PR. These metrics should help the humans reviewing this PR gauge whether it might negatively affect compile times or editor responsiveness for users who install these typings.

Let’s review the numbers, shall we?

Comparison details 📊

	master	#50720	diff
Batch compilation
Memory usage (MiB)	91.2	89.6	-1.9%
Type count	15937	15945	0%
Assignability cache size	5085	5085	0%
Language service
Samples taken	2612	2612	0%
Identifiers in tests	2612	2612	0%
getCompletionsAtPosition
Mean duration (ms)	452.3	433.7	-4.1%
Mean CV	6.5%	7.1%
Worst duration (ms)	650.3	618.4	-4.9%
Worst identifier	toBe	expected
getQuickInfoAtPosition
Mean duration (ms)	456.4	437.9	-4.1%
Mean CV	7.1%	7.7%
Worst duration (ms)	699.5	586.2	-16.2%
Worst identifier	a	toBe

It looks like nothing changed too much. I won’t post performance data again unless it gets worse.

[typescript-bot]

@jacksteamdev Thank you for submitting this PR! I see this is your first time submitting to DefinitelyTyped 👋 — I'm the local bot who will help you through the process of getting things through.

This is a live comment which I will keep updated.

1 package in this PR

• jest on npm, on unpkg

Code Reviews

Because this is a widely-used package, a DT maintainer will need to review it before it can be merged.

Status

• ✅ No merge conflicts
• ✅ Continuous integration tests have passed
• ❌ Most recent commit is approved by a DT maintainer

Once every item on this list is checked, I'll ask you for permission to merge and publish the changes.

Inactive

This PR has been inactive for 34 days — it is still unreviewed!

---

Diagnostic Information: What the bot saw about this PR

{
  "type": "info",
  "now": "-",
  "pr_number": 50720,
  "author": "jacksteamdev",
  "headCommitOid": "fe85fdfd985f8ede19974ce4b1cff4a4bf126e37",
  "lastPushDate": "2021-02-02T17:08:56.000Z",
  "lastActivityDate": "2021-03-07T12:11:40.000Z",
  "maintainerBlessed": false,
  "hasMergeConflict": false,
  "isFirstContribution": true,
  "popularityLevel": "Critical",
  "pkgInfo": [
    {
      "name": "jest",
      "kind": "edit",
      "files": [
        {
          "path": "types/jest/index.d.ts",
          "kind": "definition"
        },
        {
          "path": "types/jest/jest-tests.ts",
          "kind": "test"
        }
      ],
      "owners": [
        "NoHomey",
        "jwbay",
        "asvetliakov",
        "alexjoverm",
        "epicallan",
        "ikatyang",
        "wsmd",
        "JamieMason",
        "douglasduteil",
        "ahnpnl",
        "joshuakgoldberg",
        "UselessPickles",
        "r3nya",
        "hotell",
        "sebald",
        "andys8",
        "antoinebrault",
        "gstamac",
        "ExE-Boss",
        "quassnoi",
        "Belco90",
        "tonyhallett",
        "ycmjason",
        "devanshj",
        "pawfa",
        "regevbr",
        "gerkindev"
      ],
      "addedOwners": [],
      "deletedOwners": [],
      "popularityLevel": "Critical"
    }
  ],
  "reviews": [],
  "ciResult": "pass"
}

[typescript-bot]

🔔 @NoHomey @jwbay @asvetliakov @alexjoverm @epicallan @ikatyang @wsmd @JamieMason @douglasduteil @ahnpnl @JoshuaKGoldberg @UselessPickles @r3nya @Hotell @sebald @andys8 @antoinebrault @gstamac @ExE-Boss @quassnoi @Belco90 @tonyhallett @ycmjason @devanshj @pawfa @regevbr @GerkinDev — please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

[rbuckton]

I'm not certain this is the correct change. Note that Mock defines both call and construct signatures, which makes it a bit complex. MockedFunction and MockedClass are more specific types that intersect a MockInstance with the type of the function provided, to ensure the type is both understood to be a mock and to preserve the original signature.

My assumption, after some sleuthing across various PRs over the years, is that Mock is a bit of a legacy definition. In the Jest definitions, it's only used by jest.fn and jest.isMock, and those definitions probably need to be updated:

DefinitelyTyped/types/jest/index.d.ts

Lines 163 to 170 in fe85fdf

	/**
	* Creates a mock function. Optionally takes a mock implementation.
	*/
	function fn(): Mock;
	/**
	* Creates a mock function. Optionally takes a mock implementation.
	*/
	function fn<T, Y extends any[]>(implementation?: (...args: Y) => T): Mock<T, Y>;

Should probably be something more like this:

function fn(): Mock;
function fn<F extends (...args: any[]) => any>(implementation?: F): MockedFunction<F>;
function fn<F extends new (...args: any[]) => any>(implementation?: F): MockedClass<F>;

DefinitelyTyped/types/jest/index.d.ts

Lines 177 to 180 in fe85fdf

	/**
	* Returns whether the given function is a mock function.
	*/
	function isMockFunction(fn: any): fn is Mock;

Should probably be something more like this (to preserve the type information):

function isMockFunction<F extends (...args: any[]) => any>(fn: F): fn is MockedFunction<F>;
function isMockFunction<F extends new (...args: any[]) => any>(fn: F): fn is MockedClass<F>;
function isMockFunction(fn: any): fn is Mock;

The only reason jest.fn() (without arguments) should return Mock is because the resulting function can be used for either call or construct operations. One could also argue that it could just return something like MockedFunction<any> & MockedClass<any> instead. I would venture to guess that 3rd party APIs such as jest-extended most likely want to depend on the input type just being a MockInstance, or a specific MockedFunction or MockedClass if the input must be either callable or constructable.

Due to the possible repercussions a change like this could have, I would like to have one of the definitions owners weigh in on this PR. I'd also like someone to weigh in on whether Mock should be considered deprecated in favor of MockInstance/MockedFunction/MockedClass (in which case we might consider adding a /** @deprecated */ comment to the interface).

[jacksteamdev]

@rbuckton Totally agree. Thanks for the detailed analysis! Deprecating Mock would be a big help to get library authors to type methods correctly.

[typescript-bot]

Re-ping @NoHomey, @jwbay, @asvetliakov, @alexjoverm, @epicallan, @ikatyang, @wsmd, @JamieMason, @douglasduteil, @ahnpnl, @JoshuaKGoldberg, @UselessPickles, @r3nya, @Hotell, @sebald, @andys8, @antoinebrault, @gstamac, @ExE-Boss, @quassnoi, @Belco90, @tonyhallett, @ycmjason, @devanshj, @pawfa, @regevbr, @GerkinDev:

This PR has been out for over a week, yet I haven't seen any reviews.

Could someone please give it some attention? Thanks!

[typescript-bot]

It has been more than two weeks and this PR still has no reviews.

I'll bump it to the DT maintainer queue. Thank you for your patience, @jacksteamdev.

(Ping @NoHomey, @jwbay, @asvetliakov, @alexjoverm, @epicallan, @ikatyang, @wsmd, @JamieMason, @douglasduteil, @ahnpnl, @JoshuaKGoldberg, @UselessPickles, @r3nya, @Hotell, @sebald, @andys8, @antoinebrault, @gstamac, @ExE-Boss, @quassnoi, @Belco90, @tonyhallett, @ycmjason, @devanshj, @pawfa, @regevbr, @GerkinDev.)

[elibarzilay]

@jacksteamdev -- Sounds like this should be closed following @rbuckton's comment and your reply--?