@serve-tools/polyfill-request-idle-callback

Defer a small optional task so it does not run in the current interaction. The @serve-tools/polyfill-request-idle-callback package implements APIs from the W3C requestIdleCallback Working Draft by installing missing globals while preserving existing native implementations.

import "@serve-tools/polyfill-request-idle-callback";

const summaries: string[] = [];
requestIdleCallback(() => {
	summaries.push("Prepared search suggestions");
	console.log(summaries[0]);
}, { timeout: 1_000 });

The callback logs “Prepared search suggestions” when scheduled; the timeout provides forward progress when idle time is scarce. Keep each callback short: a timeout does not create extra idle time. Use the matching ponyfill to import the fallback without installing globals.

Install

npm install @serve-tools/polyfill-request-idle-callback

Import from a CDN

import "https://esm.run/@serve-tools/polyfill-request-idle-callback";

Usage

Install both globals

Import the package for its side effects to install both functions.

The package explicitly marks its root and selective installers as side-effectful. Do not remove its imports as unused.

Install individual globals

Import a ./apply/* subpath to install only the function an application needs:

import "@serve-tools/polyfill-request-idle-callback/apply/requestIdleCallback";
import "@serve-tools/polyfill-request-idle-callback/apply/cancelIdleCallback";

Each installer is self-guarding and leaves an existing native implementation unchanged.

Import without global mutation

The matching top-level subpaths export a bound native implementation when it is available and otherwise export the fallback without installing a global:

import { requestIdleCallback } from "@serve-tools/polyfill-request-idle-callback/requestIdleCallback";
import { cancelIdleCallback } from "@serve-tools/polyfill-request-idle-callback/cancelIdleCallback";

The global, selective, and mutation-free import patterns above are covered by the package's TypeScript fixture and runtime tests.

Public API

• The package root installs requestIdleCallback and cancelIdleCallback when either global is missing.
• ./apply/requestIdleCallback and ./apply/cancelIdleCallback install one missing global.
• ./requestIdleCallback and ./cancelIdleCallback export a bound native function when available and the fallback otherwise without changing globals.

Relationship to the ponyfill

This package uses @serve-tools/ponyfill-request-idle-callback as its fallback implementation and integrates it with native globals. Use the ponyfill directly when global mutation is not wanted and native identity is not required.

Compatibility

The package is an ES module for browser windows with document, performance, MessageChannel, and requestAnimationFrame. It preserves existing native functions and fills only missing globals. The fallback cannot observe the browser's internal rendering or input queues, so its deadline is an approximation rather than a native idle period.

Agent Skill

This package includes skills/serve-tools-polyfill-request-idle-callback/SKILL.md with version-aligned usage guidance for compatible coding agents. Activation is explicit; installing the package does not automatically trust or enable it.

Development

npm run typecheck --workspace @serve-tools/polyfill-request-idle-callback
npm test --workspace @serve-tools/polyfill-request-idle-callback
npm run build --workspace @serve-tools/polyfill-request-idle-callback

License

MIT-0