idle-requester

A lightweight, strongly-typed background fetch queue that utilizes the browser's requestIdleCallback API.

It defers non-critical API requests to the browser's idle periods, ensuring smoother user interactions and eliminating frame drops on heavy network loads.

Features

• Performance Optimized — Offloads fetches to non-blocking idle frames.
• Priority Lane — High-priority requests jump to the front of the queue.
• Auto-Retry — Configurable network failure retries.
• Abortable — Completely integrated with native AbortController signals.
• Smart Fallback — Transparent setTimeout queue worker loop for Safari and SSR setups.

Installation

npm install idle-requester

Usage

1. Vanilla JavaScript

Directly use the default singleton instance anywhere in your scripts.

import idleRequester from 'idle-requester';

const cancel = idleRequester.enqueue(
  'https://api.example.com/analytics',
  (err, data) => {
    if (err) {
      return console.error('Aborted or failed:', err);
    }

    console.log('Metrics logged:', data);
  }
);

// Cancel processing if needed before execution completes
// cancel();

2. Vue 3 (Composition API)

Manage the instance cleanup cycles within Vue component lifecycles automatically.

<script setup>
import { onUnmounted, ref } from 'vue';
import idleRequester from 'idle-requester';

const userData = ref(null);
let cancelFetch = null;

function loadRecommendationData() {
  cancelFetch = idleRequester.enqueue(
    '/api/recommendations',
    {
      priority: 'low',
      retries: 1
    },
    (err, data) => {
      if (!err) {
        userData.value = data;
      }
    }
  );
}

loadRecommendationData();

onUnmounted(() => {
  if (cancelFetch) {
    cancelFetch();
  }
});
</script>

<template>
  <div v-if="userData">
    <!-- Render data here -->
  </div>
</template>

3. React

Incorporate the utility inside a useEffect hook to prevent leaking asynchronous memory state during unmount steps.

import React, { useEffect, useState } from 'react';
import idleRequester from 'idle-requester';

export const SuggestionsComponent = () => {
  const [items, setItems] = useState([]);

  useEffect(() => {
    const cancel = idleRequester.enqueue(
      '/api/suggestions',
      (err, data) => {
        if (!err && data) {
          setItems(data);
        }
      }
    );

    return () => {
      cancel();
    };
  }, []);

  return (
    <ul>
      {items.map((item: any) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
};

4. Angular

Encapsulate the worker within a service block, or resolve individual items using RxJS patterns or component pipelines.

import { Component, OnInit, OnDestroy } from '@angular/core';
import idleRequester from 'idle-requester';

@Component({
  selector: 'app-background-loader',
  template: `<p>Background processing element</p>`
})
export class BackgroundLoaderComponent implements OnInit, OnDestroy {
  private cancelTask?: () => boolean;

  ngOnInit() {
    this.cancelTask = idleRequester.enqueue(
      'https://api.example.com/logs',
      {
        method: 'POST',
        priority: 'low'
      },
      (err, data) => {
        if (err) {
          console.error('Log sync failed', err);
        }
      }
    );
  }

  ngOnDestroy() {
    if (this.cancelTask) {
      this.cancelTask();
    }
  }
}

API Reference

idleRequester.enqueue(url, options, callback)

| Parameter | Type | Required | Description | | ---------- | ------------------ | -------- | ----------------------------------------- | | url | string | Yes | Target endpoint string | | options | IdleFetchOptions | No | Configuration options | | callback | Function | No | Signature matches (error, data) => void |

Advanced Options

interface IdleFetchOptions extends RequestInit {
  priority?: 'high' | 'low';
  // Default: 'low'
  // 'high' puts the request at the front of the queue

  retries?: number;
  // Default: 0
  // Amount of retry iteration limits

  timeout?: number;
  // Default: 3000ms
  // Deadline timeout constant
}

Instantiating Isolated Queues

If you want to maintain separate isolated environments across individual modules, instantiate distinct contextual objects manually instead of consuming the default export singleton.

import { IdleRequester } from 'idle-requester';

const specializedQueue = new IdleRequester({
  timeout: 5000
});

License

MIT