Support a non-recursive mode

[bpasero]

In VS Code we have moved to parcel-bundler/watcher for most file watching tasks except for non-recursive watching where we still use node.js fs.watch. It would be great if we could have an option to disable the recursive watching and only watch:

• a folder and its children, or
• a file

Depending on the OS this would mean:

• Linux: not to recurse the file tree for adding watchers in children of children
• Windows: not setting bWatchSubtree for ReadDirectoryChangesW
• macOS: I could not find an option to drive this so it would probably require to do some filtering

[devongovett]

What's the use case for a non-recursive mode for VS Code?

[bpasero]

@devongovett we have an ask in microsoft/vscode#3025 to allow VSCode extensions to use our official API for monitoring folders for file changes. Out of the box we only watch the folders that are opened in VSCode using Parcel but extension might want to watch folders outside of the opened folders for changes.

To better control the overhead of file watching through this API, we would only install recursive file watchers if the extension indicates the need for it and otherwise just watch "flat". We are worried about the overhead of using recursive file watching everywhere, especially since the amount of changes are pretty much unbounded when watching recursively (less likely to be unbounded when watching just 1 hierarchy).

Specifically on Linux there is also a limit of open file handles you can have. Recursive file watching on Linux requires a folder handle per folder, so recursive file watching comes at a cost unfortunately.

To give an example: the TypeScript extension might have a desire to monitor any folder that is being added to node_modules/@types to update the language service for new type definitions that are getting installed. It would be sufficient to just monitor the folder itself and not watch recursively.