scheduler 0.25.0: unstable_UserBlockingPriority

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify unstable_UserBlockingPriority in pkg:npm/scheduler@0.25.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/scheduler@0.25.0
Demonstrate these symbols/APIs:
  - unstable_UserBlockingPriority

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:34a8932e0c955b9dd756104ac850967611238760330cfa067c963dd15727387b","contract":["getUserBlockingPriority returns numeric constant for user-blocking priority level","isUserBlockingPriority identifies user-blocking priority correctly and rejects other priority levels","runWithUserBlockingPriority executes callback under user-blocking priority context","runWithUserBlockingPriority restores previous priority level after callback completion","wrapWithUserBlockingPriority binds user-blocking priority to callback execution","scheduleUserBlockingCallback creates task node with user-blocking priority","cancelScheduledTask invalidates scheduled task callback","comparePriority confirms user-blocking priority is higher than normal and lower than immediate"],"goal":"verify unstable_UserBlockingPriority in pkg:npm/scheduler@0.25.0","kind":"HOW","packages":["pkg:npm/scheduler@0.25.0"],"schemaVersion":1,"symbols":["unstable_UserBlockingPriority"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/scheduler@0.25.0"],"schemaVersion":1,"subject":"pkg:npm/scheduler@0.25.0","symbols":["unstable_UserBlockingPriority"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-scheduler-user-blocking",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-scheduler-user-blocking",
      "version": "1.0.0",
      "dependencies": {
        "scheduler": "0.25.0"
      }
    },
    "node_modules/scheduler": {
      "version": "0.25.0",
      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.25.0.tgz",
      "integrity": "sha512-xFVuu11jh+xcO7JOAGJNOXld8/TcEHK/4CituBUeUb5hqxJLj9YuemAEuvm9gQ/+pgXYfbQuqAkiYu+u7YEsNA==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-scheduler-user-blocking",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "scheduler": "0.25.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify unstable_UserBlockingPriority in pkg:npm/scheduler@0.25.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/scheduler@0.25.0"
  ],
  "symbols": [
    "unstable_UserBlockingPriority"
  ]
}

import Scheduler from "scheduler";

const {
  unstable_ImmediatePriority,
  unstable_UserBlockingPriority,
  unstable_NormalPriority,
  unstable_LowPriority,
  unstable_IdlePriority,
  unstable_runWithPriority,
  unstable_getCurrentPriorityLevel,
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_wrapCallback,
} = Scheduler;

/**
 * Returns the numerical constant for unstable_UserBlockingPriority.
 * @returns {number} The priority level number (2).
 */
export function getUserBlockingPriority() {
  return unstable_UserBlockingPriority;
}

/**
 * Checks whether a given priority level matches unstable_UserBlockingPriority.
 * @param {number} priority - The priority level to check.
 * @returns {boolean} True if matching user-blocking priority.
 */
export function isUserBlockingPriority(priority) {
  return priority === unstable_UserBlockingPriority;
}

/**
 * Runs a given callback function with user-blocking priority level.
 * @template T
 * @param {() => T} fn - The callback to execute.
 * @returns {T} The result of the callback function.
 */
export function runWithUserBlockingPriority(fn) {
  return unstable_runWithPriority(unstable_UserBlockingPriority, fn);
}

/**
 * Returns the current active scheduler priority level.
 * @returns {number} The active priority level.
 */
export function getCurrentPriorityLevel() {
  return unstable_getCurrentPriorityLevel();
}

/**
 * Wraps a callback to ensure it executes with user-blocking priority.
 * @template T
 * @param {(...args: any[]) => T} fn - The callback to wrap.
 * @returns {(...args: any[]) => T} The wrapped callback.
 */
export function wrapWithUserBlockingPriority(fn) {
  return unstable_runWithPriority(unstable_UserBlockingPriority, () => {
    return unstable_wrapCallback(fn);
  });
}

/**
 * Schedules a callback task with user-blocking priority.
 * @param {Function} callback - Task callback.
 * @param {object} [options] - Scheduling options (e.g. delay).
 * @returns {object} The scheduled task node.
 */
export function scheduleUserBlockingCallback(callback, options) {
  return unstable_scheduleCallback(unstable_UserBlockingPriority, callback, options);
}

/**
 * Cancels a previously scheduled task.
 * @param {object} taskNode - The task node returned by scheduleCallback.
 */
export function cancelScheduledTask(taskNode) {
  return unstable_cancelCallback(taskNode);
}

/**
 * Compares two priority levels. Returns negative if priorityA is higher priority than priorityB
 * (lower numerical value means higher priority in Scheduler: 1=Immediate, 2=UserBlocking, 3=Normal, 4=Low, 5=Idle).
 * @param {number} priorityA
 * @param {number} priorityB
 * @returns {number} Negative if priorityA is higher, 0 if equal, positive if priorityB is higher.
 */
