appium-mac2-driver 4.5.0 → 4.6.0

package/node_modules/asyncbox/lib/lock.ts

@@ -0,0 +1,360 @@
+import {AsyncResource} from 'node:async_hooks';
+
+const DEFAULT_MAX_PENDING = 1000;
+// setTimeout fires after 1 ms for anything above this
+const MAX_TIMER_MS = 2 ** 31 - 1;
+
+/** Options shared by the {@link AsyncLock} constructor and {@link AsyncLock.acquire}. */
+export interface AsyncLockOptions {
+  /**
+   * Max ms a task may wait in the queue before failing. `0` means never.
+   * @default 0
+   */
+  timeout?: number;
+  /**
+   * Max ms between calling `acquire` and the task finishing (queue wait included). `0` means never.
+   * @default 0
+   */
+  maxOccupationTime?: number;
+  /**
+   * Max ms the task may run once it holds the lock; the lock is then released. `0` means never.
+   * @default 0
+   */
+  maxExecutionTime?: number;
+  /**
+   * Max number of tasks waiting per key; further ones are rejected right away. `0` rejects every
+   * task that would have to wait.
+   * @default 1000
+   */
+  maxPending?: number;
+}
+
+/** Per-call options of {@link AsyncLock.acquire}; override the constructor ones. */
+export interface AcquireOptions extends AsyncLockOptions {
+  /**
+   * Put the task at the front of the queue instead of the back.
+   * @default false
+   */
+  skipQueue?: boolean;
+}
+
+type Task<T> = () => T | PromiseLike<T>;
+type Outcome<T> = {value: T} | {error: unknown};
+type Queues = Map<string, Array<() => void>>;
+type ResolvedOptions = Required<AsyncLockOptions> & {skipQueue?: boolean};
+type ClaimOptions = Pick<ResolvedOptions, 'timeout' | 'maxPending' | 'skipQueue'>;
+
+/**
+ * Promise-based mutex keyed by string. Tasks with the same key run one at a time, in FIFO order.
+ *
+ * Each task runs in the async context (`AsyncLocalStorage`) of the code that called
+ * {@link AsyncLock.acquire}, not in the context of the task that held the lock before it.
+ */
+export class AsyncLock {
+  private readonly queues: Queues = new Map();
+  private readonly defaults: Required<AsyncLockOptions>;
+
+  constructor(opts: AsyncLockOptions = {}) {
+    validateOptions(opts);
+    this.defaults = {
+      timeout: 0,
+      maxOccupationTime: 0,
+      maxExecutionTime: 0,
+      maxPending: DEFAULT_MAX_PENDING,
+      ...stripUndefined(opts),
+    };
+  }
+
+  /**
+   * Run `fn` once the lock for `key` is free and release the lock when it settles.
+   *
+   * Multiple keys are held together. They are acquired one by one in sorted order, whatever order
+   * they are given in, so that overlapping calls cannot deadlock; duplicates are ignored. Keys that
+   * are already held stay held while a later one is awaited. `timeout` and `maxOccupationTime` are
+   * budgets for the whole call, while `maxExecutionTime` counts from the moment all the keys are
+   * held and releases all of them.
+   *
+   * @param key - Resource key, or a non-empty array of keys
+   * @param fn - Task to run while holding the lock; may be sync or async
+   * @param opts - Per-call options
+   * @returns The result of `fn`
+   * @throws {TypeError} Synchronously, if an argument is invalid
+   */
+  acquire<T>(key: string | readonly string[], fn: Task<T>, opts: AcquireOptions = {}): Promise<T> {
+    if (typeof fn !== 'function') {
+      throw new TypeError('You must pass a function to execute');
+    }
+    if (
+      typeof key !== 'string' &&
+      !(Array.isArray(key) && key.length > 0 && [...key].every((k) => typeof k === 'string'))
+    ) {
+      throw new TypeError('The key must be a string or a non-empty array of strings');
+    }
+    validateOptions(opts);
+    // A canonical order keeps overlapping multi-key calls, e.g. ['a', 'b'] and ['b', 'a'], from deadlocking
+    const keys = typeof key === 'string' ? [key] : [...new Set(key)].sort();
+    const acquisition = new Acquisition(this.queues, keys, fn, {...this.defaults, ...stripUndefined(opts)});
+    acquisition.enqueue();
+    return acquisition.promise;
+  }
+
+  /**
+   * Number of tasks waiting for `key`, not counting the running one.
+   *
+   * @param key - Resource key
+   */
+  getQueueLength(key: string): number {
+    return this.queues.get(key)?.length ?? 0;
+  }
+
+  /**
+   * Whether `key` has a running or pending task. Without a key, whether any key does.
+   *
+   * @param key - Resource key
+   */
+  isBusy(key?: string): boolean {
+    return key === undefined ? this.queues.size > 0 : this.queues.has(key);
+  }
+}
+
+/** The place of one acquisition in the queue of one key; once granted, it holds the key. */
+class KeyClaim {
+  private holding = false;
+  private dropped = false;
+  private queueTimer?: NodeJS.Timeout;
+
+  constructor(
+    private readonly queues: Queues,
+    private readonly key: string,
+    private readonly opts: ClaimOptions,
+    private readonly onGranted: () => void,
+    private readonly onDenied: (error: Error) => void,
+  ) {}
+
+  /**
+   * Take the key right away if it is free, otherwise wait in its queue.
+   *
+   * @returns Whether the key is held. If not, `onGranted` is called once it is, unless the claim
+   * is denied.
+   */
+  join(): boolean {
+    const {timeout, maxPending, skipQueue} = this.opts;
+    const queue = this.queues.get(this.key);
+    if (!queue) {
+      this.queues.set(this.key, []);
+      this.holding = true;
+      return true;
+    }
+    if (queue.length >= maxPending) {
+      this.onDenied(new Error(`Too many pending tasks in queue ${this.key}`));
+    } else {
+      if (skipQueue) {
+        queue.unshift(this.grant);
+      } else {
+        queue.push(this.grant);
+      }
+      if (timeout) {
+        this.queueTimer = setTimeout(
+          () => this.onDenied(new Error(`async-lock timed out in queue ${this.key}`)),
+          timeout,
+        );
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Leave the queue, or release the key if it is held. Idempotent.
+   *
+   * @returns The handover of the key to its next waiter. The caller must run it only after it
+   * has released all of its keys, so that no waiter starts while a batch is partially released.
+   */
+  drop(): (() => void) | undefined {
+    if (this.dropped) {
+      return undefined;
+    }
+    this.dropped = true;
+    clearTimeout(this.queueTimer);
+    if (this.holding) {
+      return this.releaseKey();
+    }
+    const queue = this.queues.get(this.key);
+    const idx = queue?.indexOf(this.grant) ?? -1;
+    if (idx >= 0) {
+      queue?.splice(idx, 1);
+    }
+    return undefined;
+  }
+
+  private releaseKey(): (() => void) | undefined {
+    const next = this.queues.get(this.key)?.shift();
+    if (!next) {
+      this.queues.delete(this.key);
+    }
+    return next;
+  }
+
+  // An arrow function, because this exact reference sits in the queue and is removed by drop()
+  private readonly grant = (): void => {
+    clearTimeout(this.queueTimer);
+    this.holding = true;
+    if (this.dropped) {
+      // Dropped while the key was being handed over to it: pass the key on instead of using it
+      this.releaseKey()?.();
+      return;
+    }
+    this.onGranted();
+  };
+}
+
+/**
+ * One `acquire` call: its promise, its timers and its claims on all of its keys. The keys are
+ * claimed one by one, the task runs once all of them are held and they are released together.
+ */
+class Acquisition<T> {
+  readonly promise: Promise<T>;
+  private resolve!: (value: T) => void;
+  private reject!: (error: unknown) => void;
+  private readonly task: Task<T>;
+  private readonly claims: KeyClaim[] = [];
+  private running = false;
+  private settled = false;
+  private queueDeadline = 0;
+  private occupationTimer?: NodeJS.Timeout;
+  private executionTimer?: NodeJS.Timeout;
+
+  constructor(
+    private readonly queues: Queues,
+    private readonly keys: string[],
+    task: Task<T>,
+    private readonly opts: ResolvedOptions,
+  ) {
+    // Queued tasks are started from the previous task's promise chain; bind to keep our context
+    this.task = AsyncResource.bind(task);
+    this.promise = new Promise<T>((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+    });
+  }
+
+  /** Start the task right away if all the keys are free, otherwise wait for them. */
+  enqueue(): void {
+    const {timeout, maxOccupationTime} = this.opts;
+    if (timeout) {
+      this.queueDeadline = performance.now() + timeout;
+    }
+    if (maxOccupationTime) {
+      this.occupationTimer = setTimeout(() => this.expire(), maxOccupationTime);
+    }
+    this.claimKeys(0);
+  }
+
+  // Free keys are claimed in a loop, not recursively, so that a large batch cannot overflow the stack
+  private claimKeys(from: number): void {
+    const {maxPending, skipQueue} = this.opts;
+    try {
+      for (let index = from; index < this.keys.length; index++) {
+        // The queue timeout is a budget for waiting for all the keys, not for each one
+        const timeout = this.queueDeadline ? Math.max(this.queueDeadline - performance.now(), 1) : 0;
+        const claim = new KeyClaim(
+          this.queues,
+          this.keys[index],
+          {timeout, maxPending, skipQueue},
+          () => this.claimKeys(index + 1),
+          (error) => this.abort(error),
+        );
+        this.claims.push(claim);
+        if (!claim.join()) {
+          return;
+        }
+      }
+      this.execute();
+    } catch (error) {
+      this.abort(error);
+    }
+  }
+
+  private execute(): void {
+    const {maxExecutionTime} = this.opts;
+    this.running = true;
+    if (maxExecutionTime) {
+      this.executionTimer = setTimeout(
+        () => this.abort(new Error(`Maximum execution time is exceeded ${this.keys.join(', ')}`)),
+        maxExecutionTime,
+      );
+    }
+    new Promise<T>((resolve) => resolve(this.task())).then(
+      (value) => this.finish({value}),
+      (error) => this.finish({error}),
+    );
+  }
+
+  private finish(outcome: Outcome<T>): void {
+    this.settle(outcome);
+    this.release();
+  }
+
+  // Reject and release all the keys; a running task is left to finish on its own
+  private abort(error: unknown): void {
+    this.settle({error});
+    this.release();
+  }
+
+  // A running task keeps its keys until it finishes, an unstarted one gives them up
+  private expire(): void {
+    const keys = this.keys.join(', ');
+    if (this.running) {
+      this.settle({error: new Error(`Maximum occupation time is exceeded while executing ${keys}`)});
+    } else {
+      this.abort(new Error(`Maximum occupation time is exceeded in queue ${keys}`));
+    }
+  }
+
+  private settle(outcome: Outcome<T>): void {
+    if (this.settled) {
+      return;
+    }
+    this.settled = true;
+    clearTimeout(this.occupationTimer);
+    if ('error' in outcome) {
+      this.reject(outcome.error);
+    } else {
+      this.resolve(outcome.value);
+    }
+  }
+
+  // Idempotent, so a task that outlives its execution timeout cannot release the keys twice
+  private release(): void {
+    clearTimeout(this.executionTimer);
+    const handovers = this.claims
+      .splice(0)
+      .reverse()
+      .map((claim) => claim.drop());
+    for (const handover of handovers) {
+      handover?.();
+    }
+  }
+}
+
+function validateOptions(opts: AcquireOptions): void {
+  if (opts === null || typeof opts !== 'object') {
+    throw new TypeError('The options must be an object');
+  }
+  for (const name of ['timeout', 'maxOccupationTime', 'maxExecutionTime'] as const) {
+    const value = opts[name];
+    if (value !== undefined && !(Number.isFinite(value) && value >= 0 && value <= MAX_TIMER_MS)) {
+      throw new TypeError(`${name} must be a number of milliseconds between 0 and ${MAX_TIMER_MS}`);
+    }
+  }
+  if (opts.skipQueue !== undefined && typeof opts.skipQueue !== 'boolean') {
+    throw new TypeError('skipQueue must be a boolean');
+  }
+  const {maxPending} = opts;
+  if (maxPending !== undefined && maxPending !== Infinity && !(Number.isInteger(maxPending) && maxPending >= 0)) {
+    throw new TypeError('maxPending must be a non-negative integer or Infinity');
+  }
+}
+
+function stripUndefined<T extends object>(obj: T): Partial<T> {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as Partial<T>;
+}

package/node_modules/asyncbox/lib/long-sleep.ts

@@ -0,0 +1,38 @@
+import {sleep} from './sleep.js';
+import type {LongSleepOptions} from './types.js';
+
+const LONG_SLEEP_THRESHOLD = 5000; // anything over 5000ms will turn into a spin
+
+/**
+ * Sometimes `Promise.delay` or `setTimeout` are inaccurate for large wait
+ * times. To safely wait for these long times (e.g. in the 5+ minute range), you
+ * can use `longSleep`.
+ *
+ * You can also pass a `progressCb` option which is a callback function that
+ * receives an object with the properties `elapsedMs`, `timeLeft`, and
+ * `progress`. This will be called on every wait interval so you can do your
+ * wait logging or whatever.
+ * @param ms - The number of milliseconds to wait
+ * @param options - Options for controlling the long sleep behavior
+ */
+export async function longSleep(
+  ms: number,
+  {thresholdMs = LONG_SLEEP_THRESHOLD, intervalMs = 1000, progressCb = null}: LongSleepOptions = {},
+): Promise<void> {
+  if (ms < thresholdMs) {
+    return await sleep(ms);
+  }
+  const endAt = performance.now() + ms;
+  let timeLeft: number;
+  let elapsedMs = 0;
+  do {
+    const pre = performance.now();
+    await sleep(intervalMs);
+    const post = performance.now();
+    timeLeft = endAt - post;
+    elapsedMs = elapsedMs + (post - pre);
+    if (typeof progressCb === 'function') {
+      progressCb({elapsedMs: Math.round(elapsedMs), timeLeft: Math.round(timeLeft), progress: elapsedMs / ms});
+    }
+  } while (timeLeft > 0);
+}

package/node_modules/asyncbox/lib/retry.ts

@@ -0,0 +1,61 @@
+import {sleep} from './sleep.js';
+
+/**
+ * An async/await way of running a method until it doesn't throw an error
+ * @param times - The maximum number of times to retry the function
+ * @param fn - The async function to retry
+ * @param args - Arguments to pass to the function
+ */
+export async function retry<T = any>(
+  times: number,
+  fn: (...args: any[]) => Promise<T>,
+  ...args: any[]
+): Promise<T | null> {
+  let tries = 0;
+  let done = false;
+  let res: T | null = null;
+  while (!done && tries < times) {
+    tries++;
+    try {
+      res = await fn(...args);
+      done = true;
+    } catch (err) {
+      if (tries >= times) {
+        throw err;
+      }
+    }
+  }
+  return res;
+}
+
+/**
+ * You can also use `retryInterval` to add a sleep in between retries. This can
+ * be useful if you want to throttle how fast we retry.
+ * @param times - The maximum number of times to retry the function
+ * @param sleepMs - The number of milliseconds to wait between retries
+ * @param fn - The async function to retry
+ * @param args - Arguments to pass to the function
+ */
+export async function retryInterval<T = any>(
+  times: number,
+  sleepMs: number,
+  fn: (...args: any[]) => Promise<T>,
+  ...args: any[]
+): Promise<T | null> {
+  let count = 0;
+  const wrapped = async (): Promise<T> => {
+    count++;
+    let res: T;
+    try {
+      res = await fn(...args);
+    } catch (e) {
+      // do not pause when finished the last retry
+      if (count !== times) {
+        await sleep(sleepMs);
+      }
+      throw e;
+    }
+    return res;
+  };
+  return await retry(times, wrapped);
+}

package/node_modules/asyncbox/lib/sleep.ts

@@ -0,0 +1,79 @@
+import {PromiseCancellationError} from './errors.js';
+import type {CancellablePromise, SleepArg, SleepOptions} from './types.js';
+
+/**
+ * An async/await version of `setTimeout`. The returned promise has a `cancel()` method that clears
+ * the timer and usually rejects with {@link PromiseCancellationError} unless you use the object form with
+ * `cancelError: null` to resolve on cancel.
+ *
+ * @param ms - Milliseconds to wait
+ * @returns A thenable you can `await`; call `.cancel()` to abort early.
+ */
+export function sleep(ms: number): CancellablePromise<void>;
+/**
+ * Object form: `ms` plus optional `cancelError` (non-empty string or `Error`, `null` to resolve on
+ * cancel, or omitted / `undefined` / `''` for default {@link PromiseCancellationError}). Any non-array
+ * object with a finite `ms` is accepted at runtime (including class instances), matching structural typing.
+ *
+ * @param options - Duration and optional cancellation behavior
+ * @returns A thenable you can `await`; call `.cancel()` to abort early.
+ */
+export function sleep(options: SleepOptions): CancellablePromise<void>;
+export function sleep(arg: SleepArg): CancellablePromise<void> {
+  const {ms, cancelError} = parseSleepArg(arg);
+  let timeoutId: NodeJS.Timeout | undefined;
+  let resolveFn: ((value: void) => void) | undefined;
+  let rejectFn: ((error: Error) => void) | undefined;
+
+  const promise = new Promise<void>((resolve, reject) => {
+    resolveFn = resolve;
+    rejectFn = reject;
+    timeoutId = setTimeout(resolve, ms);
+  }) as CancellablePromise<void>;
+
+  promise.cancel = () => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = undefined;
+    }
+    if (cancelError === null) {
+      resolveFn?.(undefined);
+    } else {
+      let err: Error;
+      if (typeof cancelError === 'string' && cancelError) {
+        err = new PromiseCancellationError(cancelError);
+      } else if (cancelError instanceof Error) {
+        err = cancelError;
+      } else {
+        err = new PromiseCancellationError();
+      }
+      rejectFn?.(err);
+    }
+    resolveFn = undefined;
+    rejectFn = undefined;
+  };
+
+  return promise;
+}
+
+/** Non-array object values (including class instances); excludes `null` and arrays. */
+function isSleepArgObject(value: unknown): value is Record<PropertyKey, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseSleepArg(arg: SleepArg): {ms: number; cancelError?: string | Error | null} {
+  if (typeof arg === 'number') {
+    if (!Number.isFinite(arg)) {
+      throw new TypeError('sleep: expected a finite number or an object with ms');
+    }
+    return {ms: arg};
+  }
+  if (isSleepArgObject(arg)) {
+    const ms = arg.ms;
+    if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+      throw new TypeError('sleep: options.ms must be a finite number');
+    }
+    return {ms, cancelError: arg.cancelError as string | Error | null | undefined};
+  }
+  throw new TypeError('sleep: expected a finite number or an object with ms');
+}

