@nasriya/overwatch - npm Package Compare versions

Comparing version 1.1.0 to 1.1.1

dist/@types/overwatch.d.ts

 import Watcher from "./watcher/Watcher";
 import { WatchOptions } from "./docs/docs";
 export type { WatchOptions, OnWatchedDataUpdateHandler, onWatchedDataRemoveHandler, onWatchedDataRenameHandler, onWatchedDataAddHandler, WatchedDataChangeEvent, onWatchedDataChangeHandler, RenameEvent, UpdateEvent, RemoveEvent, AddEvent, ChangeEvent, WatchedFile, WatchedFolder, WatchedData } from './docs/docs';
+export { Watcher } from "./watcher/Watcher";
 declare class Overwatch {
@@ -59,4 +60,55 @@ #private;
     set detectionInterval(interval: number);
+    /**
+     * Provides runtime control over the internal scanning engine.
+     *
+     * Use this property to pause or resume the file system scanning engine manually,
+     * without removing or altering existing watchers. This is useful for temporarily
+     * reducing resource usage during periods when file monitoring is not needed.
+     *
+     * Example:
+     * ```ts
+     * overwatch.control.pause();  // Temporarily stop scanning
+     * overwatch.control.resume(); // Resume scanning
+     * console.log(overwatch.control.isRunning()); // Check engine state
+     * ```
+     *
+     * This property is read-only and exposes the following methods:
+     * - `pause()` – Stops the internal scanning engine.
+     * - `resume()` – Starts or resumes scanning.
+     * - `isRunning()` – Returns a boolean indicating whether scanning is active.
+     */
+    readonly control: Readonly<{
+        /**
+         * Starts or resumes the internal scanning engine.
+         *
+         * This method triggers the engine responsible for detecting changes to all watched paths.
+         * If the engine is already running, calling this again has no effect.
+         *
+         * Use this to resume file system monitoring after calling `pause()`.
+         * @since v1.1.0
+         */
+        resume: () => void;
+        /**
+         * Temporarily pauses the internal scanning engine.
+         *
+         * While paused, the system will not scan for changes or emit any file system events.
+         * Existing watchers remain intact and will resume functioning once `resume()` is called.
+         *
+         * Useful for temporarily reducing I/O load without removing watchers.
+         * @since v1.1.0
+         */
+        pause: () => void;
+        /**
+         * Indicates whether the scanning engine is currently active.
+         *
+         * @returns `true` if the engine is currently scanning for changes,
+         *          `false` if it has been paused via `pause()`.
+         *
+         * You can use this to programmatically check the system state before pausing or resuming.
+         * @since v1.1.0
+         */
+        isRunning: () => boolean;
+    }>;
 }
 declare const overwatch: Overwatch;
 export default overwatch;

dist/@types/vom/vom.d.ts

@@ -16,5 +16,18 @@ import Snapshot from "./snapshot";
      * The dispatch interval is used to check for changes such as added, removed, or renamed files and directories.
