typings: add JSDoc typings for timers

[VoltrexKeyva]

Added JSDoc typings for the timers lib module.

[VoltrexKeyva]

On a note, the setTimeout(), setInterval() and setImmediate() functions take rest parameters at the end to pass to the given callback which are defined as arg1, arg2, arg3, but as it takes more parameters than that with the usage of the arguments object and a for loop, we can't make JSDoc typings tell the user that the function takes more parameters than just 3 without the usage of the spread operator (...) to point out rest parameters (e.g. ...args) in the function parameters itself, could we do anything about this?

Hit the wrong button

[apapirovski]

Left a couple of small clarifications but the rest looks good.

[apapirovski]

On a note, the setTimeout(), setInterval() and setImmediate() functions take rest parameters at the end to pass to the given callback which are defined as arg1, arg2, arg3, but as it takes more parameters than that with the usage of the arguments object and a for loop, we can't make JSDoc typings tell the user that the function takes more parameters than just 3 without the usage of the spread operator (...) to point out rest parameters (e.g. ...args) in the function parameters itself, could we do anything about this?

Spread operator was slower than what we have, last time I tried it, but you could always make that change locally and see how the benchmarks perform with it.

Other than that, I'm not super familiar with JSDoc intricacies but I assume that replacing arg1, arg2, arg3 with ...args is not something it'll take to well since the code doesn't match? (Or if it doesn't enforce it then I would say that just representing the intention of the function rather than how it's coded is probably more important.)

[VoltrexKeyva]

On a note, the setTimeout(), setInterval() and setImmediate() functions take rest parameters at the end to pass to the given callback which are defined as arg1, arg2, arg3, but as it takes more parameters than that with the usage of the arguments object and a for loop, we can't make JSDoc typings tell the user that the function takes more parameters than just 3 without the usage of the spread operator (...) to point out rest parameters (e.g. ...args) in the function parameters itself, could we do anything about this?

Spread operator was slower than what we have, last time I tried it, but you could always make that change locally and see how the benchmarks perform with it.

Other than that, I'm not super familiar with JSDoc intricacies but I assume that replacing arg1, arg2, arg3 with ...args is not something it'll take to well since the code doesn't match? (Or if it doesn't enforce it then I would say that just representing the intention of the function rather than how it's coded is probably more important.)

yea, JSDoc does not enforce typings if the code does not match; so the only of doing this is replacing those 3 parameters at the end with a rest parameter but that may cause a perf regression, so I think we should just let it either be this way as it is, or maybe change the parameter to a rest one and benchmarking them, overall the intension of the function is the most important.

[apapirovski]

so I think we should just let it either be this way as it is, or maybe change the parameter to a rest one and benchmarking them

Would definitely encourage trying this locally. I don't know if it's been tried in over a year at this point so the performance could've easily gotten on par. If you prefer not to run them locally, can always open a PR and run the benchmarks in CI.

[apapirovski]

@VoltrexMaster so looking at JSDoc documentation, it seems like we could actually get away with https://jsdoc.app/tags-param.html#multiple-types-and-repeatable-parameters where you specify arg3 as being repeated. It's a bit ugly but at least gets information across? So it seems like you could do

/**
 * Schedules the immediate execution of `callback`
 * after I/O events' callbacks.
 * @param {Function} callback
 * @param {any} [arg1]
 * @param {any} [arg2]
 * @param {...*} [arg3]
 * @returns {Immediate}
 */

[VoltrexKeyva]

@apapirovski sadly that doesn't work, stays the same type as any as a single parameter, the code must match for it to work.

[apapirovski]

Interesting. The documentation calls this out as the solution to using arguments in your code... wonder if regression, outdated documentation, or if it only works with a single param function?

[VoltrexKeyva]

Interesting. The documentation calls this out as the solution to using arguments in your code... wonder if regression, outdated documentation, or if it only works with a single param function?

Imma just let it stay like this, I may try to benchmark the functions after applying rest parameters in the future and open a PR to make the changes if a perf regression doesn't happen.

[targos]

Landed in c4096a3