docs: generate documentation
[poolifier.git] / 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 */
56 export const availableParallelism = (): number => {
57 let availableParallelism = 1
58 try {
59 availableParallelism = os.availableParallelism()
60 } catch {
61 const cpus = os.cpus()
62 if (Array.isArray(cpus) && cpus.length > 0) {
63 availableParallelism = cpus.length
64 }
65 }
66 return availableParallelism
67 }
68
69 /**
70 * Returns the worker type of the given worker.
71 *
72 * @param worker - The worker to get the type of.
73 * @returns The worker type of the given worker.
74 * @internal
75 */
76 export const getWorkerType = (worker: IWorker): WorkerType | undefined => {
77 if (worker instanceof ThreadWorker) {
78 return WorkerTypes.thread
79 } else if (worker instanceof ClusterWorker) {
80 return WorkerTypes.cluster
81 }
82 }
83
84 /**
85 * Returns the worker id of the given worker.
86 *
87 * @param worker - The worker to get the id of.
88 * @returns The worker id of the given worker.
89 * @internal
90 */
91 export const getWorkerId = (worker: IWorker): number | undefined => {
92 if (worker instanceof ThreadWorker) {
93 return worker.threadId
94 } else if (worker instanceof ClusterWorker) {
95 return worker.id
96 }
97 }
98
99 /**
100 * Sleeps for the given amount of milliseconds.
101 *
102 * @param ms - The amount of milliseconds to sleep.
103 * @returns A promise that resolves after the given amount of milliseconds.
104 * @internal
105 */
106 export const sleep = async (ms: number): Promise<void> => {
107 await new Promise((resolve) => {
108 setTimeout(resolve, ms)
109 })
110 }
111
112 /**
113 * Computes the retry delay in milliseconds using an exponential back off algorithm.
114 *
115 * @param retryNumber - The number of retries that have already been attempted
116 * @param delayFactor - The base delay factor in milliseconds
117 * @returns Delay in milliseconds
118 * @internal
119 */
120 export const exponentialDelay = (
121 retryNumber = 0,
122 delayFactor = 100
123 ): number => {
124 const delay = Math.pow(2, retryNumber) * delayFactor
125 const randomSum = delay * 0.2 * secureRandom() // 0-20% of the delay
126 return delay + randomSum
127 }
128
129 /**
130 * Computes the average of the given data set.
131 *
132 * @param dataSet - Data set.
133 * @returns The average of the given data set.
134 * @internal
135 */
136 export const average = (dataSet: number[]): number => {
137 if (Array.isArray(dataSet) && dataSet.length === 0) {
138 return 0
139 }
140 if (Array.isArray(dataSet) && dataSet.length === 1) {
141 return dataSet[0]
142 }
143 return (
144 dataSet.reduce((accumulator, number) => accumulator + number, 0) /
145 dataSet.length
146 )
147 }
148
149 /**
150 * Computes the median of the given data set.
151 *
152 * @param dataSet - Data set.
153 * @returns The median of the given data set.
154 * @internal
155 */
156 export const median = (dataSet: number[]): number => {
157 if (Array.isArray(dataSet) && dataSet.length === 0) {
158 return 0
159 }
160 if (Array.isArray(dataSet) && dataSet.length === 1) {
161 return dataSet[0]
162 }
163 const sortedDataSet = dataSet.slice().sort((a, b) => a - b)
164 return (
165 (sortedDataSet[(sortedDataSet.length - 1) >> 1] +
166 sortedDataSet[sortedDataSet.length >> 1]) /
167 2
168 )
169 }
170
171 /**
172 * Rounds the given number to the given scale.
173 * The rounding is done using the "round half away from zero" method.
174 *
175 * @param num - The number to round.
176 * @param scale - The scale to round to.
177 * @returns The rounded number.
178 * @internal
179 */
180 export const round = (num: number, scale = 2): number => {
181 const rounder = Math.pow(10, scale)
182 return Math.round(num * rounder * (1 + Number.EPSILON)) / rounder
183 }
184
185 /**
186 * Is the given object a plain object?
187 *
188 * @param obj - The object to check.
189 * @returns `true` if the given object is a plain object, `false` otherwise.
190 * @internal
191 */
192 export const isPlainObject = (obj: unknown): boolean =>
193 typeof obj === 'object' &&
194 obj !== null &&
195 obj?.constructor === Object &&
196 Object.prototype.toString.call(obj) === '[object Object]'
197
198 /**
199 * Detects whether the given value is a kill behavior or not.
200 *
201 * @typeParam KB - Which specific KillBehavior type to test against.
202 * @param killBehavior - Which kind of kill behavior to detect.
203 * @param value - Any value.
204 * @returns `true` if `value` was strictly equals to `killBehavior`, otherwise `false`.
205 * @internal
206 */
207 export const isKillBehavior = <KB extends KillBehavior>(
208 killBehavior: KB,
209 value: unknown
210 ): value is KB => {
211 return value === killBehavior
212 }
213
214 /**
215 * Detects whether the given value is an asynchronous function or not.
216 *
217 * @param fn - Any value.
218 * @returns `true` if `fn` was an asynchronous function, otherwise `false`.
219 * @internal
220 */
221 export const isAsyncFunction = (
222 fn: unknown
223 ): fn is (...args: unknown[]) => Promise<unknown> => {
224 return typeof fn === 'function' && fn.constructor.name === 'AsyncFunction'
225 }
226
227 /**
228 * Updates the given measurement statistics.
229 *
230 * @param measurementStatistics - The measurement statistics to update.
231 * @param measurementRequirements - The measurement statistics requirements.
232 * @param measurementValue - The measurement value.
233 * @param numberOfMeasurements - The number of measurements.
234 * @internal
235 */
236 export const updateMeasurementStatistics = (
237 measurementStatistics: MeasurementStatistics,
238 measurementRequirements: MeasurementStatisticsRequirements,
239 measurementValue: number
240 ): void => {
241 if (measurementRequirements.aggregate) {
242 measurementStatistics.aggregate =
243 (measurementStatistics.aggregate ?? 0) + measurementValue
244 measurementStatistics.minimum = min(
245 measurementValue,
246 measurementStatistics.minimum ?? Infinity
247 )
248 measurementStatistics.maximum = max(
249 measurementValue,
250 measurementStatistics.maximum ?? -Infinity
251 )
252 if (
253 (measurementRequirements.average || measurementRequirements.median) &&
254 measurementValue != null
255 ) {
256 measurementStatistics.history.push(measurementValue)
257 if (measurementRequirements.average) {
258 measurementStatistics.average = average(measurementStatistics.history)
259 } else if (measurementStatistics.average != null) {
260 delete measurementStatistics.average
261 }
262 if (measurementRequirements.median) {
263 measurementStatistics.median = median(measurementStatistics.history)
264 } else if (measurementStatistics.median != null) {
265 delete measurementStatistics.median
266 }
267 }
268 }
269 }
270
271 /**
272 * Generates a cryptographically secure random number in the [0,1[ range
273 *
274 * @returns A number in the [0,1[ range
275 * @internal
276 */
277 export const secureRandom = (): number => {
278 return webcrypto.getRandomValues(new Uint32Array(1))[0] / 0x100000000
279 }
280
281 /**
282 * Returns the minimum of the given numbers.
283 * If no numbers are given, `Infinity` is returned.
284 *
285 * @param args - The numbers to get the minimum of.
286 * @returns The minimum of the given numbers.
287 * @internal
288 */
289 export const min = (...args: number[]): number =>
290 args.reduce((minimum, num) => (minimum < num ? minimum : num), Infinity)
291
292 /**
293 * Returns the maximum of the given numbers.
294 * If no numbers are given, `-Infinity` is returned.
295 *
296 * @param args - The numbers to get the maximum of.
297 * @returns The maximum of the given numbers.
298 * @internal
299 */
300 export const max = (...args: number[]): number =>
301 args.reduce((maximum, num) => (maximum > num ? maximum : num), -Infinity)