Registry / scheduler-polyfill

scheduler-polyfill

library1.3.0jsnpmunverified

Polyfill for the Prioritized Task Scheduling API (window.scheduler), providing scheduler.postTask(), scheduler.yield(), TaskController, and TaskSignal. Version 1.3.0, actively maintained by Google Chrome Labs. Uses setTimeout, MessageChannel, and requestIdleCallback with fallbacks. Suitable for browsers that haven't implemented the native API (Chrome 94+, Firefox 101+, Safari 15.4+). Ships TypeScript types. Good for progressive enhancement in scheduling-intensive web apps.

npm install scheduler-polyfill

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SCHEDULER-POLYFILL

scheduler-polyfill

javascriptv1.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

scheduler-polyfill (side-effect import)

✓ import 'scheduler-polyfill';

✗ import schedulerPolyfill from 'scheduler-polyfill';

This package is a polyfill that adds self.scheduler, TaskController, etc. as globals. It exports no named symbols; use a side-effect import. TypeScript types are automatically available after the import.

TaskController

✓ import 'scheduler-polyfill'; const controller = new TaskController('user-blocking');

✗ import { TaskController } from 'scheduler-polyfill';

TaskController is added to the global scope. Named import from the package does not work; it must be accessed as a global after the side-effect import.

TaskSignal (via TaskController)

✓ import 'scheduler-polyfill'; const controller = new TaskController('background'); const signal = controller.signal;

✗ import { TaskSignal } from 'scheduler-polyfill';

TaskSignal is not directly constructable; it is obtained from TaskController.signal. It becomes a global after the import.

Shows how to side-effect import the polyfill, create a TaskController, and schedule a postTask with priority and signal. Works in browsers that don't natively support scheduler.

// Install: npm install scheduler-polyfill import 'scheduler-polyfill'; async function example() { const priority = 'user-blocking'; const controller = new TaskController(priority); // Schedule a task with signal const result = await self.scheduler.postTask( () => { console.log('Task running with priority:', priority); return 'done'; }, { signal: controller.signal, priority } ); console.log(result); // "done" } example();

Debug

Known issues

gotchaThe polyfill does not support priority or signal inheritance for scheduler.yield(); all continuations are scheduled with 'user-visible' priority.

fix

None; this is a known limitation. Do not rely on inherited priorities for yield().

affects: <=1.3.0

gotchaIn browsers that do not support requestIdleCallback, 'background' tasks will not have low event loop priority and may run in arbitrary order.

fix

Use feature detection or ensure the polyfill runs only in modern environments where requestIdleCallback is available.

affects: <=1.3.0

gotchauser-blocking and user-visible tasks share the same event loop priority (setTimeout-like); they are not strictly prioritized above each other in non-native environments.

fix

For strict priority ordering, rely on native scheduler rather than the polyfill.

affects: <=1.3.0

gotchaThe polyfill may not accurately reflect native scheduler behavior in environments that already support the API; it will only polyfill if self.scheduler is undefined.

fix

Avoid loading the polyfill in modern browsers that already support scheduler to prevent unintended side effects. Use dynamic import with feature detection.

affects: <=1.3.0

Errors

Common errors & fixes

TypeError: Failed to construct 'TaskController': Please use the 'new' operator, this DOM object constructor cannot be called as a function.

Attempting to call TaskController without 'new' because the global is not correctly polyfilled (likely not imported first).

fix

Ensure you have imported 'scheduler-polyfill' as a side-effect before using TaskController.

Uncaught SyntaxError: import declarations may only appear at top level of a module

Using import statement inside a non-module script or incorrectly bundling the polyfill.

fix

Add type="module" to your script tag or use a bundler that supports ES modules.

Cannot read properties of undefined (reading 'postTask')

self.scheduler is undefined because the polyfill import failed or the browser does not support modules and the polyfill was not loaded.

fix

Check that the polyfill import executes correctly. For non-module scripts, use a <script> tag pointing to the standalone bundle instead.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/GoogleChromeLabs/scheduler-polyfill ↗

packagescheduler-polyfill ↗

homepagehttps://github.com/GoogleChromeLabs/scheduler-polyfill ↗