rustcatch - npm Package Compare versions

Comparing version 0.3.2 to 0.3.3

package.json

 {
   "name": "rustcatch",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "A high-performance, cross-platform global keyboard event listener for Node.js, written in Rust.",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

README.md

@@ -7,3 +7,3 @@ # rustcatch 🦀
 
-`rustcatch` allows your Node.js application to listen for keyboard events from any application across the entire operating system, not just the focused terminal window.
+`rustcatch` allows your Node.js application to listen for keyboard events from any application across the entire operating system, not just the focused terminal window. It's ideal for creating system-wide hotkeys, shortcuts, or capturing input from devices that emulate a keyboard, like a USB barcode scanner.
 
@@ -16,11 +16,15 @@ ## Why `rustcatch`?
 -   🛡️ **Safe & Reliable:** Leverages Rust's memory and thread safety guarantees to prevent common issues found in native C++ addons.
--   📦 **Simple Installation:** Designed to use pre-built binaries, removing the need for end-users to have a Rust toolchain installed.
+-   📦 **Simple Installation:** Uses pre-built binaries, removing the need for end-users to have a Rust toolchain installed.
 
+## How It Works
+
+This module uses a **pre-compiled binary** approach. When you install `rustcatch` via `npm`, it downloads a `.node` file that is already compiled for your operating system and architecture. This means you don't need Rust, C++ compilers, or any other build tools to use this package in your project.
+
 ## Platform Support
 
-| OS            | Supported | Notes                                                               |
+| OS            | Supported | Notes for Users                                                       |
 | :------------ | :-------: | :------------------------------------------------------------------ |
 | Windows       |     ✅    | Works out of the box.                                               |
-| macOS         |     ✅    | Requires Accessibility permissions for the terminal/app in settings.|
-| Linux (X11)   |     ✅    | Requires `libxdo-dev`, `libxtst-dev`, and other X11 development libs. |
+| macOS         |    (TBD)  | Requires Accessibility permissions for the terminal/app in settings.|
+| Linux (X11)   |    (TBD)  | Requires `libxdo-dev`, `libxtst-dev`, and other X11 development libs. |
 
@@ -30,10 +34,10 @@ ## Installation
 ```bash
-# To install from GitHub (until published on NPM)
-npm install GITHUB_USERNAME/rustcatch
+npm install rustcatch
 ```
-*(Replace `GITHUB_USERNAME` with the actual GitHub username.)*
 
+The package will automatically download the correct pre-built binary for your system.
+
 ## Quick Start Example
 
-Here is a simple example of how to use `rustcatch` to log key presses and releases.
+Here is a simple example of how to use `rustcatch` to log key presses.
 
@@ -43,2 +47,5 @@ ```javascript
 
+console.log('Starting global listener... Press any key.');
+console.log('This script will be kept alive by a timer. Press Ctrl+C to exit.');
+
 // Add a listener for the 'keydown' event
@@ -60,16 +67,28 @@ rustcatch.on('keydown', (event) => {
   console.log('Global listener started successfully.');
-  console.log('Press any key (even in other windows)...');
 } catch (error) {
   console.error('Failed to start listener:', error);
+  process.exit(1);
 }
 
-// Stop the listener after 30 seconds
-setTimeout(() => {
-  if (rustcatch.isRunning) {
-    rustcatch.stop();
-    console.log('Global listener stopped.');
-  }
-}, 30000);
+// See the "Important Note on Usage" below
+setInterval(() => {}, 1000 * 60 * 60);
+
+process.on('SIGINT', () => {
+    if (rustcatch.isRunning) {
+        rustcatch.stop();
+        console.log('\nGlobal listener stopped.');
+    }
+    process.exit(0);
+});
 ```
 
+## ⚠️ Important Note on Usage
+
+Because `rustcatch` runs its core logic in a separate background thread, the main Node.js process might not see any pending tasks and exit immediately after starting.
+
+To prevent this, you must keep the Node.js event loop busy. You can do this by:
+-   Running a web server (e.g., Express, Fastify).
+-   Keeping a WebSocket connection open.
+-   Using a simple `setInterval` as shown in the example above to keep the process alive indefinitely.
+
 ## API Reference
@@ -82,3 +101,3 @@
 #### `rustcatch.start()`
-Starts the global keyboard listener. It will begin emitting `keydown` and `keyup` events.
+Starts the global keyboard listener. It will begin emitting `keydown` and `keyup` events. Throws an error if the listener cannot be started.
 
@@ -93,2 +112,3 @@ #### `rustcatch.stop()`
 -   Returns `true` if the listener is currently active, otherwise `false`.
+-   **Note:** This property is updated asynchronously. It may not be `true` immediately after calling `start()`.
 
@@ -98,18 +118,49 @@ ### Events
 #### `on('keydown', callback)`
--   **`callback(event)`**
-    -   **`event`** `<Object>`
-        -   `type` `<string>` - Always `'keydown'`.
-        -   `key` `<string>` - A string representation of the key that was pressed (e.g., `'KeyA'`, `'Space'`, `'ControlLeft'`).
--   Emitted when any key is pressed down.
+-   `callback(event)`: The event object.
+    -   `event.type`: `'keydown'`
+    -   `event.key`: A string representation of the key (e.g., `'KeyA'`, `'Space'`, `'Num1'`, `'Return'`).
 
 #### `on('keyup', callback)`
--   **`callback(event)`**
-    -   **`event`** `<Object>`
-        -   `type` `<string>` - Always `'keyup'`.
-        -   `key` `<string>` - A string representation of the key that was released.
--   Emitted when any key is released.
+-   `callback(event)`: The event object.
+    -   `event.type`: `'keyup'`
+    -   `event.key`: A string representation of the key.
 
+## For Developers: Building from Source
+
+If you want to contribute to the project or build the binaries for your own system, you'll need to compile the Rust source code.
+
+### Prerequisites
+
+1.  **Rust Toolchain:** Install via [rustup.rs](https://rustup.rs/).
+2.  **Node.js:** v16 or later.
+3.  **Build Tools:**
+    *   **Windows:** Install "Desktop development with C++" from the Visual Studio Installer.
+    *   **macOS:** Install Xcode Command Line Tools.
+    *   **Linux:** Install `build-essential` and `libxdo-dev libxtst-dev`.
+
+### Build Steps
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/Xzdes/rustcatch.git
+    cd rustcatch
+    ```
+2.  **Install JavaScript dependencies:**
+    This will install development tools like `cargo-cp-artifact`.
+    ```bash
+    npm install
+    ```
+3.  **Build the native addon:**
+    This command compiles the Rust code and copies the final `.node` file to the correct location (`build/Release/addon.node`).
+    ```bash
+    npm run build
+    ```
+4.  **Run tests (optional):**
+    ```bash
+    npm test
+    ```
+
 ## Contributing
 
-Contributions are welcome! Please feel free to open an issue or submit a pull request.
+Contributions are welcome! Please feel free to open an issue to discuss a bug or feature, or submit a pull request with your changes.
 
@@ -116,0 +167,0 @@ ## License

No alert changes

Improved metrics

Total package byte prevSize

382015

0.56%

Number of lines in readme file

161

46.36%

No dependency changes