@vitest/utils 4.1.10: delay

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 @vitest/utils.delay in pkg:npm/%40vitest/utils@4.1.10
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40vitest/utils@4.1.10
Demonstrate these symbols/APIs:
  - @vitest/utils.delay

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:109bd8d983a62470d059f0f037cb967196ce76adab100dfac9f9aced075c2057","contract":["delay returns a Promise that resolves to undefined after the specified millisecond timeout","delay defers execution asynchronously even when timeout is zero","delay uses custom scheduler function when provided instead of global setTimeout","delay integrates with getSafeTimers to delay execution using unmocked native timers","delay supports concurrent invocations that resolve independently according to their timeouts","delay allows manual control and early cancellation through scheduler coordination"],"goal":"verify @vitest/utils.delay in pkg:npm/%40vitest/utils@4.1.10","kind":"HOW","packages":["pkg:npm/%40vitest/utils@4.1.10"],"schemaVersion":1,"symbols":["@vitest/utils.delay"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40vitest/utils@4.1.10"],"schemaVersion":1,"subject":"pkg:npm/%40vitest/utils@4.1.10","symbols":["@vitest/utils.delay"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-vitest-utils-delay",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-utils-delay",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@vitest/utils": "4.1.10"
      }
    },
    "node_modules/@vitest/pretty-format": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.10.tgz",
      "integrity": "sha512-W1HsjSH4MXQ9YfmmhLAoIYf1HRfekQCGngeIgcei6MP5QQGWUe0gkopdZQaVCFO+JDJMrAJGwa5pRpNpvy4P8Q==",
      "license": "MIT",
      "dependencies": {
        "tinyrainbow": "^3.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/utils": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.10.tgz",
      "integrity": "sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==",
      "license": "MIT",
      "dependencies": {
        "@vitest/pretty-format": "4.1.10",
        "convert-source-map": "^2.0.0",
        "tinyrainbow": "^3.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/convert-source-map": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
      "license": "MIT"
    },
    "node_modules/tinyrainbow": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.1.tgz",
      "integrity": "sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "sample-vitest-utils-delay",
  "version": "1.0.0",
  "description": "Clean-room verification sample for @vitest/utils.delay",
  "type": "module",
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@vitest/utils": "4.1.10"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @vitest/utils.delay in pkg:npm/%40vitest/utils@4.1.10",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40vitest/utils@4.1.10"
  ],
  "symbols": [
    "@vitest/utils.delay"
  ]
}

import { delay, getSafeTimers, setSafeTimers } from '@vitest/utils/timers';

/**
 * Pause execution for a given duration in milliseconds.
 *
 * @param {number} ms - Milliseconds to delay
 * @param {Function} [scheduler] - Optional scheduler function
 * @returns {Promise<void>}
 */
export function sleep(ms, scheduler) {
  return delay(ms, scheduler);
}

/**
 * Execute a callback after a specified delay.
 *
 * @param {number} ms - Delay in milliseconds
 * @param {Function} callback - Function to run after delay
 * @returns {Promise<any>}
 */
export async function delayedAction(ms, callback) {
  await delay(ms);
  return callback();
}

/**
 * Pause execution using safe native timers unaffected by fake timer mocks.
 *
 * @param {number} ms - Delay in milliseconds
 * @returns {Promise<void>}
 */
export async function safeSleep(ms) {
  const { setTimeout: safeTimeout } = getSafeTimers();
  return delay(ms, safeTimeout);
}

export { delay, getSafeTimers, setSafeTimers };
export default delay;

import assert from 'node:assert/strict';
import { delay, getSafeTimers, setSafeTimers } from '@vitest/utils/timers';
import { sleep, delayedAction, safeSleep } from '../src/index.mjs';

// 1. delay returns a Promise that resolves to undefined after the specified millisecond timeout
{
  const start = Date.now();
  const promise = delay(20);
  assert.ok(promise instanceof Promise);
  const result = await promise;
  assert.equal(result, undefined);
  const elapsed = Date.now() - start;
  assert.ok(elapsed >= 15, `Elapsed time ${elapsed}ms should be at least 15ms`);

  // Verify helper sleep
  const sleepResult = await sleep(10);
  assert.equal(sleepResult, undefined);
}

// 2. delay defers execution asynchronously even when timeout is zero
{
  let executed = false;
  const promise = delay(0).then(() => {
    executed = true;
  });
  assert.equal(executed, false, 'Promise should not resolve synchronously');
  await promise;
  assert.equal(executed, true, 'Promise should resolve after event loop tick');
}

// 3. delay uses custom scheduler function when provided instead of global setTimeout
{
  let schedulerCalled = false;
  let passedTimeout = -1;
  let passedFnType = '';

  const customScheduler = (fn, timeout) => {
    schedulerCalled = true;
    passedTimeout = timeout;
    passedFnType = typeof fn;
    fn();
  };

  await delay(50, customScheduler);
  assert.equal(schedulerCalled, true);
  assert.equal(passedTimeout, 50);
  assert.equal(passedFnType, 'function');
}

// 4. delay integrates with getSafeTimers to delay execution using unmocked native timers
{
  setSafeTimers();
  const safeTimers = getSafeTimers();
  assert.equal(typeof safeTimers.setTimeout, 'function');
  assert.equal(typeof safeTimers.clearTimeout, 'function');

  const start = Date.now();
  await safeSleep(20);
  const elapsed = Date.now() - start;
  assert.ok(elapsed >= 15, `Safe delay elapsed time ${elapsed}ms should be at least 15ms`);
}

// 5. delay supports concurrent invocations that resolve independently according to their timeouts
{
  const timeline = [];
  const task1 = delay(40).then(() => timeline.push('task-40ms'));
  const task2 = delay(10).then(() => timeline.push('task-10ms'));
  const task3 = delayedAction(25, () => timeline.push('task-25ms'));

  await Promise.all([task1, task2, task3]);
  assert.deepEqual(timeline, ['task-10ms', 'task-25ms', 'task-40ms']);
}

// 6. delay allows manual control and early cancellation through scheduler coordination
{
  let timerId;
  let resolved = false;

  const promise = delay(1000, (fn) => {
    timerId = setTimeout(fn, 1000);
  }).then(() => {
    resolved = true;
  });

  clearTimeout(timerId);
  await delay(50);
  assert.equal(resolved, false, 'Cleared timer should not trigger promise resolution');
}

console.log('Contract tests passed successfully.');