+     * @since v1.0.0
      */
     dispatch(): void;
     /**
+     * Pauses the dispatch interval for checking for changes in the virtual object structure.
+     * The dispatch interval is used to check for changes such as added, removed, or renamed files and directories.
+     * @since v1.1.0
+     */
+    pause(): void;
+    /**
+     * Whether the VirtualObjectManager is currently running and checking for changes.
+     * @returns true if the VirtualObjectManager is running, false otherwise.
+     * @since v1.1.0
+     */
+    get isRunning(): boolean;
+    /**
      * The interval (in milliseconds) at which the virtual object structure is checked for changes.
@@ -21,0 +34,0 @@ * This interval is used to check for changes such as added, removed, or renamed files and directories.

dist/@types/watcher/Watcher.d.ts

 import { onWatchedDataAddHandler, onWatchedDataChangeHandler, onWatchedDataRemoveHandler, onWatchedDataRenameHandler, OnWatchedDataUpdateHandler, WatchOptions } from "../docs/docs";
-declare class Watcher {
+export declare class Watcher {
     #private;
@@ -4,0 +4,0 @@ constructor(path_: string, type: 'File' | 'Directory', watchOptions?: WatchOptions);

dist/cjs/overwatch.js

@@ -6,2 +6,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Watcher = void 0;
 const atomix_1 = __importDefault(require("@nasriya/atomix"));
@@ -13,2 +14,4 @@ const vom_1 = __importDefault(require("./vom/vom"));
 const fs_1 = __importDefault(require("fs"));
+var Watcher_2 = require("./watcher/Watcher");
+Object.defineProperty(exports, "Watcher", { enumerable: true, get: function () { return Watcher_2.Watcher; } });
 class Overwatch {
@@ -257,4 +260,55 @@ #_vom = new vom_1.default();
     }
+    /**
+     * Provides runtime control over the internal scanning engine.
+     *
+     * Use this property to pause or resume the file system scanning engine manually,
+     * without removing or altering existing watchers. This is useful for temporarily
+     * reducing resource usage during periods when file monitoring is not needed.
+     *
+     * Example:
+     * ```ts
+     * overwatch.control.pause();  // Temporarily stop scanning
+     * overwatch.control.resume(); // Resume scanning
+     * console.log(overwatch.control.isRunning()); // Check engine state
+     * ```
+     *
+     * This property is read-only and exposes the following methods:
+     * - `pause()` – Stops the internal scanning engine.
+     * - `resume()` – Starts or resumes scanning.
+     * - `isRunning()` – Returns a boolean indicating whether scanning is active.
+     */
+    control = atomix_1.default.dataTypes.record.freeze({
+        /**
+         * Starts or resumes the internal scanning engine.
+         *
+         * This method triggers the engine responsible for detecting changes to all watched paths.
+         * If the engine is already running, calling this again has no effect.
+         *
+         * Use this to resume file system monitoring after calling `pause()`.
+         * @since v1.1.0
+         */
+        resume: () => this.#_vom.dispatch(),
+        /**
+         * Temporarily pauses the internal scanning engine.
+         *
+         * While paused, the system will not scan for changes or emit any file system events.
+         * Existing watchers remain intact and will resume functioning once `resume()` is called.
+         *
+         * Useful for temporarily reducing I/O load without removing watchers.
+         * @since v1.1.0
+         */
+        pause: () => this.#_vom.pause(),
+        /**
+         * Indicates whether the scanning engine is currently active.
+         *
+         * @returns `true` if the engine is currently scanning for changes,
+         *          `false` if it has been paused via `pause()`.
+         *
+         * You can use this to programmatically check the system state before pausing or resuming.
+         * @since v1.1.0
+         */
+        isRunning: () => this.#_vom.isRunning
+    });
 }
 const overwatch = new Overwatch;
 exports.default = overwatch;

dist/cjs/vom/vom.js

@@ -92,2 +92,3 @@ "use strict";
      * The dispatch interval is used to check for changes such as added, removed, or renamed files and directories.
+     * @since v1.0.0
      */
