timemachine

library0.1jsnpmunverified

Timemachine is a JavaScript utility designed to facilitate testing of time-dependent applications by overriding the native `Date` object. The package is currently at version 0.3.2, with its last known publication being over six years ago, indicating an abandoned status. It provides a straightforward API to configure a specific date, timestamp, or a time offset, and can optionally simulate a continuously ticking clock, which is useful for testing dynamic time displays or intervals. A key differentiator for Timemachine is its broad compatibility, supporting global namespaces, RequireJS, CommonJS, and NodeJS environments, making it suitable for older or mixed JavaScript projects. Its core functionality involves directly monkey-patching the global `Date` constructor and its prototypes, allowing for precise control over time within test scenarios where time manipulation is critical.

testing

npm install timemachine

github ↗package ↗

INSTALL

IMPORT

SIG · TIMEMACHINE

timemachine

testingjavascriptv0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

timemachine

✓ const timemachine = require('timemachine');

✗ import { timemachine } from 'timemachine';

Primarily designed for CommonJS or global environments; direct named ESM imports are not supported.

timemachine

✓ import timemachine from 'timemachine';

While CommonJS-first, bundlers may enable this default ESM import pattern. Check your bundler configuration.

timemachine (global)

✓  // Then, use `timemachine.config(...)` globally.

✗ import timemachine from 'timemachine'; // No module system in browser global context

For browser environments without a module loader, `timemachine` is exposed as a global variable.

Demonstrates how to configure Timemachine to a specific date, show its effect, and then reset to native time.

const timemachine = require('timemachine'); console.log('Real current date:', new Date().toISOString()); // Configure timemachine to a specific date and time timemachine.config({ dateString: 'December 25, 1991 13:12:59', tick: false // Optional: set to true to make the clock 'tick' from this point }); console.log('Mocked date:', new Date().toISOString()); // Simulate a short passage of time (if tick is true, otherwise it remains static) setTimeout(() => { console.log('Date after 100ms (if tick was true):', new Date().toISOString()); }, 100); // Reset timemachine to restore the native Date object timemachine.reset(); console.log('Date after reset:', new Date().toISOString());

Debug

Known issues

breakingThe `timemachine` package is abandoned, with its last release (0.3.2) over six years ago. This means it receives no further updates, bug fixes, or security patches, making it unsuitable for modern JavaScript development or critical applications.

fix

Consider migrating to actively maintained alternatives like `jest.useFakeTimers()` (for Jest), `@sinonjs/fake-timers`, or `date-fns` for robust date manipulation without monkey-patching.

affects: 0.3.2

gotchaTimemachine achieves its functionality by monkey-patching the global `Date` object. This can lead to unexpected side effects, conflicts with other libraries that also modify `Date`, or issues in environments (e.g., some sandboxed test runners or strict mode contexts) where global object mutations are restricted or handled differently.

fix

Always ensure to call `timemachine.reset()` after your time-sensitive operations to restore the native `Date` behavior and prevent leaks between tests. Isolate tests to prevent interference.

affects: >=0.1.0

gotchaThe library's age means it might not fully support or interact correctly with modern JavaScript features (e.g., `Temporal` API, Web Workers where `Date` might be isolated) or newer Node.js/browser environments and their built-in `Date` implementations. It also lacks explicit ESM support out-of-the-box.

fix

Carefully test its behavior in your specific environment. For ESM, you might need bundler configurations for CommonJS interop. Modern alternatives often offer better compatibility.

affects: 0.3.2

deprecatedThe README mentions installation via Bower, a package manager that has been largely deprecated in favor of npm and yarn for web development. This reinforces the project's outdated status.

fix

Install via npm (`npm install timemachine`) if you still need to use this package, but again, consider alternatives.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot read property 'config' of undefined

The `timemachine` object was not correctly imported or loaded into the scope.

fix

Ensure `require('timemachine')` is executed and assigned, or that the script loading the library has completed in a browser environment before attempting to call its methods.

My tests are failing with incorrect dates/times, even when I expect them to be mocked.

Another library or test setup is interfering with the global `Date` object, or `timemachine.reset()` was not called from a previous test, causing state leakage.

fix

Review your test setup for other time-mocking libraries. Ensure `timemachine.reset()` is called in an `afterEach` or `afterAll` hook in your test framework to clean up state.

Upgrade

Version history

0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/schickling/timemachine ↗

packagehttps://www.npmjs.com/package/timemachine ↗