fluxion-ts 0.5.1 → 0.6.1

package/README.md

@@ -12,7 +12,7 @@
 
 Fluxion is a filesystem-routing dynamic server for Node.js.
 
-- Route files from a dynamic directory(by chokidar)
+- Route files from a dynamic directory by chokidar or native `fs.watch`
 - Load API handlers by extension, default: `.ts`
 - Serve other files as static resources
 - Run the business server in worker processes
@@ -283,6 +283,7 @@ interface FluxionOptions {
   port: number;
   reloadDelay?: number;
   metaPort?: number;
+  nativeWatcher?: boolean;
   injections?: InjectionConfig[];
   moduleDir?: string;
   workerOptions?: Partial<WorkerOptions>;
@@ -318,6 +319,28 @@ Primary meta API port. Defaults to `port + 1` and must be different from `port`.
 
 Debounce delay for file re-registration. Defaults to `300` and must be at least `50`.
 
+### `nativeWatcher`
+
+Use native file watcher (`fs.watch`) instead of chokidar. Defaults to `false`.
+
+When set to `true`, Fluxion uses Node.js built-in `fs.watch()` for file watching. When `false` (default), it uses `chokidar` for better cross-platform compatibility.
+
+**Trade-offs:**
+
+- `chokidar` (default): Better cross-platform support, more stable, handles edge cases
+- `fs.watch`: Native implementation, lighter weight, but may have platform-specific quirks
+
+Example:
+
+```ts
+fluxion({
+  dir: './dynamicDirectory',
+  host: '127.0.0.1',
+  port: 3000,
+  nativeWatcher: true,  // use native fs.watch instead of chokidar
+});
+```
+
 ### `apiExts`
 
 Extensions registered as API handlers. Defaults to:
@@ -428,6 +451,28 @@ Primary meta API port. Defaults to `port + 1` and must be different from `port`.
 
 Debounce delay for file re-registration. Defaults to `300` and must be at least `50`.
 
+### `nativeWatcher`
+
+Use native file watcher (`fs.watch`) instead of chokidar. Defaults to `false`.
+
+When set to `true`, Fluxion uses Node.js built-in `fs.watch()` for file watching. When `false` (default), it uses `chokidar` for better cross-platform compatibility.
+
+**Trade-offs:**
+
+- `chokidar` (default): Better cross-platform support, more stable, handles edge cases
+- `fs.watch`: Native implementation, lighter weight, but may have platform-specific quirks
+
+Example:
+
+```ts
+fluxion({
+  dir: './dynamicDirectory',
+  host: '127.0.0.1',
+  port: 3000,
+  nativeWatcher: true,  // use native fs.watch instead of chokidar
+});
+```
+
 ### `apiExts`
 
 Extensions registered as API handlers. Defaults to:

package/dist/index.cjs

@@ -355,7 +355,7 @@ function normalizeOptions(options) {
         '**/.nyc_output/**',
         '**/*.tmp',
         '**/*.temp',
-    ], https, } = options;
+    ], https, nativeWatcher = false, } = options;
     const logger = options.logger ?? 'one-line';
     expectLoggerOption(logger);
     expect.isString(dir, 'FluxionOptions.dir must be a string');
@@ -397,6 +397,7 @@ function normalizeOptions(options) {
         include,
         apiInclude,
         exclude,
+        nativeWatcher,
         https: normalizeHttpsOptions(https, moduleDir),
     };
 }
@@ -2854,6 +2855,99 @@ class FluxionWatcher {
     }
 }
 
+class FluxionNativeWatcher {
+    constructor(cx) {
+        this.timer = null;
+        this.watcher = null;
+        this.filesChanged = new Set();
+        this.cx = cx;
+    }
+    /**
+     * Recursively register all files in the options directory.
+     */
+    init() {
+        const dirPath = path$1.isAbsolute(this.cx.options.dir)
+            ? this.cx.options.dir
+            : path$1.join(process.cwd(), this.cx.options.dir);
+        const registerRecursive = (dir, relativePath) => {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const entryPath = path$1.join(dir, entry.name);
+                const entryRelativePath = path$1.join(relativePath, entry.name);
+                if (entry.isDirectory()) {
+                    registerRecursive(entryPath, entryRelativePath);
+                }
+                else if (entry.isFile()) {
+                    try {
+                        this.cx.router.register(entryRelativePath);
+                    }
+                    catch (err) {
+                        this.cx.logger.error(`Error registering [${entryRelativePath}]: ${err.message}`);
+                    }
+                }
+            }
+        };
+        if (fs.existsSync(dirPath)) {
+            registerRecursive(dirPath, '');
+            this.cx.logger.info(`Initial registration complete for directory: ${this.cx.options.dir}`);
+        }
+        else {
+            this.cx.logger.warn(`Directory does not exist: ${this.cx.options.dir}`);
+        }
+        return this;
+    }
+    /**
+     * Since all actions are mapped to `rename` and `change` (WatchEventType).
+     *
+     * We could only record every file and reload them all.
+     */
+    start() {
+        this.init();
+        this.watcher = fs
+            .watch(this.cx.options.dir, { recursive: true }, (_eventType, filename) => {
+            if (!filename) {
+                return;
+            }
+            this.filesChanged.add(filename);
+            if (!this.timer) {
+                this.timer = setTimeout(() => {
+                    this.filesChanged.forEach((p, _, s) => {
+                        try {
+                            this.cx.router.register(p);
+                        }
+                        catch (err) {
+                            this.cx.logger.error(`Error refreshing handlers: ${err.message}`);
+                        }
+                        finally {
+                            s.delete(p);
+                        }
+                    });
+                    this.timer = null;
+                }, this.cx.options.reloadDelay);
+            }
+        })
+            .on('error', (err) => {
+            this.cx.logger.error(`Watcher error: ${err.message}`);
+            this.cx.logger.error(`Restarting watcher...`);
+            this.stop().start();
+        });
+        this.cx.logger.info(`Watcher started on directory: ${this.cx.options.dir}`);
+        return this;
+    }
+    stop() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.filesChanged.clear();
+        return this;
+    }
+}
+
 const balanced = (a, b, str) => {
     const ma = a instanceof RegExp ? maybeMatch(a, str) : a;
     const mb = b instanceof RegExp ? maybeMatch(b, str) : b;
@@ -5378,7 +5472,8 @@ async function fluxion(options) {
         // Replace logger with worker logger that prefixes PID
         context.logger = createWorkerLogger(context.logger, process.pid);
         // Only worker creates the watcher
-        context.watcher = new FluxionWatcher(context).start();
+        const Watcher = context.options.nativeWatcher ? FluxionNativeWatcher : FluxionWatcher;
+        context.watcher = new Watcher(context).start();
         initWorker(context);
     }
 }