CKTIS / JavaScript
IdleDeadline: callback reason and remaining idle time
`didTimeout` tells you why an idle callback ran; `timeRemaining()` estimates how many milliseconds are left in the current idle period.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
window.requestIdleCallback(callback);
window.requestIdleCallback(callback, { timeout: milliseconds });
// Inside callback(deadline), where deadline is an IdleDeadline:
deadline.didTimeout; // read-only boolean property
deadline.timeRemaining(); // number of milliseconds, no argumentsThe browser passes an IdleDeadline object to the callback registered with window.requestIdleCallback(). IdleDeadline.didTimeout/timeRemaining refers to two members of that object: a property and a method. This is a Window Web API, not part of ECMAScript 2024. It is not available in Web Workers, and browser support varies, so check availability before calling it.
deadline.didTimeout is a read-only boolean. true means the callback is running because its optional timeout expired; false means it was invoked as part of an idle period. If the timeout expires before the callback has run, the browser queues a task to invoke it. This neither interrupts running code nor guarantees an exact start time. Without a timeout, the callback may wait a long time.
deadline.timeRemaining() takes no arguments and returns a nonnegative estimate of the remaining idle time in milliseconds, possibly fractional. It returns 0 when didTimeout === true, but it can also return 0 when didTimeout === false and the idle budget is exhausted. The estimate is neither reserved execution time nor a countdown to timeout. Read it during the current callback rather than relying on it after an await.
Split work into small chunks and check timeRemaining() > 0 before each one. On the timeout path, do at most one small essential chunk and schedule another callback for the rest. A loop condition with || deadline.didTimeout can drain the whole queue even when there is no idle budget.
Examples
(() => {
function logIdleStatus(host) {
if (typeof host.requestIdleCallback !== 'function') {
console.log('requestIdleCallback unavailable');
return;
}
host.requestIdleCallback((deadline) => {
const reason = deadline.didTimeout ? 'timeout' : 'idle';
const budget = deadline.timeRemaining() > 0
? 'budget available'
: 'no idle budget';
console.log(`${reason}: ${budget}`);
}, { timeout: 100 });
}
if (typeof window !== 'undefined') {
logIdleStatus(window);
return;
}
// Test doubles exercise the callback without browser scheduling.
for (const [didTimeout, remaining] of [[false, 5], [false, 0], [true, 0]]) {
logIdleStatus({
requestIdleCallback(callback) {
callback({ didTimeout, timeRemaining: () => remaining });
},
});
}
logIdleStatus({});
})();Result
idle: budget available idle: no idle budget timeout: no idle budget requestIdleCallback unavailable
In Node.js, the example logs all four lines in order. It uses test doubles for the three deadline cases and an object without the API for the fallback. This does not test browser scheduling. If you paste the code into a browser page’s developer console, it logs only one line: one of the first three asynchronously if the API is supported, or the fourth immediately if it is not. The 100 ms option does not force the timeout path.
Related lessons
- JavaScript · Lesson 6 · Advanced · Version: 4