# custom-idle-queue

> Optimize the speed of important tasks on limited ressources

Latest version **5.0.2** (published 2026-03-13) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install custom-idle-queue
pnpm add custom-idle-queue
yarn add custom-idle-queue
bun add custom-idle-queue
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.2 |
| Published | 2026-03-13 |
| First published | 2017-09-27 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 56.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 22 |
| Author | pubkey |
| Maintainers | pubkey |
| Keywords | requestIdleCallback, idle, performance, optimisation |

## Links

- npm: https://www.npmjs.com/package/custom-idle-queue
- Repository: https://github.com/pubkey/custom-idle-queue
- Homepage: https://github.com/pubkey/custom-idle-queue#readme
- Issues: https://github.com/pubkey/custom-idle-queue/issues
- npm.io page: https://npm.io/package/custom-idle-queue

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 5.0.2 (latest) — 2026-03-13
- 5.0.0 — 2026-03-13
- 4.1.0 — 2025-05-27
- 4.0.0 — 2025-05-13
- 3.0.1 — 2020-05-26
- 3.0.0 — 2020-05-26
- 2.1.2 — 2018-09-06
- 2.1.1 — 2018-09-06
- 2.1.0 — 2018-09-06
- 2.0.1 — 2018-03-13
- 2.0.0 — 2017-12-14
- 1.0.0 — 2017-09-27

## README

# Custom Idle Queue

This is a npm-module that lets you optimize the performance of important tasks by delaying background-tasks. It works a bit like [requestIdleCallback](https://developer.mozilla.org/de/docs/Web/API/Window/requestIdleCallback) but instead of fetching idle-time of the CPU, you can use this for any given limited ressource.

## Quickstart

In this example we define `database-requests` as limited ressource. We create an idleQueue arround all calls to the ressource to ensure our `importantTask` is as fast as possible and the `backgroundTask` only runs when no `importantTask` is using the database.

`npm install custom-idle-queue --save`

```javascript
// require
const { IdleQueue } = require('custom-idle-queue');

// OR import
import { IdleQueue } from 'custom-idle-queue';

// create a new queue
const myQueue = new IdleQueue();


// wrap all calls to your limited ressource
const readFromDatabase = key => myQueue.wrapCall(
    () => pseudoDatabaseModule.get(key)
);
const writeToDatabase = (key, value) => myQueue.wrapCall(
    () => pseudoDatabaseModule.set(key, value);
);
const deleteFromDatabase = (key) => myQueue.wrapCall(
    () => pseudoDatabaseModule.delete(key, value);
);

// this is the important task
const importantTask = async function increaseClickNumber() {
    const oldNumber = await readFromDatabase('nr');
    const newNumber = oldNumber++;
    await writeToDatabase('nr', newNumber);
    await writeToDatabase('time_' + newNumber, new Date().getTime());
    return newNumber;
};

// this is the background task
const backgroundTask = async function cleanUpOldClicks() {
    const newest = await readFromDatabase('nr');
    const limitDate = new Date().getTime() - 1000*60*60;
    for (let i = 0; i < newest; i++) {
        const date = await readFromDatabase('time_' + i);
        if(date < limitDate){
            await deleteFromDatabase('time_' + i);
        }
    }
}

// we now run the backgroundTask in an intervall without slowing down the importantTask
(async() => {
    while(true){
        await myQueue.requestIdlePromise(); // wait until database-requests in idle
        await backgroundTask();

        await new Promise(res => setTimeout(res, 2000)); // wait 2 seconds
    }
})();

// if we now run the importantTask, it will not be slowed down by the backgroundTask
document
    .querySelector('#myButton')
    .addEventListener('click', () => {
        const newNr = await importantTask();
        labelDomElement.innerHTML = newNr.toString();
    });

// You can find the full documentation here https://github.com/pubkey/custom-idle-queue/blob/master/docs.md

```

## Use cases
This module can be used on any limited ressource like

- HTTP-Requests
- Database-Calls
- Service-Worker-Calls
- Animations

## Limitations

- **IdleQueue cannot predict the future**

When you start a `backgroundTask` first and the `importantTask` afterwards, the `backgroundTask` will slow down the `importantTask` because it is already running. To prevent this, you should use `requestIdlePromise` as granular as possible. The backgroundTask-function from the example would be better when it awaits the idle-state before each usage of the limited ressource. This will ensure that the `backgroundTask` will be paused until the `importantTask` has finished.

```js
// this is the background task
const backgroundTask = async function cleanUpOldClicks() {
    await myQueue.requestIdlePromise(); // request idle-state each time
    const newest = await readFromDatabase('nr');
    const limitDate = new Date().getTime() - 1000*60*60;
    for (let i = 0; i < newest; i++) {
        await myQueue.requestIdlePromise(); // request idle-state each time
        const date = await readFromDatabase('time_' + i);
        if(date < limitDate){
            await myQueue.requestIdlePromise(); // request idle-state each time
            await deleteFromDatabase('time_' + i);
        }
    }
}
```

- **You cannot optimize CPU-only ressources**

Because javascript runs in a single process, it doesn't make sense to define CPU as limited ressource. For example if you have a CPU-only-Function like `calculatePrimeNumber`, you should not limit the access to the function with an idle-queue because at the time you call `idleQueue.lock()` or `idleQueue.wrapCall()`, the process will instantly run `calculatePrimeNumber` before it even can change the idle-queue state.



## Browser-Support

This module is using the [Promise-](https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Promise) and the [Map](https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Map)-Object. If your runtime does not support them, you have to add them via polyfills.

## [Read the full documentation here](https://github.com/pubkey/custom-idle-queue/blob/master/docs.md)

---
_Source: https://npm.io/package/custom-idle-queue · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._