src/utils.ts

   1 import * as os from 'node:os'
   2 import type {
   3   MeasurementStatisticsRequirements,
   4   WorkerChoiceStrategyOptions
   5 } from './pools/selection-strategies/selection-strategies-types'
   6 import type { KillBehavior } from './worker/worker-options'
   7 import type { MeasurementStatistics } from './pools/worker'
   8
   9 /**
  10  * Default task name.
  11  */
  12 export const DEFAULT_TASK_NAME = 'default'
  13
  14 /**
  15  * An intentional empty function.
  16  */
  17 export const EMPTY_FUNCTION: () => void = Object.freeze(() => {
  18   /* Intentionally empty */
  19 })
  20
  21 /**
  22  * Default worker choice strategy options.
  23  */
  24 export const DEFAULT_WORKER_CHOICE_STRATEGY_OPTIONS: WorkerChoiceStrategyOptions =
  25   {
  26     choiceRetries: 6,
  27     runTime: { median: false },
  28     waitTime: { median: false },
  29     elu: { median: false }
  30   }
  31
  32 /**
  33  * Default measurement statistics requirements.
  34  */
  35 export const DEFAULT_MEASUREMENT_STATISTICS_REQUIREMENTS: MeasurementStatisticsRequirements =
  36   {
  37     aggregate: false,
  38     average: false,
  39     median: false
  40   }
  41
  42 /**
  43  * Returns safe host OS optimized estimate of the default amount of parallelism a pool should use.
  44  * Always returns a value greater than zero.
  45  *
  46  * @returns The host OS optimized maximum pool size.
  47  * @internal
  48  */
  49 export const availableParallelism = (): number => {
  50   let availableParallelism = 1
  51   try {
  52     availableParallelism = os.availableParallelism()
  53   } catch {
  54     const numberOfCpus = os.cpus()
  55     if (Array.isArray(numberOfCpus) && numberOfCpus.length > 0) {
  56       availableParallelism = numberOfCpus.length
  57     }
  58   }
  59   return availableParallelism
  60 }
  61
  62 // /**
  63 //  * Computes the retry delay in milliseconds using an exponential back off algorithm.
  64 //  *
  65 //  * @param retryNumber - The number of retries that have already been attempted
  66 //  * @param maxDelayRatio - The maximum ratio of the delay that can be randomized
  67 //  * @returns Delay in milliseconds
  68 //  * @internal
  69 //  */
  70 // export const exponentialDelay = (
  71 //   retryNumber = 0,
  72 //   maxDelayRatio = 0.2
  73 // ): number => {
  74 //   const delay = Math.pow(2, retryNumber) * 100
  75 //   const randomSum = delay * maxDelayRatio * Math.random() // 0-(maxDelayRatio*100)% of the delay
  76 //   return delay + randomSum
  77 // }
  78
  79 /**
  80  * Computes the average of the given data set.
  81  *
  82  * @param dataSet - Data set.
  83  * @returns The average of the given data set.
  84  * @internal
  85  */
  86 export const average = (dataSet: number[]): number => {
  87   if (Array.isArray(dataSet) && dataSet.length === 0) {
  88     return 0
  89   }
  90   if (Array.isArray(dataSet) && dataSet.length === 1) {
  91     return dataSet[0]
  92   }
  93   return (
  94     dataSet.reduce((accumulator, number) => accumulator + number, 0) /
  95     dataSet.length
  96   )
  97 }
  98
  99 /**
 100  * Computes the median of the given data set.
 101  *
 102  * @param dataSet - Data set.
 103  * @returns The median of the given data set.
 104  * @internal
 105  */
 106 export const median = (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   const sortedDataSet = dataSet.slice().sort((a, b) => a - b)
 114   return (
 115     (sortedDataSet[(sortedDataSet.length - 1) >> 1] +
 116       sortedDataSet[sortedDataSet.length >> 1]) /
 117     2
 118   )
 119 }
 120
 121 /**
 122  * Rounds the given number to the given scale.
 123  * The rounding is done using the "round half away from zero" method.
 124  *
 125  * @param num - The number to round.
 126  * @param scale - The scale to round to.
 127  * @returns The rounded number.
 128  */
 129 export const round = (num: number, scale = 2): number => {
 130   const rounder = Math.pow(10, scale)
 131   return Math.round(num * rounder * (1 + Number.EPSILON)) / rounder
 132 }
 133
 134 /**
 135  * Is the given object a plain object?
 136  *
 137  * @param obj - The object to check.
 138  * @returns `true` if the given object is a plain object, `false` otherwise.
 139  */
 140 export const isPlainObject = (obj: unknown): boolean =>
 141   typeof obj === 'object' &&
 142   obj !== null &&
 143   obj?.constructor === Object &&
 144   Object.prototype.toString.call(obj) === '[object Object]'
 145
 146 /**
 147  * Detects whether the given value is a kill behavior or not.
 148  *
 149  * @typeParam KB - Which specific KillBehavior type to test against.
 150  * @param killBehavior - Which kind of kill behavior to detect.
 151  * @param value - Any value.
 152  * @returns `true` if `value` was strictly equals to `killBehavior`, otherwise `false`.
 153  * @internal
 154  */
 155 export const isKillBehavior = <KB extends KillBehavior>(
 156   killBehavior: KB,
 157   value: unknown
 158 ): value is KB => {
 159   return value === killBehavior
 160 }
 161
 162 /**
 163  * Detects whether the given value is an asynchronous function or not.
 164  *
 165  * @param fn - Any value.
 166  * @returns `true` if `fn` was an asynchronous function, otherwise `false`.
 167  */
 168 export const isAsyncFunction = (
 169   fn: unknown
 170 ): fn is (...args: unknown[]) => Promise<unknown> => {
 171   return typeof fn === 'function' && fn.constructor.name === 'AsyncFunction'
 172 }
 173
 174 /**
 175  * Updates the given measurement statistics.
 176  *
 177  * @param measurementStatistics - The measurement statistics to update.
 178  * @param measurementRequirements - The measurement statistics requirements.
 179  * @param measurementValue - The measurement value.
 180  * @param numberOfMeasurements - The number of measurements.
 181  * @internal
 182  */
 183 export const updateMeasurementStatistics = (
 184   measurementStatistics: MeasurementStatistics,
 185   measurementRequirements: MeasurementStatisticsRequirements,
 186   measurementValue: number
 187 ): void => {
 188   if (measurementRequirements.aggregate) {
 189     measurementStatistics.aggregate =
 190       (measurementStatistics.aggregate ?? 0) + measurementValue
 191     measurementStatistics.minimum = Math.min(
 192       measurementValue,
 193       measurementStatistics.minimum ?? Infinity
 194     )
 195     measurementStatistics.maximum = Math.max(
 196       measurementValue,
 197       measurementStatistics.maximum ?? -Infinity
 198     )
 199     if (
 200       (measurementRequirements.average || measurementRequirements.median) &&
 201       measurementValue != null
 202     ) {
 203       measurementStatistics.history.push(measurementValue)
 204       if (measurementRequirements.average) {
 205         measurementStatistics.average = average(measurementStatistics.history)
 206       }
 207       if (measurementRequirements.median) {
 208         measurementStatistics.median = median(measurementStatistics.history)
 209       }
 210     }
 211   }
 212 }
 213
 214 /**
 215  * Executes a function once at a time.
 216  *
 217  * @param fn - The function to execute.
 218  * @param context - The context to bind the function to.
 219  * @returns The function to execute.
 220  */
 221 export const once = (
 222   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 223   fn: (...args: any[]) => void,
 224   context: unknown
 225   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 226 ): ((...args: any[]) => void) => {
 227   let called = false
 228   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 229   return function (...args: any[]): void {
 230     if (!called) {
 231       called = true
 232       fn.apply(context, args)
 233       called = false
 234     }
 235   }
 236 }