src/utils/Utils.ts

   1 import { getRandomValues, randomBytes, randomInt, randomUUID } from 'node:crypto';
   2 import { env, nextTick } from 'node:process';
   3
   4 import {
   5   formatDuration,
   6   hoursToMinutes,
   7   hoursToSeconds,
   8   isDate,
   9   millisecondsToHours,
  10   millisecondsToMinutes,
  11   millisecondsToSeconds,
  12   minutesToSeconds,
  13   secondsToMilliseconds,
  14 } from 'date-fns';
  15
  16 import { Constants } from './Constants';
  17 import { type TimestampedData, WebSocketCloseEventStatusString } from '../types';
  18
  19 export const logPrefix = (prefixString = ''): string => {
  20   return `${new Date().toLocaleString()}${prefixString}`;
  21 };
  22
  23 export const generateUUID = (): string => {
  24   return randomUUID();
  25 };
  26
  27 export const validateUUID = (uuid: string): boolean => {
  28   return /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(
  29     uuid,
  30   );
  31 };
  32
  33 export const sleep = async (milliSeconds: number): Promise<NodeJS.Timeout> => {
  34   return new Promise<NodeJS.Timeout>((resolve) => setTimeout(resolve as () => void, milliSeconds));
  35 };
  36
  37 export const formatDurationMilliSeconds = (duration: number): string => {
  38   duration = convertToInt(duration);
  39   if (duration < 0) {
  40     throw new RangeError('Duration cannot be negative');
  41   }
  42   const days = Math.floor(duration / (24 * 3600 * 1000));
  43   const hours = Math.floor(millisecondsToHours(duration) - days * 24);
  44   const minutes = Math.floor(
  45     millisecondsToMinutes(duration) - days * 24 * 60 - hoursToMinutes(hours),
  46   );
  47   const seconds = Math.floor(
  48     millisecondsToSeconds(duration) -
  49       days * 24 * 3600 -
  50       hoursToSeconds(hours) -
  51       minutesToSeconds(minutes),
  52   );
  53   if (days === 0 && hours === 0 && minutes === 0 && seconds === 0) {
  54     return formatDuration({ seconds }, { zero: true });
  55   }
  56   return formatDuration({
  57     days,
  58     hours,
  59     minutes,
  60     seconds,
  61   });
  62 };
  63
  64 export const formatDurationSeconds = (duration: number): string => {
  65   return formatDurationMilliSeconds(secondsToMilliseconds(duration));
  66 };
  67
  68 // More efficient time validation function than the one provided by date-fns
  69 export const isValidTime = (date: unknown): boolean => {
  70   if (typeof date === 'number') {
  71     return !isNaN(date);
  72   } else if (isDate(date)) {
  73     return !isNaN(date.getTime());
  74   }
  75   return false;
  76 };
  77
  78 export const convertToDate = (
  79   value: Date | string | number | null | undefined,
  80 ): Date | null | undefined => {
  81   if (isNullOrUndefined(value)) {
  82     return value as null | undefined;
  83   }
  84   if (isDate(value)) {
  85     return value;
  86   }
  87   if (isString(value) || typeof value === 'number') {
  88     const valueToDate = new Date(value!);
  89     if (isNaN(valueToDate.getTime())) {
  90       throw new Error(`Cannot convert to date: '${value!}'`);
  91     }
  92     return valueToDate;
  93   }
  94 };
  95
  96 export const convertToInt = (value: unknown): number => {
  97   if (!value) {
  98     return 0;
  99   }
 100   let changedValue: number = value as number;
 101   if (Number.isSafeInteger(value)) {
 102     return value as number;
 103   }
 104   if (typeof value === 'number') {
 105     return Math.trunc(value);
 106   }
 107   if (isString(value)) {
 108     changedValue = parseInt(value as string);
 109   }
 110   if (isNaN(changedValue)) {
 111     throw new Error(`Cannot convert to integer: '${String(value)}'`);
 112   }
 113   return changedValue;
 114 };
 115
 116 export const convertToFloat = (value: unknown): number => {
 117   if (!value) {
 118     return 0;
 119   }
 120   let changedValue: number = value as number;
 121   if (isString(value)) {
 122     changedValue = parseFloat(value as string);
 123   }
 124   if (isNaN(changedValue)) {
 125     throw new Error(`Cannot convert to float: '${String(value)}'`);
 126   }
 127   return changedValue;
 128 };
 129
 130 export const convertToBoolean = (value: unknown): boolean => {
 131   let result = false;
 132   if (value != null) {
 133     // Check the type
 134     if (typeof value === 'boolean') {
 135       return value;
 136     } else if (isString(value) && ((value as string).toLowerCase() === 'true' || value === '1')) {
 137       result = true;
 138     } else if (typeof value === 'number' && value === 1) {
 139       result = true;
 140     }
 141   }
 142   return result;
 143 };
 144
 145 export const getRandomFloat = (max = Number.MAX_VALUE, min = 0): number => {
 146   if (max < min) {
 147     throw new RangeError('Invalid interval');
 148   }
 149   if (max - min === Infinity) {
 150     throw new RangeError('Invalid interval');
 151   }
 152   return (randomBytes(4).readUInt32LE() / 0xffffffff) * (max - min) + min;
 153 };
 154
 155 export const getRandomInteger = (max = Constants.MAX_RANDOM_INTEGER, min = 0): number => {
 156   max = Math.floor(max);
 157   if (!isNullOrUndefined(min) && min !== 0) {
 158     min = Math.ceil(min);
 159     return Math.floor(randomInt(min, max + 1));
 160   }
 161   return Math.floor(randomInt(max + 1));
 162 };
 163
 164 /**
 165  * Rounds the given number to the given scale.
 166  * The rounding is done using the "round half away from zero" method.
 167  *
 168  * @param numberValue - The number to round.
 169  * @param scale - The scale to round to.
 170  * @returns The rounded number.
 171  */
 172 export const roundTo = (numberValue: number, scale: number): number => {
 173   const roundPower = Math.pow(10, scale);
 174   return Math.round(numberValue * roundPower * (1 + Number.EPSILON)) / roundPower;
 175 };
 176
 177 export const getRandomFloatRounded = (max = Number.MAX_VALUE, min = 0, scale = 2): number => {
 178   if (min) {
 179     return roundTo(getRandomFloat(max, min), scale);
 180   }
 181   return roundTo(getRandomFloat(max), scale);
 182 };
 183
 184 export const getRandomFloatFluctuatedRounded = (
 185   staticValue: number,
 186   fluctuationPercent: number,
 187   scale = 2,
 188 ): number => {
 189   if (fluctuationPercent < 0 || fluctuationPercent > 100) {
 190     throw new RangeError(
 191       `Fluctuation percent must be between 0 and 100. Actual value: ${fluctuationPercent}`,
 192     );
 193   }
 194   if (fluctuationPercent === 0) {
 195     return roundTo(staticValue, scale);
 196   }
 197   const fluctuationRatio = fluctuationPercent / 100;
 198   return getRandomFloatRounded(
 199     staticValue * (1 + fluctuationRatio),
 200     staticValue * (1 - fluctuationRatio),
 201     scale,
 202   );
 203 };
 204
 205 export const extractTimeSeriesValues = (timeSeries: Array<TimestampedData>): number[] => {
 206   return timeSeries.map((timeSeriesItem) => timeSeriesItem.value);
 207 };
 208
 209 export const isObject = (item: unknown): boolean => {
 210   return (
 211     isNullOrUndefined(item) === false && typeof item === 'object' && Array.isArray(item) === false
 212   );
 213 };
 214
 215 type CloneableData =
 216   | number
 217   | string
 218   | boolean
 219   | null
 220   | undefined
 221   | Date
 222   | CloneableData[]
 223   | { [key: string]: CloneableData };
 224
 225 type FormatKey = (key: string) => string;
 226
 227 const deepClone = <I extends CloneableData, O extends CloneableData = I>(
 228   value: I,
 229   formatKey?: FormatKey,
 230   refs: Map<I, O> = new Map<I, O>(),
 231 ): O => {
 232   const ref = refs.get(value);
 233   if (ref !== undefined) {
 234     return ref;
 235   }
 236   if (Array.isArray(value)) {
 237     const clone: CloneableData[] = [];
 238     refs.set(value, clone as O);
 239     for (let i = 0; i < value.length; i++) {
 240       clone[i] = deepClone(value[i], formatKey, refs);
 241     }
 242     return clone as O;
 243   }
 244   if (value instanceof Date) {
 245     return new Date(value.valueOf()) as O;
 246   }
 247   if (typeof value !== 'object' || value === null) {
 248     return value as unknown as O;
 249   }
 250   const clone: Record<string, CloneableData> = {};
 251   refs.set(value, clone as O);
 252   for (const key of Object.keys(value)) {
 253     clone[typeof formatKey === 'function' ? formatKey(key) : key] = deepClone(
 254       value[key],
 255       formatKey,
 256       refs,
 257     );
 258   }
 259   return clone as O;
 260 };
 261
 262 export const cloneObject = <T>(object: T): T => {
 263   return deepClone(object as CloneableData) as T;
 264 };
 265
 266 export const hasOwnProp = (object: unknown, property: PropertyKey): boolean => {
 267   return isObject(object) && Object.hasOwn(object as object, property);
 268 };
 269
 270 export const isCFEnvironment = (): boolean => {
 271   return !isNullOrUndefined(env.VCAP_APPLICATION);
 272 };
 273
 274 export const isIterable = <T>(obj: T): boolean => {
 275   return !isNullOrUndefined(obj) ? typeof obj[Symbol.iterator as keyof T] === 'function' : false;
 276 };
 277
 278 const isString = (value: unknown): boolean => {
 279   return typeof value === 'string';
 280 };
 281
 282 export const isEmptyString = (value: unknown): boolean => {
 283   return isNullOrUndefined(value) || (isString(value) && (value as string).trim().length === 0);
 284 };
 285
 286 export const isNotEmptyString = (value: unknown): boolean => {
 287   return isString(value) && (value as string).trim().length > 0;
 288 };
 289
 290 export const isUndefined = (value: unknown): boolean => {
 291   return value === undefined;
 292 };
 293
 294 export const isNullOrUndefined = (value: unknown): boolean => {
 295   return value == null;
 296 };
 297
 298 export const isEmptyArray = (object: unknown): boolean => {
 299   return Array.isArray(object) && object.length === 0;
 300 };
 301
 302 export const isNotEmptyArray = (object: unknown): boolean => {
 303   return Array.isArray(object) && object.length > 0;
 304 };
 305
 306 export const isEmptyObject = (obj: object): boolean => {
 307   if (obj?.constructor !== Object) {
 308     return false;
 309   }
 310   // Iterates over the keys of an object, if
 311   // any exist, return false.
 312   for (const _ in obj) {
 313     return false;
 314   }
 315   return true;
 316 };
 317
 318 export const insertAt = (str: string, subStr: string, pos: number): string =>
 319   `${str.slice(0, pos)}${subStr}${str.slice(pos)}`;
 320
 321 /**
 322  * Computes the retry delay in milliseconds using an exponential backoff algorithm.
 323  *
 324  * @param retryNumber - the number of retries that have already been attempted
 325  * @param delayFactor - the base delay factor in milliseconds
 326  * @returns delay in milliseconds
 327  */
 328 export const exponentialDelay = (retryNumber = 0, delayFactor = 100): number => {
 329   const delay = Math.pow(2, retryNumber) * delayFactor;
 330   const randomSum = delay * 0.2 * secureRandom(); // 0-20% of the delay
 331   return delay + randomSum;
 332 };
 333
 334 /**
 335  * Generates a cryptographically secure random number in the [0,1[ range
 336  *
 337  * @returns A number in the [0,1[ range
 338  */
 339 export const secureRandom = (): number => {
 340   return getRandomValues(new Uint32Array(1))[0] / 0x100000000;
 341 };
 342
 343 export const JSONStringifyWithMapSupport = (
 344   obj: Record<string, unknown> | Record<string, unknown>[] | Map<unknown, unknown>,
 345   space?: number,
 346 ): string => {
 347   return JSON.stringify(
 348     obj,
 349     (_, value: Record<string, unknown>) => {
 350       if (value instanceof Map) {
 351         return {
 352           dataType: 'Map',
 353           value: [...value],
 354         };
 355       }
 356       return value;
 357     },
 358     space,
 359   );
 360 };
 361
 362 /**
 363  * Converts websocket error code to human readable string message
 364  *
 365  * @param code - websocket error code
 366  * @returns human readable string message
 367  */
 368 export const getWebSocketCloseEventStatusString = (code: number): string => {
 369   if (code >= 0 && code <= 999) {
 370     return '(Unused)';
 371   } else if (code >= 1016) {
 372     if (code <= 1999) {
 373       return '(For WebSocket standard)';
 374     } else if (code <= 2999) {
 375       return '(For WebSocket extensions)';
 376     } else if (code <= 3999) {
 377       return '(For libraries and frameworks)';
 378     } else if (code <= 4999) {
 379       return '(For applications)';
 380     }
 381   }
 382   if (
 383     !isUndefined(
 384       WebSocketCloseEventStatusString[code as keyof typeof WebSocketCloseEventStatusString],
 385     )
 386   ) {
 387     return WebSocketCloseEventStatusString[code as keyof typeof WebSocketCloseEventStatusString];
 388   }
 389   return '(Unknown)';
 390 };
 391
 392 export const isArraySorted = <T>(array: T[], compareFn: (a: T, b: T) => number): boolean => {
 393   for (let index = 0; index < array.length - 1; ++index) {
 394     if (compareFn(array[index], array[index + 1]) > 0) {
 395       return false;
 396     }
 397   }
 398   return true;
 399 };
 400
 401 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 402 export const once = <T, A extends any[], R>(
 403   fn: (...args: A) => R,
 404   context: T,
 405 ): ((...args: A) => R) => {
 406   let result: R;
 407   return (...args: A) => {
 408     if (fn) {
 409       result = fn.apply<T, A, R>(context, args);
 410       (fn as unknown as undefined) = (context as unknown as undefined) = undefined;
 411     }
 412     return result;
 413   };
 414 };
 415
 416 export const min = (...args: number[]): number =>
 417   args.reduce((minimum, num) => (minimum < num ? minimum : num), Infinity);
 418
 419 export const max = (...args: number[]): number =>
 420   args.reduce((maximum, num) => (maximum > num ? maximum : num), -Infinity);
 421
 422 export const throwErrorInNextTick = (error: Error): void => {
 423   nextTick(() => {
 424     throw error;
 425   });
 426 };