@sinonjs/fake-timers 15.4.0: createClock

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 @sinonjs/fake-timers.createClock in pkg:npm/%40sinonjs/fake-timers@15.4.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40sinonjs/fake-timers@15.4.0
Demonstrate these symbols/APIs:
  - @sinonjs/fake-timers.createClock
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - 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:9000e220f8b1ea487ef923122ac81d6fca26b029fc7dd81749c3130576ff7214","constraints":{"executionContext":"node"},"contract":["createClock creates an independent fake clock initialized at the specified start timestamp","clock.setTimeout schedules a timer that fires callback with provided arguments when advanced past delay","clock.clearTimeout cancels a scheduled timer so it does not fire","clock.setInterval repeatedly invokes callback every interval until clearInterval","clock.tick synchronously advances clock time by ms and executes expired timers in chronological order","clock.tickAsync advances clock time asynchronously, awaiting resolved promises returned by async callbacks","clock.runAll exhausts and triggers all scheduled timers until the queue is empty","clock.runToLast advances time to the expiration timestamp of the latest scheduled timer and fires pending timers","clock.setSystemTime modifies current clock time without executing scheduled timers","clock.reset resets clock.now back to the initial start timestamp and clears all active timers","clock.countTimers returns the number of active scheduled timers remaining in the queue","clock.next advances clock time to the very next scheduled timer and executes it"],"goal":"verify @sinonjs/fake-timers.createClock in pkg:npm/%40sinonjs/fake-timers@15.4.0","kind":"HOW","packages":["pkg:npm/%40sinonjs/fake-timers@15.4.0"],"schemaVersion":1,"symbols":["@sinonjs/fake-timers.createClock"]},"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","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40sinonjs/fake-timers@15.4.0"],"schemaVersion":1,"subject":"pkg:npm/%40sinonjs/fake-timers@15.4.0","symbols":["@sinonjs/fake-timers.createClock"],"verifierAdapter":"node-typescript@1"}

import FakeTimers from '@sinonjs/fake-timers';

export const { createClock } = FakeTimers;

/**
 * Creates a standalone Clock instance.
 *
 * @param {number|Date} [start=0] - Initial timestamp for the clock
 * @param {number} [loopLimit=10000] - Max iterations for runAll / runToLast to prevent infinite loops
 * @returns {import('@sinonjs/fake-timers').Clock} Clock instance
 */
export function initializeClock(start = 0, loopLimit = 10000) {
  return createClock(start, loopLimit);
}

export default {
  createClock,
  initializeClock,
};

{
  "name": "sample-fake-timers-create-clock",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-fake-timers-create-clock",
      "version": "1.0.0",
      "dependencies": {
        "@sinonjs/fake-timers": "15.4.0"
      }
    },
    "node_modules/@sinonjs/commons": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-3.0.1.tgz",
      "integrity": "sha512-K3mCHKQ9sVh8o1C9cxkwxaOmXoAMlDxC1mYyHrjqOWEcBjYr76t96zL2zlj5dUGZ3HSw240X1qgH3Mjf1yJWpQ==",
      "license": "BSD-3-Clause",
      "dependencies": {
        "type-detect": "4.0.8"
      }
    },
    "node_modules/@sinonjs/fake-timers": {
      "version": "15.4.0",
      "resolved": "https://registry.npmjs.org/@sinonjs/fake-timers/-/fake-timers-15.4.0.tgz",
      "integrity": "sha512-DsG+8/LscQIQg68J6Ef3dv10u6nVyetYn923s3/sus5eaGfTo1of5WMZSLf0UJc9KDuKPilPH0UDJCjvNbDNCA==",
      "license": "BSD-3-Clause",
      "dependencies": {
        "@sinonjs/commons": "^3.0.1"
      }
    },
    "node_modules/type-detect": {
      "version": "4.0.8",
      "resolved": "https://registry.npmjs.org/type-detect/-/type-detect-4.0.8.tgz",
      "integrity": "sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g==",
      "license": "MIT",
      "engines": {
        "node": ">=4"
      }
    }
  }
}

