feat: esbuild support for addWatchFile and getWatchFiles

[edemaine]

🔗 Linked issue

#53 (for esbuild)

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR adds this.addWatchFile support for esbuild in the context of hooks resolveId, load, and transform.

• The implementation is similar to how this.warn and this.error were already implemented, which is to build an array for the hook context and then return it from the esbuild hook.
• To support resolveId, I had to .call resolveId with this set to the actual context, whereas previously resolveId was called with this set to the options object. I believe the new behavior aligns with the Rollup spec.
• I factored out a createEsbuildPluginContext helper because we needed it for both resolve and build.

I also added a basic this.getWatchFiles() which returns the current array of watched files added via this.addWatchFile.

• My understanding is that this doesn't match the Rollup spec of returning all watched files, including implicitly watched files. I've added a note to the README accordingly.
• But this behavior seems better than nothing / the current behavior of returning the empty array.
• I could also remove it if this seems too partial an implementation.

Context:

• We need this.addWatchFile for a transpiling unplugin because resolveId returns a not-real filename (with added .tsx extension to force the output to behave like TypeScript).
• Also because esbuild only automatically watch files with a context of "file", and unplugin sets the context to the plugin name, so esbuild --watch currently doesn't work at all.

I also removed some accidental (I think) modification of the context object via Object.assign.

I have tested this in the context of our unplugin, but I'm not sure how to write tests for this within the current testing infrastructure.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[sxzz]

LGTM, @antfu could plz you review together?

[antfu]

Adding this would indicate that it works for every bundler. Would love to have a simple test for it.

[edemaine]

I added a simple test for this in resolveId (and perhaps we should in transform and load too).

And good that we tested: Webpack doesn't do this. Does anyone know whether Resolvers in Webpack can access a compilation object, so we can call createContext? I didn't see an easy way... One option would be to throw an error in these situations.

[edemaine]

I've done a bunch of searching and it seems like loaders and resolvers are treated very differently in Webpack, and only loaders have all the APIs we need. I'm unclear whether a loader can be used as a resolver. But at least for now, I've added the same consistent interface to resolveId (so types work and function calls don't crash from lack of functions), but most of the API functions throw errors. (Some do work; I could implement error, warn, and parse still.)

Also documented the limitations here (which are fewer than before — previously resolveId offered no this API in Webpack or esbuild).

[edemaine]

@antfu This should be ready for re-review when you get a chance. Thanks!

[edemaine]

Any chance this could be merged and released? It's a bottleneck for Civet now, and I'd prefer not to depend on a fork.

Alternatively, I could remove the changes to resolveId if they're too controversial, and just keep the changes for esbuild in load, which is what we really need (because this is the only place addWatchFile is supported across all build systems.

[edemaine]

Thank you!!