scheduler 0.25.0: unstable_getFirstCallbackNode

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 scheduler.unstable_getFirstCallbackNode 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:
  - scheduler.unstable_getFirstCallbackNode

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:161468c9c6e946e8d5ed13b6931445561f04f41211769fcb6d9199221eeae790","contract":["scheduler.unstable_getFirstCallbackNode is exported as a function","scheduler.unstable_getFirstCallbackNode returns null when no tasks are queued","scheduler.unstable_getFirstCallbackNode returns the task descriptor at the head of the task queue","scheduler.unstable_getFirstCallbackNode prioritizes earlier expiring tasks at the queue head","scheduler.unstable_getFirstCallbackNode retains node with null callback when head task is cancelled"],"goal":"verify scheduler.unstable_getFirstCallbackNode in pkg:npm/scheduler@0.25.0","kind":"HOW","packages":["pkg:npm/scheduler@0.25.0"],"schemaVersion":1,"symbols":["scheduler.unstable_getFirstCallbackNode"]},"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":["scheduler.unstable_getFirstCallbackNode"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-scheduler-get-first-callback-node",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-scheduler-get-first-callback-node",
      "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-get-first-callback-node",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of scheduler unstable_getFirstCallbackNode",
  "main": "src/index.js",
  "dependencies": {
    "scheduler": "0.25.0"
  }
}

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

const scheduler = require('scheduler');

/**
 * Returns the current head callback node in the scheduler task queue.
 * @returns {object|null} The task node at the head of the queue, or null if empty.
 */
function getFirstCallbackNode() {
  return scheduler.unstable_getFirstCallbackNode();
}

/**
 * Schedules a task with priority and returns the task descriptor.
 * @param {number} priority - The priority level constant.
 * @param {Function} callback - The callback function.
 * @returns {object} The scheduled task object.
 */
function scheduleTask(priority, callback) {
  return scheduler.unstable_scheduleCallback(priority, callback);
}

/**
 * Cancels a scheduled task.
 * @param {object} task - The task descriptor to cancel.
 */
function cancelTask(task) {
  scheduler.unstable_cancelCallback(task);
}

module.exports = {
  scheduler,
  getFirstCallbackNode,
  scheduleTask,
  cancelTask
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  scheduler,
  getFirstCallbackNode,
  scheduleTask,
  cancelTask
} = require('../src/index.js');

// 1. scheduler.unstable_getFirstCallbackNode is exported as a function
assert.equal(
  typeof scheduler.unstable_getFirstCallbackNode,
  'function',
  'unstable_getFirstCallbackNode must be a function'
);

// 2. scheduler.unstable_getFirstCallbackNode returns null when no tasks are queued
{
  const head = getFirstCallbackNode();
  assert.equal(head, null, 'getFirstCallbackNode must return null when queue is empty');
}

// 3. scheduler.unstable_getFirstCallbackNode returns the task descriptor at the head of the task queue
{
  const noop = () => {};
  const task = scheduleTask(scheduler.unstable_NormalPriority, noop);
  const head = getFirstCallbackNode();

  assert.ok(head, 'Task descriptor must be returned');
  assert.equal(head, task, 'Head node must match scheduled task');
  assert.equal(typeof head.id, 'number', 'Task must have a numeric id');
  assert.equal(head.callback, noop, 'Task callback must match provided function');
  assert.equal(
    head.priorityLevel,
    scheduler.unstable_NormalPriority,
    'Task priority level must match NormalPriority'
  );
  assert.equal(typeof head.startTime, 'number', 'Task startTime must be numeric');
  assert.equal(typeof head.expirationTime, 'number', 'Task expirationTime must be numeric');
  assert.equal(typeof head.sortIndex, 'number', 'Task sortIndex must be numeric');
}

// 4. scheduler.unstable_getFirstCallbackNode prioritizes earlier expiring tasks at the queue head
{
  // Current queue has normal task (id 1, expiration startTime + 5000)
  // Schedule a low priority task (expiration startTime + 10000)
  const lowTask = scheduleTask(scheduler.unstable_LowPriority, () => {});
  // Head is still normal task because normal expires earlier than low
  const normalHead = getFirstCallbackNode();
  assert.equal(normalHead.priorityLevel, scheduler.unstable_NormalPriority);

  // Schedule an immediate priority task (expiration startTime - 1)
  const immediateTask = scheduleTask(scheduler.unstable_ImmediatePriority, () => {});
  const immediateHead = getFirstCallbackNode();
  assert.equal(immediateHead, immediateTask, 'Immediate task must become head of the queue');
}

// 5. scheduler.unstable_getFirstCallbackNode retains node with null callback when head task is cancelled
{
  const headBeforeCancel = getFirstCallbackNode();
  assert.ok(headBeforeCancel, 'Queue must have a head node');
  cancelTask(headBeforeCancel);

  const headAfterCancel = getFirstCallbackNode();
  assert.equal(headAfterCancel, headBeforeCancel, 'Cancelled task remains at head of min-heap until flushed');
  assert.equal(headAfterCancel.callback, null, 'Cancelled head task callback must be null');
}

console.log('Contract assertions for scheduler.unstable_getFirstCallbackNode passed.');