package/node_modules/asyncbox/lib/wait-for-condition.ts

@@ -0,0 +1,52 @@
+import {sleep} from './sleep.js';
+import type {WaitForConditionOptions} from './types.js';
+
+/**
+ * Takes a condition (a function returning a boolean or boolean promise), and
+ * waits until the condition is true.
+ *
+ * Throws a `/Condition unmet/` error if the condition has not been satisfied
+ * within the allocated time, unless an error is provided in the options, as the
+ * `error` property, which is either thrown itself, or used as the message.
+ *
+ * The condition result is returned if it is not falsy. If the condition throws an
+ * error then this exception will be immediately passed through.
+ *
+ * The default options are: `{ waitMs: 5000, intervalMs: 500 }`
+ * @param condFn - The condition function to evaluate
+ * @param options - Options for controlling the wait behavior
+ */
+export async function waitForCondition<T>(
+  condFn: () => Promise<T> | T,
+  options: WaitForConditionOptions = {},
+): Promise<T> {
+  const opts: WaitForConditionOptions & {waitMs: number; intervalMs: number} = {
+    ...options,
+    waitMs: typeof options.waitMs === 'number' ? options.waitMs : 5000,
+    intervalMs: typeof options.intervalMs === 'number' ? options.intervalMs : 500,
+  };
+  const debug = opts.logger ? opts.logger.debug.bind(opts.logger) : () => undefined;
+  const error = opts.error;
+  const begunAt = performance.now();
+  const endAt = begunAt + opts.waitMs;
+  const spin = async function spin(): Promise<T> {
+    const result = await condFn();
+    if (result) {
+      return result;
+    }
+    const now = performance.now();
+    const waited = Math.round(now - begunAt);
+    const remainingTime = endAt - now;
+    if (now < endAt) {
+      debug(`Waited for ${waited} ms so far`);
+      await sleep(Math.min(opts.intervalMs, remainingTime));
+      return await spin();
+    }
+    // if there is an error option, it is either a string message or an error itself
+    if (error) {
+      throw typeof error === 'string' ? new Error(error) : error;
+    }
+    throw new Error(`Condition unmet after ${waited} ms. Timing out.`);
+  };
+  return await spin();
+}

