@appium/support 2.55.4 → 2.57.0

package/lib/fs.js

@@ -1,76 +1,162 @@
-// jshint ignore: start
-import _ from 'lodash';
-import path from 'path';
-import _fs from 'fs';
-import rimraf from 'rimraf';
-import ncp from 'ncp';
+// @ts-check
+
 import B from 'bluebird';
-import mv from 'mv';
-import which from 'which';
-import glob from 'glob';
 import crypto from 'crypto';
+import { close, constants, createReadStream, createWriteStream, promises as fsPromises, read, write, open } from 'fs';
+import glob from 'glob';
 import klaw from 'klaw';
+import _ from 'lodash';
+import mv from 'mv';
+import ncp from 'ncp';
+import path from 'path';
+import pkgDir from 'pkg-dir';
+import readPkg from 'read-pkg';
+import rimrafIdx from 'rimraf';
 import sanitize from 'sanitize-filename';
-import findRoot from 'find-root';
-import { pluralize } from './util';
+import which from 'which';
 import log from './logger';
 import Timer from './timing';
+import { pluralize } from './util';
 
-const mkdirAsync = B.promisify(_fs.mkdir);
-const ncpAsync = B.promisify(ncp);
-const findRootCached = _.memoize(findRoot);
+const ncpAsync = /** @type {(source: string, dest: string, opts: ncp.Options|undefined) => B<void>} */(B.promisify(ncp));
+const findRootCached = _.memoize(pkgDir.sync);
 
 const fs = {
+  /**
+   * Resolves `true` if `path` is _readable_, which differs from Node.js' default behavior of "can we see it?"
+   * @param {import('fs').PathLike} path
+   * @returns {Promise<boolean>}
+   */
   async hasAccess (path) {
     try {
-      await this.access(path, _fs.R_OK);
+      await fsPromises.access(path, constants.R_OK);
     } catch (err) {
       return false;
     }
     return true;
   },
-  exists (path) { return this.hasAccess(path); },
-  rimraf: B.promisify(rimraf),
-  rimrafSync: rimraf.sync.bind(rimraf),
-  async mkdir (...args) {
+
+  /**
+   * Alias for {@linkcode fs.hasAccess}
+   * @param {import('fs').PathLike} path
+   */
+  async exists (path) {
+    return await fs.hasAccess(path);
+  },
+
+  /**
+   * Remove a directory and all its contents, recursively
+   * @todo Replace with `rm()` from `fs.promises` when Node.js v12 support is dropped.
+   */
+  rimraf: /** @type {(dirpath: string, opts?: import('rimraf').Options) => Promise<void>} */(B.promisify(rimrafIdx)),
+
+  /**
+   * Alias of {@linkcode rimrafIdx.sync}
+   * @todo Replace with `rmSync()` from `fs` when Node.js v12 support is dropped.
+   */
+  rimrafSync: rimrafIdx.sync,
+
+  /**
+   * Like Node.js' `fsPromises.mkdir()`, but will _not_ reject if the directory already exists.
+   *
+   * @param {string|Buffer|URL} filepath
+   * @param {import('fs').MakeDirectoryOptions} [opts]
+   * @returns {Promise<string|undefined>}
+   * @see https://nodejs.org/api/fs.html#fspromisesmkdirpath-options
+   */
+  async mkdir (filepath, opts = {}) {
     try {
-      return await mkdirAsync(...args);
+      return await fsPromises.mkdir(filepath, opts);
     } catch (err) {
-      if (err && err.code !== 'EEXIST') {
+      if (err?.code !== 'EEXIST') {
         throw err;
       }
     }
   },
-  async copyFile (source, destination, ...otherArgs) {
-    if (!await this.hasAccess(source)) {
+  /**
+   * Copies files _and entire directories_
+   * @param {string} source - Source to copy
+   * @param {string} destination - Destination to copy to
+   * @param {ncp.Options} [opts] - Additional arguments to pass to `ncp`
+   * @see https://npm.im/ncp
+   * @returns {Promise<void>}
+   */
+  async copyFile (source, destination, opts = {}) {
+    if (!await fs.hasAccess(source)) {
       throw new Error(`The file at '${source}' does not exist or is not accessible`);
     }
-    return await ncpAsync(source, destination, ...otherArgs);
+    return await ncpAsync(source, destination, opts);
   },
+
+  /**
+   * Create an MD5 hash of a file.
+   * @param {import('fs').PathLike} filePath
+   * @returns {Promise<string>}
+   */
   async md5 (filePath) {
-    return await this.hash(filePath, 'md5');
+    return await fs.hash(filePath, 'md5');
   },
-  mv: B.promisify(mv),
-  which: B.promisify(which),
-  glob: B.promisify(glob),
+
+  /**
+   * Move a file
+   */
+  mv: /** @type {(from: string, to: string, opts?: mv.Options) => B<void>} */(B.promisify(mv)),
+
+  /**
+   * Find path to an executable in system `PATH`
+   * @see https://github.com/npm/node-which
+   */
+  which,
+
+  /**
+   * Given a glob pattern, resolve with list of files matching that pattern
+   * @see https://github.com/isaacs/node-glob
+   */
+  glob: /** @type {(pattern: string, opts?: glob.IOptions) => B<string[]>} */(B.promisify(glob)),
+
+  /**
+   * Sanitize a filename
+   * @see https://github.com/parshap/node-sanitize-filename
+   */
   sanitizeName: sanitize,
+
+  /**
+   * Create a hex digest of some file at `filePath`
+   * @param {import('fs').PathLike} filePath
+   * @param {string} [algorithm]
+   * @returns {Promise<string>}
+   */
   async hash (filePath, algorithm = 'sha1') {
     return await new B((resolve, reject) => {
       const fileHash = crypto.createHash(algorithm);
-      const readStream = _fs.createReadStream(filePath);
+      const readStream = createReadStream(filePath);
       readStream.on('error', (e) => reject(
         new Error(`Cannot calculate ${algorithm} hash for '${filePath}'. Original error: ${e.message}`)));
       readStream.on('data', (chunk) => fileHash.update(chunk));
       readStream.on('end', () => resolve(fileHash.digest('hex')));
     });
   },
-  /** The callback function which will be called during the directory walking
-   * @name WalkDirCallback
-   * @function
-   * @param {string} itemPath The path of the file or folder
-   * @param {boolean} isDirectory Shows if it is a directory or a file
-   * @return {boolean} return true if you want to stop walking
-  */
+
+  /**
+   * Returns an `Walker` instance, which is a readable stream (and thusly an async iterator).
+   *
+   * @param {string} dir - Dir to start walking at
+   * @param {import('klaw').Options} [opts]
+   * @returns {import('klaw').Walker}
+   * @see https://www.npmjs.com/package/klaw
+   */
+  walk (dir, opts) {
+    return klaw(dir, opts);
+  },
+
+  /**
+   * Recursively create a directory.
+   * @param {import('fs').PathLike} dir
+   * @returns {Promise<string|undefined>}
+   */
+  async mkdirp (dir) {
+    return await fs.mkdir(dir, {recursive: true});
+  },
 
   /**
    * Walks a directory given according to the parameters given. The callback will be invoked with a path joined with the dir parameter
@@ -78,7 +164,7 @@ const fs = {
    * @param {boolean} recursive Set it to true if you want to continue walking sub directories
    * @param {WalkDirCallback} callback The callback to be called when a new path is found
    * @throws {Error} If the `dir` parameter contains a path to an invalid folder
-   * @return {?string} returns the found path or null if the item was not found
+   * @returns {Promise<string?>} returns the found path or null if the item was not found
    */
   async walkDir (dir, recursive, callback) { //eslint-disable-line promise/prefer-await-to-callbacks
     let isValidRoot = false;
@@ -131,7 +217,9 @@ const fs = {
       })
       .on('end', function () {
         lastFileProcessed
-          .then(resolve)
+          .then((file) => {
+            resolve(/** @type {string|undefined} */(file) ?? null);
+          })
           .catch(function (err) {
             log.warn(`Unexpected error: ${err.message}`);
             reject(err);
@@ -149,14 +237,14 @@ const fs = {
   /**
    * Reads the closest `package.json` file from absolute path `dir`.
    * @param {string} dir - Directory to search from
-   * @throws {TypeError} If `dir` is not a nonempty string or relative path
+   * @param {import('read-pkg').Options} [opts] - Additional options for `read-pkg`
    * @throws {Error} If there were problems finding or reading a `package.json` file
    * @returns {object} A parsed `package.json`
    */
-  readPackageJsonFrom (dir) {
-    const root = fs.findRoot(dir);
+  readPackageJsonFrom (dir, opts = {}) {
+    const cwd = fs.findRoot(dir);
     try {
-      return JSON.parse(_fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+      return readPkg.sync({...opts, cwd});
     } catch (err) {
       err.message = `Failed to read a \`package.json\` from dir \`${dir}\`:\n\n${err.message}`;
       throw err;
@@ -178,34 +266,75 @@ const fs = {
       throw new Error(`\`findRoot()\` could not find \`package.json\` from ${dir}`);
     }
     return result;
-  }
-};
+  },
+
+  // add the supported `fs` functions
+  access: fsPromises.access,
+  appendFile: fsPromises.appendFile,
+  chmod: fsPromises.chmod,
+  close: B.promisify(close),
+  constants,
+  createWriteStream,
+  createReadStream,
+  lstat: fsPromises.lstat,
+  /**
+   * Warning: this is a promisified {@linkcode open fs.open}.
+   * It resolves w/a file descriptor instead of a {@linkcode fsPromises.FileHandle FileHandle} object, as {@linkcode fsPromises.open} does. Use {@linkcode fs.openFile} if you want a `FileHandle`.
+   * @type {(path: import('fs').PathLike, flags: import('fs').OpenMode, mode?: import('fs').Mode) => Promise<number>}
+   */
+  open: B.promisify(open),
+  openFile: fsPromises.open,
+  readdir: fsPromises.readdir,
+  read: B.promisify(read),
+  readFile: fsPromises.readFile,
+  readlink: fsPromises.readlink,
+  realpath: fsPromises.realpath,
+  rename: fsPromises.rename,
+  stat: fsPromises.stat,
+  symlink: fsPromises.symlink,
+  unlink: fsPromises.unlink,
+  write: B.promisify(write),
+  writeFile: fsPromises.writeFile,
+
+  // deprecated props
+
+  /**
+   * Use `constants.F_OK` instead.
+   * @deprecated
+   */
+  F_OK: constants.F_OK,
+
+  /**
+   * Use `constants.R_OK` instead.
+   * @deprecated
+   */
+  R_OK: constants.R_OK,
+
+  /**
+   * Use `constants.W_OK` instead.
+   * @deprecated
+   */
+  W_OK: constants.W_OK,
 
-// add the supported `fs` functions
-const simples = [
-  'open', 'close', 'access', 'readFile', 'writeFile', 'write', 'read',
-  'readlink', 'chmod', 'unlink', 'readdir', 'stat', 'rename', 'lstat',
-  'appendFile', 'realpath', 'symlink',
-];
-for (const s of simples) {
-  fs[s] = B.promisify(_fs[s]);
-}
-
-const syncFunctions = [
-  'createReadStream',
-  'createWriteStream',
-];
-for (const s of syncFunctions) {
-  fs[s] = _fs[s];
-}
-
-// add the constants from `fs`
-const constants = [
-  'F_OK', 'R_OK', 'W_OK', 'X_OK', 'constants',
-];
-for (const c of constants) {
-  fs[c] = _fs[c];
-}
+  /**
+   * Use `constants.X_OK` instead.
+   * @deprecated
+   */
+  X_OK: constants.X_OK
+};
 
 export { fs };
 export default fs;
+
+/**
+ * The callback function which will be called during the directory walking
+ * @callback WalkDirCallback
+ * @param {string} itemPath The path of the file or folder
+ * @param {boolean} isDirectory Shows if it is a directory or a file
+ * @return {boolean} return true if you want to stop walking
+*/
+
+/**
+ * @typedef {import('glob')} glob
+ * @typedef {import('mv')} mv
+ */

package/lib/image-util.js

@@ -15,7 +15,7 @@ const { MIME_JPEG, MIME_PNG, MIME_BMP } = Jimp;
  *
  * @param {Buffer|string} data - binary image buffer or base64-encoded image
  * string
- * @returns {Jimp} - the jimp image object
+ * @returns {Promise<AppiumJimp>} - the jimp image object
  */
 async function getJimpImage (data) {
   return await new B((resolve, reject) => {
@@ -26,15 +26,19 @@ async function getJimpImage (data) {
     if (_.isString(data)) {
       data = Buffer.from(data, 'base64');
     }
-    new Jimp(data, (err, imgObj) => {
+    new Jimp(data,
+      /**
+       * @param {Error?} err
+       * @param {AppiumJimp} imgObj
+       */
+    (err, imgObj) => {
       if (err) {
         return reject(err);
       }
       if (!imgObj) {
         return reject(new Error('Could not create jimp image from that data'));
       }
-      imgObj._getBuffer = imgObj.getBuffer.bind(imgObj);
-      imgObj.getBuffer = B.promisify(imgObj._getBuffer, {context: imgObj});
+      imgObj.getBuffer = B.promisify(imgObj.getBuffer.bind(imgObj), {context: imgObj});
       resolve(imgObj);
     });
   });
@@ -45,7 +49,7 @@ async function getJimpImage (data) {
  *
  * @param {string} base64Image The string with base64 encoded image
  * @param {Region} rect The selected region of image
- * @return {string} base64 encoded string of cropped image
+ * @return {Promise<string>} base64 encoded string of cropped image
  */
 async function cropBase64Image (base64Image, rect) {
   const image = await base64ToImage(base64Image);
@@ -57,7 +61,7 @@ async function cropBase64Image (base64Image, rect) {
  * Create a pngjs image from given base64 image
  *
  * @param {string} base64Image The string with base64 encoded image
- * @return {PNG} The image object
+ * @return {Promise<PNG>} The image object
  */
 async function base64ToImage (base64Image) {
   const imageBuffer = Buffer.from(base64Image, 'base64');
@@ -76,7 +80,7 @@ async function base64ToImage (base64Image) {
  * Create a base64 string for given image object
  *
  * @param {PNG} image The image object
- * @return {string} The string with base64 encoded image
+ * @return {Promise<string>} The string with base64 encoded image
  */
 async function imageToBase64 (image) {
   return await new B((resolve, reject) => {
@@ -138,3 +142,15 @@ export {
   cropBase64Image, base64ToImage, imageToBase64, cropImage,
   getJimpImage, MIME_JPEG, MIME_PNG, MIME_BMP
 };
+
+/**
+ * @typedef {Omit<Jimp,'getBuffer'> & {getBuffer: Jimp['getBufferAsync']}} AppiumJimp
+ */
+
+/**
+ * @typedef Region
+ * @property {number} left
+ * @property {number} top
+ * @property {number} width
+ * @property {number} height
+ */

package/lib/index.js

@@ -1,10 +1,10 @@
 import * as tempDir from './tempdir';
 import * as system from './system';
 import * as util from './util';
-import * as fsIndex from './fs';
+import { fs } from './fs';
 import * as net from './net';
 import * as plist from './plist';
-import * as mkdirpIndex from './mkdirp';
+import { mkdirp } from './mkdirp';
 import * as logger from './logging';
 import * as process from './process';
 import * as zip from './zip';
@@ -12,17 +12,17 @@ import * as imageUtil from './image-util';
 import * as mjpeg from './mjpeg';
 import * as node from './node';
 import * as timing from './timing';
+import * as env from './env';
 
+export { npm } from './npm';
 
-const { fs } = fsIndex;
 const { cancellableDelay } = util;
-const { mkdirp } = mkdirpIndex;
 
 export {
   tempDir, system, util, fs, cancellableDelay, plist, mkdirp, logger, process,
-  zip, imageUtil, net, mjpeg, node, timing,
+  zip, imageUtil, net, mjpeg, node, timing, env
 };
 export default {
   tempDir, system, util, fs, cancellableDelay, plist, mkdirp, logger, process,
-  zip, imageUtil, net, mjpeg, node, timing,
+  zip, imageUtil, net, mjpeg, node, timing, env
 };

package/lib/log-internal.js

@@ -3,12 +3,6 @@ import _ from 'lodash';
 
 const DEFAULT_REPLACER = '**SECURE**';
 
-/**
- * @typedef {Object} SecureValuePreprocessingRule
- * @property {RegExp} pattern The parsed pattern which is going to be used for replacement
- * @property {string} replacer [DEFAULT_SECURE_REPLACER] The replacer value to use. By default
- * equals to `DEFAULT_SECURE_REPLACER`
- */
 
 class SecureValuesPreprocessor {
   constructor () {
@@ -23,19 +17,6 @@ class SecureValuesPreprocessor {
     return this._rules;
   }
 
-  /**
-   * @typedef {Object} Rule
-   * @property {string} pattern A valid RegExp pattern to be replaced
-   * @property {string} text A text match to replace. Either this property or the
-   * above one must be provided. `pattern` has priority over `text` if both are provided.
-   * @property {string} flags ['g'] Regular expression flags for the given pattern.
-   * Supported flag are the same as for the standard JavaScript RegExp constructor:
-   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#Advanced_searching_with_flags_2
-   * The 'g' (global matching) is always enabled though.
-   * @property {string} replacer [DEFAULT_SECURE_REPLACER] The replacer value to use. By default
-   * equals to `DEFAULT_SECURE_REPLACER`
-   */
-
   /**
    * Parses single rule from the given JSON file
    *
@@ -45,32 +26,28 @@ class SecureValuesPreprocessor {
    * @returns {SecureValuePreprocessingRule} The parsed rule
    */
   parseRule (rule) {
-    const raiseError = (msg) => {
-      throw new Error(`${JSON.stringify(rule)} -> ${msg}`);
-    };
-
     let pattern;
     let replacer = DEFAULT_REPLACER;
     let flags = ['g'];
     if (_.isString(rule)) {
       if (rule.length === 0) {
-        raiseError('The value must not be empty');
+        throw new Error(`${JSON.stringify(rule)} -> The value must not be empty`);
       }
       pattern = `\\b${_.escapeRegExp(rule)}\\b`;
     } else if (_.isPlainObject(rule)) {
       if (_.has(rule, 'pattern')) {
         if (!_.isString(rule.pattern) || rule.pattern.length === 0) {
-          raiseError(`The value of 'pattern' must be a valid non-empty string`);
+          throw new Error(`${JSON.stringify(rule)} -> The value of 'pattern' must be a valid non-empty string`);
         }
         pattern = rule.pattern;
       } else if (_.has(rule, 'text')) {
         if (!_.isString(rule.text) || rule.text.length === 0) {
-          raiseError(`The value of 'text' must be a valid non-empty string`);
+          throw new Error(`${JSON.stringify(rule)} -> The value of 'text' must be a valid non-empty string`);
         }
         pattern = `\\b${_.escapeRegExp(rule.text)}\\b`;
       }
       if (!pattern) {
-        raiseError(`Must either have a field named 'pattern' or 'text'`);
+        throw new Error(`${JSON.stringify(rule)} -> Must either have a field named 'pattern' or 'text'`);
       }
 
       if (_.has(rule, 'flags')) {
@@ -87,27 +64,23 @@ class SecureValuesPreprocessor {
         replacer = rule.replacer;
       }
     } else {
-      raiseError('Must either be a string or an object');
+      throw new Error(`${JSON.stringify(rule)} -> Must either be a string or an object`);
     }
 
-    try {
-      return {
-        pattern: new RegExp(pattern, flags.join('')),
-        replacer,
-      };
-    } catch (e) {
-      raiseError(e.message);
-    }
+    return {
+      pattern: new RegExp(pattern, flags.join('')),
+      replacer,
+    };
   }
 
   /**
    * Loads rules from the given JSON file
    *
-   * @param {string|string[]|Rule[]>} source The full path to the JSON file containing secure
+   * @param {string|string[]|Rule[]} source The full path to the JSON file containing secure
    * values replacement rules or the rules themselves represented as an array
    * @throws {Error} If the format of the source file is invalid or
    * it does not exist
-   * @returns {Array<string>} The list of issues found while parsing each rule.
+   * @returns {Promise<string[]>} The list of issues found while parsing each rule.
    * An empty list is returned if no rule parsing issues were found
    */
   async loadRules (source) {
@@ -165,3 +138,23 @@ const SECURE_VALUES_PREPROCESSOR = new SecureValuesPreprocessor();
 
 export { SECURE_VALUES_PREPROCESSOR, SecureValuesPreprocessor };
 export default SECURE_VALUES_PREPROCESSOR;
+
+/**
+ * @typedef Rule
+ * @property {string} pattern A valid RegExp pattern to be replaced
+ * @property {string} text A text match to replace. Either this property or the
+ * above one must be provided. `pattern` has priority over `text` if both are provided.
+ * @property {string} [flags] Regular expression flags for the given pattern.
+ * Supported flag are the same as for the standard JavaScript RegExp constructor:
+ * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#Advanced_searching_with_flags_2
+ * The 'g' (global matching) is always enabled though.
+ * @property {string} [replacer] The replacer value to use. By default
+ * equals to `DEFAULT_SECURE_REPLACER`
+ */
+
+/**
+ * @typedef SecureValuePreprocessingRule
+ * @property {RegExp} pattern The parsed pattern which is going to be used for replacement
+ * @property {string} [replacer] The replacer value to use. By default
+ * equals to `DEFAULT_SECURE_REPLACER`
+ */