{
  "name": "sample-fake-timers-create-clock",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "@sinonjs/fake-timers": "15.4.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @sinonjs/fake-timers.createClock in pkg:npm/%40sinonjs/fake-timers@15.4.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40sinonjs/fake-timers@15.4.0"
  ],
  "symbols": [
    "@sinonjs/fake-timers.createClock"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert/strict';
import FakeTimers, { createClock, initializeClock } from '../index.mjs';

// Contract 1: createClock creates an independent fake clock initialized at the specified start timestamp
{
  const initialTime = 5000;
  const clock = initializeClock(initialTime);
  assert.strictEqual(typeof createClock, 'function');
  assert.strictEqual(typeof clock.setTimeout, 'function');
  assert.strictEqual(typeof clock.clearTimeout, 'function');
  assert.strictEqual(typeof clock.setInterval, 'function');
  assert.strictEqual(typeof clock.clearInterval, 'function');
  assert.strictEqual(typeof clock.tick, 'function');
  assert.strictEqual(typeof clock.tickAsync, 'function');
  assert.strictEqual(typeof clock.runAll, 'function');
  assert.strictEqual(typeof clock.runToLast, 'function');
  assert.strictEqual(typeof clock.setSystemTime, 'function');
  assert.strictEqual(typeof clock.reset, 'function');
  assert.strictEqual(typeof clock.countTimers, 'function');
  assert.strictEqual(typeof clock.next, 'function');
  assert.strictEqual(clock.now, initialTime);
}

// Contract 2: clock.setTimeout schedules a timer that fires callback with provided arguments when advanced past delay
{
  const clock = createClock(1000);
  let executed = false;
  let receivedArgs = [];
  clock.setTimeout((arg1, arg2) => {
    executed = true;
    receivedArgs = [arg1, arg2];
  }, 150, 'alpha', 42);

  assert.strictEqual(executed, false);
  clock.tick(149);
  assert.strictEqual(executed, false);
  assert.strictEqual(clock.now, 1149);

  clock.tick(1);
  assert.strictEqual(executed, true);
  assert.deepEqual(receivedArgs, ['alpha', 42]);
  assert.strictEqual(clock.now, 1150);
}

// Contract 3: clock.clearTimeout cancels a scheduled timer so it does not fire
{
  const clock = createClock(0);
  let executed = false;
  const timerId = clock.setTimeout(() => {
    executed = true;
  }, 100);

  clock.clearTimeout(timerId);
  clock.tick(200);
  assert.strictEqual(executed, false);
  assert.strictEqual(clock.countTimers(), 0);
}

// Contract 4: clock.setInterval repeatedly invokes callback every interval until clearInterval
{
  const clock = createClock(0);
  let count = 0;
  const intervalId = clock.setInterval(() => {
    count++;
  }, 50);

  clock.tick(175);
  assert.strictEqual(count, 3);

  clock.clearInterval(intervalId);
  clock.tick(150);
  assert.strictEqual(count, 3);
}

// Contract 5: clock.tick synchronously advances clock time by ms and executes expired timers in chronological order
{
  const clock = createClock(0);
  const log = [];
  clock.setTimeout(() => log.push('timer300'), 300);
  clock.setTimeout(() => log.push('timer100'), 100);
  clock.setTimeout(() => log.push('timer200'), 200);

  clock.tick(250);
  assert.deepEqual(log, ['timer100', 'timer200']);
  assert.strictEqual(clock.now, 250);

  clock.tick(100);
  assert.deepEqual(log, ['timer100', 'timer200', 'timer300']);
  assert.strictEqual(clock.now, 350);
}

// Contract 6: clock.tickAsync advances clock time asynchronously, awaiting resolved promises returned by async callbacks
{
  const clock = createClock(0);
  let asyncFinished = false;
  clock.setTimeout(async () => {
    await Promise.resolve();
    asyncFinished = true;
  }, 100);

  assert.strictEqual(asyncFinished, false);
  await clock.tickAsync(100);
  assert.strictEqual(asyncFinished, true);
}

// Contract 7: clock.runAll exhausts and triggers all scheduled timers until the queue is empty
{
  const clock = createClock(0);
  const order = [];
  clock.setTimeout(() => order.push('first'), 50);
  clock.setTimeout(() => order.push('third'), 150);
  clock.setTimeout(() => order.push('second'), 100);

  assert.strictEqual(clock.countTimers(), 3);
  clock.runAll();
  assert.deepEqual(order, ['first', 'second', 'third']);
  assert.strictEqual(clock.countTimers(), 0);
  assert.strictEqual(clock.now, 150);
}

// Contract 8: clock.runToLast advances time to the expiration timestamp of the latest scheduled timer and fires pending timers
{
  const clock = createClock(0);
  const fired = [];
  clock.setTimeout(() => fired.push('a'), 100);
  clock.setTimeout(() => fired.push('c'), 500);
  clock.setTimeout(() => fired.push('b'), 200);

  clock.runToLast();
  assert.deepEqual(fired, ['a', 'b', 'c']);
  assert.strictEqual(clock.now, 500);
}

// Contract 9: clock.setSystemTime modifies current clock time without executing scheduled timers
{
  const clock = createClock(1000);
  let executed = false;
  clock.setTimeout(() => {
    executed = true;
  }, 500);

  clock.setSystemTime(5000);
  assert.strictEqual(clock.now, 5000);
  assert.strictEqual(executed, false);
  assert.strictEqual(clock.countTimers(), 1);
}

// Contract 10: clock.reset resets clock.now back to the initial start timestamp and clears all active timers
{
  const clock = createClock(2000);
  clock.setTimeout(() => {}, 300);
  clock.setInterval(() => {}, 100);
  clock.tick(500);

  assert.strictEqual(clock.now, 2500);
  assert.strictEqual(clock.countTimers(), 1);

  clock.reset();
  assert.strictEqual(clock.now, 2000);
  assert.strictEqual(clock.countTimers(), 0);
}

// Contract 11: clock.countTimers returns the number of active scheduled timers remaining in the queue
{
  const clock = createClock(0);
  assert.strictEqual(clock.countTimers(), 0);

  const t1 = clock.setTimeout(() => {}, 100);
  const t2 = clock.setTimeout(() => {}, 200);
  const t3 = clock.setInterval(() => {}, 50);
  assert.strictEqual(clock.countTimers(), 3);

  clock.clearTimeout(t1);
  assert.strictEqual(clock.countTimers(), 2);

  clock.clearInterval(t3);
  assert.strictEqual(clock.countTimers(), 1);

  clock.clearTimeout(t2);
  assert.strictEqual(clock.countTimers(), 0);
}

// Contract 12: clock.next advances clock time to the very next scheduled timer and executes it
{
  const clock = createClock(0);
  const log = [];
  clock.setTimeout(() => log.push('first'), 100);
  clock.setTimeout(() => log.push('second'), 250);

  clock.next();
  assert.deepEqual(log, ['first']);
  assert.strictEqual(clock.now, 100);
  assert.strictEqual(clock.countTimers(), 1);

  clock.next();
  assert.deepEqual(log, ['first', 'second']);
  assert.strictEqual(clock.now, 250);
  assert.strictEqual(clock.countTimers(), 0);
}

console.log('All contracts passed.');