package/node_modules/asyncbox/lib/with-timeout.ts

@@ -0,0 +1,43 @@
+import {TimeoutError} from './errors.js';
+
+/**
+ * Resolves with `promise` or rejects if it does not settle before `timeoutMs`.
+ *
+ * If the deadline passes first: with no third argument (or a falsy non-error value), rejects
+ * with {@link TimeoutError} whose message includes `timeoutMs`; with a non-empty string,
+ * rejects with {@link TimeoutError} using that message; with an `Error` instance, rejects
+ * with that same instance.
+ *
+ * @param promise - Promise to race against the timeout.
+ * @param timeoutMs - Maximum time in milliseconds before rejecting if `promise` has not settled.
+ * @param messageOrError - Optional override for the timeout rejection: custom {@link TimeoutError}
+ * message when the string is non-empty, or an existing `Error` to reject with verbatim.
+ * Omitted, `undefined`, or other falsy non-error values use the default timeout message (includes `timeoutMs`).
+ */
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  messageOrError?: string | Error,
+): Promise<T> {
+  let timer: NodeJS.Timeout | null = null;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          if (typeof messageOrError === 'string' && messageOrError) {
+            reject(new TimeoutError(messageOrError));
+          } else if (!messageOrError) {
+            reject(new TimeoutError(`Operation timed out after ${timeoutMs}ms`));
+          } else {
+            reject(messageOrError);
+          }
+        }, timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}

package/node_modules/asyncbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asyncbox",
-  "version": "6.4.3",
+  "version": "6.5.0",
   "description": "A collection of small async/await utilities",
   "keywords": [
     "async",
@@ -28,18 +28,18 @@
     "build/esm/package.json"
   ],
   "type": "module",
-  "main": "./build/cjs/lib/asyncbox.js",
-  "module": "./build/esm/lib/asyncbox.js",
-  "types": "./build/cjs/lib/asyncbox.d.ts",
+  "main": "./build/cjs/lib/index.js",
+  "module": "./build/esm/lib/index.js",
+  "types": "./build/cjs/lib/index.d.ts",
   "exports": {
     ".": {
       "import": {
-        "types": "./build/esm/lib/asyncbox.d.ts",
-        "default": "./build/esm/lib/asyncbox.js"
+        "types": "./build/esm/lib/index.d.ts",
+        "default": "./build/esm/lib/index.js"
       },
       "require": {
-        "types": "./build/cjs/lib/asyncbox.d.ts",
-        "default": "./build/cjs/lib/asyncbox.js"
+        "types": "./build/cjs/lib/index.d.ts",
+        "default": "./build/cjs/lib/index.js"
       }
     },
     "./package.json": "./package.json"