Feature request: debounce delay in watch mode

[olivier-thatch]

When esbuild is running in watch mode and it detects a change, it immediately triggers a new build. If many files are being updated in a very short timeframe, this can cause build errors (if e.g. some files are missing). The build will eventually succeed, but the build errors are noisy.

For example, in our case we use orval to generate a TypeScript client library for our backend API. When orval is invoked, it deletes all of the existing client library files and regenerates them from scratch. esbuild picks up on the first event and triggers a rebuild while orval is not done regenerating the library, which causes the build to fail. Once orval is done, esbuild runs again and the build succeeds.

This could be solved by adding a debounce delay configuration option for esbuild's watch mode. Something like this:

await ctx.watch({ debounce: 1000 })

With this option, when a file event occurs, esbuild would wait for the specified delay before triggering a new build, and the wait period would be reset to the full debounce delay if any other file event occurs.

[evanw]

This sounds reasonable.

However, I think it would be more straightforward as delay than debounce. With esbuild's poll-based model (see the docs for details), esbuild doesn't actually get any file system events. Instead it gradually scans the files involved in the previous build for changes over time and prioritizes more frequent scans of more recently changed files. Debouncing with this model would behave strangely as a full scan can take up to 2 seconds, meaning the granularity of the debounce delay is an implementation detail but it might be in 2 second intervals, with a minimum delay of 4 seconds to check everything twice. Either that or esbuild would have to scan everything very quickly and burn a lot of CPU, but that's not something that people generally want.

So calling it delay and implementing it as a delay makes it possible to add something like this now, and leave the option open for potentially also adding a real debounce in the future if esbuild's polling implementation ever changes.

Edit: Note that another option is to not delete the client library files and regenerate them from scratch, but to instead generate them into a separate directory and then quickly swap the directory into place (or equivalently change where a symlink points to). That would involve adding a little bit of logic to the script that invokes orval.

[olivier-thatch]

Thanks for implementing this! I will upgrade esbuild and experiment with the new delay option.