export function comparePriority(priorityA, priorityB) {
  return priorityA - priorityB;
}

export default Scheduler;
export {
  unstable_ImmediatePriority,
  unstable_UserBlockingPriority,
  unstable_NormalPriority,
  unstable_LowPriority,
  unstable_IdlePriority,
  unstable_runWithPriority,
  unstable_getCurrentPriorityLevel,
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_wrapCallback,
};

import assert from "node:assert/strict";
import {
  getUserBlockingPriority,
  isUserBlockingPriority,
  runWithUserBlockingPriority,
  getCurrentPriorityLevel,
  wrapWithUserBlockingPriority,
  scheduleUserBlockingCallback,
  cancelScheduledTask,
  comparePriority,
  unstable_ImmediatePriority,
  unstable_UserBlockingPriority,
  unstable_NormalPriority,
  unstable_LowPriority,
  unstable_IdlePriority,
} from "../src/index.mjs";

async function runContract() {
  // 1. getUserBlockingPriority returns numeric constant for user-blocking priority level
  const priority = getUserBlockingPriority();
  assert.equal(typeof priority, "number");
  assert.equal(priority, 2);
  assert.equal(priority, unstable_UserBlockingPriority);

  // 2. isUserBlockingPriority identifies user-blocking priority correctly and rejects other priority levels
  assert.equal(isUserBlockingPriority(unstable_UserBlockingPriority), true);
  assert.equal(isUserBlockingPriority(2), true);
  assert.equal(isUserBlockingPriority(unstable_ImmediatePriority), false);
  assert.equal(isUserBlockingPriority(unstable_NormalPriority), false);
  assert.equal(isUserBlockingPriority(unstable_LowPriority), false);
  assert.equal(isUserBlockingPriority(unstable_IdlePriority), false);
  assert.equal(isUserBlockingPriority(999), false);

  // 3. runWithUserBlockingPriority executes callback under user-blocking priority context
  let observedPriorityInside = null;
  const computationResult = runWithUserBlockingPriority(() => {
    observedPriorityInside = getCurrentPriorityLevel();
    return "executed_successfully";
  });
  assert.equal(computationResult, "executed_successfully");
  assert.equal(observedPriorityInside, 2);
  assert.equal(observedPriorityInside, unstable_UserBlockingPriority);

  // 4. runWithUserBlockingPriority restores previous priority level after callback completion
  const initialPriority = getCurrentPriorityLevel();
  runWithUserBlockingPriority(() => {
    assert.equal(getCurrentPriorityLevel(), unstable_UserBlockingPriority);
  });
  assert.equal(getCurrentPriorityLevel(), initialPriority);

  // 5. wrapWithUserBlockingPriority binds user-blocking priority to callback execution
  let wrappedObservedPriority = null;
  const wrappedFn = wrapWithUserBlockingPriority(() => {
    wrappedObservedPriority = getCurrentPriorityLevel();
    return "wrapped_ok";
  });
  const wrappedResult = wrappedFn();
  assert.equal(wrappedResult, "wrapped_ok");
  assert.equal(wrappedObservedPriority, 2);
  assert.equal(wrappedObservedPriority, unstable_UserBlockingPriority);

  // 6. scheduleUserBlockingCallback creates task node with user-blocking priority
  let taskExecuted = false;
  const taskNode = scheduleUserBlockingCallback(() => {
    taskExecuted = true;
  });
  assert.equal(typeof taskNode, "object");
  assert.notEqual(taskNode, null);
  assert.equal(taskNode.priorityLevel, unstable_UserBlockingPriority);
  assert.equal(typeof taskNode.id, "number");

  // 7. cancelScheduledTask invalidates scheduled task callback
  const taskToCancel = scheduleUserBlockingCallback(() => {
    throw new Error("Should not be called");
  });
  cancelScheduledTask(taskToCancel);
  assert.equal(taskToCancel.callback, null);

  // 8. comparePriority confirms user-blocking priority is higher than normal and lower than immediate
  assert.ok(comparePriority(unstable_UserBlockingPriority, unstable_NormalPriority) < 0);
  assert.ok(comparePriority(unstable_UserBlockingPriority, unstable_LowPriority) < 0);
  assert.ok(comparePriority(unstable_UserBlockingPriority, unstable_IdlePriority) < 0);
  assert.ok(comparePriority(unstable_UserBlockingPriority, unstable_ImmediatePriority) > 0);
  assert.equal(comparePriority(unstable_UserBlockingPriority, 2), 0);

  console.log("All unstable_UserBlockingPriority contract assertions passed successfully.");
}

runContract().catch((err) => {
  console.error("Contract test failed:", err);
  process.exit(1);
});