@appium/support 2.55.4 → 2.56.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 rimraf 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?: rimraf.Options) => Promise<void>} */(B.promisify(rimraf)),
+
+  /**
+   * Alias of {@linkcode rimraf.sync}
+   * @todo Replace with `rmSync()` from `fs` when Node.js v12 support is dropped.
+   */
+  rimrafSync: rimraf.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,70 @@ 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`.
+   */
+  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
+*/
+

package/lib/index.js

@@ -12,17 +12,23 @@ 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;
+/**
+ * Alias for `fs.mkdir(dir, {recursive: true}`). Use `fs.mkdirp` instead.
+ * @deprecated
+ */
 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

@@ -4,7 +4,7 @@ import _ from 'lodash';
 const DEFAULT_REPLACER = '**SECURE**';
 
 /**
- * @typedef {Object} SecureValuePreprocessingRule
+ * @typedef 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`
@@ -24,7 +24,7 @@ class SecureValuesPreprocessor {
   }
 
   /**
-   * @typedef {Object} Rule
+   * @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.

package/lib/logging.js

@@ -104,7 +104,7 @@ function getLogger (prefix = null) {
 }
 
 /**
- * @typedef {Object} LoadResult
+ * @typedef LoadResult
  * @property {List<string>} issues The list of rule parsing issues (one item per rule).
  * Rules with issues are skipped. An empty list is returned if no parsing issues exist.
  * @property {List<SecureValuePreprocessingRule>} rules The list of successfully loaded

package/lib/mkdirp.js

@@ -1,9 +1,6 @@
-import mkdirp from 'mkdirp';
-
+import { fs } from './fs';
 /**
- * TODO: once we drop support for Node 10, this should be removed in favor
- * of fs.mkdir(dir, {recursive: true});
+ * @deprecated Use `fs.mkdirp` instead.
  */
-
-
+const { mkdirp } = fs;
 export { mkdirp };

package/lib/net.js

@@ -111,20 +111,20 @@ async function uploadFileToFtp (localFileStream, parsedUri, uploadOptions = {})
 }
 
 /**
- * @typedef {Object} AuthCredentials
+ * @typedef AuthCredentials
  * @property {string} user - Non-empty user name
  * @property {string} pass - Non-empty password
  */
 
 /**
- * @typedef {Object} FtpUploadOptions
+ * @typedef FtpUploadOptions
  * @property {boolean} isMetered [true] - Whether to log the actual upload performance
  * (e.g. timings and speed)
  * @property {AuthCredentials} auth
  */
 
 /**
- * @typedef {Object} HttpUploadOptions
+ * @typedef HttpUploadOptions
  * @property {boolean} isMetered [true] - Whether to log the actual upload performance
  * (e.g. timings and speed)
  * @property {string} method [POST] - The HTTP method used for file upload
@@ -183,7 +183,7 @@ async function uploadFile (localPath, remoteUri, uploadOptions = {}) {
 }
 
 /**
- * @typedef {Object} DownloadOptions
+ * @typedef DownloadOptions
  * @property {boolean} isMetered [true] - Whether to log the actual download performance
  * (e.g. timings and speed)
  * @property {AuthCredentials} auth

package/lib/node.js

@@ -1,7 +1,15 @@
 import { isWindows } from './system';
 import log from './logger';
+import _ from 'lodash';
 import { exec } from 'teen_process';
 import path from 'path';
+import { v4 as uuidV4 } from 'uuid';
+
+const ECMA_SIZES = Object.freeze({
+  STRING: 2,
+  BOOLEAN: 4,
+  NUMBER: 8,
+});
 
 /**
  * Internal utility to link global package to local context
@@ -63,4 +71,99 @@ async function requirePackage (packageName) {
   }
 }
 
-export { requirePackage };
+function extractAllProperties (obj) {
+  const stringProperties = [];
+  for (const prop in obj) {
+    stringProperties.push(prop);
+  }
+  if (_.isFunction(Object.getOwnPropertySymbols)) {
+    stringProperties.push(...(Object.getOwnPropertySymbols(obj)));
+  }
+  return stringProperties;
+}
+
+function _getSizeOfObject (seen, object) {
+  if (_.isNil(object)) {
+    return 0;
+  }
+
+  let bytes = 0;
+  const properties = extractAllProperties(object);
+  for (const key of properties) {
+    // Do not recalculate circular references
+    if (typeof object[key] === 'object' && !_.isNil(object[key])) {
+      if (seen.has(object[key])) {
+        continue;
+      }
+      seen.add(object[key]);
+    }
+
+    bytes += getCalculator(seen)(key);
+    try {
+      bytes += getCalculator(seen)(object[key]);
+    } catch (ex) {
+      if (ex instanceof RangeError) {
+        // circular reference detected, final result might be incorrect
+        // let's be nice and not throw an exception
+        bytes = 0;
+      }
+    }
+  }
+
+  return bytes;
+}
+
+function getCalculator (seen) {
+  return function calculator (obj) {
+    if (_.isBuffer(obj)) {
+      return obj.length;
+    }
+
+    switch (typeof (obj)) {
+      case 'string':
+        return obj.length * ECMA_SIZES.STRING;
+      case 'boolean':
+        return ECMA_SIZES.BOOLEAN;
+      case 'number':
+        return ECMA_SIZES.NUMBER;
+      case 'symbol':
+        return _.isFunction(Symbol.keyFor) && Symbol.keyFor(obj)
+          ? Symbol.keyFor(obj).length * ECMA_SIZES.STRING
+          : (obj.toString().length - 8) * ECMA_SIZES.STRING;
+      case 'object':
+        return _.isArray(obj)
+          ? obj.map(getCalculator(seen)).reduce((acc, curr) => acc + curr, 0)
+          : _getSizeOfObject(seen, obj);
+      default:
+        return 0;
+    }
+  };
+}
+
+/**
+ * Calculate the in-depth size in memory of the provided object.
+ * The original implementation is borrowed from https://github.com/miktam/sizeof.
+ *
+ * @param {*} obj An object whose size should be calculated
+ * @returns {number} Object size in bytes.
+ */
+function getObjectSize (obj) {
+  return getCalculator(new WeakSet())(obj);
+}
+
+const OBJECTS_MAPPING = new WeakMap();
+
+/**
+ * Calculates a unique object identifier
+ *
+ * @param {object} object Any valid ECMA object
+ * @returns {string} A uuidV4 string that uniquely identifies given object
+ */
+function getObjectId (object) {
+  if (!OBJECTS_MAPPING.has(object)) {
+    OBJECTS_MAPPING.set(object, uuidV4());
+  }
+  return OBJECTS_MAPPING.get(object);
+}
+
+export { requirePackage, getObjectSize, getObjectId };