tessl/npm-scheduler

Cooperative scheduler for the browser environment that provides time-slicing capabilities for JavaScript applications.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Scheduler

Name: tessl/npm-scheduler
Author: tessl

Scheduler is a cooperative scheduling library for browser environments that provides time-slicing capabilities for JavaScript applications. It implements a priority-based task scheduler that can yield control back to the browser's main thread to maintain responsiveness during intensive computations.

Package Information

Package Name: scheduler
Package Type: npm
Language: JavaScript
Installation: npm install scheduler

Core Imports

import { 
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_runWithPriority,
  unstable_ImmediatePriority,
  unstable_UserBlockingPriority,
  unstable_NormalPriority,
  unstable_LowPriority,
  unstable_IdlePriority
} from "scheduler";

For CommonJS:

const { 
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_runWithPriority,
  unstable_ImmediatePriority,
  unstable_UserBlockingPriority,
  unstable_NormalPriority,
  unstable_LowPriority,
  unstable_IdlePriority
} = require("scheduler");

For testing environments:

import { 
  unstable_flushAll,
  unstable_advanceTime,
  reset
} from "scheduler/unstable_mock";

For PostTask API environments:

import { 
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_runWithPriority,
  unstable_getCurrentPriorityLevel,
  unstable_next,
  unstable_wrapCallback,
  unstable_shouldYield,
  unstable_requestPaint,
  unstable_now,
  unstable_forceFrameRate,
  unstable_ImmediatePriority,
  unstable_UserBlockingPriority,
  unstable_NormalPriority,
  unstable_LowPriority,
  unstable_IdlePriority
} from "scheduler/unstable_post_task";

Note: The PostTask implementation uses the browser's native scheduler.postTask() API when available and provides a more limited feature set compared to the main scheduler implementation. Profiling is not available (unstable_Profiling is null).

For React Native environments (imports from scheduler/index.native.js):

import { 
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_getCurrentPriorityLevel,
  unstable_shouldYield,
  unstable_requestPaint,
  unstable_now,
  unstable_ImmediatePriority,
  unstable_UserBlockingPriority,
  unstable_NormalPriority,
  unstable_LowPriority,
  unstable_IdlePriority
} from "scheduler";

Note: In React Native, the following functions throw "Not implemented" errors:

unstable_next()
unstable_runWithPriority()
unstable_wrapCallback()
unstable_forceFrameRate()

Additionally, unstable_Profiling is null in React Native environments.

Basic Usage

import { 
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_NormalPriority,
  unstable_UserBlockingPriority
} from "scheduler";

// Schedule a task with normal priority
const task = unstable_scheduleCallback(unstable_NormalPriority, (didTimeout) => {
  console.log("Task executed, timed out:", didTimeout);
  // Return a continuation function if work is not complete
  if (workRemaining) {
    return (didTimeout) => {
      // Continue work in next time slice
    };
  }
  // Return null/undefined when work is complete
});

// Schedule high-priority task
const urgentTask = unstable_scheduleCallback(
  unstable_UserBlockingPriority,
  () => {
    // Handle user interaction
    updateUI();
  }
);

// Cancel a task if needed
unstable_cancelCallback(task);

Architecture

Scheduler is built around several key components:

Priority System: Five priority levels from Immediate to Idle with different timeout behaviors
Task Queue: Min-heap data structure for efficient priority-based scheduling
Time Slicing: Yields control to browser after configurable time intervals (default 5ms)
Multiple Backends: Different implementations for browser, React Native, testing, and PostTask API
Profiling Support: Optional performance monitoring and event logging

Capabilities

Core Scheduling

Essential functions for scheduling and managing tasks with priority-based execution.

function unstable_scheduleCallback(
  priorityLevel: PriorityLevel,
  callback: (didTimeout: boolean) => void | ((didTimeout: boolean) => void | null),
  options?: { delay: number }
): Task;

function unstable_cancelCallback(task: Task): void;

function unstable_getCurrentPriorityLevel(): PriorityLevel;

Core Scheduling

Priority Management

Functions for executing code with specific priority contexts and managing priority levels.

function unstable_runWithPriority<T>(
  priorityLevel: PriorityLevel,
  eventHandler: () => T
): T;

function unstable_next<T>(eventHandler: () => T): T;

function unstable_wrapCallback<T>(callback: T): T;

Priority Management

Timing and Yielding

Utilities for controlling when the scheduler yields control and managing frame rates.

function unstable_shouldYield(): boolean;
function unstable_now(): number;
function unstable_requestPaint(): void;
function unstable_forceFrameRate(fps: number): void;

Timing and Yielding

Testing Utilities

Mock scheduler functions specifically designed for testing environments and time control.

function unstable_flushAll(): void;
function unstable_flushExpired(): void;
function unstable_advanceTime(ms: number): void;
function reset(): void;

Testing Utilities

Profiling

Performance monitoring and event logging capabilities for development and debugging.

const unstable_Profiling: {
  startLoggingProfilingEvents(): void;
  stopLoggingProfilingEvents(): ArrayBuffer | null;
} | null;

Profiling

Types

type PriorityLevel = 0 | 1 | 2 | 3 | 4 | 5;

interface Task {
  id: number;
  callback: ((didTimeout: boolean) => void | ((didTimeout: boolean) => void | null)) | null;
  priorityLevel: PriorityLevel;
  startTime: number;
  expirationTime: number;
  sortIndex: number;
  isQueued?: boolean;
}

type Callback = (didTimeout: boolean) => void | Callback | null;

Priority Level Constants

const unstable_ImmediatePriority: 1;      // Times out immediately
const unstable_UserBlockingPriority: 2;  // Times out in 250ms
const unstable_NormalPriority: 3;        // Times out in 5000ms (default)
const unstable_LowPriority: 4;           // Times out in 10000ms
const unstable_IdlePriority: 5;          // Never times out