idle-task
v4.3.0
Published
Improve your website performance by executing JavaScript during a browser's idle periods🚀
Downloads
512
Maintainers
Readme
idle-task
Improve your website performance by executing JavaScript during a browser's idle periods.
Table of Contents
- Features
- Install
- Quick Start
- API
- Recipes
- Contributing
- License
Features
idle-task
wraps requestIdleCallback .
The features are as follows.
Manage tasks priority
import { setIdleTask } from 'idle-task';
setIdleTask(yourLowPrioryFunction, { priority: 'low' });
setIdleTask(yourHighPrioryFunction, { priority: 'high' });
Get result by using Promise based API
import { getResultFromIdleTask } from 'idle-task';
// get result asynchronously
const result = await getResultFromIdleTask(yourFunction);
Cache
import { setIdleTask, waitForIdleTask } from 'idle-task';
const taskKey = setIdleTask(yourFunction);
const result1 = await waitForIdleTask(taskKey);
// from cache
const result2 = await waitForIdleTask(taskKey);
Optimize executing tasks
import { setIdleTask } from 'idle-task';
setIdleTask(longTask);
// these functions will be executed during next browser's idle time.
setIdleTask(shortTask);
setIdleTask(shortTask);
Analyze tasks execution time
import { setIdleTask, configureIdleTask } from 'idle-task';
configureIdleTask({ debug: true })
// output the execution time to the web console.
setIdleTask(yourFunction1);
Install
npm i idle-task
Quick Start
The simplest way is to use setIdleTask
.
import { setIdleTask } from 'idle-task';
const sendAnalyticsData = () =>
console.log("send analytics data during a browser's idle periods.");
setIdleTask(sendAnalyticsData);
If you want to get the result of a task, please use waitForIdleTask
.
import { setIdleTask, waitForIdleTask } from 'idle-task';
const taskKey = setIdleTask(yourFunction);
const result = await waitForIdleTask(taskKey);
API
setIdleTask
const sendAnalyticsData = () => console.log("send analytics data");
const options = {
priority: 'high',
revalidateInterval: 5000,
revalidateWhenExecuted: true,
};
const taskKey = setIdleTask(sendAnalyticsData, options);
idle-task
has a FIFO(First-In-First-Out) queue.
setIdleTask
enqueues a task which idle-task
will dequeue and run when the browser is idle.
setIdleTask
returns TaskKey
Object which is necessary for cancelIdleTask
, getIdleTaskStatus
and waitForIdleTask
.
I recommend less than 50 ms to execute a task because of RAIL model . If you want to know how long did it take to finish a task, please use debug mode .
setIdleTask
can also be set options as below.
priority?: 'low' | 'high'
You can run a task preferentially using priority: 'high'
(default is false
) option.
setIdleTask
adds it to the head of the queue.
revalidateInterval?: number
You can reregister your task by using revalidateInterval
.
If you set revalidateInterval: 5000
, idle-task
will enqueue your task every 5000 ms .
const saveUserArticleDraft = () => {
// save user editing article data to database.
}
// saveUserArticleDraft will be executed when the browser is idle.
// In addition, idle-task registers saveUserArticleDraft task every 5000 ms.
setIdleTask(saveUserArticleDraft, { revalidateInterval: 5000 });
revalidateWhenExecuted?: boolean
You can reregister your task by using revalidateWhenExecuted
which default is false
.
idle-task
will enqueue your task when it had been executed.
const saveUserArticleDraft = () => {
// save user editing article data to database.
}
// saveUserArticleDraft will be executed when the browser is idle.
// In addition, idle-task registers saveUserArticleDraft task when it had been executed.
setIdleTask(saveUserArticleDraft, { revalidateWhenExecuted: true });
overwriteTask?: IdleTaskKey
You can overwrite registered task by using overwriteTask
.
If the task have already been executed, idle-task
remove its result from the cache and enqueue the new task, otherwise idle-task
will remove it from the queue and enqueue the new task.
const generateRandomNumber = () => Math.floor( Math.random() * 100 );
const taskKey = setIdleTask(generateRandomNumber);
const randomNumber1 = await waitForIdleTask(taskKey);
setIdleTask(generateRandomNumber, { overwriteTask: taskKey });
const randomNumber2 = await waitForIdleTask(taskKey);
waitForIdleTask
const generateRandomNumber = () => Math.floor( Math.random() * 100 );
const taskKey = setIdleTask(generateRandomNumber);
const randomNumber = await waitForIdleTask(taskKey);
You can get the result of the task by using waitForIdleTask
.
waitForIdleTask
can also be set options as below.
timeout?: number
waitForIdleTask
maybe wait for the task eternally because it will be finished when the browser is idle.
timeout
option can prevent it.
const generateRandomNumber = () => Math.floor( Math.random() * 100 );
const taskKey = setIdleTask(generateRandomNumber);
try {
const firstRandomNumber = await waitForIdleTask(taskKey, { timeout: 1000 });
} catch (e) {
if (e instanceof WaitForIdleTaskTimeoutError) {
console.error('this is timeout error')
}
}
In this case, waitForIdleTask
will throw WaitForIdleTaskTimeoutError
as default if the task can't be finished within 1000 ms.
timeoutStrategy?: 'error' | ’forceRun'
const generateRandomNumber = () => Math.floor( Math.random() * 100 );
const taskKey = setIdleTask(generateRandomNumber);
const firstRandomNumber = await waitForIdleTask(taskKey, { timeout: 1000, timeoutStrategy: 'error' });
You can choose the movement when the idle task is timeout.
waitForIdleTask
executes the task even if having not yet run it after the time has come.
If you set error
, waitForIdleTask
throws an error if the task can't be finished within the time which you set.
getResultFromIdleTask
const generateRandomNumber = () => Math.floor( Math.random() * 100 );
const randomNumber = await getResultFromIdleTask(generateRandomNumber, {
priority: 'high',
timeout: 3000,
timeoutStrategy: 'error'
});
// same
const taskKey = setIdleTask(generateRandomNumber, { priority: 'high' });
const randomNumber = await waitForIdleTask(taskKey, { timeout: 3000, timeoutStrategy: 'error' });
You can get the result by using getResultFromIdleTask
if you don't need the task id.
getResultFromIdleTask
can also be set options which is SetIdleTaskOptions.priority
and WaitForIdleTaskOptions.timeout
.
forceRunIdleTask
const generateRandomNumber = () => Math.floor( Math.random() * 100 );
const taskKey = setIdleTask(generateRandomNumber);
const randomNumber = await forceRunIdleTask(taskKey);
You can get the result immediately whether the task was executed during a browser's idle periods or not.
forceRunIdleTask
gets result from cache if the task was executed.
cancelIdleTask
const taskKey = setIdleTask(() => console.log("task will be canceled."));
cancelIdleTask(taskKey);
You can stop to run a task by using cancelIdleTask
if it is not executed.
cancelAllIdleTasks
setIdleTask(() => console.log("task 1 will be canceled."));
setIdleTask(() => console.log("task 2 will be canceled."));
setIdleTask(() => console.log("task 3 will be canceled."));
cancelAllIdleTasks();
You can stop to run all tasks by using cancelAllIdleTasks
if they are not executed.
getIdleTaskStatus
const taskKey = setIdleTask(() => console.log("task"));
const idleTaskStatus = getIdleTaskStatus(taskKey);
// execute immediately if the task has not been executed yet.
if (idleTaskStatus === 'ready') {
forceRunIdleTask(taskKey)
}
You can know the task status by using getIdleTaskStatus
.
getIdleTaskStatus
returns string as following.
ready
- The task has not been executed.
executed
- The task has been executed.
- This doesn't mean that the task has been completed because JavaScript don't have API which help us to know the promise result like
fullfilled
.
unknown
idle-task
doesn't know the task status because its result doesn't exist anywhere.- This case means that the task was canceled by API like
cancelIdleTask
.
configureIdleTask
configureIdleTask({
interval: 1000, // ms
debug: process.env.NODE_ENV === 'development',
timeout: 3000,
});
configureIdleTask
configures idle-task
.
You can set properties as below.
interval?: number
idle-task
checks tasks which was registered by setIdleTask
during a browser's idle periods, so they will not always be executed .
Please set interval
if you want to guarantee to run tasks as much as possible.
Even if the browser is not idle, idle-task
checks tasks every 1000 ms when interval
is 1000
and will execute tasks without negative impact on performance.
debug?: boolean
If debug
is true
, you can know how long did it take to finish the task via the web console.
I recommend less than 50 ms to execute a task because of RAIL model .
The default is false
.
timeout?: number
This option configures timeout
of waitForIdleTask
and getResultFromIdleTask
as default setting.
configureIdleTask({ timeout: 3000 });
const taskKey = setIdleTask(yourFunction);
// timeout is 3000
const result = await waitForIdleTask(taskKey);
// timeout is 5000 if you set timeout as option
const result = await waitForIdleTask(taskKey, { timeout: 5000 });
timeoutStrategy?: 'error' | ’forceRun'
This option configures timeoutStrategy
of waitForIdleTask
and getResultFromIdleTask
as default setting.
configureIdleTask({ timeout: 3000, timeoutStrategy: 'forceRun' });
const taskKey = setIdleTask(yourFunction);
// run task in 3000 ms regardless of whether the task has already been executed or not.
const result = await waitForIdleTask(taskKey);
// timeoutStrategy is 'error' if you set timeoutStrategy as option
try {
const result = await waitForIdleTask(taskKey, { timeoutStrategy: 'error' });
} catch {
console.error('timeout!')
}
Recipes
Vanilla JS
dynamic import
import { setIdleTask } from 'idle-task';
// this module is loaded during a browser's idle periods because it is not important for UI.
const taskKey = setIdleTask(() => import('./sendAnalyticsData'))
const button = document.getElementById('button');
button.addEventListener('click', async () => {
// You should use waitForIdleTask if the module is not important.
// On the other hand, I recommend to use forceRunIdleTask if the module is important.
const { default: sendAnalyticsData } = await waitForIdleTask(taskKey);
// Send analytics data to server when the browser is idle.
setIdleTask(sendAnalyticsData);
})
fetch external resources
import { getResultFromIdleTask } from 'idle-task';
const checkAccessTokenWhenIdle = (accessToken: string): Promise<any> => {
const fetchCheckAccessToken = async (): Promise<any> => {
const response = await fetch(`https://yourdomain/api/check?accessToken=${accessToken}`);
// Promise callback will execute immediately after fetching completely even if the browser is busy.
// One of the solutions is to run it when next browser's idle time.
return getResultFromIdleTask(() => response.json());
};
return getResultFromIdleTask(fetchCheckAccessToken);
}
const { isSuccess } = await checkAccessTokenWhenIdle('1234');
React
fetch external resources
import {useState, useEffect} from 'react';
import {setIdleTask, cancelIdleTask, waitForIdleTask} from 'idle-task';
const fetchNewsList = async () => {
const response = await fetch('https://yourdomain/api/news');
return response.json();
}
// this is not important UI for the website main content like e-commerce sites.
export default function WebsiteNewsList() {
const [newsList, setNewsList] = useState([]);
const [isLoading, setIsLoading] = useState(true);
useEffect(() => {
// fetch news list when the browser is idle and cache it.
const taskKey = setIdleTask(fetchNewsList)
waitForIdleTask(taskKey)
.then(setNewsList)
.finally(() => setIsLoading(false));
return () => {
// stop to fetch news list and remove the cache when the component re-render.
cancelIdleTask(taskKey)
};
}, [])
if (isLoading) {
return <div>Loading...</div>
}
return newsList.map(news => (
<div id={news.id}>
{news.publiedDate}
{news.title}
{news.description}
</div>
))
}
React.lazy
import {useState, useEffect, lazy, Suspense} from 'react';
import {setIdleTask, waitForIdleTask, forceRunIdleTask} from 'idle-task';
const taskKey = setIdleTask(() => import('~/components/Modal'))
const taskPromise = waitForIdleTask(taskKey)
const Modal = lazy(() => taskPromise);
export default function WebsiteNewsList() {
const [isClicked, setIsClicked] = useState(false);
const onClick = () => setIsClicked(true);
useEffect(() => {
if (isClicked) {
// Import Modal immediately whether importing it was completed during the browser's idle periods or not.
forceRunIdleTask(taskKey);
}
}, [isClicked])
return (
<>
<button type='button' onClick={onClick} />
<Suspense>
{isClicked && <Modal />}
</Suspense>
</>
)
}
Contributing
Please see CONTRIBUTING.md .
Thank you for contributing!!
License
Released under the MIT license.