Merge branch 'develop'

# Conflicts:
#	README.md
#	lib/image.class.spec.ts
#	lib/keyboard.class.ts
#	lib/mouse.class.ts
#	lib/movement.function.ts
#	lib/region.class.spec.ts
#	lib/region.class.ts
#	lib/screen.class.spec.ts
#	lib/screen.class.ts
#	lib/screen.colorAt.spec.ts
#	package-lock.json
#	package.json

Author: s1hofmann

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## 2.0.0
+- Feature: Apple Silicon [(libnut#49)](https://github.com/nut-tree/libnut/issues/49)
+- Enhancement: Enable warning message for missing accessibility permissions on macOS [(#354)](https://github.com/nut-tree/nut.js/issues/354)
+- Enhancement: Add runtime typechecks for `screen.find` etc. [(#351)](https://github.com/nut-tree/nut.js/issues/351)
+- Bugfix: Fix Windows scaling issue [(#349)](https://github.com/nut-tree/nut.js/issues/349)
+- Maintenance: Refine types [(#340)](https://github.com/nut-tree/nut.js/issues/340)
+- Maintenance: Cleanup deprecated code [(#341)](https://github.com/nut-tree/nut.js/issues/341)
+- Enhancement: Support for mouse capturing games [(#168)](https://github.com/nut-tree/nut.js/issues/168)
+- Feature: Provide functions to convert images between BGR and RGB color mode [(#336)](https://github.com/nut-tree/nut.js/issues/336)
+- Feature: Audio keys support [(#233)](https://github.com/nut-tree/nut.js/issues/233)
+- Enhancement: Configurable interval for `waitFor` [(#312)](https://github.com/nut-tree/nut.js/issues/312)
+- Bugfix: Apply pixel density scaling on `colorAt` [(#327)](https://github.com/nut-tree/nut.js/issues/327)
+- Enhancement: Change `find` signature to only work on `Image` instances [(#329)](https://github.com/nut-tree/nut.js/issues/329)
+- Enhancement: Adjust `assert` class to new `Screen#find` parameter types [(#324)](https://github.com/nut-tree/nut.js/issues/324)
+- Feature: Get screen pixel color [(#259)](https://github.com/nut-tree/nut.js/issues/259)
+- Feature: Add `Screen#findAll` to enable matching multiple template occurrences [(#320)](https://github.com/nut-tree/nut.js/issues/321)
+- Enhancement: Make Screen#find accept `Promise<Image>` [(#320)](https://github.com/nut-tree/nut.js/issues/320)
+- Enhancement: Accepting a Buffer with image data for `Screen#find` [(#204)](https://github.com/nut-tree/nut.js/issues/204)
+- Enhancement: Get rid of adapter layer in favour of providerRegistry [(#310)](https://github.com/nut-tree/nut.js/issues/310)
+- Feature: Provide a default implementation for `ImageReader` and `ImageWriter` [(#307)](https://github.com/nut-tree/nut.js/issues/307)
+- Feature: Define interface for mouse movement type [(#130)](https://github.com/nut-tree/nut.js/issues/130)
+- Feature: Separate image matching code [(#279)](https://github.com/nut-tree/nut.js/issues/279)
+- Enhancement: Export `FileType` [(#301)](https://github.com/nut-tree/nut.js/issues/301)
+- Enhancement: Export `ImageWriterParameters` [(#296)](https://github.com/nut-tree/nut.js/issues/296)
+- Enhancement: Export provider interfaces [(#294)](https://github.com/nut-tree/nut.js/issues/294)
+- Feature: Introduce a registry for providers [(#292)](https://github.com/nut-tree/nut.js/issues/292)
+- Feature: Add methods to grab the current screen content as Buffer [(#278)](https://github.com/nut-tree/nut.js/issues/278)
+
 ## 1.7.0
 - Enhancement: Trigger snapshot releases [(#234)](https://github.com/nut-tree/nut.js/issues/234)
 - Feature: Cancel screen.waitFor if needed [(#241)](https://github.com/nut-tree/nut.js/issues/241)

README.md

@@ -10,8 +10,10 @@
 
 [![Downloads per month](https://img.shields.io/npm/dm/@nut-tree/nut-js)](https://www.npmjs.com/package/@nut-tree/nut-js)
 
-<p style="text-align: center">
-Native UI testing / automation with node.js
+<h1 align="center"><a href="https://nutjs.dev">nutjs.dev</a></h1>
+
+<p align="center">
+Native UI testing / automation with Node.js
 </p>
 <br/>
 
@@ -42,6 +44,10 @@ Check out this demo video to get a first impression of what nut.js is capable of
 
 [![nut.js demo video](https://img.youtube.com/vi/MpIyUJnU_Bk/1.jpg)](https://www.youtube.com/watch?v=MpIyUJnU_Bk)
 
+# Tutorials
+
+Please consult the project website at [nutjs.dev](https://nutjs.dev/docs/tutorial-first_steps/prerequisits) for in-depth tutorials
+
 # Examples
 
 [nut-tree/trailmix](https://github.com/nut-tree/trailmix) contains a set of ready to use examples which demo the usage ot nut.js.
@@ -50,10 +56,6 @@ Check out this demo video to get a first impression of what nut.js is capable of
 
 nut.js provides [public API documentation](https://nut-tree.github.io/apidoc/) auto-generated by [TypeDoc](https://typedoc.org).
 
-# Discussion
-
-In [nut-tree/rfc](https://github.com/nut-tree/rfc) documents regarding larger design / implementation changes in nut.js are up for discussion.
-
 # Community
 
 Feel free to join our [Discord community](https://discord.gg/sJkN7789XR)
@@ -89,11 +91,11 @@ It's work in progress and will undergo constant modification.
 
 ## Screen
 
-- [x] Find an image on screen
+- [x] Find an image on screen (requires an additional provider package like e.g. [nut-tree/template-matcher](https://www.npmjs.com/package/@nut-tree/template-matcher))
 - [x] Find all image occurrences on screen
-- [x] Wait for an image to appear on screen
+- [x] Wait for an image to appear on screen (requires an additional provider package like e.g. [nut-tree/template-matcher](https://www.npmjs.com/package/@nut-tree/template-matcher))
 - [x] Retrieve RGBA color information on screen
-- [x] Hooks to trigger actions based on images
+- [x] Hooks to trigger actions based on images (requires an additional provider package like e.g. [nut-tree/template-matcher](https://www.npmjs.com/package/@nut-tree/template-matcher))
 - [x] Highlighting screen regions
 
 ## Integration
@@ -103,12 +105,12 @@ It's work in progress and will undergo constant modification.
 
 # Sample
 
-The following snippet shows a valid `nut.js` example (on macOS)
+The following snippet shows a valid `nut.js` example:
 
 ```js
 "use strict";
 
-const { keyboard, Key, mouse, left, right, up, down, screen } = require("@nut-tree/nut-js");
+const { mouse, left, right, up, down, straightTo, centerOf, Region} = require("@nut-tree/nut-js");
 
 const square = async () => {
   await mouse.move(right(500));
@@ -117,30 +119,23 @@ const square = async () => {
   await mouse.move(up(500));
 };
 
-const openSpotlight = async () => {
-  await keyboard.pressKey(Key.LeftSuper);
-  await keyboard.pressKey(Key.Space);
-  await keyboard.releaseKey(Key.Space);
-  await keyboard.releaseKey(Key.LeftSuper);
-};
-
 (async () => {
     await square();
-    await openSpotlight();
-    await keyboard.type("calculator");
-    await keyboard.type(Key.Return);
+    await mouse.move(
+        straightTo(
+            centerOf(
+                new Region(100, 100, 200, 300)
+            )
+        )
+    );
 })();
 ```
 
 # Installation
 
-`nut.js` comes with a pre-built version of OpenCV for your respective target platform.
-In order to use these pre-compiled bindings, certain runtime conditions have to be met.
-
 ## Prerequisites
 
 This section lists runtime requirements for `nut.js` on the respective target platform.
-`nut.js` is built and tested against node 10 and later as well as Electron 4 and later, so in order to use `nut.js` please make sure to use one of these versions.
 
 #### Windows
 

lib/image.class.spec.ts

@@ -1,4 +1,4 @@
-import {Image} from "./image.class";
+import {Image, isImage} from "./image.class";
 import {imageToJimp} from "./provider/io/imageToJimp.function";
 import {ColorMode} from "./colormode.enum";
 
@@ -65,4 +65,65 @@ describe("Image class", () => {
             expect(imageToJimp).not.toBeCalledTimes(1)
         });
     });
+
+    describe('isImage typeguard', () => {
+        it('should identify an Image', () => {
+            // GIVEN
+            const img = new Image(100, 100, Buffer.from([]), 4, 'foo');
+
+            // WHEN
+            const result = isImage(img);
+
+            // THEN
+            expect(result).toBeTruthy();
+        });
+
+        it('should rule out non-objects', () => {
+            // GIVEN
+            const i = "foo";
+
+            // WHEN
+            const result = isImage(i);
+
+            // THEN
+            expect(result).toBeFalsy();
+        });
+
+        it('should rule out possible object with missing properties', () => {
+            // GIVEN
+            const img = {
+                width: 100,
+                height: 100,
+                data: Buffer.from([]),
+                channels: 'foo',
+                id: 'foo',
+                colorMode: ColorMode.BGR
+            };
+
+            // WHEN
+            const result = isImage(img);
+
+            // THEN
+            expect(result).toBeFalsy();
+        });
+
+        it('should rule out possible object with wrong property type', () => {
+            // GIVEN
+            const img = {
+                width: 100,
+                height: 100,
+                data: Buffer.from([]),
+                channels: 'foo',
+                id: 'foo',
+                colorMode: ColorMode.BGR,
+                pixelDensity: 25
+            };
+
+            // WHEN
+            const result = isImage(img);
+
+            // THEN
+            expect(result).toBeFalsy();
+        });
+    })
 });

lib/image.class.ts

@@ -70,3 +70,23 @@ export class Image {
         return new Image(width, height, jimpImage.bitmap.data, channels, id);
     }
 }
+
+const testImage = new Image(100, 100, Buffer.from([]), 4, "typeCheck");
+const imageKeys = Object.keys(testImage);
+
+export function isImage(possibleImage: any): possibleImage is Image {
+    if (typeof possibleImage !== 'object') {
+        return false;
+    }
+    for (const key of imageKeys) {
+        if (!(key in possibleImage)) {
+            return false;
+        }
+        const possibleImageKeyType = typeof possibleImage[key];
+        const imageKeyType = typeof testImage[key as keyof typeof testImage];
+        if (possibleImageKeyType !== imageKeyType) {
+            return false
+        }
+    }
+    return true;
+}

lib/keyboard.class.ts

@@ -65,7 +65,7 @@ export class KeyboardClass {
      * @example
      * ```typescript
      *    // Will press and hold key combination STRG + V
-     *    await keyboard.pressKey(Key.STRG, Key.A);
+     *    await keyboard.pressKey(Key.STRG, Key.V);
      * ```
      *
      * @param keys Array of {@link Key}s to press and hold
@@ -87,7 +87,7 @@ export class KeyboardClass {
      * @example
      * ```typescript
      *    // Will release key combination STRG + V
-     *    await keyboard.releaseKey(Key.STRG, Key.A);
+     *    await keyboard.releaseKey(Key.STRG, Key.V);
      * ```
      *
      * @param keys Array of {@link Key}s to release

lib/location.function.spec.ts

@@ -1,21 +1,45 @@
-import { centerOf, randomPointIn } from "./location.function";
-import { Point } from "./point.class";
-import { Region } from "./region.class";
+import {centerOf, randomPointIn} from "./location.function";
+import {Point} from "./point.class";
+import {Region} from "./region.class";
 
 describe("Location", () => {
-  it("should return the center point of an area.", () => {
-    const expected = new Point(2, 2);
-    const testRegion = new Region(0, 0, 4, 4);
+    describe('centerOf', () => {
+        it("should return the center point of an area.", () => {
+            const expected = new Point(2, 2);
+            const testRegion = new Region(0, 0, 4, 4);
 
-    expect(centerOf(testRegion)).resolves.toEqual(expected);
-  });
+            expect(centerOf(testRegion)).resolves.toEqual(expected);
+        });
 
-  it("should return a random point inside of an area.", async () => {
-    const testRegion = new Region(100, 20, 50, 35);
-    const result = await randomPointIn(testRegion);
-    expect(result.x).toBeGreaterThanOrEqual(testRegion.left);
-    expect(result.x).toBeLessThanOrEqual(testRegion.left + testRegion.width);
-    expect(result.y).toBeGreaterThanOrEqual(testRegion.top);
-    expect(result.y).toBeLessThanOrEqual(testRegion.top + testRegion.height);
-  });
+        it("should throw on non Region input", async () => {
+            const testRegion = {
+                left: 0,
+                top: 0,
+                width: 4
+            };
+
+            await expect(centerOf(testRegion as Region)).rejects.toThrowError(/^centerOf requires a Region, but received/);
+        });
+    });
+
+    describe('randomPointIn', () => {
+        it("should return a random point inside of an area.", async () => {
+            const testRegion = new Region(100, 20, 50, 35);
+            const result = await randomPointIn(testRegion);
+            expect(result.x).toBeGreaterThanOrEqual(testRegion.left);
+            expect(result.x).toBeLessThanOrEqual(testRegion.left + testRegion.width);
+            expect(result.y).toBeGreaterThanOrEqual(testRegion.top);
+            expect(result.y).toBeLessThanOrEqual(testRegion.top + testRegion.height);
+        });
+
+        it("should throw on non Region input", async () => {
+            const testRegion = {
+                left: 0,
+                top: 0,
+                width: 4
+            };
+
+            await expect(randomPointIn(testRegion as Region)).rejects.toThrowError(/^randomPointIn requires a Region, but received/);
+        });
+    });
 });

lib/location.function.ts

@@ -1,26 +1,32 @@
-import { Point } from "./point.class";
-import { Region } from "./region.class";
+import {Point} from "./point.class";
+import {isRegion, Region} from "./region.class";
 
 /**
  * {@link centerOf} returns the center {@link Point} for a given {@link Region}
  * @param target {@link Region} to determine the center {@link Point} for
  */
 export const centerOf = async (target: Region | Promise<Region>): Promise<Point> => {
-  const targetRegion = await target;
-  const x = Math.floor(targetRegion.left + targetRegion.width / 2);
-  const y = Math.floor(targetRegion.top + targetRegion.height / 2);
+    const targetRegion = await target;
+    if (!isRegion(targetRegion)) {
+        throw Error(`centerOf requires a Region, but received ${JSON.stringify(targetRegion)}`)
+    }
+    const x = Math.floor(targetRegion.left + targetRegion.width / 2);
+    const y = Math.floor(targetRegion.top + targetRegion.height / 2);
 
-  return new Point(x, y);
+    return new Point(x, y);
 };
 
 /**
  * {@link randomPointIn} returns a random {@link Point} within a given {@link Region}
  * @param target {@link Region} the random {@link Point} has to be within
  */
 export const randomPointIn = async (target: Region | Promise<Region>): Promise<Point> => {
-  const targetRegion = await target;
-  const x = Math.floor(targetRegion.left + Math.random() * targetRegion.width);
-  const y = Math.floor(targetRegion.top + Math.random() * targetRegion.height);
+    const targetRegion = await target;
+    if (!isRegion(targetRegion)) {
+        throw Error(`randomPointIn requires a Region, but received ${JSON.stringify(targetRegion)}`)
+    }
+    const x = Math.floor(targetRegion.left + Math.random() * targetRegion.width);
+    const y = Math.floor(targetRegion.top + Math.random() * targetRegion.height);
 
-  return new Point(x, y);
+    return new Point(x, y);
 };

lib/mouse.class.ts

@@ -1,5 +1,5 @@
 import {Button} from "./button.enum";
-import {Point} from "./point.class";
+import {isPoint, Point} from "./point.class";
 import {busyWaitForNanoSeconds, sleep} from "./sleep.function";
 import {calculateMovementTimesteps, EasingFunction, linear} from "./mouse-movement.function";
 import {ProviderRegistry} from "./provider/provider-registry.class";
@@ -36,6 +36,9 @@ export class MouseClass {
      * @param target {@link Point} to move the cursor to
      */
     public async setPosition(target: Point): Promise<MouseClass> {
+        if (!isPoint(target)) {
+            throw Error(`setPosition requires a Point, but received ${JSON.stringify(target)}`)
+        }
         return new Promise<MouseClass>(async (resolve, reject) => {
             try {
                 await this.providerRegistry.getMouse().setMousePosition(target);
@@ -67,7 +70,7 @@ export class MouseClass {
                     const node = pathSteps[idx];
                     const minTime = timeSteps[idx];
                     await busyWaitForNanoSeconds(minTime);
-                    await this.providerRegistry.getMouse().setMousePosition(node);
+                    await this.setPosition(node);
                 }
                 resolve(this);
             } catch (e) {