@appium/support 4.0.0 → 4.0.2

package/README.md

@@ -1,62 +1,112 @@
 # appium-support
 
-Utility functions used to support libs used across appium packages.
-
-`npm install appium-support`
-
-Appium, as of version 1.5 is all based on promises, so this module provides promise wrappers for some common operations.
-
-Most notably, we wrap `fs` for file system commands. Note the addition of `hasAccess`.
-Also note that `fs.mkdir` doesn't throw an error if the directory already exists, it will just resolve.
-
-### Methods
-
-- system.isWindows
-- system.isMac
-- system.isLinux
-- system.isOSWin64
-- system.arch
-- system.macOsxVersion
-
-- util.hasContent - returns true if input string has content
-- util.hasValue - returns true if input value is not undefined and no null
-- util.escapeSpace
-- util.escapeSpecialChars
-- util.localIp
-- util.cancellableDelay
-- util.multiResolve - multiple path.resolve
-- util.unwrapElement - parse an element ID from an element object: e.g.: `{ELEMENT: 123, "element-6066-11e4-a52e-4f735466cecf": 123}` returns `123`
-- util.wrapElement - convert an element ID to an element object of the form: e.g.: `123` returns `{ELEMENT: 123, "element-6066-11e4-a52e-4f735466cecf": 123}`
-
-- *fs.hasAccess* - use this over `fs.access`
-- *fs.exists* - calls `fs.hasAccess`
-- *fs.rimraf*
-- *fs.mkdir* - doesn't throw an error if directory already exists
-- *fs.copyFile*
-- fs.open
-- fs.close
-- fs.access
-- fs.readFile
-- fs.writeFile
-- fs.write
-- fs.readlink
-- fs.chmod
-- fs.unlink
-- fs.readdir
-- fs.stat
-- fs.rename
-- *fs.md5*
-
-- plist.parsePlistFile
-- plist.updatePlistFile
-
-- mkdirp
-
-- logger
-
-- zip.extractAllTo - Extracts contents of a zipfile to a directory
-- zip.readEntries - Reads entries (files and directories) of a zipfile
-- zip.toInMemoryZip - Converts a directory into a base64 zipfile
+Utility functions used to support Appium drivers and plugins.
+
+# Usage in drivers and plugins
+
+It is recommended to have Appium as a peer dependency in driver and plugin packages.
+Add the following line to `peerDependencies` section of your module's `package.json`:
+
+```js
+  "peerDependencies": {
+    "appium": "^<minimum_server_version>"
+  }
+```
+
+Afterwards import it in your code similarly to the below example:
+
+```js
+import {timing, util} from 'appium/support';
+```
+
+# Usage in helper modules
+
+If you want to use this module in a helper library, which is not a driver or a plugin,
+then add the following line to `dependencies` section of your module's `package.json`:
+
+```js
+  "dependencies": {
+    "@appium/support": "<module_version>"
+  }
+```
+
+Afterwards import it in your code similarly to the below example:
+
+```js
+import {timing, util} from '@appium/support';
+```
+
+### Categories
+
+All utility functions are split into a bunch of different categories. Each category has its own file under the `lib` folder. All utility functions in these files are documented.
+
+#### fs
+
+Most of the functions there are just thin wrappers over utility functions available in [Promises API](https://nodejs.org/api/fs.html#promises-api).
+
+#### env
+
+Several helpers needed by the server to cope with internal dependencies and manifests.
+
+#### console
+
+Wrappers for the command line interface abstraction used by the Appium server.
+
+#### image-util
+
+Utilities to work with images. Use [sharp](https://github.com/lovell/sharp) under the hood.
+
+#### log-internal
+
+Utilities needed for internal Appium log config assistance.
+
+#### logging
+
+See [below](#logger)
+
+#### mjpeg
+
+Helpers needed to implement [MJPEG streaming](https://en.wikipedia.org/wiki/Motion_JPEG#Video_streaming).
+
+#### net
+
+Helpers needed for network interactions, for example, upload and download of files.
+
+#### node
+
+Set of Node.js-specific utility functions needed, for example, to ensure objects immutability or to calculate their sizes.
+
+#### npm
+
+Set of [npm](https://en.wikipedia.org/wiki/Npm_(software))-related helpers.
+
+#### plist
+
+Set of utilities used to read and write data from [plist](https://en.wikipedia.org/wiki/Property_List) files in javascript.
+
+#### process
+
+Helpers for interactions with system processes. These APIs don't support Windows.
+
+#### system
+
+Set of helper functions needed to determine properties of the current operating system.
+
+#### tempdir
+
+Set of helpers that allow interactions with temporary folders.
+
+#### timing
+
+Helpers that allow to measure execution time.
+
+#### util
+
+Miscellaneous utilities.
+
+#### zip
+
+Helpers that allow to work with archives in .ZIP format.
 
 
 ## logger
@@ -85,10 +135,9 @@ Will produce
 warn mymodule a warning
 ```
 
-
 ### Environment variables
 
-There are two environment variable flags that affect the way `appium-base-driver` `logger` works.
+There are two environment variable flags that affect the way `logger` works.
 
 `_TESTING`
 
@@ -108,43 +157,43 @@ There are two environment variable flags that affect the way `appium-base-driver
 `log[level](message)`
 
 - logs to `level`
-    ```js
-    import { logger } from 'appium-support';
-    let log = logger.getLogger('mymodule');
+```js
+import { logger } from 'appium-support';
+let log = logger.getLogger('mymodule');
 
-    log.info('hi!');
-    // => info mymodule hi!
-    ```
+log.info('hi!');
+// => info mymodule hi!
+```
 
 `log.unwrap()`
 
 - retrieves the underlying [npmlog](https://github.com/npm/npmlog) object, in order to manage how logging is done at a low level (e.g., changing output streams, retrieving an array of messages, adding log levels, etc.).
 
-    ```js
-    import { getLogger } from 'appium-base-driver';
-    let log = getLogger('mymodule');
+```js
+import { getLogger } from 'appium-base-driver';
+let log = getLogger('mymodule');
 
-    log.info('hi!');
+log.info('hi!');
 
-    let npmlogger = log.unwrap();
+let npmlogger = log.unwrap();
 
-    // any `npmlog` methods
-    let logs = npmlogger.record;
-    // logs === [ { id: 0, level: 'info', prefix: 'mymodule', message: 'hi!', messageRaw: [ 'hi!' ] }]
-    ```
+// any `npmlog` methods
+let logs = npmlogger.record;
+// logs === [ { id: 0, level: 'info', prefix: 'mymodule', message: 'hi!', messageRaw: [ 'hi!' ] }]
+```
 
 `log.errorAndThrow(error)`
 
 - logs the error passed in, at `error` level, and then throws the error. If the error passed in is not an instance of [Error](https://nodejs.org/api/errors.html#errors_class_error) (either directly, or a subclass of `Error`) it will be wrapped in a generic `Error` object.
 
-    ```js
-    import { getLogger } from 'appium-base-driver';
-    let log = getLogger('mymodule');
+```js
+import { getLogger } from 'appium-base-driver';
+let log = getLogger('mymodule');
 
-    // previously there would be two lines
-    log.error('This is an error');
-    throw new Error('This is an error');
+// previously there would be two lines
+log.error('This is an error');
+throw new Error('This is an error');
 
-    // now is compacted
-    log.errorAndThrow('This is an error');
-    ```
+// now is compacted
+log.errorAndThrow('This is an error');
+```

package/build/lib/image-util.d.ts

@@ -3,9 +3,8 @@
  *
  * @param {string} base64Image The string with base64 encoded image.
  * Supports all image formats natively supported by Sharp library.
- * @param {sharp.Region} rect The selected region of image
+ * @param {import('sharp').Region} rect The selected region of image
  * @return {Promise<string>} base64 encoded string of cropped image
  */
-export function cropBase64Image(base64Image: string, rect: sharp.Region): Promise<string>;
-import sharp from "sharp";
+export function cropBase64Image(base64Image: string, rect: import('sharp').Region): Promise<string>;
 //# sourceMappingURL=image-util.d.ts.map

package/build/lib/image-util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-util.d.ts","sourceRoot":"","sources":["../../lib/image-util.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,6CALW,MAAM,QAEN,MAAM,MAAM,GACX,QAAQ,MAAM,CAAC,CAK1B"}
+{"version":3,"file":"image-util.d.ts","sourceRoot":"","sources":["../../lib/image-util.js"],"names":[],"mappings":"AAoBA;;;;;;;GAOG;AACH,6CALW,MAAM,QAEN,OAAO,OAAO,EAAE,MAAM,GACrB,QAAQ,MAAM,CAAC,CAK1B"}

package/build/lib/image-util.js

@@ -1,20 +1,33 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cropBase64Image = void 0;
-const sharp_1 = __importDefault(require("sharp"));
+let _sharp;
+/**
+ * @returns {import('sharp')}
+ */
+function requireSharp() {
+    if (!_sharp) {
+        try {
+            _sharp = require('sharp');
+        }
+        catch (err) {
+            throw new Error(`Cannot load the 'sharp' module needed for images processing. ` +
+                `Consider visiting https://sharp.pixelplumbing.com/install ` +
+                `for troubleshooting. Original error: ${err.message}`);
+        }
+    }
+    return _sharp;
+}
 /**
  * Crop the image by given rectangle (use base64 string as input and output)
  *
  * @param {string} base64Image The string with base64 encoded image.
  * Supports all image formats natively supported by Sharp library.
- * @param {sharp.Region} rect The selected region of image
+ * @param {import('sharp').Region} rect The selected region of image
  * @return {Promise<string>} base64 encoded string of cropped image
  */
 async function cropBase64Image(base64Image, rect) {
-    const buf = await (0, sharp_1.default)(Buffer.from(base64Image, 'base64')).extract(rect).toBuffer();
+    const buf = await requireSharp()(Buffer.from(base64Image, 'base64')).extract(rect).toBuffer();
     return buf.toString('base64');
 }
 exports.cropBase64Image = cropBase64Image;

package/build/lib/image-util.js.map

@@ -1 +1 @@
-{"version":3,"file":"image-util.js","sourceRoot":"","sources":["../../lib/image-util.js"],"names":[],"mappings":";;;;;;AAAA,kDAA0B;AAE1B;;;;;;;GAOG;AACI,KAAK,UAAU,eAAe,CAAC,WAAW,EAAE,IAAI;IACrD,MAAM,GAAG,GAAG,MAAM,IAAA,eAAK,EAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IACrF,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAHD,0CAGC"}
+{"version":3,"file":"image-util.js","sourceRoot":"","sources":["../../lib/image-util.js"],"names":[],"mappings":";;;AAAA,IAAI,MAAM,CAAC;AAEX;;GAEG;AACH,SAAS,YAAY;IACnB,IAAI,CAAC,MAAM,EAAE;QACX,IAAI;YACF,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;SAC3B;QAAC,OAAO,GAAG,EAAE;YACZ,MAAM,IAAI,KAAK,CACb,+DAA+D;gBAC/D,4DAA4D;gBAC5D,wCAAwC,GAAG,CAAC,OAAO,EAAE,CACtD,CAAC;SACH;KACF;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,eAAe,CAAC,WAAW,EAAE,IAAI;IACrD,MAAM,GAAG,GAAG,MAAM,YAAY,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC9F,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAHD,0CAGC"}

package/lib/image-util.js

@@ -1,14 +1,32 @@
-import sharp from 'sharp';
+let _sharp;
+
+/**
+ * @returns {import('sharp')}
+ */
+function requireSharp() {
+  if (!_sharp) {
+    try {
+      _sharp = require('sharp');
+    } catch (err) {
+      throw new Error(
+        `Cannot load the 'sharp' module needed for images processing. ` +
+        `Consider visiting https://sharp.pixelplumbing.com/install ` +
+        `for troubleshooting. Original error: ${err.message}`
+      );
+    }
+  }
+  return _sharp;
+}
 
 /**
  * Crop the image by given rectangle (use base64 string as input and output)
  *
  * @param {string} base64Image The string with base64 encoded image.
  * Supports all image formats natively supported by Sharp library.
- * @param {sharp.Region} rect The selected region of image
+ * @param {import('sharp').Region} rect The selected region of image
  * @return {Promise<string>} base64 encoded string of cropped image
  */
 export async function cropBase64Image(base64Image, rect) {
-  const buf = await sharp(Buffer.from(base64Image, 'base64')).extract(rect).toBuffer();
+  const buf = await requireSharp()(Buffer.from(base64Image, 'base64')).extract(rect).toBuffer();
   return buf.toString('base64');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/support",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Support libs used across appium packages",
   "keywords": [
     "automation",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@appium/tsconfig": "^0.3.0",
-    "@appium/types": "^0.11.1",
+    "@appium/types": "^0.12.0",
     "@colors/colors": "1.5.0",
     "@types/archiver": "5.3.2",
     "@types/base64-stream": "1.0.2",
@@ -55,11 +55,12 @@
     "@types/ncp": "2.0.5",
     "@types/npmlog": "4.1.4",
     "@types/pluralize": "0.0.29",
-    "@types/semver": "7.3.13",
+    "@types/semver": "7.5.0",
     "@types/shell-quote": "1.7.1",
     "@types/supports-color": "8.1.1",
     "@types/teen_process": "2.0.0",
     "@types/uuid": "9.0.1",
+    "@types/which": "3.0.0",
     "archiver": "5.3.1",
     "axios": "1.4.0",
     "base64-stream": "1.0.0",
@@ -85,17 +86,19 @@
     "read-pkg": "5.2.0",
     "resolve-from": "5.0.0",
     "sanitize-filename": "1.6.3",
-    "semver": "7.5.0",
-    "sharp": "0.32.1",
+    "semver": "7.5.1",
     "shell-quote": "1.8.1",
     "source-map-support": "0.5.21",
     "supports-color": "8.1.1",
     "teen_process": "2.0.2",
-    "type-fest": "3.10.0",
+    "type-fest": "3.11.1",
     "uuid": "9.0.0",
     "which": "3.0.1",
     "yauzl": "2.10.0"
   },
+  "optionalDependencies": {
+    "sharp": "0.32.1"
+  },
   "engines": {
     "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
     "npm": ">=8"
@@ -103,7 +106,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6b245534c213f3b8d6405515aee1e89133295098",
+  "gitHead": "d0ebbaa0c683eeba04d9d967af2d0fde76197950",
   "typedoc": {
     "entryPoint": "./lib/index.js"
   }