appium-ios-remotexpc 5.2.1 → 5.2.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [5.2.2](https://github.com/appium/appium-ios-remotexpc/compare/v5.2.1...v5.2.2) (2026-06-24)
+
+### Miscellaneous Chores
+
+* Add scripts to typescript checks ([#253](https://github.com/appium/appium-ios-remotexpc/issues/253)) ([f06a206](https://github.com/appium/appium-ios-remotexpc/commit/f06a2060a41f834ca049cb31d9f453c12d9fc013))
+
 ## [5.2.1](https://github.com/appium/appium-ios-remotexpc/compare/v5.2.0...v5.2.1) (2026-06-24)
 
 ### Miscellaneous Chores

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "5.2.1",
+  "version": "5.2.2",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "type": "module",

package/scripts/lib/progress.mjs

@@ -16,6 +16,10 @@ export function startTimeoutProgressLogger({
   let timer = null;
   let isStopped = false;
 
+  /**
+   * @param {string} status
+   * @param {boolean} isComplete
+   */
   const logProgress = (status, isComplete = false) => {
     const elapsedMs = performance.now() - startedAt;
     const boundedElapsedMs = Math.min(elapsedMs, timeoutMs);
@@ -28,6 +32,10 @@ export function startTimeoutProgressLogger({
     );
   };
 
+  /**
+   * @param {string} status
+   * @param {boolean} isComplete
+   */
   const stop = (status, isComplete = false) => {
     if (isStopped) {
       return;

package/scripts/lib/tunnel-registry.mjs

@@ -35,7 +35,7 @@ export async function refreshServiceCatalog(udid, entry, log) {
  * @template T
  * @param {object} opts
  * @param {import('appium-ios-remotexpc').TunnelRegistryServer | null} opts.registryServer
- * @param {T} opts.result
+ * @param {T & { tunnel: { Address: string, RsdPort?: number } }} opts.result
  * @param {(result: T) => string} opts.getUdid
  * @param {(result: T, existing: import('appium-ios-remotexpc').TunnelRegistryEntry | undefined, now: number) => import('appium-ios-remotexpc').TunnelRegistryEntry} opts.buildEntry
  * @param {{info: (message: string) => void, warn: (message: string) => void}} opts.log

package/scripts/pair-appletv.mjs

@@ -20,12 +20,23 @@ const log = logger.getLogger('AppleTVPairing');
 const APPLETV_PAIRING_DISCOVERY_PROGRESS_INTERVAL_MS = 1000;
 const APPLETV_PAIRING_DISCOVERY_PROGRESS_BAR_WIDTH = 24;
 
+/**
+ * @param {import('appium-ios-remotexpc').AppleTVPairingService} pairingService
+ * @param {number} timeoutMs
+ * @returns {{ startedAt: number, promise: Promise<AppleTVDevice[]> }}
+ */
 function discoverAppleTVPairingDevices(pairingService, timeoutMs) {
   const startedAt = performance.now();
   const promise = pairingService.discoverDevices({ timeoutMs });
   return { startedAt, promise };
 }
 
+/**
+ *
+ * @param {{ startedAt: number, promise: Promise<AppleTVDevice[]> }} discovery
+ * @param {number} timeoutMs
+ * @returns {Promise<AppleTVDevice[]>}
+ */
 async function waitForAppleTVPairingDiscovery(discovery, timeoutMs) {
   const progress = startTimeoutProgressLogger({
     log,
@@ -48,6 +59,12 @@ async function waitForAppleTVPairingDiscovery(discovery, timeoutMs) {
   }
 }
 
+/**
+ * @param {import('appium-ios-remotexpc').AppleTVPairingService} pairingService
+ * @param {string} deviceSelector
+ * @param {number} discoveryTimeoutMs
+ * @returns {Promise<{ success: boolean, deviceId: string, pairingFile?: string, error?: Error | null }>}
+ */
 async function discoverAndPairWithProgress(
   pairingService,
   deviceSelector,
@@ -124,3 +141,7 @@ async function main() {
 }
 
 await main();
+
+/**
+ * @typedef {import('appium-ios-remotexpc').AppleTVDevice} AppleTVDevice
+ */

package/scripts/start-appletv-tunnel.mjs

@@ -39,6 +39,7 @@ const APPLETV_TUNNEL_DISCOVERY_PROGRESS_BAR_WIDTH = 24;
 /** @type {import('appium-ios-remotexpc').TunnelRegistryServer | null} */
 let registryServer = null;
 
+/** @type {(() => void)[]} */
 const registryWatcherStops = [];
 /** @type {Map<string, Promise<void>>} */
 const reconnectingByUdid = new Map();
@@ -48,6 +49,10 @@ const establishedTunnelsByUdid = new Map();
 /** @type {Map<string, () => void>} */
 const lifecycleWatchStopByUdid = new Map();
 
+/**
+ * @param {import('appium-ios-tuntap').TunnelConnection} tunnelConnection
+ * @returns {Promise<void>}
+ */
 async function closeTunnelQuietly(tunnelConnection) {
   try {
     await tunnelConnection.closer();
@@ -56,6 +61,10 @@ async function closeTunnelQuietly(tunnelConnection) {
   }
 }
 
+/**
+ * @param {string} udid
+ * @returns {void}
+ */
 function stopLifecycleWatch(udid) {
   const stop = lifecycleWatchStopByUdid.get(udid);
   if (stop) {
@@ -68,7 +77,7 @@ function stopLifecycleWatch(udid) {
  *
  * @param {import('appium-ios-remotexpc').AppleTVTunnelService} tunnelService
  * @param {number} timeoutMs
- * @returns {Promise<number, Promise<AppleTVDevice[]>>}
+ * @returns {{ startedAt: number, promise: Promise<AppleTVDevice[]> }}
  */
 function startDevicesDiscovery(tunnelService, timeoutMs) {
   const startedAt = performance.now();
@@ -78,7 +87,7 @@ function startDevicesDiscovery(tunnelService, timeoutMs) {
 
 /**
  *
- * @param {Promise<AppleTVDevice[]>} discovery
+ * @param {{ startedAt: number, promise: Promise<AppleTVDevice[]> }} discovery
  * @param {number} timeoutMs
  * @returns {Promise<AppleTVDevice[]>}
  */
@@ -109,9 +118,13 @@ async function waitForDevicesDiscovery(discovery, timeoutMs) {
  * @returns {boolean}
  */
 function isNoDevicesFoundError(err) {
-  return err instanceof Error && ('code' in err && err.code === 'NO_DEVICES') || err.message?.includes('No devices found');
+  return err instanceof Error && ('code' in err && err.code === 'NO_DEVICES') || /** @type {Error} */ (err).message?.includes('No devices found');
 }
 
+/**
+ * @param {AppleTvEstablishedTunnel} result
+ * @returns {void}
+ */
 function registerEstablishedTunnel(result) {
   const udid = result.device.identifier;
   stopLifecycleWatch(udid);
@@ -125,11 +138,15 @@ function registerEstablishedTunnel(result) {
   }
   establishedTunnelsByUdid.set(udid, result);
 }
+
+/** @type {import('appium-ios-remotexpc').AppleTVTunnelService | null} */
 let tunnelService = null;
 
 /**
- * @param {object} registry
+ * @param {import('appium-ios-remotexpc').TunnelRegistry} registry
  * @param {AppleTvEstablishedTunnel[]} successfulResults
+ * @param {object} callbacks
+ * @param {function({ udid: string, address: string }): Promise<void>} [callbacks.onTunnelDead]
  */
 function attachAppleTvTunnelRegistryLifecycleWatch(registry, successfulResults, callbacks = {}) {
   for (const result of successfulResults) {
@@ -163,7 +180,14 @@ function attachAppleTvTunnelRegistryLifecycleWatch(registry, successfulResults,
   );
 }
 
+/**
+ * @returns {void}
+ */
 function setupCleanupHandlers() {
+  /**
+   * @param {string} signal
+   * @returns {Promise<void>}
+   */
   const cleanup = async (signal) => {
     log.warn(`\nCleaning up (${signal})...`);
 
@@ -230,6 +254,7 @@ function setupCleanupHandlers() {
  */
 async function establishOneTunnel(startResult) {
   const { tcpSocket, psk, device } = startResult;
+  /** @type {{ notify: ((reason: string) => void) | null }} */
   const lifecycle = { notify: null };
 
   const tunnelConnection = await TunnelManager.getTunnelPsk(
@@ -247,6 +272,10 @@ async function establishOneTunnel(startResult) {
       RsdPort: tunnelConnection.RsdPort,
     },
     tunnelConnection,
+    /**
+     * @param {(reason: string) => void} handler
+     * @returns {void}
+     */
     registerOnDead: (handler) => {
       lifecycle.notify = handler;
     },
@@ -256,6 +285,12 @@ async function establishOneTunnel(startResult) {
   return result;
 }
 
+/**
+ * @param {AppleTvEstablishedTunnel} result
+ * @param {import('appium-ios-remotexpc').TunnelRegistryEntry | undefined} existing
+ * @param {number} now
+ * @returns {import('appium-ios-remotexpc').TunnelRegistryEntry}
+ */
 function buildAppleTvTunnelEntry(result, existing, now) {
   const udid = result.device.identifier;
   const entry = {
@@ -272,6 +307,11 @@ function buildAppleTvTunnelEntry(result, existing, now) {
   return entry;
 }
 
+/**
+ *
+ * @param {AppleTvEstablishedTunnel} result
+ * @returns {Promise<boolean>}
+ */
 async function publishDiscoveredTunnelEntry(result) {
   return await publishTunnelRegistryEntry({
     registryServer,
@@ -282,6 +322,16 @@ async function publishDiscoveredTunnelEntry(result) {
   });
 }
 
+/**
+ *
+ * @param {object} opts
+ * @param {string} opts.udid
+ * @param {number} opts.maxRetries
+ * @param {import('appium-ios-remotexpc').AppleTVTunnelService} opts.tunnelService
+ * @param {function(string): Promise<void>} opts.reconnectTunnelByUdid
+ * @param {number} opts.discoveryTimeoutMs
+ * @returns {Promise<void>}
+ */
 async function runAppleTvReconnectAttempts({
   udid,
   maxRetries,
@@ -327,6 +377,14 @@ async function runAppleTvReconnectAttempts({
   log.error(`Reconnect retries exhausted for ${udid}`);
 }
 
+/**
+ *
+ * @param {object} opts
+ * @param {number} opts.reconnectRetries
+ * @param {import('appium-ios-remotexpc').AppleTVTunnelService} opts.tunnelService
+ * @param {number} opts.discoveryTimeoutMs
+ * @returns {function(string): Promise<void>}
+ */
 function createAppleTvReconnectTunnelByUdid({
   reconnectRetries,
   tunnelService,
@@ -565,3 +623,7 @@ await main();
  * @property {import('appium-ios-tuntap').TunnelConnection} tunnelConnection
  * @property {(handler: (reason: string) => void) => void} registerOnDead
  */
+
+/**
+ * @typedef {import('appium-ios-remotexpc').AppleTVDevice} AppleTVDevice
+ */

package/scripts/tunnel-creation.mjs

@@ -40,6 +40,10 @@ const establishedTunnelsByUdid = new Map();
 /** @type {Map<string, () => void>} */
 const lifecycleWatchStopByUdid = new Map();
 
+/**
+ * @param {import('appium-ios-tuntap').TunnelConnection} tunnelConnection
+ * @returns {Promise<void>}
+ */
 async function closeTunnelQuietly(tunnelConnection) {
   try {
     await tunnelConnection.closer();
@@ -48,6 +52,10 @@ async function closeTunnelQuietly(tunnelConnection) {
   }
 }
 
+/**
+ * @param {string} udid
+ * @returns {void}
+ */
 function stopLifecycleWatch(udid) {
   const stop = lifecycleWatchStopByUdid.get(udid);
   if (stop) {
@@ -56,6 +64,10 @@ function stopLifecycleWatch(udid) {
   }
 }
 
+/**
+ * @param {TunnelCreationSuccessResult} result
+ * @returns {void}
+ */
 function registerEstablishedTunnel(result) {
   const udid = result.device.Properties.SerialNumber;
   stopLifecycleWatch(udid);
@@ -70,6 +82,11 @@ function registerEstablishedTunnel(result) {
   establishedTunnelsByUdid.set(udid, result);
 }
 
+/**
+ *
+ * @param {string} connectionType
+ * @returns {number}
+ */
 function connectionTypeRank(connectionType) {
   if (connectionType === 'USB') {
     return 0;
@@ -104,15 +121,25 @@ function dedupeDevicesByUdid(devices) {
   return [...byUdid.values()];
 }
 
+/**
+ *
+ * @param {TunnelCreationSuccessResult} result
+ * @param {import('appium-ios-remotexpc').TunnelRegistryEntry | undefined} existing
+ * @param {number} now
+ * @returns {import('appium-ios-remotexpc').TunnelRegistryEntry}
+ */
 function buildTunnelEntry(result, existing, now) {
   const udid = result.device.Properties.SerialNumber;
+  /** @type {import('appium-ios-remotexpc').TunnelRegistryEntry} */
   const entry = {
     udid,
     deviceId: result.device.DeviceID,
     address: result.tunnel.Address,
     rsdPort: result.tunnel.RsdPort,
     services: {},
+    // @ts-expect-error - connectionType is not typed
     connectionType: result.device.Properties.ConnectionType,
+    // @ts-expect-error - productId is not typed
     productId: result.device.Properties.ProductID,
     createdAt: existing?.createdAt ?? now,
     lastUpdated: now,
@@ -120,6 +147,10 @@ function buildTunnelEntry(result, existing, now) {
   return entry;
 }
 
+/**
+ * @param {TunnelCreationSuccessResult} result
+ * @returns {Promise<boolean>}
+ */
 async function publishDiscoveredTunnelEntry(result) {
   return await publishTunnelRegistryEntry({
     registryServer,
@@ -130,6 +161,7 @@ async function publishDiscoveredTunnelEntry(result) {
   });
 }
 
+/** @type {(() => void)[]} */
 const registryWatcherStops = [];
 /** @type {Map<string, Promise<void>>} */
 const reconnectingByUdid = new Map();
@@ -137,8 +169,11 @@ const reconnectingByUdid = new Map();
 /**
  * When the native forwarder exits, drop the UDID from the HTTP registry and tear down state.
  *
- * @param {object} registry
+ * @param {import('appium-ios-remotexpc').TunnelRegistry} registry
  * @param {TunnelCreationSuccessResult[]} successful
+ * @param {object} callbacks
+ * @param {function({ udid: string, address: string }): Promise<void>} [callbacks.onTunnelDead]
+ * @returns {void}
  */
 function attachTunnelRegistryLifecycleWatch(registry, successful, callbacks = {}) {
   for (const result of successful) {
@@ -172,6 +207,15 @@ function attachTunnelRegistryLifecycleWatch(registry, successful, callbacks = {}
   );
 }
 
+/**
+ *
+ * @param {object} opts
+ * @param {string} opts.udid
+ * @param {number} opts.maxRetries
+ * @param {import('appium-ios-remotexpc').UsbmuxDevice} opts.device
+ * @param {function(string): Promise<void>} opts.reconnectTunnelByUdid
+ * @returns {Promise<void>}
+ */
 async function runReconnectAttempts({
   udid,
   maxRetries,
@@ -193,6 +237,7 @@ async function runReconnectAttempts({
         registryServer.getRegistry(),
         [result],
         {
+
           onTunnelDead: async ({ udid: droppedUdid }) => {
             await reconnectTunnelByUdid(droppedUdid);
           },
@@ -211,6 +256,12 @@ async function runReconnectAttempts({
   log.error(`Reconnect retries exhausted for ${udid}`);
 }
 
+/**
+ * @param {object} opts
+ * @param {number} opts.reconnectRetries
+ * @param {Map<string, import('appium-ios-remotexpc').UsbmuxDevice>} opts.devicesByUdid
+ * @returns {function(string): Promise<void>}
+ */
 function createReconnectTunnelByUdid({
   reconnectRetries,
   devicesByUdid,
@@ -245,7 +296,14 @@ function createReconnectTunnelByUdid({
   };
 }
 
+/**
+ * @returns {void}
+ */
 function setupCleanupHandlers() {
+  /**
+   * @param {string} signal
+   * @returns {Promise<void>}
+   */
   const cleanup = async (signal) => {
     log.warn(`\nCleaning up (${signal})...`);
 
@@ -298,6 +356,10 @@ function setupCleanupHandlers() {
   });
 }
 
+/**
+ * @param {import('appium-ios-remotexpc').UsbmuxDevice} device
+ * @returns {Promise<TunnelCreationSuccessResult>}
+ */
 async function createTunnelForDevice(device) {
   const udid = device.Properties.SerialNumber;
 
@@ -323,6 +385,7 @@ async function createTunnelForDevice(device) {
     log.info('CoreDeviceProxy started successfully');
 
     log.info(`Creating tunnel...`);
+    /** @type {{ notify: ((reason: string) => void) | null }} */
     const lifecycle = { notify: null };
     const tunnelConnection = await TunnelManager.getTunnel(
       socket,
@@ -339,7 +402,9 @@ async function createTunnelForDevice(device) {
     log.info(`   Tunnel Address: ${tunnelConnection.Address}`);
     log.info(`   Tunnel RsdPort: ${tunnelConnection.RsdPort}`);
 
+    /** @type {TunnelCreationSuccessResult} */
     const result = {
+      // @ts-expect-error - device is not typed
       device,
       tunnel: {
         Address: tunnelConnection.Address,
@@ -347,6 +412,10 @@ async function createTunnelForDevice(device) {
       },
       success: true,
       tunnelConnection,
+      /**
+       * @param {(reason: string) => void} handler
+       * @returns {void}
+       */
       registerOnDead: (handler) => {
         lifecycle.notify = handler;
       },
@@ -358,6 +427,7 @@ async function createTunnelForDevice(device) {
     const errorMessage = `Failed to create tunnel for device ${udid}: ${error}`;
     log.error(`❌ ${errorMessage}`);
     return {
+      // @ts-expect-error - device is not typed
       device,
       tunnel: { Address: '', RsdPort: 0 },
       success: false,
@@ -366,6 +436,9 @@ async function createTunnelForDevice(device) {
   }
 }
 
+/**
+ * @returns {Promise<void>}
+ */
 async function main() {
   setupCleanupHandlers();
 
@@ -492,6 +565,10 @@ async function main() {
           registryServer.getRegistry(),
           [result],
           {
+            /**
+             * @param {{ udid: string }} ctx
+             * @returns {Promise<void>}
+             */
             onTunnelDead: async ({ udid }) => {
               await reconnectTunnelByUdid(udid);
             },
@@ -554,8 +631,9 @@ await main();
  * Successful tunnel row (USB lockdown + CoreDeviceProxy) used for the registry and lifecycle watch.
  *
  * @typedef {object} TunnelCreationSuccessResult
- * @property {{ Properties: { SerialNumber: string }, DeviceID: number }} device
+ * @property {{ Properties: { SerialNumber: string, [key: string]: unknown }, DeviceID: number }} device
  * @property {{ Address: string, RsdPort?: number }} tunnel
  * @property {import('appium-ios-tuntap').TunnelConnection} tunnelConnection
  * @property {(handler: (reason: string) => void) => void} registerOnDead
+ * @property {boolean} success
  */