@appium/support 7.1.0 → 7.2.0

package/lib/util.ts

@@ -1,9 +1,9 @@
 import B from 'bluebird';
-import _ from 'lodash';
+import {randomUUID} from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import stream from 'node:stream';
-import {promisify} from 'node:util';
+import {isDeepStrictEqual, promisify} from 'node:util';
 import {asyncmap} from 'asyncbox';
 import {fs} from './fs';
 import * as semver from 'semver';
@@ -11,7 +11,7 @@ import {quote as shellQuote, parse as shellParse} from 'shell-quote';
 export {shellParse};
 import pluralizeLib from 'pluralize';
 import {Base64Encode} from 'base64-stream';
-export {v1 as uuidV1, v3 as uuidV3, v4 as uuidV4, v5 as uuidV5} from 'uuid';
+import {v1 as uuidV1Lib, v3 as uuidV3Lib, v5 as uuidV5Lib} from 'uuid';
 import * as _lockfile from 'lockfile';
 import type {Element} from '@appium/types';
 
@@ -28,6 +28,36 @@ export const GiB = MiB * 1024;
 /** A string which is never `''`. */
 export type NonEmptyString<T extends string = string> = T extends '' ? never : T;
 
+/**
+ * @deprecated This helper is slated for removal. Please migrate callers away from UUID v1.
+ */
+export function uuidV1(...args: Parameters<typeof uuidV1Lib>): ReturnType<typeof uuidV1Lib> {
+  return uuidV1Lib(...args);
+}
+
+/**
+ * @deprecated This helper is slated for removal. Please migrate callers away from UUID v3.
+ */
+export function uuidV3(...args: Parameters<typeof uuidV3Lib>): ReturnType<typeof uuidV3Lib> {
+  return uuidV3Lib(...args);
+}
+
+/**
+ * Generates a v4 UUID using Node.js crypto.
+ *
+ * @returns A UUID v4 string
+ */
+export function uuidV4(): string {
+  return randomUUID();
+}
+
+/**
+ * @deprecated This helper is slated for removal. Please migrate callers away from UUID v5.
+ */
+export function uuidV5(...args: Parameters<typeof uuidV5Lib>): ReturnType<typeof uuidV5Lib> {
+  return uuidV5Lib(...args);
+}
+
 /**
  * Type guard: returns true if the value is a non-empty string.
  *
@@ -35,7 +65,7 @@ export type NonEmptyString<T extends string = string> = T extends '' ? never : T
  * @returns `true` if `val` is a string with at least one character
  */
 export function hasContent(val: unknown): val is NonEmptyString {
-  return _.isString(val) && val !== '';
+  return typeof val === 'string' && val !== '';
 }
 
 /**
@@ -45,10 +75,124 @@ export function hasContent(val: unknown): val is NonEmptyString {
  * @returns `true` if `val` is non-null and non-undefined (and not NaN for numbers)
  */
 export function hasValue<T>(val: T): val is NonNullable<T> {
-  if (_.isNumber(val)) {
-    return !_.isNaN(val);
+  if (typeof val === 'number') {
+    return !Number.isNaN(val);
   }
-  return !_.isUndefined(val) && !_.isNull(val);
+  return val !== undefined && val !== null;
+}
+
+/**
+ * Creates a memoized version of a function.
+ *
+ * @param fn - Function to memoize
+ * @param resolver - Optional cache key resolver. If omitted, the first argument is used as the cache key.
+ * @returns Memoized function with a mutable `.cache` map (compatible with lodash-style cache resets in tests).
+ */
+export function memoize<Fn extends (...args: any[]) => any>(
+  fn: Fn,
+  resolver?: (...args: Parameters<Fn>) => unknown
+): Fn & {cache: Map<unknown, ReturnType<Fn>>} {
+  const memoizedFn = (function (this: unknown, ...args: Parameters<Fn>) {
+    const key = resolver ? resolver.apply(this, args) : args[0];
+    if (memoizedFn.cache.has(key)) {
+      return memoizedFn.cache.get(key) as ReturnType<Fn>;
+    }
+    const result = fn.apply(this, args);
+    memoizedFn.cache.set(key, result);
+    return result;
+  }) as unknown as Fn & {cache: Map<unknown, ReturnType<Fn>>};
+  memoizedFn.cache = new Map<unknown, ReturnType<Fn>>();
+  return memoizedFn;
+}
+
+/**
+ * Returns true if the value is a plain object (Object prototype or null prototype).
+ *
+ * @param value - Value to check
+ * @returns `true` if the value is a plain object
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype;
+}
+
+/**
+ * Returns true when the value has no elements/properties.
+ *
+ * @param value - Value to check
+ * @returns `true` if the value is empty
+ */
+export function isEmpty(value: unknown): boolean {
+  if (value == null) {
+    return true;
+  }
+  if (typeof value === 'string' || Array.isArray(value) || Buffer.isBuffer(value)) {
+    return value.length === 0;
+  }
+  if (value instanceof Map || value instanceof Set) {
+    return value.size === 0;
+  }
+  if (typeof value === 'object' || typeof value === 'function') {
+    return Object.keys(value).length === 0;
+  }
+  return true;
+}
+
+/**
+ * Performs a deep equality check between two values.
+ *
+ * @param left - First value
+ * @param right - Second value
+ * @returns `true` when values are deeply equal
+ */
+export function isEqual(left: unknown, right: unknown): boolean {
+  return isDeepStrictEqual(left, right);
+}
+
+/**
+ * Escapes RegExp special characters in a string.
+ *
+ * @param value - Input string
+ * @returns Escaped string safe for RegExp source
+ */
+export function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Returns a duplicate-free copy of the input array.
+ *
+ * @param values - Input array
+ * @returns New array with unique values preserving input order
+ */
+export function uniq<T>(values: readonly T[]): T[] {
+  return [...new Set(values)];
+}
+
+/**
+ * Truncates a string to a maximum length.
+ *
+ * @param value - Input string
+ * @param options - Truncation options or max length
+ * @returns Truncated string
+ */
+export function truncateString(value: string, options: TruncateStringOptions | number = {}): string {
+  const normalizedOptions = typeof options === 'number' ? {length: options} : options;
+  const {length, omission = '…'} = normalizedOptions;
+  const stringValue =
+    value == null ? '' : typeof value === 'number' && Object.is(value, -0) ? '-0' : String(value);
+  const maxLength = length ?? 30;
+  if (maxLength <= 0) {
+    return omission;
+  }
+  if (stringValue.length <= maxLength) {
+    return stringValue;
+  }
+  const contentLength = maxLength - omission.length;
+  return contentLength > 0 ? `${stringValue.slice(0, contentLength)}${omission}` : omission;
 }
 
 /**
@@ -177,7 +321,7 @@ export function jsonStringify(
   replacer: ((key: string, value: unknown) => unknown) | null = null,
   space: number | string = 2
 ): string {
-  const replacerFunc = _.isFunction(replacer) ? replacer : (_k: string, v: unknown) => v;
+  const replacerFunc = typeof replacer === 'function' ? replacer : (_k: string, v: unknown) => v;
 
   const bufferToJSON = Buffer.prototype.toJSON;
   delete (Buffer.prototype as Record<string, unknown>).toJSON;
@@ -204,7 +348,7 @@ export function jsonStringify(
 export function unwrapElement(el: Element | string): string {
   const elObj = el as unknown as Record<string, string>;
   for (const propName of [W3C_WEB_ELEMENT_IDENTIFIER, 'ELEMENT']) {
-    if (_.has(elObj, propName)) {
+    if (Object.hasOwn(elObj, propName)) {
       return elObj[propName];
     }
   }
@@ -238,11 +382,11 @@ export function filterObject<T extends Record<string, unknown>>(
   obj: T,
   predicate?: ((value: unknown, obj: T) => boolean) | unknown
 ): Partial<T> {
-  const newObj = _.clone(obj) as Record<string, unknown>;
+  const newObj = {...obj} as Record<string, unknown>;
   let pred: (v: unknown, o: T) => boolean;
-  if (_.isUndefined(predicate)) {
-    pred = (v) => !_.isUndefined(v);
-  } else if (!_.isFunction(predicate)) {
+  if (predicate === undefined) {
+    pred = (v) => v !== undefined;
+  } else if (typeof predicate !== 'function') {
     const valuePredicate = predicate;
     pred = (v) => v === valuePredicate;
   } else {
@@ -354,6 +498,40 @@ export function coerceVersion(ver: string, strict = true): string | null {
 
 const SUPPORTED_OPERATORS = ['==', '!=', '>', '<', '>=', '<=', '='];
 
+/** Options for pluralize(). */
+export interface PluralizeOptions {
+  /** If true, prefix the result with the count (e.g. "3 ducks"). */
+  inclusive?: boolean;
+}
+
+/** Options for toInMemoryBase64(). */
+export interface EncodingOptions {
+  /** Maximum size of the resulting buffer in bytes. Default 1GB. */
+  maxSize?: number;
+}
+
+/** Options for getLockFileGuard(). */
+export interface LockFileOptions {
+  /** Max time in seconds to wait for the lock. Default 120. */
+  timeout?: number;
+  /** If true, attempt to unlock and retry once if the first acquisition times out (e.g. stale lock). */
+  tryRecovery?: boolean;
+}
+
+/** Options for truncateString(). */
+export interface TruncateStringOptions {
+  /** Maximum length of the resulting string. Default 30. */
+  length?: number;
+  /** Suffix appended to truncated strings. Default "…". */
+  omission?: string;
+}
+
+/** Guard function that runs the given behavior under the lock. */
+type LockFileGuardFn<T> = (behavior: () => Promise<T> | T) => Promise<T>;
+
+/** Return type of getLockFileGuard: guard function with a .check() method. */
+type LockFileGuard<T> = LockFileGuardFn<T> & {check: () => Promise<boolean>};
+
 /**
  * Compares two version strings using the given operator.
  *
@@ -389,13 +567,7 @@ export function compareVersions(
  * @returns Quoted string suitable for shell parsing
  */
 export function quote(args: string | string[]): string {
-  return shellQuote(_.castArray(args));
-}
-
-/** Options for pluralize(). */
-export interface PluralizeOptions {
-  /** If true, prefix the result with the count (e.g. "3 ducks"). */
-  inclusive?: boolean;
+  return shellQuote(Array.isArray(args) ? args : [args]);
 }
 
 /**
@@ -412,20 +584,14 @@ export function pluralize(
   options: PluralizeOptions | boolean = {}
 ): string {
   let inclusive = false;
-  if (_.isBoolean(options)) {
+  if (typeof options === 'boolean') {
     inclusive = options;
-  } else if (_.isBoolean(options?.inclusive)) {
+  } else if (typeof options?.inclusive === 'boolean') {
     inclusive = options.inclusive;
   }
   return pluralizeLib(word, count, inclusive);
 }
 
-/** Options for toInMemoryBase64(). */
-export interface EncodingOptions {
-  /** Maximum size of the resulting buffer in bytes. Default 1GB. */
-  maxSize?: number;
-}
-
 /**
  * Reads a file and returns its contents as a base64-encoded buffer.
  *
@@ -487,20 +653,6 @@ export async function toInMemoryBase64(
   return Buffer.concat(resultBuffers);
 }
 
-/** Options for getLockFileGuard(). */
-export interface LockFileOptions {
-  /** Max time in seconds to wait for the lock. Default 120. */
-  timeout?: number;
-  /** If true, attempt to unlock and retry once if the first acquisition times out (e.g. stale lock). */
-  tryRecovery?: boolean;
-}
-
-/** Guard function that runs the given behavior under the lock. */
-type LockFileGuardFn<T> = (behavior: () => Promise<T> | T) => Promise<T>;
-
-/** Return type of getLockFileGuard: guard function with a .check() method. */
-type LockFileGuard<T> = LockFileGuardFn<T> & {check: () => Promise<boolean>};
-
 /**
  * Creates a guard that serializes access to a critical section using a lock file.
  * The returned function acquires the lock, runs the given behavior, then releases the lock.
@@ -537,13 +689,14 @@ export function getLockFileGuard<T>(
           acquired = true;
         } catch (e) {
           const err = e as Error;
-          if (_.includes(err.message, 'EEXIST') && tryRecovery && !triedRecovery) {
+          if (err.message?.includes('EEXIST') && tryRecovery && !triedRecovery) {
             _lockfile.unlockSync(lockFile);
             triedRecovery = true;
           } else {
             throw new Error(
               `Could not acquire lock on '${lockFile}' after ${timeout}s. ` +
-                `Original error: ${err.message}`
+                `Original error: ${err.message}`,
+              {cause: e}
             );
           }
         }