appium-remote-debugger 15.2.12 → 15.2.14

package/lib/rpc/{rpc-message-handler.js → rpc-message-handler.ts}

@@ -1,21 +1,42 @@
-import log from '../logger';
+import { EventEmitter } from 'node:events';
+import { log } from '../logger';
 import _ from 'lodash';
 import { util } from '@appium/support';
-import EventEmitters from 'events';
+import type { StringRecord } from '@appium/types';
 
+/**
+ * Represents a data message from the Web Inspector.
+ */
+interface DataMessage {
+  id?: string;
+  method: string;
+  params: StringRecord;
+  result: any;
+  error?: string | DataErrorMessage;
+}
 
-export default class RpcMessageHandler extends EventEmitters {
-  constructor () {
-    super();
-  }
+/**
+ * Represents an error message structure in a data message.
+ */
+interface DataErrorMessage {
+  message: string;
+  code: number;
+  data: any;
+}
 
+/**
+ * Handles messages from the Web Inspector and dispatches them as events.
+ * Extends EventEmitter to provide event-based message handling.
+ */
+export default class RpcMessageHandler extends EventEmitter {
   /**
-   * Handle a message from the Web Inspector.
+   * Handles a message from the Web Inspector by parsing the selector
+   * and emitting appropriate events.
    *
-   * @param {import('@appium/types').StringRecord} plist
-   * @returns {Promise<void>}
+   * @param plist - The plist message from the Web Inspector containing
+   *                __selector and __argument properties.
    */
-  async handleMessage (plist) {
+  async handleMessage(plist: StringRecord): Promise<void> {
     const selector = plist.__selector;
     if (!selector) {
       log.debug('Got an invalid plist');
@@ -70,35 +91,41 @@ export default class RpcMessageHandler extends EventEmitters {
   }
 
   /**
-   * Parse the data key from the plist.
+   * Parses the data key from a plist message.
+   * The data key is a JSON string that needs to be parsed.
    *
-   * @param {import('@appium/types').StringRecord} plist
-   * @returns {DataMessage}
-   * @throws {Error} if the data key cannot be parsed
+   * @param plist - The plist message containing the data key.
+   * @returns The parsed DataMessage object.
+   * @throws Error if the data key cannot be parsed.
    */
-  parseDataKey (plist) {
+  private parseDataKey(plist: StringRecord): DataMessage {
     try {
       return JSON.parse(plist.__argument.WIRMessageDataKey.toString('utf8'));
-    } catch (err) {
+    } catch (err: any) {
       log.error(`Unparseable message data: ${_.truncate(JSON.stringify(plist), {length: 100})}`);
       throw new Error(`Unable to parse message data: ${err.message}`);
     }
   }
 
   /**
-   * Dispatch a data message.
+   * Dispatches a data message by emitting events.
+   * If msgId is provided, emits a message-specific event.
+   * Otherwise, emits method-based events with appropriate argument mapping.
    *
-   * @param {string} msgId If not empty then the following event is going to be emitted:
-   * - <msgId, error, result>
-   * If empty then the following event is going to be emitted:
-   * - <name, error, ..args>
-   * @param {string | undefined} method
-   * @param {import('@appium/types').StringRecord | undefined} params
-   * @param {any} result
-   * @param {Error | undefined} error
-   * @returns {Promise<void>}
+   * @param msgId - If not empty, emits an event with this ID: <msgId, error, result>.
+   *                If empty, emits method-based events: <name, error, ...args>.
+   * @param method - The method name from the data message.
+   * @param params - The parameters from the data message.
+   * @param result - The result from the data message.
+   * @param error - Any error that occurred during message processing.
    */
-  async dispatchDataMessage (msgId, method, params, result, error) {
+  private async dispatchDataMessage(
+    msgId: string,
+    method: string | undefined,
+    params: StringRecord | undefined,
+    result: any,
+    error: Error | undefined
+  ): Promise<void> {
     if (msgId) {
       if (this.listenerCount(msgId)) {
         if (_.has(result?.result, 'value')) {
@@ -114,22 +141,20 @@ export default class RpcMessageHandler extends EventEmitters {
       return;
     }
 
-    /** @type {any[]} */
-    const eventNames = [method];
-    /** @type {any[]} */
-    let args = [params];
+    const eventNames: string[] = method ? [method] : [];
+    let args: any[] = [params];
 
     // some events have different names, or the arguments are mapped from the
     // parameters received
     switch (method) {
       case 'Page.frameStoppedLoading':
         eventNames.push('Page.frameNavigated');
-      case 'Page.frameNavigated': // eslint-disable-line no-fallthrough
+      // eslint-disable-next-line no-fallthrough
+      case 'Page.frameNavigated':
         args = [`'${method}' event`];
         break;
       case 'Timeline.eventRecorded':
-        // @ts-ignore This is fine for the given method
-        args = [params || params.record];
+        args = [params || (params as any)?.record];
         break;
       case 'Console.messageAdded':
         args = [params?.message];
@@ -142,13 +167,13 @@ export default class RpcMessageHandler extends EventEmitters {
         break;
     }
 
-    if (_.startsWith(method, 'Network.')) {
+    if (method && _.startsWith(method, 'Network.')) {
       // aggregate Network events, and add original method name to the arguments
       eventNames.push('NetworkEvent');
       args.push(method);
     }
-    if (_.startsWith(method, 'Console.')) {
-      // aggregate Network events, and add original method name to the arguments
+    if (method && _.startsWith(method, 'Console.')) {
+      // aggregate Console events, and add original method name to the arguments
       eventNames.push('ConsoleEvent');
       args.push(method);
     }
@@ -159,12 +184,12 @@ export default class RpcMessageHandler extends EventEmitters {
   }
 
   /**
-   * Handle a data message from the Web Inspector.
+   * Handles a data message from the Web Inspector by parsing it and
+   * dispatching appropriate events based on the message type.
    *
-   * @param {import('@appium/types').StringRecord} plist
-   * @returns {Promise<void>}
+   * @param plist - The plist message from the Web Inspector.
    */
-  async handleDataMessage (plist) {
+  private async handleDataMessage(plist: StringRecord): Promise<void> {
     const dataKey = this.parseDataKey(plist);
     let msgId = (dataKey.id || '').toString();
     let result = dataKey.result;
@@ -172,7 +197,7 @@ export default class RpcMessageHandler extends EventEmitters {
     let method = dataKey.method;
     let params = dataKey.params;
 
-    const parseError = () => {
+    const parseError = (): Error | undefined => {
       const defaultMessage = 'Error occurred in handling data message';
       if (result?.wasThrown) {
         const message = (result?.result?.value || result?.result?.description)
@@ -182,10 +207,10 @@ export default class RpcMessageHandler extends EventEmitters {
       }
       if (dataKey.error) {
         if (_.isPlainObject(dataKey.error)) {
-          const dataKeyError = /** @type {DataErrorMessage} */ (dataKey.error);
-          let error = new Error(defaultMessage);
+          const dataKeyError = dataKey.error as DataErrorMessage;
+          const error = new Error(defaultMessage);
           for (const key of Object.keys(dataKeyError)) {
-            error[key] = dataKeyError[key];
+            (error as any)[key] = dataKeyError[key as keyof DataErrorMessage];
           }
           return error;
         }
@@ -213,9 +238,9 @@ export default class RpcMessageHandler extends EventEmitters {
             method = message.method;
             result = message.result || message;
             params = result.params;
-          } catch (err) {
+          } catch (err: any) {
             // if this happens then some aspect of the protocol is missing to us
-            // so print the entire message to get visibiity into what is going on
+            // so print the entire message to get visibility into what is going on
             log.error(`Unexpected message format from Web Inspector: ${util.jsonStringify(plist, null)}`);
             throw err;
           }
@@ -227,22 +252,6 @@ export default class RpcMessageHandler extends EventEmitters {
       default: {
         await this.dispatchDataMessage(msgId, method, params, result, parseError());
       }
-    } // switch
-  } // function
+    }
+  }
 }
-
-/**
- * @typedef {Object} DataMessage
- * @property {string} [id]
- * @property {string} method
- * @property {import('@appium/types').StringRecord} params
- * @property {any} result
- * @property {string | DataErrorMessage} [error]
- */
-
-/**
- * @typedef {Object} DataErrorMessage
- * @property {string} message
- * @property {number} code
- * @property {any} data
- */

package/lib/types.ts

@@ -83,6 +83,10 @@ export type AppIdKey = string | number;
 export type PageIdKey = string | number;
 export type TargetId = string;
 
+export interface RemoteCommandId {
+  id: string;
+}
+
 export interface RemoteCommandOpts {
   appIdKey?: AppIdKey;
   pageIdKey?: PageIdKey;

package/lib/{utils.js → utils.ts}

@@ -3,6 +3,8 @@ import { errorFromMJSONWPStatusCode } from '@appium/base-driver';
 import { util, node } from '@appium/support';
 import nodeFs from 'node:fs';
 import path from 'node:path';
+import type { StringRecord } from '@appium/types';
+import type { AppInfo, AppDict, Page } from './types';
 
 const MODULE_NAME = 'appium-remote-debugger';
 export const WEB_CONTENT_BUNDLE_ID = 'com.apple.WebKit.WebContent';
@@ -16,13 +18,13 @@ const ACCEPTED_PAGE_TYPES = [
 export const RESPONSE_LOG_LENGTH = 100;
 
 /**
- * Takes a dictionary from the remote debugger and makes a more manageable
- * dictionary whose keys are understandable
+ * Takes a dictionary from the remote debugger and converts it into a more
+ * manageable AppInfo object with understandable keys.
  *
- * @param {Record<string, any>} dict
- * @returns {[string, import('./types').AppInfo]}
+ * @param dict - Dictionary from the remote debugger containing application information.
+ * @returns A tuple containing the application ID and the AppInfo object.
  */
-export function appInfoFromDict (dict) {
+export function appInfoFromDict(dict: Record<string, any>): [string, AppInfo] {
   const id = dict.WIRApplicationIdentifierKey;
   const isProxy = _.isString(dict.WIRIsApplicationProxyKey)
     ? dict.WIRIsApplicationProxyKey.toLowerCase() === 'true'
@@ -30,8 +32,7 @@ export function appInfoFromDict (dict) {
   // automation enabled can be either from the keys
   //   - WIRRemoteAutomationEnabledKey (boolean)
   //   - WIRAutomationAvailabilityKey (string or boolean)
-  /** @type {boolean|string} */
-  let isAutomationEnabled = !!dict.WIRRemoteAutomationEnabledKey;
+  let isAutomationEnabled: boolean | string = !!dict.WIRRemoteAutomationEnabledKey;
   if (_.has(dict, 'WIRAutomationAvailabilityKey')) {
     if (_.isString(dict.WIRAutomationAvailabilityKey)) {
       isAutomationEnabled = dict.WIRAutomationAvailabilityKey === 'WIRAutomationAvailabilityUnknown'
@@ -41,8 +42,7 @@ export function appInfoFromDict (dict) {
       isAutomationEnabled = !!dict.WIRAutomationAvailabilityKey;
     }
   }
-  /** @type {import('./types').AppInfo} */
-  const entry = {
+  const entry: AppInfo = {
     id,
     isProxy,
     name: dict.WIRApplicationNameKey,
@@ -56,13 +56,13 @@ export function appInfoFromDict (dict) {
 }
 
 /**
- * Take a dictionary from the remote debugger and makes a more manageable
- * dictionary of pages available.
+ * Takes a dictionary from the remote debugger and converts it into an array
+ * of Page objects with understandable keys. Filters out non-web pages.
  *
- * @param {import('@appium/types').StringRecord} pageDict
- * @returns {import('./types').Page[]}
+ * @param pageDict - Dictionary from the remote debugger containing page information.
+ * @returns An array of Page objects representing the available pages.
  */
-export function pageArrayFromDict (pageDict) {
+export function pageArrayFromDict(pageDict: StringRecord): Page[] {
   return _.values(pageDict)
     // count only WIRTypeWeb pages and ignore all others (WIRTypeJavaScript etc)
     .filter((dict) => _.isUndefined(dict.WIRTypeKey) || ACCEPTED_PAGE_TYPES.includes(dict.WIRTypeKey))
@@ -75,14 +75,16 @@ export function pageArrayFromDict (pageDict) {
 }
 
 /**
+ * Finds all application identifier keys that match the given bundle ID.
+ * If no matches are found and the bundle ID is not WEB_CONTENT_BUNDLE_ID,
+ * falls back to searching for WEB_CONTENT_BUNDLE_ID.
  *
- * @param {string} bundleId
- * @param {import('./types').AppDict} appDict
- * @returns {string[]}
+ * @param bundleId - The bundle identifier to search for.
+ * @param appDict - The application dictionary to search in.
+ * @returns An array of unique application identifier keys matching the bundle ID.
  */
-export function appIdsForBundle (bundleId, appDict) {
-  /** @type {string[]} */
-  const appIds = _.toPairs(appDict)
+export function appIdsForBundle(bundleId: string, appDict: AppDict): string[] {
+  const appIds: string[] = _.toPairs(appDict)
     .filter(([, data]) => data.bundleId === bundleId)
     .map(([key]) => key);
 
@@ -95,11 +97,15 @@ export function appIdsForBundle (bundleId, appDict) {
 }
 
 /**
- * @template {import('@appium/types').StringRecord} T
- * @param {T} params
- * @returns {T}
+ * Validates that all parameters in the provided object have non-nil values.
+ * Throws an error if any parameters are missing (null or undefined).
+ *
+ * @template T - The type of the parameters object.
+ * @param params - An object containing parameters to validate.
+ * @returns The same parameters object if all values are valid.
+ * @throws Error if any parameters are missing, listing all missing parameter names.
  */
-export function checkParams (params) {
+export function checkParams<T extends StringRecord>(params: T): T {
   // check if all parameters have a value
   const errors = _.toPairs(params)
     .filter(([, value]) => _.isNil(value))
@@ -111,30 +117,33 @@ export function checkParams (params) {
 }
 
 /**
- * @param {any} value
- * @param {boolean} [multiline=false]
- * @returns {string}
+ * Converts a value to a JSON string, removing noisy function properties
+ * that can muddy the logs.
+ *
+ * @param value - The value to stringify.
+ * @param multiline - If true, formats the JSON with indentation. Defaults to false.
+ * @returns A JSON string representation of the value with noisy properties removed.
  */
-export function simpleStringify (value, multiline = false) {
+export function simpleStringify(value: any, multiline: boolean = false): string {
   if (!value) {
     return JSON.stringify(value);
   }
 
-  // we get back objects sometimes with string versions of functions
-  // which muddy the logs
-  let cleanValue = _.clone(value);
-  for (const property of ['ceil', 'clone', 'floor', 'round', 'scale', 'toString']) {
-    delete cleanValue[property];
-  }
+  const cleanValue = removeNoisyProperties(_.clone(value));
   return multiline ? JSON.stringify(cleanValue, null, 2) : JSON.stringify(cleanValue);
 }
 
 /**
+ * Converts the result from a JavaScript evaluation in the remote debugger
+ * into a usable format. Handles errors, serialization, and cleans up noisy
+ * function properties.
  *
- * @param {any} res
- * @returns {any}
+ * @param res - The raw result from the remote debugger's JavaScript evaluation.
+ * @returns The cleaned and converted result value.
+ * @throws Error if the result is undefined, has an unexpected type, or contains
+ *               an error status code.
  */
-export function convertJavascriptEvaluationResult (res) {
+export function convertJavascriptEvaluationResult(res: any): any {
   if (_.isUndefined(res)) {
     throw new Error(`Did not get OK result from remote debugger. Result was: ${_.truncate(simpleStringify(res), {length: RESPONSE_LOG_LENGTH})}`);
   } else if (_.isString(res)) {
@@ -156,23 +165,17 @@ export function convertJavascriptEvaluationResult (res) {
   // with either have an object with a `value` property (even if `null`),
   // or a plain object
   const value = _.has(res, 'value') ? res.value : res;
-
-  // get rid of noisy functions on objects
-  if (_.isObject(value)) {
-    for (const property of ['ceil', 'clone', 'floor', 'round', 'scale', 'toString']) {
-      delete value[property];
-    }
-  }
-  return value;
+  return removeNoisyProperties(value);
 }
 
 /**
- * Calculates the path to the current module's root folder
+ * Calculates the path to the current module's root folder.
+ * The result is memoized for performance.
  *
- * @returns {string} The full path to module root
- * @throws {Error} If the current module root folder cannot be determined
+ * @returns The full path to the module root directory.
+ * @throws Error if the module root folder cannot be determined.
  */
-export const getModuleRoot = _.memoize(function getModuleRoot () {
+export const getModuleRoot = _.memoize(function getModuleRoot(): string {
   const root = node.getModuleRootSync(MODULE_NAME, __filename);
   if (!root) {
     throw new Error(`Cannot find the root folder of the ${MODULE_NAME} Node.js module`);
@@ -181,9 +184,27 @@ export const getModuleRoot = _.memoize(function getModuleRoot () {
 });
 
 /**
- * @returns {import('@appium/types').StringRecord}
+ * Reads and parses the package.json file from the module root.
+ *
+ * @returns The parsed package.json contents as a StringRecord.
  */
-export function getModuleProperties() {
+export function getModuleProperties(): StringRecord {
   const fullPath = path.resolve(getModuleRoot(), 'package.json');
   return JSON.parse(nodeFs.readFileSync(fullPath, 'utf8'));
 }
+
+/**
+ * Removes noisy function properties from an object that can muddy the logs.
+ * These properties are often added by JavaScript number objects and similar.
+ *
+ * @param obj - The object to clean.
+ * @returns The cleaned object.
+ */
+function removeNoisyProperties<T>(obj: T): T {
+  if (_.isObject(obj)) {
+    for (const property of ['ceil', 'clone', 'floor', 'round', 'scale', 'toString']) {
+      delete obj[property];
+    }
+  }
+  return obj;
+}

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "appium"
   ],
-  "version": "15.2.12",
+  "version": "15.2.14",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {

package/lib/atoms.js

@@ -1,84 +0,0 @@
-import { fs } from '@appium/support';
-import path from 'path';
-import _ from 'lodash';
-import log from './logger';
-import { getModuleRoot } from './utils';
-
-const ATOMS_CACHE = {};
-
-/**
- * @param {any} obj
- * @returns {string}
- */
-function atomsStringify(obj) {
-  if (typeof obj === 'undefined') {
-    return 'undefined';
-  }
-  return JSON.stringify(obj);
-}
-
-/**
- *
- * @param {string} atomName
- * @returns {Promise<Buffer>}
- */
-async function getAtom (atomName) {
-  // check if we have already loaded and cached this atom
-  if (!_.has(ATOMS_CACHE, atomName)) {
-    const atomFileName = path.resolve(getModuleRoot(), 'atoms', `${atomName}.js`);
-    try {
-      ATOMS_CACHE[atomName] = await fs.readFile(atomFileName);
-    } catch {
-      throw new Error(`Unable to load Atom '${atomName}' from file '${atomFileName}'`);
-    }
-  }
-
-  return ATOMS_CACHE[atomName];
-}
-
-/**
- * @param {string} script
- * @param {string} frame
- * @returns {Promise<string>}
- */
-async function wrapScriptForFrame (script, frame) {
-  log.debug(`Wrapping script for frame '${frame}'`);
-  const elFromCache = await getAtom('get_element_from_cache');
-  return `(function (window) { var document = window.document; ` +
-    `return (${script}); })((${elFromCache.toString('utf8')})(${atomsStringify(frame)}))`;
-}
-
-/**
- *
- * @param {string} atom
- * @param {any[]} [args]
- * @param {string[]} [frames]
- * @param {string?} [asyncCallBack]
- * @returns {Promise<string>}
- */
-async function getScriptForAtom (atom, args = [], frames = [], asyncCallBack = null) {
-  const atomSrc = (await getAtom(atom)).toString('utf8');
-  let script;
-  if (frames.length > 0) {
-    script = atomSrc;
-    for (const frame of frames) {
-      script = await wrapScriptForFrame(script, frame);
-    }
-  } else {
-    log.debug(`Executing '${atom}' atom in default context`);
-    script = `(${atomSrc})`;
-  }
-
-  // add the arguments, as strings
-  args = args.map(atomsStringify);
-  if (asyncCallBack) {
-    script += `(${args.join(',')}, ${asyncCallBack}, true)`;
-  } else {
-    script += `(${args.join(',')})`;
-  }
-
-  return script;
-}
-
-export { getAtom, getScriptForAtom };
-export default getAtom;

package/lib/logger.js

@@ -1,6 +0,0 @@
-import { logger } from '@appium/support';
-
-
-const log = logger.getLogger('RemoteDebugger');
-
-export default log;

package/lib/rpc/index.js

@@ -1,4 +0,0 @@
-import { RpcClientSimulator } from './rpc-client-simulator';
-import { RpcClientRealDevice } from './rpc-client-real-device';
-
-export { RpcClientSimulator, RpcClientRealDevice };