node-simctl 8.0.8 → 8.1.0

package/lib/subcommands/{install.js → install.ts}

@@ -1,20 +1,18 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Install the particular application package on Simulator.
  * It is required that Simulator is in _booted_ state.
  *
- * @this {import('../simctl').Simctl}
- * @param {string} appPath - Full path to .app package, which is
+ * @param appPath - Full path to .app package, which is
  *                           going to be installed.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.installApp = async function installApp (appPath) {
+export async function installApp (this: Simctl, appPath: string): Promise<void> {
   await this.exec('install', {
     args: [this.requireUdid('install'), appPath],
   });
-};
+}
 
-export default commands;

package/lib/subcommands/{io.js → io.ts}

@@ -3,21 +3,19 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs/promises';
 import { uuidV4 } from '../helpers';
-
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Gets base64 screenshot for device
  * It is required that Simulator is in _booted_ state.
  *
- * @this {import('../simctl').Simctl}
  * @since Xcode SDK 8.1
- * @return {Promise<string>} Base64-encoded Simulator screenshot.
+ * @return Base64-encoded Simulator screenshot.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.getScreenshot = async function getScreenshot () {
+export async function getScreenshot (this: Simctl): Promise<string> {
   const udid = this.requireUdid('io screenshot');
   const pathToScreenshotPng = path.resolve(os.tmpdir(), `${await uuidV4()}.png`);
   try {
@@ -28,6 +26,5 @@ commands.getScreenshot = async function getScreenshot () {
   } finally {
     await rimraf(pathToScreenshotPng);
   }
-};
+}
 
-export default commands;

package/lib/subcommands/{keychain.js → keychain.ts}

@@ -4,15 +4,17 @@ import { uuidV4 } from '../helpers';
 import path from 'path';
 import _ from 'lodash';
 import { rimraf } from 'rimraf';
-
-const commands = {};
+import type { Simctl } from '../simctl';
+import type { CertOptions } from '../types';
 
 /**
- *
- * @param {string|Buffer} payload
- * @param {(filePath: string) => Promise<any>} onPayloadStored
+ * @param payload - Certificate payload (string or Buffer)
+ * @param onPayloadStored - Callback function to execute with the file path
  */
-async function handleRawPayload (payload, onPayloadStored) {
+async function handleRawPayload (
+  payload: string | Buffer,
+  onPayloadStored: (filePath: string) => Promise<any>
+): Promise<void> {
   const filePath = path.resolve(os.tmpdir(), `${await uuidV4()}.pem`);
   try {
     if (_.isBuffer(payload)) {
@@ -26,81 +28,77 @@ async function handleRawPayload (payload, onPayloadStored) {
   }
 }
 
-
-/**
- * @typedef {Object} CertOptions
- * @property {boolean} [raw=false] - whether the `cert` argument
- * is the path to the certificate on the local file system or
- * a raw certificate content
- */
-
 /**
  * Adds the given certificate to the Trusted Root Store on the simulator
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
- * @param {string} cert the full path to a valid .cert file containing
+ * @param cert the full path to a valid .cert file containing
  * the certificate content or the certificate content itself, depending on
  * options
- * @param {CertOptions} [opts={}]
+ * @param opts - Certificate options
  * @throws {Error} if the current SDK version does not support the command
  * or there was an error while adding the certificate
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.addRootCertificate = async function addRootCertificate (cert, opts = {}) {
+export async function addRootCertificate (
+  this: Simctl,
+  cert: string | Buffer,
+  opts: CertOptions = {}
+): Promise<void> {
   const {
     raw = false,
   } = opts;
-  const execMethod = async (/** @type {string} */certPath) => await this.exec('keychain', {
+  const execMethod = async (certPath: string) => await this.exec('keychain', {
     args: [this.requireUdid('keychain add-root-cert'), 'add-root-cert', certPath],
   });
   if (raw) {
     await handleRawPayload(cert, execMethod);
   } else {
-    await execMethod(cert);
+    await execMethod(cert as string);
   }
-};
+}
 
 /**
  * Adds the given certificate to the Keychain Store on the simulator
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
- * @param {string} cert the full path to a valid .cert file containing
+ * @param cert the full path to a valid .cert file containing
  * the certificate content or the certificate content itself, depending on
  * options
- * @param {CertOptions} [opts={}]
+ * @param opts - Certificate options
  * @throws {Error} if the current SDK version does not support the command
  * or there was an error while adding the certificate
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.addCertificate = async function addCertificate (cert, opts = {}) {
+export async function addCertificate (
+  this: Simctl,
+  cert: string | Buffer,
+  opts: CertOptions = {}
+): Promise<void> {
   const {
     raw = false,
   } = opts;
-  const execMethod = async (certPath) => await this.exec('keychain', {
+  const execMethod = async (certPath: string) => await this.exec('keychain', {
     args: [this.requireUdid('keychain add-cert'), 'add-cert', certPath],
   });
   if (raw) {
     await handleRawPayload(cert, execMethod);
   } else {
-    await execMethod(cert);
+    await execMethod(cert as string);
   }
-};
+}
 
 /**
  * Resets the simulator keychain
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
  * @throws {Error} if the current SDK version does not support the command
  * or there was an error while resetting the keychain
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.resetKeychain = async function resetKeychain () {
+export async function resetKeychain (this: Simctl): Promise<void> {
   await this.exec('keychain', {
     args: [this.requireUdid('keychain reset'), 'reset'],
   });
-};
+}
 
-export default commands;

package/lib/subcommands/{launch.js → launch.ts}

@@ -1,31 +1,28 @@
 import _ from 'lodash';
 import { retryInterval } from 'asyncbox';
-
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Execute the particular application package on Simulator.
  * It is required that Simulator is in _booted_ state and
  * the application with given bundle identifier is already installed.
  *
- * @this {import('../simctl').Simctl}
- * @param {string} bundleId - Bundle identifier of the application,
+ * @param bundleId - Bundle identifier of the application,
  *                            which is going to be removed.
- * @param {number} [tries=5] - The maximum number of retries before
+ * @param tries - The maximum number of retries before
  *                             throwing an exception.
- * @return {Promise<string>} the actual command output
+ * @return the actual command output
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.launchApp = async function launchApp (bundleId, tries = 5) {
-  // @ts-ignore A string will always be returned
-  return await retryInterval(tries, 1000, async () => {
+export async function launchApp (this: Simctl, bundleId: string, tries: number = 5): Promise<string> {
+  const result = await retryInterval(tries, 1000, async () => {
     const {stdout} = await this.exec('launch', {
       args: [this.requireUdid('launch'), bundleId],
     });
-    return _.trim(stdout);
+    return _.trim(stdout) || '';
   });
-};
+  return result || '';
+}
 
-export default commands;

package/lib/subcommands/{list.js → list.ts}

@@ -1,31 +1,24 @@
 import _ from 'lodash';
 import { SIM_RUNTIME_NAME, normalizeVersion } from '../helpers';
-import log, { LOG_PREFIX } from '../logger';
-
-
-const commands = {};
-
-/**
- * @typedef {Object} DeviceInfo
- * @property {string} name - The device name.
- * @property {string} udid - The device UDID.
- * @property {string} state - The current Simulator state, for example 'booted' or 'shutdown'.
- * @property {string} sdk - The SDK version, for example '10.3'.
- */
+import { log, LOG_PREFIX } from '../logger';
+import type { Simctl } from '../simctl';
+import type { DeviceInfo } from '../types';
 
 /**
  * Parse the list of existing Simulator devices to represent
  * it as convenient mapping.
  *
- * @this {import('../simctl').Simctl}
- * @param {string?} [platform] - The platform name, for example 'watchOS'.
- * @return {Promise<Record<string, any>>} The resulting mapping. Each key is platform version,
+ * @param platform - The platform name, for example 'watchOS'.
+ * @return The resulting mapping. Each key is platform version,
  *                  for example '10.3' and the corresponding value is an
- *                  array of the matching {@link DeviceInfo} instances.
+ *                  array of the matching DeviceInfo instances.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  */
-commands.getDevicesByParsing = async function getDevicesByParsing (platform) {
+export async function getDevicesByParsing (
+  this: Simctl,
+  platform?: string | null
+): Promise<Record<string, DeviceInfo[]>> {
   const {stdout} = await this.exec('list', {
     args: ['devices'],
   });
@@ -42,8 +35,8 @@ commands.getDevicesByParsing = async function getDevicesByParsing (platform) {
   const deviceSectionRe = _.isEmpty(platform) || !platform
     ? new RegExp(`\\-\\-\\s+(\\S+)\\s+(\\S+)\\s+\\-\\-(\\n\\s{4}.+)*`, 'mgi')
     : new RegExp(`\\-\\-\\s+${_.escapeRegExp(platform)}\\s+(\\S+)\\s+\\-\\-(\\n\\s{4}.+)*`, 'mgi');
-  const matches = [];
-  let match;
+  const matches: RegExpExecArray[] = [];
+  let match: RegExpExecArray | null;
   // make an entry for each sdk version
   while ((match = deviceSectionRe.exec(stdout))) {
     matches.push(match);
@@ -54,7 +47,7 @@ commands.getDevicesByParsing = async function getDevicesByParsing (platform) {
 
   const lineRe = /([^\s].+) \((\w+-.+\w+)\) \((\w+\s?\w+)\)/; // https://regex101.com/r/lG7mK6/3
   // get all the devices for each sdk
-  const devices = {};
+  const devices: Record<string, DeviceInfo[]> = {};
   for (match of matches) {
     const sdk = platform ? match[1] : match[2];
     devices[sdk] = devices[sdk] || [];
@@ -84,27 +77,40 @@ commands.getDevicesByParsing = async function getDevicesByParsing (platform) {
     }
   }
   return devices;
-};
+}
 
 /**
  * Parse the list of existing Simulator devices to represent
  * it as convenient mapping for the particular platform version.
  *
- * @this {import('../simctl').Simctl}
- * @param {string?} [forSdk] - The sdk version,
+ * @param forSdk - The sdk version,
  *                           for which the devices list should be parsed,
  *                           for example '10.3'.
- * @param {string?} [platform] - The platform name, for example 'watchOS'.
- * @return {Promise<Object|DeviceInfo[]>} If _forSdk_ is set then the list
+ * @param platform - The platform name, for example 'watchOS'.
+ * @return If _forSdk_ is set then the list
  *                                    of devices for the particular platform version.
- *                                    Otherwise the same result as for {@link getDevicesByParsing}
+ *                                    Otherwise the same result as for getDevicesByParsing
  *                                    function.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code or if no matching
  *                 platform version is found in the system.
  */
-commands.getDevices = async function getDevices (forSdk, platform) {
-  let devices = {};
+export async function getDevices (
+  this: Simctl,
+  forSdk: string,
+  platform?: string | null
+): Promise<DeviceInfo[]>;
+export async function getDevices (
+  this: Simctl,
+  forSdk?: undefined | null,
+  platform?: string | null
+): Promise<Record<string, DeviceInfo[]>>;
+export async function getDevices (
+  this: Simctl,
+  forSdk?: string | null,
+  platform?: string | null
+): Promise<Record<string, DeviceInfo[]> | DeviceInfo[]> {
+  let devices: Record<string, DeviceInfo[]> = {};
   try {
     const {stdout} = await this.exec('list', {
       args: ['devices', '-j'],
@@ -128,9 +134,9 @@ commands.getDevices = async function getDevices (forSdk, platform) {
     const versionMatchRe = _.isEmpty(platform) || !platform
       ? new RegExp(`^([^\\s-]+)[\\s-](\\S+)`, 'i')
       : new RegExp(`^${_.escapeRegExp(platform)}[\\s-](\\S+)`, 'i');
-    for (let [sdkName, entries] of _.toPairs(JSON.parse(stdout).devices)) {
+    for (const [sdkNameRaw, entries] of _.toPairs(JSON.parse(stdout).devices)) {
       // there could be a longer name, so remove it
-      sdkName = sdkName.replace(SIM_RUNTIME_NAME, '');
+      const sdkName = sdkNameRaw.replace(SIM_RUNTIME_NAME, '');
       const versionMatch = versionMatchRe.exec(sdkName);
       if (!versionMatch) {
         continue;
@@ -139,8 +145,8 @@ commands.getDevices = async function getDevices (forSdk, platform) {
       // the sdk can have dashes (`12-2`) or dots (`12.1`)
       const sdk = (platform ? versionMatch[1] : versionMatch[2]).replace('-', '.');
       devices[sdk] = devices[sdk] || [];
-      devices[sdk].push(...entries.filter((el) => _.isUndefined(el.isAvailable) || el.isAvailable)
-        .map((el) => {
+      devices[sdk].push(...(entries as any[]).filter((el) => _.isUndefined(el.isAvailable) || el.isAvailable)
+        .map((el: any) => {
           delete el.availability;
           return {
             sdk,
@@ -150,7 +156,7 @@ commands.getDevices = async function getDevices (forSdk, platform) {
         })
       );
     }
-  } catch (err) {
+  } catch (err: any) {
     log.debug(LOG_PREFIX, `Unable to get JSON device list: ${err.stack}`);
     log.debug(LOG_PREFIX, 'Falling back to manual parsing');
     devices = await this.getDevicesByParsing(platform);
@@ -170,20 +176,22 @@ commands.getDevices = async function getDevices (forSdk, platform) {
     ? ` Only the following Simulator SDK versions are available on your system: ${availableSDKs.join(', ')}`
     : ` No Simulator SDK versions are available on your system. Please install some via Xcode preferences.`;
   throw new Error(errMsg);
-};
+}
 
 /**
  * Get the runtime for the particular platform version using --json flag
  *
- * @this {import('../simctl').Simctl}
- * @param {string} platformVersion - The platform version name,
+ * @param platformVersion - The platform version name,
  *                                   for example '10.3'.
- * @param {string} [platform='iOS'] - The platform name, for example 'watchOS'.
- * @return {Promise<string>} The corresponding runtime name for the given
+ * @param platform - The platform name, for example 'watchOS'.
+ * @return The corresponding runtime name for the given
  *                  platform version.
  */
-commands.getRuntimeForPlatformVersionViaJson = async function getRuntimeForPlatformVersionViaJson (
-  platformVersion, platform = 'iOS') {
+export async function getRuntimeForPlatformVersionViaJson (
+  this: Simctl,
+  platformVersion: string,
+  platform: string = 'iOS'
+): Promise<string> {
   const {stdout} = await this.exec('list', {
     args: ['runtimes', '--json'],
   });
@@ -194,20 +202,22 @@ commands.getRuntimeForPlatformVersionViaJson = async function getRuntimeForPlatf
     }
   }
   throw new Error(`Could not use --json flag to parse platform version`);
-};
+}
 
 /**
  * Get the runtime for the particular platform version.
  *
- * @this {import('../simctl').Simctl}
- * @param {string} platformVersion - The platform version name,
+ * @param platformVersion - The platform version name,
  *                                   for example '10.3'.
- * @param {string} [platform='iOS'] - The platform name, for example 'watchOS'.
- * @return {Promise<string>} The corresponding runtime name for the given
+ * @param platform - The platform name, for example 'watchOS'.
+ * @return The corresponding runtime name for the given
  *                  platform version.
  */
-commands.getRuntimeForPlatformVersion = async function getRuntimeForPlatformVersion (
-  platformVersion, platform = 'iOS') {
+export async function getRuntimeForPlatformVersion (
+  this: Simctl,
+  platformVersion: string,
+  platform: string = 'iOS'
+): Promise<string> {
   // Try with parsing
   try {
     const {stdout} = await this.exec('list', {
@@ -226,16 +236,15 @@ commands.getRuntimeForPlatformVersion = async function getRuntimeForPlatformVers
 
   // if nothing was found, pass platform version back
   return platformVersion;
-};
+}
 
 /**
  * Get the list of device types available in the current Xcode installation
  *
- * @this {import('../simctl').Simctl}
- * @return {Promise<string[]>} List of the types of devices available
+ * @return List of the types of devices available
  * @throws {Error} If the corresponding simctl command fails
  */
-commands.getDeviceTypes = async function getDeviceTypes () {
+export async function getDeviceTypes (this: Simctl): Promise<string[]> {
   const {stdout} = await this.exec('list', {
     args: ['devicetypes', '-j'],
   });
@@ -252,17 +261,16 @@ commands.getDeviceTypes = async function getDeviceTypes () {
    */
   try {
     const deviceTypes = JSON.parse(stdout.trim());
-    return deviceTypes.devicetypes.map((type) => type.name);
-  } catch (err) {
+    return deviceTypes.devicetypes.map((type: any) => type.name);
+  } catch (err: any) {
     throw new Error(`Unable to get list of device types: ${err.message}`);
   }
-};
+}
 
 /**
  * Get the full list of runtimes, devicetypes, devices and pairs as Object
  *
- * @this {import('../simctl').Simctl}
- * @return {Promise<Object>} Object containing device types, runtimes devices and pairs.
+ * @return Object containing device types, runtimes devices and pairs.
  * The resulting JSON will be like:
  *   {
  *     "devicetypes" : [
@@ -293,15 +301,14 @@ commands.getDeviceTypes = async function getDeviceTypes () {
  *   }
  * @throws {Error} If the corresponding simctl command fails
  */
-commands.list = async function list () {
+export async function list (this: Simctl): Promise<any> {
   const {stdout} = await this.exec('list', {
     args: ['-j'],
   });
   try {
     return JSON.parse(stdout.trim());
-  } catch (e) {
+  } catch (e: any) {
     throw new Error(`Unable to parse simctl list: ${e.message}`);
   }
-};
+}
 
-export default commands;

package/lib/subcommands/{location.js → location.ts}

@@ -1,13 +1,13 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Formats the given location argument for simctl usage
  *
- * @param {string} name Argument name
- * @param {string|number} value Location argument value
- * @returns {string} Formatted value, for example -73.768254
+ * @param name Argument name
+ * @param value Location argument value
+ * @returns Formatted value, for example -73.768254
  */
-function formatArg (name, value) {
+function formatArg (name: string, value: string | number): string {
   const flt = parseFloat(`${value}`);
   if (isNaN(flt)) {
     throw new TypeError(`${name} must be a valid number, got '${value}' instead`);
@@ -19,31 +19,32 @@ function formatArg (name, value) {
  * Set the Simulator location to a specific latitude and longitude.
  * This functionality is only available since Xcode 14.
  *
- * @this {import('../simctl').Simctl}
- * @param {string|number} latitude Location latitude value
- * @param {string|number} longitude Location longitude value
+ * @param latitude Location latitude value
+ * @param longitude Location longitude value
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {TypeError} If any of the arguments is not a valid value.
  */
-commands.setLocation = async function setLocation (latitude, longitude) {
+export async function setLocation (
+  this: Simctl,
+  latitude: string | number,
+  longitude: string | number
+): Promise<void> {
   const lat = formatArg('latitude', latitude);
   const lon = formatArg('longitude', longitude);
   await this.exec('location', {
     args: [this.requireUdid('location'), 'set', `${lat},${lon}`],
   });
-};
+}
 
 /**
  * Stop any running scenario and clear any simulated location.
  *
  * @since Xcode 14.
- * @this {import('../simctl').Simctl}
  */
-commands.clearLocation = async function clearLocation () {
+export async function clearLocation (this: Simctl): Promise<void> {
   await this.exec('location', {
     args: [this.requireUdid('location'), 'clear'],
   });
-};
+}
 
-export default commands;

package/lib/subcommands/{openurl.js → openurl.ts}

@@ -1,22 +1,21 @@
-const commands = {};
+import type { Simctl } from '../simctl';
+import type { TeenProcessExecResult } from 'teen_process';
 
 /**
  * Open URL scheme on Simulator. iOS will automatically try
  * to find a matching application, which supports the given scheme.
  * It is required that Simulator is in _booted_ state.
  *
- * @this {import('../simctl').Simctl}
- * @param {string} url - The URL scheme to open, for example http://appiom.io
+ * @param url - The URL scheme to open, for example http://appiom.io
  *                       will be opened by the built-in mobile browser.
- * @return {Promise<import('teen_process').TeenProcessExecResult>} Command execution result.
+ * @return Command execution result.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.openUrl = async function openUrl (url) {
+export async function openUrl (this: Simctl, url: string): Promise<TeenProcessExecResult<string>> {
   return await this.exec('openurl', {
     args: [this.requireUdid('openurl'), url],
   });
-};
+}
 
-export default commands;

package/lib/subcommands/{pbcopy.js → pbcopy.ts}

@@ -1,23 +1,27 @@
-const commands = {};
+import type { Simctl } from '../simctl';
+import type { SubProcess } from 'teen_process';
 
 /**
  * Set the content of Simulator pasteboard.
  * It is required that Simulator is in _booted_ state.
  *
  * @since Xcode SDK 8.1
- * @this {import('../simctl').Simctl}
- * @param {string} content - The actual string content to be set.
- * @param {BufferEncoding} [encoding='utf8'] - The encoding of the given pasteboard content.
+ * @param content - The actual string content to be set.
+ * @param encoding - The encoding of the given pasteboard content.
  * utf8 by default.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.setPasteboard = async function setPasteboard (content, encoding = 'utf8') {
+export async function setPasteboard (
+  this: Simctl,
+  content: string,
+  encoding: BufferEncoding = 'utf8'
+): Promise<void> {
   const pbCopySubprocess = await this.exec('pbcopy', {
     args: [this.requireUdid('pbcopy')],
     asynchronous: true,
-  });
+  }) as SubProcess;
   await pbCopySubprocess.start(0);
   const exitCodeVerifier = pbCopySubprocess.join();
   const stdin = pbCopySubprocess.proc?.stdin;
@@ -27,6 +31,5 @@ commands.setPasteboard = async function setPasteboard (content, encoding = 'utf8
     stdin.end();
   }
   await exitCodeVerifier;
-};
+}
 
-export default commands;

package/lib/subcommands/{pbpaste.js → pbpaste.ts}

@@ -1,24 +1,22 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Get the content of Simulator pasteboard.
  * It is required that Simulator is in _booted_ state.
  *
  * @since Xcode 8.1 SDK
- * @this {import('../simctl').Simctl}
- * @param {string} [encoding='utf8'] - The encoding of the returned pasteboard content.
+ * @param encoding - The encoding of the returned pasteboard content.
  *                                      UTF-8 by default.
- * @return {Promise<string>} Current content of Simulator pasteboard or an empty string.
+ * @return Current content of Simulator pasteboard or an empty string.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.getPasteboard = async function getPasteboard (encoding = 'utf8') {
+export async function getPasteboard (this: Simctl, encoding: BufferEncoding = 'utf8'): Promise<string> {
   const {stdout} = await this.exec('pbpaste', {
     args: [this.requireUdid('pbpaste')],
     encoding,
   });
   return stdout;
-};
+}
 
-export default commands;