Async implementation

.husky/pre-commit

@@ -0,0 +1 @@
+npm run lint-staged

CONTRIBUTING.md

@@ -13,9 +13,11 @@ When reporting bugs, please include the following:
 Example bug report:
 
 Title: PixelSearch coordinates are offset by the horizontal resolution
+
 Description: When using PixelSearch, the coordinates are offset by the horizontal resolution of the screen.
 For example, if I search for a blue pixel located at (700, 500), the function returns (2620, 500) on a
 1920x1080 screen.
+
 Code:
 
 ```typescript

README.md

@@ -1,9 +1,9 @@
 # AutoIt JS
 
-Node.js bindings for AutoItX3.dll.
-
 <div align="center">
 
+Node.js bindings for AutoItX3.dll.
+
 ![NPM Version](https://img.shields.io/npm/v/%40ahmic%2Fautoit-js)
 ![GitHub License](https://img.shields.io/github/license/KasimAhmic/autoit-js)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/KasimAhmic/autoit-js/build.yml)
@@ -15,24 +15,51 @@ Node.js bindings for AutoItX3.dll.
 
 ## What is AutoIt JS?
 
-AutoIt is a Windows automation tool that can be used to automate tasks on Windows. AutoIt provides its own scripting language however, it can be difficult to work with if you need to integrate Windows automation into an existing test suite.
+AutoIt is a Windows automation tool that can be used to automate tasks on Windows. AutoIt provides its own
+scripting language however, it can be difficult to work with if you need to integrate Windows automation into
+an existing test suite.
 
 Enter AutoIt JS.
 
-AutoIt JS wraps the AutoItX3.dll library using [Koffi](https://koffi.dev/) to provide a simple to use interface for AutoIt. It allows you to take your existing JavaScript/TypeScript test suite powered by PlayWright/Cypress/Puppeteer/etc. and automate Windows programs with ease.
+AutoIt JS wraps the AutoItX3.dll library using [Koffi](https://koffi.dev/) to provide a simple to use
+interface for AutoIt. It allows you to take your existing JavaScript/TypeScript test suite powered by
+Playwright/Cypress/Puppeteer/etc. and automate Windows programs with ease.
 
 ## Example Usage
 
+### New Asynchronous API in v2
+
+You can use the new asynchronous API in async contexts like Playwright and Cypress tests to avoid blocking the
+event loop and slowing down your tests.
+
 ```typescript
 import { Init, Run, Send, WinClose, WinWaitActive, autoit } from '@ahmic/autoit-js';
 
 autoit.load();
 
