node-native-win-utils 2.1.0 → 2.1.1

package/dist/index.cjs

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OpenCV = exports.KeyboardListener = exports.textRecognition = exports.KeyCodeHelper = exports.rawPressKey = exports.typeString = exports.mouseDrag = exports.mouseClick = exports.mouseMove = exports.captureWindowN = exports.getWindowData = void 0;
+exports.OpenCV = exports.KeyboardListener = exports.captureScreenAsync = exports.textRecognition = exports.KeyCodeHelper = exports.rawPressKey = exports.typeString = exports.mouseDrag = exports.mouseClick = exports.mouseMove = exports.captureWindowN = exports.getWindowData = void 0;
 exports.captureWindow = captureWindow;
 exports.keyPress = keyPress;
 exports.captureScreenToFile = captureScreenToFile;
@@ -20,6 +20,7 @@ const bindings = nodeGypBuild(path_1.default.resolve(dirnameLocal_cjs_1.__dirnam
 const { setKeyDownCallback, setKeyUpCallback, unsetKeyDownCallback, unsetKeyUpCallback, getWindowData, captureWindowN, captureScreenAsync, mouseMove, mouseClick, mouseDrag, typeString, pressKey, imread, imwrite, matchTemplate, blur, bgrToGray, drawRectangle, getRegion, textRecognition } = bindings;
 exports.getWindowData = getWindowData;
 exports.captureWindowN = captureWindowN;
+exports.captureScreenAsync = captureScreenAsync;
 exports.mouseMove = mouseMove;
 exports.mouseClick = mouseClick;
 exports.mouseDrag = mouseDrag;
@@ -56,21 +57,36 @@ function captureScreenToFile(path) {
     });
 }
 /**
- * Represents a class to listen to keyboard events.
+ * Class that implements a private keyboard listener.
+ * This class leverages native C++ bindings to hook into system keyboard events.
+ * The C++ layer uses global ThreadSafeFunction objects to safely dispatch events
+ * (using a dedicated monitoring thread, mutexes, and atomic flags) to JavaScript.
  * @extends EventEmitter
  */
 class KeyboardListenerPrivate extends events_1.default {
+    /**
+     * Constructs the keyboard listener and sets up native callbacks.
+     * The callbacks (set via setKeyDownCallback and setKeyUpCallback) are defined in the
+     * C++ binding layer. They are responsible for invoking these JavaScript callbacks
+     * in a thread-safe manner once a key event is detected.
+     */
     constructor() {
         super();
+        // Set the callback for key down events.
         setKeyDownCallback((keyCode) => {
+            // Look up the human-readable key name from a mapping.
             const keyName = keyCodes_cjs_1.keyCodes.get(keyCode.toString());
+            // Emit the 'keyDown' event to all registered JavaScript listeners.
             this.emit("keyDown", {
                 keyCode,
                 keyName,
             });
         });
+        // Set the callback for key up events.
         setKeyUpCallback((keyCode) => {
+            // Look up the human-readable key name from a mapping.
             const keyName = keyCodes_cjs_1.keyCodes.get(keyCode.toString());
+            // Emit the 'keyUp' event to all registered JavaScript listeners.
             this.emit("keyUp", {
                 keyCode,
                 keyName,
@@ -78,13 +94,33 @@ class KeyboardListenerPrivate extends events_1.default {
         });
     }
 }
+/**
+ * A singleton manager for the KeyboardListenerPrivate instance.
+ * This class ensures that only one native keyboard listener is active at any time.
+ * When the listener is destroyed, it calls unsetKeyDownCallback and unsetKeyUpCallback
+ * to clean up native resources, mirroring the cleanup logic in the C++ bindings.
+ */
 class KeyboardListener {
+    /**
+     * Holds the singleton instance of KeyboardListenerPrivate.
+     */
     static listenerInstance = null;
+    /**
+     * Returns the singleton instance of KeyboardListenerPrivate. If not already created,
+     * it instantiates a new instance and sets up the native callbacks.
+     * @returns The active KeyboardListenerPrivate instance.
+     */
     static listener() {
-        if (!this.listenerInstance)
+        if (!this.listenerInstance) {
             this.listenerInstance = new KeyboardListenerPrivate();
+        }
         return this.listenerInstance;
     }
+    /**
+     * Destroys the current KeyboardListenerPrivate instance and cleans up native callbacks.
+     * This method calls unsetKeyDownCallback and unsetKeyUpCallback to release any
+     * native resources (such as the global ThreadSafeFunctions) and stops the monitoring thread.
+     */
     static destroy() {
         this.listenerInstance = null;
         unsetKeyDownCallback();

package/dist/index.d.cts

@@ -82,7 +82,7 @@ export type DrawRectangle = (image: ImageData, start: Point, end: Point, rgb: Co
 export type GetRegion = (image: ImageData, region: ROI) => ImageData;
 export type TextRecognition = (trainedDataPath: string, dataLang: string, imagePath: string) => string;
 export type CaptureScreenAsync = () => Promise<Buffer>;
-declare const getWindowData: GetWindowData, captureWindowN: CaptureWindow, mouseMove: MouseMove, mouseClick: MouseClick, mouseDrag: MouseDrag, typeString: TypeString, textRecognition: TextRecognition;
+declare const getWindowData: GetWindowData, captureWindowN: CaptureWindow, captureScreenAsync: CaptureScreenAsync, mouseMove: MouseMove, mouseClick: MouseClick, mouseDrag: MouseDrag, typeString: TypeString, textRecognition: TextRecognition;
 declare const rawPressKey: PressKey;
 /**
  * Captures a window and saves it to a file.
@@ -97,20 +97,31 @@ declare function captureWindow(windowName: string, path: string): boolean;
  * @returns True if the capture and save operation is successful, otherwise false.
  */
 declare function captureScreenToFile(path: string): Promise<boolean>;
+/**
+ * Interface representing a private keyboard listener that extends EventEmitter.
+ * It declares event handlers for native keyboard events, which are forwarded from
+ * the C++ bindings using thread-safe callbacks.
+ */
 interface KeyboardListenerPrivate extends EventEmitter {
     /**
-     * Event: Fires when a key is pressed down.
+     * Registers an event handler for the 'keyDown' event.
+     * This event is fired when a key is pressed down. The C++ native binding calls
+     * this callback using a thread-safe mechanism (via Napi::ThreadSafeFunction).
      * @param event - The event name ('keyDown').
-     * @param callback - The callback function to handle the event.
+     * @param callback - Function invoked with an object containing the keyCode and keyName.
+     * @returns The current instance for method chaining.
      */
     on(event: "keyDown", callback: (data: {
         keyCode: number;
         keyName: string;
     }) => void): this;
     /**
-     * Event: Fires when a key is released.
+     * Registers an event handler for the 'keyUp' event.
+     * This event is fired when a key is released. The underlying C++ code safely
+     * invokes this callback from a background thread using a thread-safe function.
      * @param event - The event name ('keyUp').
-     * @param callback - The callback function to handle the event.
+     * @param callback - Function invoked with an object containing the keyCode and keyName.
+     * @returns The current instance for method chaining.
      */
     on(event: "keyUp", callback: (data: {
         keyCode: number;
@@ -118,15 +129,43 @@ interface KeyboardListenerPrivate extends EventEmitter {
     }) => void): this;
 }
 /**
- * Represents a class to listen to keyboard events.
+ * Class that implements a private keyboard listener.
+ * This class leverages native C++ bindings to hook into system keyboard events.
+ * The C++ layer uses global ThreadSafeFunction objects to safely dispatch events
+ * (using a dedicated monitoring thread, mutexes, and atomic flags) to JavaScript.
  * @extends EventEmitter
  */
 declare class KeyboardListenerPrivate extends EventEmitter {
+    /**
+     * Constructs the keyboard listener and sets up native callbacks.
+     * The callbacks (set via setKeyDownCallback and setKeyUpCallback) are defined in the
+     * C++ binding layer. They are responsible for invoking these JavaScript callbacks
+     * in a thread-safe manner once a key event is detected.
+     */
     constructor();
 }
+/**
+ * A singleton manager for the KeyboardListenerPrivate instance.
+ * This class ensures that only one native keyboard listener is active at any time.
+ * When the listener is destroyed, it calls unsetKeyDownCallback and unsetKeyUpCallback
+ * to clean up native resources, mirroring the cleanup logic in the C++ bindings.
+ */
 declare class KeyboardListener {
+    /**
+     * Holds the singleton instance of KeyboardListenerPrivate.
+     */
     private static listenerInstance;
+    /**
+     * Returns the singleton instance of KeyboardListenerPrivate. If not already created,
+     * it instantiates a new instance and sets up the native callbacks.
+     * @returns The active KeyboardListenerPrivate instance.
+     */
     static listener(): KeyboardListenerPrivate;
+    /**
+     * Destroys the current KeyboardListenerPrivate instance and cleans up native callbacks.
+     * This method calls unsetKeyDownCallback and unsetKeyUpCallback to release any
+     * native resources (such as the global ThreadSafeFunctions) and stops the monitoring thread.
+     */
     static destroy(): void;
 }
 /**
@@ -188,4 +227,4 @@ declare class OpenCV {
     imwrite(path: string): void;
 }
 declare function keyPress(keyCode: number, repeat?: number): Promise<boolean>;
-export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, KeyboardListener, OpenCV };
+export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, KeyboardListener, OpenCV };

package/dist/index.d.mts

@@ -82,7 +82,7 @@ export type DrawRectangle = (image: ImageData, start: Point, end: Point, rgb: Co
 export type GetRegion = (image: ImageData, region: ROI) => ImageData;
 export type TextRecognition = (trainedDataPath: string, dataLang: string, imagePath: string) => string;
 export type CaptureScreenAsync = () => Promise<Buffer>;
-declare const getWindowData: GetWindowData, captureWindowN: CaptureWindow, mouseMove: MouseMove, mouseClick: MouseClick, mouseDrag: MouseDrag, typeString: TypeString, textRecognition: TextRecognition;
+declare const getWindowData: GetWindowData, captureWindowN: CaptureWindow, captureScreenAsync: CaptureScreenAsync, mouseMove: MouseMove, mouseClick: MouseClick, mouseDrag: MouseDrag, typeString: TypeString, textRecognition: TextRecognition;
 declare const rawPressKey: PressKey;
 /**
  * Captures a window and saves it to a file.
@@ -97,20 +97,31 @@ declare function captureWindow(windowName: string, path: string): boolean;
  * @returns True if the capture and save operation is successful, otherwise false.
  */
 declare function captureScreenToFile(path: string): Promise<boolean>;
+/**
+ * Interface representing a private keyboard listener that extends EventEmitter.
+ * It declares event handlers for native keyboard events, which are forwarded from
+ * the C++ bindings using thread-safe callbacks.
+ */
 interface KeyboardListenerPrivate extends EventEmitter {
     /**
-     * Event: Fires when a key is pressed down.
+     * Registers an event handler for the 'keyDown' event.
+     * This event is fired when a key is pressed down. The C++ native binding calls
+     * this callback using a thread-safe mechanism (via Napi::ThreadSafeFunction).
      * @param event - The event name ('keyDown').
-     * @param callback - The callback function to handle the event.
+     * @param callback - Function invoked with an object containing the keyCode and keyName.
+     * @returns The current instance for method chaining.
      */
     on(event: "keyDown", callback: (data: {
         keyCode: number;
         keyName: string;
     }) => void): this;
     /**
-     * Event: Fires when a key is released.
+     * Registers an event handler for the 'keyUp' event.
+     * This event is fired when a key is released. The underlying C++ code safely
+     * invokes this callback from a background thread using a thread-safe function.
      * @param event - The event name ('keyUp').
-     * @param callback - The callback function to handle the event.
+     * @param callback - Function invoked with an object containing the keyCode and keyName.
+     * @returns The current instance for method chaining.
      */
     on(event: "keyUp", callback: (data: {
         keyCode: number;
@@ -118,15 +129,43 @@ interface KeyboardListenerPrivate extends EventEmitter {
     }) => void): this;
 }
 /**
- * Represents a class to listen to keyboard events.
+ * Class that implements a private keyboard listener.
+ * This class leverages native C++ bindings to hook into system keyboard events.
+ * The C++ layer uses global ThreadSafeFunction objects to safely dispatch events
+ * (using a dedicated monitoring thread, mutexes, and atomic flags) to JavaScript.
  * @extends EventEmitter
  */
 declare class KeyboardListenerPrivate extends EventEmitter {
+    /**
+     * Constructs the keyboard listener and sets up native callbacks.
+     * The callbacks (set via setKeyDownCallback and setKeyUpCallback) are defined in the
+     * C++ binding layer. They are responsible for invoking these JavaScript callbacks
+     * in a thread-safe manner once a key event is detected.
+     */
     constructor();
 }
+/**
+ * A singleton manager for the KeyboardListenerPrivate instance.
+ * This class ensures that only one native keyboard listener is active at any time.
+ * When the listener is destroyed, it calls unsetKeyDownCallback and unsetKeyUpCallback
+ * to clean up native resources, mirroring the cleanup logic in the C++ bindings.
+ */
 declare class KeyboardListener {
+    /**
+     * Holds the singleton instance of KeyboardListenerPrivate.
+     */
     private static listenerInstance;
+    /**
+     * Returns the singleton instance of KeyboardListenerPrivate. If not already created,
+     * it instantiates a new instance and sets up the native callbacks.
+     * @returns The active KeyboardListenerPrivate instance.
+     */
     static listener(): KeyboardListenerPrivate;
+    /**
+     * Destroys the current KeyboardListenerPrivate instance and cleans up native callbacks.
+     * This method calls unsetKeyDownCallback and unsetKeyUpCallback to release any
+     * native resources (such as the global ThreadSafeFunctions) and stops the monitoring thread.
+     */
     static destroy(): void;
 }
 /**
@@ -188,4 +227,4 @@ declare class OpenCV {
     imwrite(path: string): void;
 }
 declare function keyPress(keyCode: number, repeat?: number): Promise<boolean>;
-export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, KeyboardListener, OpenCV };
+export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, KeyboardListener, OpenCV };

package/dist/index.mjs

@@ -39,21 +39,36 @@ function captureScreenToFile(path) {
     });
 }
 /**
- * Represents a class to listen to keyboard events.
+ * Class that implements a private keyboard listener.
+ * This class leverages native C++ bindings to hook into system keyboard events.
+ * The C++ layer uses global ThreadSafeFunction objects to safely dispatch events
+ * (using a dedicated monitoring thread, mutexes, and atomic flags) to JavaScript.
  * @extends EventEmitter
  */
 class KeyboardListenerPrivate extends EventEmitter {
+    /**
+     * Constructs the keyboard listener and sets up native callbacks.
+     * The callbacks (set via setKeyDownCallback and setKeyUpCallback) are defined in the
+     * C++ binding layer. They are responsible for invoking these JavaScript callbacks
+     * in a thread-safe manner once a key event is detected.
+     */
     constructor() {
         super();
+        // Set the callback for key down events.
         setKeyDownCallback((keyCode) => {
+            // Look up the human-readable key name from a mapping.
             const keyName = keyCodes.get(keyCode.toString());
+            // Emit the 'keyDown' event to all registered JavaScript listeners.
             this.emit("keyDown", {
                 keyCode,
                 keyName,
             });
         });
+        // Set the callback for key up events.
         setKeyUpCallback((keyCode) => {
+            // Look up the human-readable key name from a mapping.
             const keyName = keyCodes.get(keyCode.toString());
+            // Emit the 'keyUp' event to all registered JavaScript listeners.
             this.emit("keyUp", {
                 keyCode,
                 keyName,
@@ -61,13 +76,33 @@ class KeyboardListenerPrivate extends EventEmitter {
         });
     }
 }
+/**
+ * A singleton manager for the KeyboardListenerPrivate instance.
+ * This class ensures that only one native keyboard listener is active at any time.
+ * When the listener is destroyed, it calls unsetKeyDownCallback and unsetKeyUpCallback
+ * to clean up native resources, mirroring the cleanup logic in the C++ bindings.
+ */
 class KeyboardListener {
+    /**
+     * Holds the singleton instance of KeyboardListenerPrivate.
+     */
     static listenerInstance = null;
+    /**
+     * Returns the singleton instance of KeyboardListenerPrivate. If not already created,
+     * it instantiates a new instance and sets up the native callbacks.
+     * @returns The active KeyboardListenerPrivate instance.
+     */
     static listener() {
-        if (!this.listenerInstance)
+        if (!this.listenerInstance) {
             this.listenerInstance = new KeyboardListenerPrivate();
+        }
         return this.listenerInstance;
     }
+    /**
+     * Destroys the current KeyboardListenerPrivate instance and cleans up native callbacks.
+     * This method calls unsetKeyDownCallback and unsetKeyUpCallback to release any
+     * native resources (such as the global ThreadSafeFunctions) and stops the monitoring thread.
+     */
     static destroy() {
         this.listenerInstance = null;
         unsetKeyDownCallback();
@@ -174,4 +209,4 @@ function keyPress(keyCode, repeat) {
         return resolve(true);
     });
 }
-export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, KeyboardListener, OpenCV };
+export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, KeyboardListener, OpenCV };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-native-win-utils",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "author": "Andrew K.",
   "license": "MIT",
   "repository": "https://github.com/T-Rumibul/node-native-win-utils.git",

package/src/index.mts

@@ -449,6 +449,7 @@ export {
   KeyCodeHelper,
   textRecognition,
   captureScreenToFile,
+  captureScreenAsync,
   KeyboardListener,
   OpenCV
 };