tessl/npm-scheduler

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

—

Pending

Overview

Eval results

Files

Core Scheduling

Name: tessl/npm-scheduler
Author: tessl

Essential functions for scheduling and managing tasks with priority-based execution in the scheduler library.

Capabilities

Schedule Callback

Schedules a task to be executed based on priority level with optional delay.

/**
 * Schedule a callback to be executed based on priority level
 * @param priorityLevel - Priority level (1-5) determining execution order and timeout
 * @param callback - Function to execute, can return continuation function
 * @param options - Optional configuration object
 * @returns Task object that can be used to cancel the scheduled callback
 */
function unstable_scheduleCallback(
  priorityLevel: PriorityLevel,
  callback: (didTimeout: boolean) => void | ((didTimeout: boolean) => void | null),
  options?: { delay: number }
): Task;

The callback function receives a didTimeout parameter indicating whether the task exceeded its priority-based timeout. Tasks can return a continuation function to spread work across multiple time slices.

Usage Examples:

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

// Simple task
const task = unstable_scheduleCallback(unstable_NormalPriority, (didTimeout) => {
  console.log("Task executed, timed out:", didTimeout);
});

// Task with delay
const delayedTask = unstable_scheduleCallback(
  unstable_NormalPriority,
  (didTimeout) => {
    console.log("Delayed task executed");
  },
  { delay: 1000 } // Delay execution by 1 second
);

// Task with continuation (time slicing)
let workItems = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const processWork = unstable_scheduleCallback(unstable_NormalPriority, function work(didTimeout) {
  // Process some work items
  const itemsToProcess = Math.min(3, workItems.length);
  for (let i = 0; i < itemsToProcess; i++) {
    const item = workItems.shift();
    console.log("Processing item:", item);
  }
  
  // If more work remains, return continuation
  if (workItems.length > 0) {
    return work; // Continue in next time slice
  }
  // Return null/undefined when work is complete
});

Cancel Callback

Cancels a previously scheduled task.

/**
 * Cancel a previously scheduled callback
 * @param task - Task object returned by unstable_scheduleCallback
 */
function unstable_cancelCallback(task: Task): void;

Usage Examples:

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

const task = unstable_scheduleCallback(unstable_NormalPriority, () => {
  console.log("This will not execute");
});

// Cancel the task before it executes
unstable_cancelCallback(task);

// Conditional cancellation
const conditionalTask = unstable_scheduleCallback(unstable_NormalPriority, () => {
  console.log("Conditional task executed");
});

if (shouldCancel) {
  unstable_cancelCallback(conditionalTask);
}

Get Current Priority Level

Returns the current priority level of the scheduler.

/**
 * Get the current priority level
 * @returns Current priority level (1-5)
 */
function unstable_getCurrentPriorityLevel(): PriorityLevel;

Usage Examples:

import { 
  unstable_getCurrentPriorityLevel,
  unstable_runWithPriority,
  unstable_UserBlockingPriority 
} from "scheduler";

// Check current priority
const currentPriority = unstable_getCurrentPriorityLevel();
console.log("Current priority:", currentPriority); // 3 (Normal priority)

// Priority changes within runWithPriority
unstable_runWithPriority(unstable_UserBlockingPriority, () => {
  const priority = unstable_getCurrentPriorityLevel();
  console.log("Priority inside:", priority); // 2 (UserBlocking priority)
});

Priority Levels and Timeouts

Each priority level has different timeout behavior:

Immediate Priority (1): Times out immediately (-1ms)
UserBlocking Priority (2): Times out after 250ms
Normal Priority (3): Times out after 5000ms
Low Priority (4): Times out after 10000ms
Idle Priority (5): Never times out

Tasks are executed in priority order, with higher priority (lower number) tasks executing first. When a task times out, the didTimeout parameter in the callback will be true.

Task Object

interface Task {
  /** Unique identifier for the task */
  id: number;
  /** Callback function or null if cancelled */
  callback: ((didTimeout: boolean) => void | ((didTimeout: boolean) => void | null)) | null;
  /** Priority level of the task */
  priorityLevel: PriorityLevel;
  /** When the task should start executing (milliseconds) */
  startTime: number;
  /** When the task expires based on priority timeout */
  expirationTime: number;
  /** Index used for heap sorting (either startTime or expirationTime) */
  sortIndex: number;
  /** Whether task is currently in the queue (profiling builds only) */
  isQueued?: boolean;
}

Install with Tessl CLI