@@ -99,2 +100,16 @@ dispatch() {
     /**
+     * Pauses the dispatch interval for checking for changes in the virtual object structure.
+     * The dispatch interval is used to check for changes such as added, removed, or renamed files and directories.
+     * @since v1.1.0
+     */
+    pause() {
+        this.#_control.reset();
+    }
+    /**
+     * Whether the VirtualObjectManager is currently running and checking for changes.
+     * @returns true if the VirtualObjectManager is running, false otherwise.
+     * @since v1.1.0
+     */
+    get isRunning() { return this.#_dispatcher.job !== null; }
+    /**
      * The interval (in milliseconds) at which the virtual object structure is checked for changes.
@@ -101,0 +116,0 @@ * This interval is used to check for changes such as added, removed, or renamed files and directories.

dist/cjs/watcher/Watcher.js

@@ -6,2 +6,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Watcher = void 0;
 const atomix_1 = __importDefault(require("@nasriya/atomix"));
@@ -181,2 +182,3 @@ class Watcher {
 }
+exports.Watcher = Watcher;
 exports.default = Watcher;

dist/esm/overwatch.js

@@ -7,2 +7,3 @@ import atomix from "@nasriya/atomix";
 import fs from "fs";
+export { Watcher } from "./watcher/Watcher.js";
 class Overwatch {
@@ -251,4 +252,55 @@ #_vom = new VirtualObjectManager();
     }
+    /**
+     * Provides runtime control over the internal scanning engine.
+     *
+     * Use this property to pause or resume the file system scanning engine manually,
+     * without removing or altering existing watchers. This is useful for temporarily
+     * reducing resource usage during periods when file monitoring is not needed.
+     *
+     * Example:
+     * ```ts
+     * overwatch.control.pause();  // Temporarily stop scanning
+     * overwatch.control.resume(); // Resume scanning
+     * console.log(overwatch.control.isRunning()); // Check engine state
+     * ```
+     *
+     * This property is read-only and exposes the following methods:
+     * - `pause()` – Stops the internal scanning engine.
+     * - `resume()` – Starts or resumes scanning.
+     * - `isRunning()` – Returns a boolean indicating whether scanning is active.
+     */
+    control = atomix.dataTypes.record.freeze({
+        /**
+         * Starts or resumes the internal scanning engine.
+         *
+         * This method triggers the engine responsible for detecting changes to all watched paths.
+         * If the engine is already running, calling this again has no effect.
+         *
+         * Use this to resume file system monitoring after calling `pause()`.
+         * @since v1.1.0
+         */
+        resume: () => this.#_vom.dispatch(),
+        /**
+         * Temporarily pauses the internal scanning engine.
+         *
+         * While paused, the system will not scan for changes or emit any file system events.
+         * Existing watchers remain intact and will resume functioning once `resume()` is called.
+         *
+         * Useful for temporarily reducing I/O load without removing watchers.
+         * @since v1.1.0
+         */
+        pause: () => this.#_vom.pause(),
+        /**
+         * Indicates whether the scanning engine is currently active.
+         *
+         * @returns `true` if the engine is currently scanning for changes,
+         *          `false` if it has been paused via `pause()`.
+         *
+         * You can use this to programmatically check the system state before pausing or resuming.
+         * @since v1.1.0
+         */
+        isRunning: () => this.#_vom.isRunning
+    });
 }
 const overwatch = new Overwatch;
 export default overwatch;

dist/esm/vom/vom.js

@@ -87,2 +87,3 @@ import atomix from "@nasriya/atomix";
      * The dispatch interval is used to check for changes such as added, removed, or renamed files and directories.
+     * @since v1.0.0
      */
@@ -94,2 +95,16 @@ dispatch() {
     /**
+     * Pauses the dispatch interval for checking for changes in the virtual object structure.
+     * The dispatch interval is used to check for changes such as added, removed, or renamed files and directories.
+     * @since v1.1.0
+     */
+    pause() {
+        this.#_control.reset();
+    }
+    /**
+     * Whether the VirtualObjectManager is currently running and checking for changes.
+     * @returns true if the VirtualObjectManager is running, false otherwise.
+     * @since v1.1.0
+     */
+    get isRunning() { return this.#_dispatcher.job !== null; }
+    /**
      * The interval (in milliseconds) at which the virtual object structure is checked for changes.
@@ -96,0 +111,0 @@ * This interval is used to check for changes such as added, removed, or renamed files and directories.

dist/esm/watcher/Watcher.js

 import atomix from "@nasriya/atomix";
-class Watcher {
+export class Watcher {
     #_path;
@@ -4,0 +4,0 @@ #_type;

package.json

 {
   "name": "@nasriya/overwatch",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A high-performance, dependency-free file system watcher that monitors file and directory changes efficiently across platforms.",
@@ -42,2 +42,9 @@ "keywords": [
   },
+  "maintainers": [
+    {
+      "name": "Ahmad Nasriya",
+      "email": "[e-mail]",
+      "url": "https://www.linkedin.com/in/ahmadnasriya/"
+    }
+  ],
   "repository": {
@@ -67,2 +74,2 @@ "type": "github",
   }
-}
+}

README.md

@@ -145,4 +145,5 @@ [![N|Solid](https://static.wixstatic.com/media/72ffe6_da8d2142d49c42b29c96ba80c8a91a6c~mv2.png)](https://nasriya.net)
 - ℹ️ The **root** is always a directory — even when watching a file, the root refers to its **parent folder**.
-
-
+- ⏸️ Use `overwatch.control.pause()` and `overwatch.control.resume()` to temporarily stop and restart the internal scanning engine without removing watchers.
+- 🔄 While paused, no file system changes are detected or emitted; resuming triggers an immediate scan and continues monitoring.
+- ✅ These control methods are safe to call multiple times and do not affect watcher registration or state.
 ___
@@ -149,0 +150,0 @@ ## License

New alerts

Unidentified License

License

Something that seems like a license was found, but its contents could not be matched with a known license.

Found 1 instance in 1 package

Fixed alerts

Unidentified License

License

Something that seems like a license was found, but its contents could not be matched with a known license.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

117832

8.44%

Lines of code

2532

8.72%

Number of lines in readme file

151

0.67%

No dependency changes