scheduler 0.25.0: unstable_NormalPriority

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_NormalPriority 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_NormalPriority
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:f222cad980c45ff2e20fc08f3dcc3b82bc3e8abcbe7261a1fe155b04bd7186d9","constraints":{"executionContext":"node"},"contract":["scheduler exports unstable_NormalPriority as a numeric priority constant with value 3","unstable_getCurrentPriorityLevel returns unstable_NormalPriority as the default ambient priority level","unstable_runWithPriority executes a function within the scope of unstable_NormalPriority and returns its result","unstable_runWithPriority restores the previous priority level after execution finishes or throws","unstable_scheduleCallback schedules a task with priorityLevel set to unstable_NormalPriority and standard 5000ms timeout","unstable_scheduleCallback executes normal priority tasks after immediate priority tasks and before low priority tasks","unstable_wrapCallback captures unstable_NormalPriority and preserves it when invoked from other priority scopes","unstable_cancelCallback cancels a task scheduled with unstable_NormalPriority"],"goal":"verify unstable_NormalPriority in pkg:npm/scheduler@0.25.0","kind":"HOW","packages":["pkg:npm/scheduler@0.25.0"],"schemaVersion":1,"symbols":["unstable_NormalPriority"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/scheduler@0.25.0"],"schemaVersion":1,"subject":"pkg:npm/scheduler@0.25.0","symbols":["unstable_NormalPriority"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-scheduler-normalpriority",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-scheduler-normalpriority",
      "version": "1.0.0",
      "license": "MIT-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-normalpriority",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for unstable_NormalPriority in scheduler@0.25.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "scheduler": "0.25.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify unstable_NormalPriority in pkg:npm/scheduler@0.25.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/scheduler@0.25.0"
  ],
  "symbols": [
    "unstable_NormalPriority"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const scheduler = require('scheduler');

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

/**
 * Execute a function within the scope of unstable_NormalPriority.
 *
 * @param {Function} callback - Function to execute.
 * @returns {*} Return value from callback.
 */
function runWithNormalPriority(callback) {
  return unstable_runWithPriority(unstable_NormalPriority, callback);
}

/**
 * Schedule a task with unstable_NormalPriority.
 *
 * @param {Function} callback - Task callback.
 * @param {object} [options] - Options such as delay.
 * @returns {object} Task node descriptor.
 */
function scheduleNormalTask(callback, options) {
  return unstable_scheduleCallback(unstable_NormalPriority, callback, options);
}

/**
 * Wrap a callback so it captures and executes under unstable_NormalPriority.
 *
 * @param {Function} callback - Callback function.
 * @returns {Function} Wrapped callback.
 */
function wrapWithNormalPriority(callback) {
  return unstable_runWithPriority(unstable_NormalPriority, () => {
    return unstable_wrapCallback(callback);
  });
}

module.exports = {
  scheduler,
  unstable_NormalPriority,
  unstable_ImmediatePriority,
  unstable_UserBlockingPriority,
  unstable_LowPriority,
  unstable_IdlePriority,
  unstable_runWithPriority,
  unstable_getCurrentPriorityLevel,
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_wrapCallback,
  runWithNormalPriority,
  scheduleNormalTask,
  wrapWithNormalPriority
};

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

const require = createRequire(import.meta.url);
const {
  scheduler,
  unstable_NormalPriority,
  unstable_ImmediatePriority,
  unstable_LowPriority,
  unstable_runWithPriority,
  unstable_getCurrentPriorityLevel,
  unstable_scheduleCallback,
  unstable_cancelCallback,
  unstable_wrapCallback,
  runWithNormalPriority,
  scheduleNormalTask,
  wrapWithNormalPriority
} = require('../src/index.js');

async function runTests() {
  // 1. scheduler exports unstable_NormalPriority as a numeric priority constant with value 3
  assert.equal(typeof scheduler.unstable_NormalPriority, 'number', 'unstable_NormalPriority must be a number');
  assert.equal(scheduler.unstable_NormalPriority, 3, 'unstable_NormalPriority value should be 3');
  assert.equal(unstable_NormalPriority, 3, 'unstable_NormalPriority export should be 3');

  // 2. unstable_getCurrentPriorityLevel returns unstable_NormalPriority as the default ambient priority level
  const defaultPriority = unstable_getCurrentPriorityLevel();
  assert.equal(defaultPriority, unstable_NormalPriority, 'Default ambient priority should be NormalPriority (3)');

  // 3. unstable_runWithPriority executes a function within the scope of unstable_NormalPriority and returns its result
  let observedInNormal = null;
  const result = runWithNormalPriority(() => {
    observedInNormal = unstable_getCurrentPriorityLevel();
    return 'computed-result';
  });
  assert.equal(observedInNormal, unstable_NormalPriority, 'Observed priority inside scope should be NormalPriority');
  assert.equal(result, 'computed-result', 'runWithPriority should return callback return value');

  // 4. unstable_runWithPriority restores the previous priority level after execution finishes or throws
  unstable_runWithPriority(unstable_LowPriority, () => {
    assert.equal(unstable_getCurrentPriorityLevel(), unstable_LowPriority, 'Outer level is LowPriority');
    const nestedResult = runWithNormalPriority(() => {
      assert.equal(unstable_getCurrentPriorityLevel(), unstable_NormalPriority, 'Inner level is NormalPriority');
      return 100;
    });
    assert.equal(nestedResult, 100);
    assert.equal(unstable_getCurrentPriorityLevel(), unstable_LowPriority, 'Level restored to LowPriority after normal return');

    assert.throws(
      () => {
        runWithNormalPriority(() => {
          assert.equal(unstable_getCurrentPriorityLevel(), unstable_NormalPriority);
          throw new Error('intentional error');
        });
      },
      /intentional error/
    );
    assert.equal(unstable_getCurrentPriorityLevel(), unstable_LowPriority, 'Level restored to LowPriority after error');
  });

  // 5. unstable_scheduleCallback schedules a task with priorityLevel set to unstable_NormalPriority and standard 5000ms timeout
  const task = scheduleNormalTask(() => 'done');
  assert.equal(task.priorityLevel, unstable_NormalPriority, 'Task priorityLevel must be NormalPriority (3)');
  assert.equal(typeof task.id, 'number', 'Task should have numeric ID');
  assert.equal(typeof task.expirationTime, 'number', 'Task should have expirationTime');
  assert.equal(typeof task.startTime, 'number', 'Task should have startTime');
  assert.equal(task.expirationTime - task.startTime, 5000, 'Normal priority task timeout offset must be 5000ms');

  // 6. unstable_scheduleCallback executes normal priority tasks after immediate priority tasks and before low priority tasks
  const executionOrder = [];
  await new Promise((resolve) => {
    unstable_scheduleCallback(unstable_LowPriority, () => {
      executionOrder.push('low');
      if (executionOrder.length === 3) resolve();
    });
    unstable_scheduleCallback(unstable_ImmediatePriority, () => {
      executionOrder.push('immediate');
      if (executionOrder.length === 3) resolve();
    });
    unstable_scheduleCallback(unstable_NormalPriority, () => {
      executionOrder.push('normal');
      if (executionOrder.length === 3) resolve();
    });
  });
  assert.deepEqual(
    executionOrder,
    ['immediate', 'normal', 'low'],
    'Callbacks should execute in order of priority: immediate, normal, then low'
  );

  // 7. unstable_wrapCallback captures unstable_NormalPriority and preserves it when invoked from other priority scopes
  const normalWrapped = wrapWithNormalPriority(() => {
    return unstable_getCurrentPriorityLevel();
  });
  unstable_runWithPriority(unstable_LowPriority, () => {
    assert.equal(unstable_getCurrentPriorityLevel(), unstable_LowPriority, 'Ambient level is LowPriority');
    const executedLevel = normalWrapped();
    assert.equal(executedLevel, unstable_NormalPriority, 'Wrapped callback executes in NormalPriority');
  });

  // 8. unstable_cancelCallback cancels a task scheduled with unstable_NormalPriority
  let cancelledExecuted = false;
  const taskToCancel = scheduleNormalTask(() => {
    cancelledExecuted = true;
  });
  unstable_cancelCallback(taskToCancel);
  assert.equal(taskToCancel.callback, null, 'Cancelled task callback should be null');

  // Wait briefly to ensure cancelled task did not run
  await new Promise((resolve) => setTimeout(resolve, 50));
  assert.equal(cancelledExecuted, false, 'Cancelled normal priority task must not execute');

  console.log('All contract assertions for scheduler.unstable_NormalPriority passed successfully.');
}

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