Add overloads for mock functions, fully expand out d.ts file

[jakebailey]

Here's a potential adjustment to the API and code to allow for overloads with to support a positional import.meta.url.

Making the PR to your branch to not duplicate things; I want to see if CI passes (they do locally).

[jakebailey]

Darn, I guess CI won't run since this isn't targeting the master branch.

[jakebailey]

Let me retarget this at master (temporarily) to check CI, but 7651cf6 (#122) is the actual change.

[jakebailey]

I'm making the assumption that err is not a part of the public API. I would like to make that same argument about opt, if possible, but I wasn't sure either way.

[jakebailey]

GitHub Actions was erroring so my windows runs got cancelled :(

(reran, CI passes, yay)

[jakebailey]

Verified that this works on my project with "esmock": "jakebailey/esmock#parent-param" and adding the parameter.

[iambumblehead]

This looks great. The adapter function is a great idea and the comments are great. Should we merge it?

[iambumblehead]

I'm afk starting now btw so might not see any response for awhile

[jakebailey]

If you're happy with it sure. My remaining questions are:

• Is opt part of the API, or just used to call esmock internally with extra options? If so, I'd like to drop it from the signature if possible. If it is part of the public API, then I'll fix the d.ts file to be accurate.
• Are you happy with the parameter names? The ones that used to be in the d.ts file were more clear to me, but the implementation uses different ones (even in other files). I went for consistency then added a big comment instead.
• And a bigger question; if you don't want to transpile esmock itself from TypeScript, would you be open to using inline comments for types and enable type checking? It's hard for me to be confident that what I'm writing is correct; I think types would help, but I don't know what your dev workflow is. It's fine if you don't want these, as my own need is satisfied once this PR is in.

[jakebailey]

RE: types, I can totally just ignore that for this PR and send a PR showing an example another day, so really, just the first two questions are what I need. 😄

[iambumblehead]

Supporting opts allows esmock to be called with many options at once and it allows future options to be added easily (for me). From my perspective, opts is the main way to control esmock and the "p" and "px" functions are sugar for calling esmock with common predefined opts values.

It would be good for esmock to use the same namings everywhere and it will happen soon, I believe, but until then I'm okay with different names being used.

[jakebailey]

Cool, thanks. I'll go inspect everything for some opts to document, then.

[iambumblehead]

Your PR re-exports types definitions from inside the "tests" folder so they aren't duplicated (just noticed this) and the type definitions are more specific and better than the previous ones. Great improvements.

[jakebailey]

I've added the options type.

Unfortunately, though, I'm not sure that I can continue to use esmock in my project; it turns out that ESM loaders aren't compatible with coverage gathering due to various issues (bcoe/c8#325); in my case, I thought that my project had been 100% tested, when in fact there are whole files I forgot to test. Not adding the esmock loader lets me see that in my testing; presumably this is because the mocked version of that module is loaded, the coverage sees that it was used, and so gets 100%, when all that happened was that it was mocked.

There is another (competing?) ESM mocker called mock-import, which can be used with another coverage program by the same author, but while it does work fine enough to mock things (though worse than esmock in that it cannot handle mocking in parallel), it also has issues with coverage.

I'm not sure that this is in scope of esmock at all, unless there's a way to load mock files as completely different paths internally (but correctly set their import.meta.url to where they would be); something I might look into.

[jakebailey]

CI failure is a flake; my commit only changed the types, so this should me mergable.

[jakebailey]

These could be documented; not sure quite what to write as personally I would suggest that people use the named functions to set these instead (i.e. treat options as an internal implementation detail).

[jakebailey]

This date's now wrong; feel free to change.

[iambumblehead]

That's too bad about the CI coverage. Things are looking pretty good here. If you recommend any links with relevant info, they could be added to the README or wiki here to give people a warning about the coverage issue.

Thanks for hanging out here and making a great contribution.

[iambumblehead]

oh of course you did give a link I'll read through that thanks

[iambumblehead]

I hope I'm not doing anything rude by merging this. I believe you are sharing it for merge so I'm going to hit merge. There are few changes coming over the next week or two and it would be great to get this now.

[jakebailey]

Yes, I switched this from a draft on purpose! Thanks for merging this.