Release/v3.0.0 (#465)

* Updated CHANGELOG.md for v3.0.0

* Version bump to v3.0.0

* Updated readme

* Updated changelog

* Updated docstrings

Author: s1hofmann

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## 3.0.0
+
+- Enhancement: Improve types of Jest matchers [(#466)](https://github.com/nut-tree/nut.js/issues/466)
+- BREAKING: Rename clipboard methods [(#463)](https://github.com/nut-tree/nut.js/issues/463)
+- Enhancement: Option to disable automatic request of permissions in macOS [(#462)](https://github.com/nut-tree/nut.js/issues/462)
+- BREAKING: Allow `screen.find` and other to work with non-image needles [(#455)](https://github.com/nut-tree/nut.js/issues/455)
+- BREAKING: Add bits per pixel and byteWidth info to image class [(#451)](https://github.com/nut-tree/nut.js/issues/451)
+- Bugfix: Installed Electron App crashes after upgrading to 2.3.0 [(#449)](https://github.com/nut-tree/nut.js/issues/449)
+- Maintenance: Add .nvmrc config [(#447)](https://github.com/nut-tree/nut.js/issues/447)
+- Enhancement: Define and export interfaces for keyboard/mouse/screen configs [(#443)](https://github.com/nut-tree/nut.js/issues/445)
+- Bugfix: 'RightShift' key is mapped to space [(#442)](https://github.com/nut-tree/nut.js/issues/442)
+- Maintenance: Introduce prettier [(#437)](https://github.com/nut-tree/nut.js/issues/437)
+- Bugfix: Win2012-R2: Error: The specified procedure could not be found [(#434)](https://github.com/nut-tree/nut.js/issues/434)
+- Feature: Logging provider [(#371)](https://github.com/nut-tree/nut.js/issues/371)
+
 ## 2.3.0
 
 - Bugfix: Segmentation Fault when retrieving window title [(#377)](https://github.com/nut-tree/nut.js/issues/377)

README.md

@@ -40,15 +40,6 @@ but additionally gives you the possibility to navigate the screen based on image
 
 A huge **"Thank you!"** goes out to all sponsors who make open source a bit more sustainable!
 
-[<img src="https://avatars.githubusercontent.com/u/17616211?v=4" width="75" alt="Reiss Cashmore" />](https://github.com/Reiss-Cashmore)
-[<img src="https://avatars.githubusercontent.com/u/1794527?v=4" width="75" alt="Chet Corcos" />](https://github.com/ccorcos)
-[<img src="https://avatars.githubusercontent.com/u/4453806?v=4" width="75" alt="Patrick Flor" />](https://github.com/senorflor)
-[<img src="https://avatars.githubusercontent.com/u/7562803?v=4" width="75" alt="Ian" />](https://github.com/iwiedenm)
-
-<hr/>
-
-[<img src="https://github.com/nut-tree/nut.js/raw/develop/.gfx/sponsors/mighty.svg" height="75" alt="Mighty browser logo"/>](https://www.mightyapp.com)
-
 # Demo
 
 Check out this demo video to get a first impression of what nut.js is capable of.
@@ -102,46 +93,72 @@ It's work in progress and will undergo constant modification.
 
 ## 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 (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 (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
+- [x] Find a single or multiple occurrences of 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] 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] Find a single or multiple occurrences of text on screen (\*)
+- [x] Wait for a piece of text to appear on screen (\*)
+- [x] Find a single or multiple windows on screen (\*)
+- [x] Wait for a window to appear on screen (\*)
+- [x] Hooks to trigger actions based on detected text, images or windows (\*)
+
+(\*) Requires an additional provider package, visit [nutjs.dev](https://nutjs.dev) for more info
 
 ## Integration
 
 - [x] Jest
 - [x] Electron
+- [x] Custom log integration
 
 # Sample
 
-The following snippet shows a valid `nut.js` example:
+The following snippet shows a valid `nut.js` example (using multiple addons):
 
 ```js
 "use strict";
 
 const {
   mouse,
-  left,
-  right,
-  up,
-  down,
+  screen,
+  singleWord,
+  sleep,
+  useConsoleLogger,
+  ConsoleLogLevel,
   straightTo,
   centerOf,
-  Region,
+  Button,
+  getActiveWindow,
 } = require("@nut-tree/nut-js");
+const {
+  preloadLanguages,
+  Language,
+  LanguageModelType,
+  configure,
+} = require("@nut-tree/plugin-ocr");
+
+configure({ languageModelType: LanguageModelType.BEST });
+
+useConsoleLogger({ logLevel: ConsoleLogLevel.DEBUG });
+
+screen.config.autoHighlight = true;
+screen.config.ocrConfidence = 0.8;
 
-const square = async () => {
-  await mouse.move(right(500));
-  await mouse.move(down(500));
-  await mouse.move(left(500));
-  await mouse.move(up(500));
-};
+function activeWindowRegion() {
+  return getActiveWindow().then((activeWindow) => activeWindow.region);
+}
 
 (async () => {
-  await square();
-  await mouse.move(straightTo(centerOf(new Region(100, 100, 200, 300))));
+  await preloadLanguages([Language.English], [LanguageModelType.BEST]);
+  await sleep(5000);
+  const result = await screen.find(singleWord("@nut-tree/nut-js"));
+  await mouse.move(straightTo(centerOf(result)));
+  await mouse.click(Button.LEFT);
+  await screen.waitFor(singleWord("Native"), 15000, 1000, {
+    providerData: { partialMatch: true },
+  });
+  const content = await screen.read({ searchRegion: activeWindowRegion() });
+  console.log(content);
 })();
 ```
 

lib/query.class.ts

@@ -23,22 +23,52 @@ type Query =
 
 export type TextQuery = Extract<Query, { type: "text" }>;
 
-export type WordQuery = Extract<TextQuery, { by: { word: string | RegExp } }>;
-export type LineQuery = Extract<TextQuery, { by: { line: string | RegExp } }>;
+/**
+ * A word query is a text query that searches for a single word on screen.
+ * It will be processed by an {@link TextFinderInterface} instance.
+ */
+export type WordQuery = Extract<TextQuery, { by: { word: string } }>;
 
+/**
+ * A word query is a text query that searches for a single text line on screen.
+ * It will be processed by an {@link TextFinderInterface} instance.
+ */
+export type LineQuery = Extract<TextQuery, { by: { line: string } }>;
+
+/**
+ * A window query is a query that searches for a window on screen.
+ * It will be processed by an {@link WindowFinderInterface} instance.
+ */
 export type WindowQuery = Extract<Query, { type: "window" }>;
 
+/**
+ * Type guard for {@link WordQuery}
+ * @param possibleQuery A possible word query
+ */
 export const isWordQuery = (possibleQuery: any): possibleQuery is WordQuery => {
   return possibleQuery?.type === "text" && possibleQuery?.by?.word != null;
 };
+
+/**
+ * Type guard for {@link LineQuery}
+ * @param possibleQuery A possible line query
+ */
 export const isLineQuery = (possibleQuery: any): possibleQuery is LineQuery => {
   return possibleQuery?.type === "text" && possibleQuery?.by?.line != null;
 };
 
+/**
+ * Type guard for {@link TextQuery}
+ * @param possibleQuery A possible line or word query
+ */
 export const isTextQuery = (possibleQuery: any): possibleQuery is TextQuery => {
   return possibleQuery?.type === "text";
 };
 
+/**
+ * Type guard for {@link WindowQuery}
+ * @param possibleQuery A possible window query
+ */
 export const isWindowQuery = (
   possibleQuery: any
 ): possibleQuery is WindowQuery => {

lib/screen.class.ts

@@ -415,7 +415,7 @@ export class ScreenClass {
    * @param searchInput Filename of the template image, relative to {@link ScreenClass.config.resourceDirectory}, or an {@link Image}
    * @param timeoutMs Timeout in milliseconds after which {@link waitFor} fails
    * @param updateInterval Update interval in milliseconds to retry search
-   * @param params {@link LocationParameters} which are used to fine tune search region and / or match confidence
+   * @param params {@link OptionalSearchParameters} which are used to fine tune search region and / or match confidence
    */
   public async waitFor<PROVIDER_DATA_TYPE>(
     searchInput: RegionResultFindInput | Promise<RegionResultFindInput>,

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@nut-tree/nut-js",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "license": "Apache-2.0",
   "main": "dist/index",
   "typings": "dist/index",