Vehicles Time Travel Utility

Common errors

• TypeError: vehicles is not a function

  cause Attempting to call the top-level 'vehicles' module as a function, or incorrectly destructuring a named export when a default export was expected (or vice-versa).
  fix Check the import statement. Ensure you are importing the correct named function (e.g., `travel`) and not trying to call the module itself, for example: `import { travel } from 'vehicles';`.

• ERR_REQUIRE_ESM

  cause Trying to `require()` the `vehicles` package, which is an ES Module, from a CommonJS context.
  fix Update your project to use ES Modules (by adding `"type": "module"` to `package.json`) and use `import` statements, or switch to dynamic `import('vehicles')` if mixing CJS and ESM.

• ReferenceError: setTimeout is not defined

  cause This error typically indicates that the `vehicles` library, or another part of your test setup, is attempting to mock or interact with timers in an environment where the global `setTimeout` (or other timer functions) is not available or has been unexpectedly removed. This might occur if a test runner's environment is not correctly configured for Node.js globals.
  fix Ensure your test runner (e.g., Jest, Mocha) is configured to run in a Node.js environment or has access to Node.js global timers. Verify that no other library or setup is inadvertently removing global timer functions before `vehicles` initializes.

Warnings

• breaking The package requires Node.js version 18.2.0 or higher. Using it with older Node.js versions will result in runtime errors related to unsupported syntax or APIs, specifically ESM features.
  Fix: Upgrade your Node.js environment to version 18.2.0 or newer. Consider using a version manager like `nvm` to manage multiple Node.js versions.
• gotcha Vehicles primarily operates as an ES Module (ESM). Attempting to import it using CommonJS `require()` syntax in a pure CommonJS project might lead to errors like 'ERR_REQUIRE_ESM' or incorrect module resolution, even with bundlers, unless explicit interop is configured.
  Fix: Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) or use dynamic `import()` for ESM modules within CommonJS contexts where necessary.
• gotcha Forgetting to call `reset()` between tests can lead to test pollution, where time mocks from a previous test affect subsequent tests, causing flaky or incorrect results.
  Fix: Always include `reset()` in a `beforeEach` or `afterEach` hook within your test suite to ensure a clean state for time mocks before each test runs.

Install

• npm install vehicles npm
• yarn add vehicles yarn
• pnpm add vehicles pnpm

Imports

• travel
  wrong:

  const { travel } = require('vehicles');

  correct:

  import { travel } from 'vehicles';

  Vehicles is primarily an ESM module; CommonJS 'require' syntax may lead to runtime errors, especially with default imports or when the bundler doesn't handle interop correctly. Use named imports for specific utility functions.
• reset
  wrong:

  import reset from 'vehicles/reset';

  correct:

  import { reset } from 'vehicles';

  The 'reset' function is a named export from the main package, not a subpath. It's crucial for cleaning up time mocks between tests.
• MockedDate
  wrong:

  import { MockedDate } from 'vehicles';

  correct:

  import type { MockedDate } from 'vehicles';

  When importing types for use in TypeScript, ensure you use 'import type' to avoid including runtime code, which can prevent tree-shaking and lead to unexpected behavior.

Quickstart

Demonstrates how to use `vehicles` to mock and advance timers for testing asynchronous, time-dependent logic and validating mocked date objects.

import { travel, reset } from 'vehicles';

describe('Time-sensitive feature', () => {
  // Store original Date to restore after all tests
  const originalDate = global.Date;

  beforeEach(() => {
    // Reset time mocks before each test to ensure isolation
    reset();
  });

  afterAll(() => {
    // Restore global Date object after all tests in the suite
    global.Date = originalDate;
  });

  it('should trigger an event after a specific delay', async () => {
    let eventTriggered = false;
    setTimeout(() => {
      eventTriggered = true;
    }, 10000); // 10 seconds

    // Initial state check
    expect(eventTriggered).toBe(false);

    // Travel 5 seconds into the future
    await travel(5000);
    expect(eventTriggered).toBe(false); // Should still be false

    // Travel another 5 seconds (total 10) to trigger the event
    await travel(5000);
    expect(eventTriggered).toBe(true);
  });

  it('should mock current date correctly', async () => {
    const initialDate = new Date();
    await travel(60 * 60 * 1000); // Travel 1 hour into the future
    const afterTravelDate = new Date();
    expect(afterTravelDate.getTime()).toBe(initialDate.getTime() + 60 * 60 * 1000);
  });
});