doc: add note about timeout delay > TIMEOUT_MAX

[sitegui]

When setTimeout() and setInterval() are called with delay greater than TIMEOUT_MAX (2147483647), the supplied value is ignored and 1 is used instead. This adds a note about this in the timers docs.

I actually got surprised by this behavior when trying to schedule a job to run in the first day of every month:

function schedule() {
    var now = new Date
    var nextMonth = new Date(now.getFullYear(), now.getMonth()+1)
    setTimeout(function () {
        shedule()
        doStuff()
    }, nextMonth - now)
}

It worked the first time, but afterwards it seemed to enter an infinite loop. I only found out why after searching and reading the timers.js code.
It only worked at first because it was past the 5th day of that month ;)

[cjihrig]

Maybe say "If delay is less than one, or greater than the maximum allowed value of 2147483647, it will be assigned a value of 1."

[trevnorris]

style nit: word wrap 80 chars

[sitegui]

ops, sorry

[trevnorris]

Thanks for the added doc changes. LGTM.

@nodejs/tsc I don't believe using 2^31-1 as the TIMEOUT_MAX is in the spec. So what about fixing the impl to allow even larger values?

[indutny]

@trevnorris I don't mind, though we will need to document the lost of precision for the values greater than 2^53-1

[trevnorris]

Okay. I'll leave this open and try to get to a fix by the end of the week.

[cjihrig]

+1 if browser consistency is the only reason it's implemented like this. Would this only affect someone trying to run Node code in the browser?

[trevnorris]

@cjihrig Think so. But at that point it's really UB, since in Firefox it will throw if the timeout is larger than 2^31 - 1 while on Chrome it will wrap. Test case:

setTimeout(()=>console.log('hi'),(-1 >>> 1) + 1);

EDIT: Firefox doesn't throw. It also wraps.

[bnoordhuis]

it will wrap

Browsers don't wrap (in the modulo sense), they expire the timer immediately. If you enter the following in the web console:

> setTimeout(() => console.log('two'), 60e3 + Math.pow(2,31)); setTimeout(() => console.log('one'), Math.pow(2,31))
1
two
one

While with modulo arithmetic it would print "one two" (with a 60 second delay between them.)

I added TIMEOUT_MAX way back because someone complained node was different from the browser, so apparently it's relevant at least to some people.

[Fishrock123]

I'd suggest just making an npm module that wraps timeout and spreads it out across multiple timeouts if you need anything larger.

[trevnorris]

K. Then let's land this so devs realize a module should be made. :-)

[cjihrig]

If anyone from the future reads this, there are already a few such modules out there.

[Trott]

PR LGTM

[trevnorris]

Thanks. Landed on ac7dd5f.

[MylesBorins]

landed in lts-v4.x-staging as d02365b