-Init();
-Run('notepad.exe');
-WinWaitActive('[CLASS:Notepad]');
-Send('Hello, World!');
-WinClose('[CLASS:Notepad]');
+await Init();
+await Run('notepad.exe');
+await WinWaitActive('[CLASS:Notepad]');
+await Send('Hello, World!');
+await WinClose('[CLASS:Notepad]');
+
+autoit.unload();
+```
+
+### Synchronous API
+
+For simple scripting tasks, the synchronous API is the preferred way to use AutoIt JS.
+
+```typescript
+import { InitSync, RunSync, SendSync, WinCloseSync, WinWaitActiveSync, autoit } from '@ahmic/autoit-js';
+
+autoit.load();
+
+InitSync();
+RunSync('notepad.exe');
+WinWaitActiveSync('[CLASS:Notepad]');
+SendSync('Hello, World!');
+WinCloseSync('[CLASS:Notepad]');
 
 autoit.unload();
 ```

TestApp/CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.28)
 project(TestApp)
 enable_language(RC)
 
-set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD 20)
 
 set(RESOURCES "src/resources/TestApp.rc")
 

TestApp/src/include/handles.h

@@ -13,5 +13,6 @@ inline HWND cancelButtonHandle;
 inline HWND treeListViewHandle;
 inline HWND listViewHandle;
 inline HWND statusBarHandle;
+inline HWND eventHandle;
 inline HFONT fontHandle;
 inline HBRUSH brushHandle;

TestApp/src/include/util.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <format>
 #include <memory>
 #include <iostream>
 
@@ -251,3 +252,22 @@ inline VOID SetTheme(HWND handle) {
 		logger->warn("Failed to set theme on window. Reason: " + result);
 	}
 }
+
+inline VOID UpdateLastEvent(UINT event, WPARAM wParam) {
+	const std::wstring name = [&] {
+		switch (event) {
+			case WM_MOUSEMOVE: return std::wstring(L"Mouse Move");
+			case WM_LBUTTONDOWN: return std::wstring(L"Mouse Left Click");
+			case WM_RBUTTONDOWN: return std::wstring(L"Mouse Right Click");
+			case WM_LBUTTONDBLCLK: return std::wstring(L"Mouse Left Double Click");
+			case WM_RBUTTONDBLCLK: return std::wstring(L"Mouse Right Double Click");
+			case WM_MOUSEWHEEL: {
+				const wchar_t *dir = GET_WHEEL_DELTA_WPARAM(wParam) < 0 ? L"Down" : L"Up";
+				return std::format(L"Mouse Wheel {}", dir);
+			}
+			default: return std::wstring();
+		}
+	}();
+
+	SetWindowTextW(eventHandle, std::format(L"Last Event: {}", name).c_str());
+}

TestApp/src/main.cpp

@@ -253,7 +253,7 @@ LRESULT CALLBACK WndProc(HWND windowHandle, const UINT message, const WPARAM wPa
                 FORM_INPUT_WIDTH,
                 30);
 
-            CreateCheckBox(
+            HWND checkBoxThree = CreateCheckBox(
                 windowHandle,
                 L"Check Box 3",
                 PADDING,
@@ -293,6 +293,14 @@ LRESULT CALLBACK WndProc(HWND windowHandle, const UINT message, const WPARAM wPa
                 155,
                 MAX_CLIENT_HEIGHT - GetRectRelativeToParent(listViewHandle, windowHandle).bottom);
 
+            eventHandle = CreateStaticText(
+                windowHandle,
+                L"Last Event: ",
+                GetRectRelativeToParent(checkBoxOne, windowHandle).left,
+                GetRectRelativeToParent(checkBoxThree, windowHandle).bottom + PADDING + 5,
+                300,
+                20);
+
             statusBarHandle = CreateWindowEx(
                 0,
                 STATUSCLASSNAME,
@@ -315,9 +323,9 @@ LRESULT CALLBACK WndProc(HWND windowHandle, const UINT message, const WPARAM wPa
 
             SetTheme(listViewHandle);
             SetTheme(treeListViewHandle);
-        }
 
-        break;
+            break;
+        }
 
         case WM_COMMAND: {
             switch (LOWORD(wParam)) {
@@ -340,8 +348,19 @@ LRESULT CALLBACK WndProc(HWND windowHandle, const UINT message, const WPARAM wPa
                 default:
                     return DefWindowProc(windowHandle, message, wParam, lParam);
             }
+
+            break;
+        }
+
+        case WM_MOUSEMOVE:
+        case WM_LBUTTONDOWN:
+        case WM_RBUTTONDOWN:
+        case WM_LBUTTONDBLCLK:
+        case WM_RBUTTONDBLCLK:
+        case WM_MOUSEWHEEL: {
+            UpdateLastEvent(message, wParam);
+            break;
         }
-        break;
 
         case WM_PAINT: {
             PAINTSTRUCT ps;
@@ -400,12 +419,14 @@ LRESULT CALLBACK WndProc(HWND windowHandle, const UINT message, const WPARAM wPa
             break;
         }
 
-        case WM_DESTROY:
+        case WM_DESTROY: {
             PostQuitMessage(0);
             break;
+        }
 
-        default:
+        default: {
             return DefWindowProc(windowHandle, message, wParam, lParam);
+        }
     }
     return 0;
 }

docs/Basic Usage.md

@@ -2,6 +2,64 @@
 
 Using AutoIt JS is as straightforward as it gets; import function, call function, use result.
 
+## Synchronous Example
+
+You can use the synchronous API for simple scripting tasks if you don't want to deal with promises.
+
+```typescript
+import {
+  ControlClickByHandleSync,
+  ControlGetHandleSync,
+  InitSync,
+  RunSync,
+  SendSync,
+  WinCloseSync,
+  WinGetHandleSync,
+  WinWaitActiveSync,
+  WinWaitSync,
+  autoit,
+} from '@ahmic/autoit-js';
+
+// An instance of the AutoIt class is created automatically, you need only call load() to initialize it
+autoit.load();
+
+// Initialize AutoIt
+InitSync();
+
+// Run Notepad
+RunSync('notepad.exe');
+
+// Wait for Notepad to be active
+WinWaitActiveSync('[CLASS:Notepad]');
+
+// Type into Notepad
+SendSync('Hello, World!');
+
+// Close Notepad
+WinCloseSync('[CLASS:Notepad]');
+
+// Wait for the Save dialog to appear
+WinWaitSync('Notepad', '&Save');
+
+// Get the handle of the Save dialog
+const dialogHandle = WinGetHandleSync('Notepad', '&Save');
+
+// Get the handle of the Don't Save button
+const buttonHandle = ControlGetHandleSync(dialogHandle, 'Button2');
+
+// Click the Don't Save button
+ControlClickByHandleSync(dialogHandle, buttonHandle);
+
+// Unload AutoIt
+autoit.unload();
+```
+
+## Asynchronous Example
+
+When in asynchronous contexts like in Cypress and Playwright, you can use the asynchronous API to avoid
+blocking the event loop. The API is largely the same except that you need to `await` the functions and use the
+non `Sync` versions.
+
 ```typescript
 import {
   ControlClickByHandle,
@@ -20,31 +78,31 @@ import {
 autoit.load();
 
 // Initialize AutoIt
-Init();
+await Init();
 
 // Run Notepad
-Run('notepad.exe');
+await Run('notepad.exe');
 
 // Wait for Notepad to be active
-WinWaitActive('[CLASS:Notepad]');
+await WinWaitActive('[CLASS:Notepad]');
 
 // Type into Notepad
-Send('Hello, World!');
+await Send('Hello, World!');
 
 // Close Notepad
-WinClose('[CLASS:Notepad]');
+await WinClose('[CLASS:Notepad]');
 
 // Wait for the Save dialog to appear
-WinWait('Notepad', '&Save');
+await WinWait('Notepad', '&Save');
 
 // Get the handle of the Save dialog
-const dialogHandle = WinGetHandle('Notepad', '&Save');
+const dialogHandle = await WinGetHandle('Notepad', '&Save');
 
 // Get the handle of the Don't Save button
-const buttonHandle = ControlGetHandle(dialogHandle, 'Button2');
+const buttonHandle = await ControlGetHandle(dialogHandle, 'Button2');
 
 // Click the Don't Save button
-ControlClickByHandle(dialogHandle, buttonHandle);
+await ControlClickByHandle(dialogHandle, buttonHandle);
 
 // Unload AutoIt
 autoit.unload();