feat: ability to decorate esm module name before importing it

[j0tunn]

Description of the Change

This PR adds ability to decorate ESM-module name right before it will be imported by passing esmDecorator function to loadFilesAsync method.

Why should this be in core?

It helps to deal with ESM cashing issues just by adding some query parameters to modue name:

mocha.loadFilesAsync({
    esmDecorator: file => `${file}?foo=bar`
})

And it backwards compatible.
Note though that the sub-dependencies of the test files will not be reloaded.

Applicable issues

• ESM Import is cached when re-using the process when using mocha programmatically #4655

It is an enhancement (minor release).

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: j0tunn / name: Anton Usmansky (93082f2)

[juergba]

@giltayar could you have a look a this PR, please?

[coveralls]

Coverage increased (+0.002%) to 94.328% when pulling 93082f2 on j0tunn:master into 8f3c37b on mochajs:master.

[giltayar]

Besides the comment I added, I am not sure why we need this. What is the use case behind it? Who will use this additional parameter and for what use case.

Until we understand this, I'm not sure we should merge this PR.

[j0tunn]

Who will use this additional parameter and for what use case.

Any who has problems with esm modules caching while using mocha by API:

• loadFilesAsync and unloading files #4924
• ESM Import is cached when re-using the process when using mocha programmatically #4655

node.js doc suggests only one whay to deal with it - different queries.

There are not too many such cases for now because most of the existing community uses CJS modules for tests for now. But there will be more.
You have a bunch of code for dealing with CJS modules cache, but nothing for ESM-modules. And while this cache problem is not solved you can't say you have full support of ESM modules.

[giltayar]

@j0tunn Ah. I didn't know that Mocha.prototype.loadFileAsync was used as an API. In that case it makes total sense given that decorating the urls is the only way to load a different instance of the test files.

Note though that the sub-dependencies of the test files will not be loaded. You will probably need an ESM loader for that.

So if you change the small change that I requested, and add appropriate tests, this PR will be approved by me. But don't forget those tests...

[j0tunn]

@giltayar done

[giltayar]

@juergba from my point of view, we're good to go on this PR, which makes a lot of sense for developers using the API in an ESM setting.

[juergba]

@giltayar thank you for your review. 👍

I will have a look at this PR on coming weekend, @j0tunn please have some patience.

[juergba]

@j0tunn Mocha has its own --require option which is able to load ESM modules as well. How does it behave with this PR?

Could you provide a short sample for me to do some testing, please?

@fvictorio would you mind reviewing this PR? Does it fix your issue?

[j0tunn]

@juergba

@j0tunn Mocha has its own --require option which is able to load ESM modules as well. How does it behave with this PR?

As far as I understand --require option is about cli. This PR is about API. These are for different use cases. They are not conflicting if that is your question.

Could you provide a short sample for me to do some testing, please?

There is a short sample in PR description. In case of using mocha by API someone can use this feature like this in its own code to avoid esm-modules cache problem:

mocha.loadFilesAsync({
    esmDecorator: file => `${file}?foo=${new Date()}`
});

[fvictorio]

Thanks a lot for working on this @j0tunn!

I can confirm this seems to fix my issue if I do something like this:

        await (mocha as any).loadFilesAsync({
          esmDecorator: (file) => `${file}?invalidateCache=${Math.random()}`
        });

Notice the as any: I think this will need a PR in @types/mocha. I can do that, but I'm not familiar with the process. Do you have to wait until this is released before updating the types?

[juergba]

[...] I think this will need a PR in @types/mocha [...]

I don't know, @types/mocha isn't maintained by us. Normally we publish first, then the types get adapted.

I can confirm this seems to fix my issue if I do something like this

I won't merge this PR without any testing, this could take some time though.

Note though that the sub-dependencies of the test files will not be loaded.

@j0tunn could you add this statement to this PR's description, please?

[j0tunn]

@j0tunn could you add this statement to this PR's description, please?

Done.

[juergba]

@j0tunn thank you