From bad7dce71e18421d9ac13ba4fbe254656417e173 Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Thu, 19 Sep 2024 10:20:08 +0700
Subject: [PATCH] fix: remove fsevents from docs and JSDoc

Removes `fsevents` from the current documentation and the JSDoc/types.
---
 README.md      | 10 ++--------
 src/handler.ts |  5 +++--
 2 files changed, 5 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 80b6c543..24b8194f 100644
--- a/README.md
+++ b/README.md
@@ -144,9 +144,7 @@ recursively.
 #### Persistence
 
 * `persistent` (default: `true`). Indicates whether the process
-should continue to run as long as files are being watched. If set to
-`false` when using `fsevents` to watch, no more events will be emitted
-after `ready`, even if the process continues to run.
+should continue to run as long as files are being watched.
 
 #### Path filtering
 
@@ -180,10 +178,6 @@ to true (1) or false (0) in order to override this option.
   * `binaryInterval` (default: `300`). Interval of file system
   polling for binary files.
   ([see list of binary extensions](https://github.com/sindresorhus/binary-extensions/blob/master/binary-extensions.json))
-* `useFsEvents` (default: `true` on MacOS). Whether to use the
-`fsevents` watching interface if available. When set to `true` explicitly
-and `fsevents` is available this supercedes the `usePolling` setting. When
-set to `false` on MacOS, `usePolling: true` becomes the default.
 * `alwaysStat` (default: `false`). If relying upon the
 [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)
 object that may get passed with `add`, `addDir`, and `change` events, set
@@ -254,7 +248,7 @@ execute a command on each change, or get a stdio stream of change events.
   `Error: watch /home/ ENOSPC`
     * This means Chokidar ran out of file handles and you'll need to increase their count by executing the following command in Terminal:
   `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`
-* Upgrade to latest chokidar, to prevent fsevents-related issues:
+* If using 3.x, upgrade to latest chokidar to prevent fsevents-related issues:
     * `npm WARN optional dep failed, continuing fsevents@n.n.n`
     * `TypeError: fsevents is not a constructor`
 
diff --git a/src/handler.ts b/src/handler.ts
index 7bd12326..feb19975 100644
--- a/src/handler.ts
+++ b/src/handler.ts
@@ -140,7 +140,7 @@ const FsWatchInstances = new Map<string, FsWatchContainer>();
  * @param listener main event handler
  * @param errHandler emits info about errors
  * @param emitRaw emits raw event data
- * @returns new fsevents instance
+ * @returns {NativeFsWatcher}
  */
 function createFsWatchInstance(
   path: string,
@@ -148,7 +148,7 @@ function createFsWatchInstance(
   listener: WatchHandlers['listener'],
   errHandler: WatchHandlers['errHandler'],
   emitRaw: WatchHandlers['rawEmitter']
-) {
+): NativeFsWatcher | undefined {
   const handleEvent: WatchListener<string> = (rawEvent, evPath: string | null) => {
     listener(path);
     emitRaw(rawEvent, evPath!, { watchedPath: path });
@@ -169,6 +169,7 @@ function createFsWatchInstance(
     );
   } catch (error) {
     errHandler(error);
+    return undefined;
   }
 }