src/utils.ts

   1 import * as os from 'node:os'
   2 import { webcrypto } from 'node:crypto'
   3 import { Worker as ClusterWorker } from 'node:cluster'
   4 import { Worker as ThreadWorker } from 'node:worker_threads'
   5 import type {
   6   MeasurementStatisticsRequirements,
   7   WorkerChoiceStrategyOptions
   8 } from './pools/selection-strategies/selection-strategies-types'
   9 import type { KillBehavior } from './worker/worker-options'
  10 import {
  11   type IWorker,
  12   type MeasurementStatistics,
  13   type WorkerType,
  14   WorkerTypes
  15 } from './pools/worker'
  16
  17 /**
  18  * Default task name.
  19  */
  20 export const DEFAULT_TASK_NAME = 'default'
  21
  22 /**
  23  * An intentional empty function.
  24  */
  25 export const EMPTY_FUNCTION: () => void = Object.freeze(() => {
  26   /* Intentionally empty */
  27 })
  28
  29 /**
  30  * Default worker choice strategy options.
  31  */
  32 export const DEFAULT_WORKER_CHOICE_STRATEGY_OPTIONS: WorkerChoiceStrategyOptions =
  33   {
  34     retries: 6,
  35     runTime: { median: false },
  36     waitTime: { median: false },
  37     elu: { median: false }
  38   }
  39
  40 /**
  41  * Default measurement statistics requirements.
  42  */
  43 export const DEFAULT_MEASUREMENT_STATISTICS_REQUIREMENTS: MeasurementStatisticsRequirements =
  44   {
  45     aggregate: false,
  46     average: false,
  47     median: false
  48   }
  49
  50 /**
  51  * Returns safe host OS optimized estimate of the default amount of parallelism a pool should use.
  52  * Always returns a value greater than zero.
  53  *
  54  * @returns The host OS optimized maximum pool size.
  55  * @internal
  56  */
  57 export const availableParallelism = (): number => {
  58   let availableParallelism = 1
  59   try {
  60     availableParallelism = os.availableParallelism()
  61   } catch {
  62     const numberOfCpus = os.cpus()
  63     if (Array.isArray(numberOfCpus) && numberOfCpus.length > 0) {
  64       availableParallelism = numberOfCpus.length
  65     }
  66   }
  67   return availableParallelism
  68 }
  69
  70 /**
  71  * Sleeps for the given amount of milliseconds.
  72  *
  73  * @param ms - The amount of milliseconds to sleep.
  74  * @returns A promise that resolves after the given amount of milliseconds.
  75  */
  76 export const sleep = async (ms: number): Promise<void> => {
  77   await new Promise((resolve) => {
  78     setTimeout(resolve, ms)
  79   })
  80 }
  81
  82 /**
  83  * Computes the retry delay in milliseconds using an exponential back off algorithm.
  84  *
  85  * @param retryNumber - The number of retries that have already been attempted
  86  * @param delayFactor - The base delay factor in milliseconds
  87  * @returns Delay in milliseconds
  88  * @internal
  89  */
  90 export const exponentialDelay = (
  91   retryNumber = 0,
  92   delayFactor = 100
  93 ): number => {
  94   const delay = Math.pow(2, retryNumber) * delayFactor
  95   const randomSum = delay * 0.2 * secureRandom() // 0-20% of the delay
  96   return delay + randomSum
  97 }
  98
  99 /**
 100  * Computes the average of the given data set.
 101  *
 102  * @param dataSet - Data set.
 103  * @returns The average of the given data set.
 104  * @internal
 105  */
 106 export const average = (dataSet: number[]): number => {
 107   if (Array.isArray(dataSet) && dataSet.length === 0) {
 108     return 0
 109   }
 110   if (Array.isArray(dataSet) && dataSet.length === 1) {
 111     return dataSet[0]
 112   }
 113   return (
 114     dataSet.reduce((accumulator, number) => accumulator + number, 0) /
 115     dataSet.length
 116   )
 117 }
 118
 119 /**
 120  * Returns the worker type of the given worker.
 121  *
 122  * @param worker - The worker to get the type of.
 123  * @returns The worker type of the given worker.
 124  * @internal
 125  */
 126 export const getWorkerType = <Worker extends IWorker>(
 127   worker: Worker
 128 ): WorkerType | undefined => {
 129   if (worker instanceof ThreadWorker) {
 130     return WorkerTypes.thread
 131   }
 132   if (worker instanceof ClusterWorker) {
 133     return WorkerTypes.cluster
 134   }
 135 }
 136
 137 /**
 138  * Returns the worker id of the given worker.
 139  *
 140  * @param worker - The worker to get the id of.
 141  * @returns The worker id of the given worker.
 142  * @internal
 143  */
 144 export const getWorkerId = <Worker extends IWorker>(
 145   worker: Worker
 146 ): number | undefined => {
 147   if (worker instanceof ThreadWorker) {
 148     return worker.threadId
 149   } else if (worker instanceof ClusterWorker) {
 150     return worker.id
 151   }
 152 }
 153
 154 /**
 155  * Computes the median of the given data set.
 156  *
 157  * @param dataSet - Data set.
 158  * @returns The median of the given data set.
 159  * @internal
 160  */
 161 export const median = (dataSet: number[]): number => {
 162   if (Array.isArray(dataSet) && dataSet.length === 0) {
 163     return 0
 164   }
 165   if (Array.isArray(dataSet) && dataSet.length === 1) {
 166     return dataSet[0]
 167   }
 168   const sortedDataSet = dataSet.slice().sort((a, b) => a - b)
 169   return (
 170     (sortedDataSet[(sortedDataSet.length - 1) >> 1] +
 171       sortedDataSet[sortedDataSet.length >> 1]) /
 172     2
 173   )
 174 }
 175
 176 /**
 177  * Rounds the given number to the given scale.
 178  * The rounding is done using the "round half away from zero" method.
 179  *
 180  * @param num - The number to round.
 181  * @param scale - The scale to round to.
 182  * @returns The rounded number.
 183  */
 184 export const round = (num: number, scale = 2): number => {
 185   const rounder = Math.pow(10, scale)
 186   return Math.round(num * rounder * (1 + Number.EPSILON)) / rounder
 187 }
 188
 189 /**
 190  * Is the given object a plain object?
 191  *
 192  * @param obj - The object to check.
 193  * @returns `true` if the given object is a plain object, `false` otherwise.
 194  */
 195 export const isPlainObject = (obj: unknown): boolean =>
 196   typeof obj === 'object' &&
 197   obj !== null &&
 198   obj?.constructor === Object &&
 199   Object.prototype.toString.call(obj) === '[object Object]'
 200
 201 /**
 202  * Detects whether the given value is a kill behavior or not.
 203  *
 204  * @typeParam KB - Which specific KillBehavior type to test against.
 205  * @param killBehavior - Which kind of kill behavior to detect.
 206  * @param value - Any value.
 207  * @returns `true` if `value` was strictly equals to `killBehavior`, otherwise `false`.
 208  * @internal
 209  */
 210 export const isKillBehavior = <KB extends KillBehavior>(
 211   killBehavior: KB,
 212   value: unknown
 213 ): value is KB => {
 214   return value === killBehavior
 215 }
 216
 217 /**
 218  * Detects whether the given value is an asynchronous function or not.
 219  *
 220  * @param fn - Any value.
 221  * @returns `true` if `fn` was an asynchronous function, otherwise `false`.
 222  */
 223 export const isAsyncFunction = (
 224   fn: unknown
 225 ): fn is (...args: unknown[]) => Promise<unknown> => {
 226   return typeof fn === 'function' && fn.constructor.name === 'AsyncFunction'
 227 }
 228
 229 /**
 230  * Updates the given measurement statistics.
 231  *
 232  * @param measurementStatistics - The measurement statistics to update.
 233  * @param measurementRequirements - The measurement statistics requirements.
 234  * @param measurementValue - The measurement value.
 235  * @param numberOfMeasurements - The number of measurements.
 236  * @internal
 237  */
 238 export const updateMeasurementStatistics = (
 239   measurementStatistics: MeasurementStatistics,
 240   measurementRequirements: MeasurementStatisticsRequirements,
 241   measurementValue: number
 242 ): void => {
 243   if (measurementRequirements.aggregate) {
 244     measurementStatistics.aggregate =
 245       (measurementStatistics.aggregate ?? 0) + measurementValue
 246     measurementStatistics.minimum = Math.min(
 247       measurementValue,
 248       measurementStatistics.minimum ?? Infinity
 249     )
 250     measurementStatistics.maximum = Math.max(
 251       measurementValue,
 252       measurementStatistics.maximum ?? -Infinity
 253     )
 254     if (
 255       (measurementRequirements.average || measurementRequirements.median) &&
 256       measurementValue != null
 257     ) {
 258       measurementStatistics.history.push(measurementValue)
 259       if (measurementRequirements.average) {
 260         measurementStatistics.average = average(measurementStatistics.history)
 261       }
 262       if (measurementRequirements.median) {
 263         measurementStatistics.median = median(measurementStatistics.history)
 264       }
 265     }
 266   }
 267 }
 268
 269 /**
 270  * Executes a function once at a time.
 271  *
 272  * @param fn - The function to execute.
 273  * @param context - The context to bind the function to.
 274  * @returns The function to execute.
 275  */
 276 export const once = (
 277   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 278   fn: (...args: any[]) => void,
 279   context: unknown
 280   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 281 ): ((...args: any[]) => void) => {
 282   let called = false
 283   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 284   return function (...args: any[]): void {
 285     if (!called) {
 286       called = true
 287       fn.apply(context, args)
 288       called = false
 289     }
 290   }
 291 }
 292
 293 /**
 294  * Generate a cryptographically secure random number in the [0,1[ range
 295  *
 296  * @returns A number in the [0,1[ range
 297  */
 298 export const secureRandom = (): number => {
 299   return webcrypto.getRandomValues(new Uint32Array(1))[0] / 0x100000000
 300 }