timekeeper

What is timekeeper?

The timekeeper npm package allows developers to manipulate and control the flow of time in their Node.js applications. This is particularly useful for testing time-dependent code, such as scheduling, timeouts, and date-based logic.

What are timekeeper's main functionalities?

Freeze Time

This feature allows you to freeze the current time to a specific date. This is useful for testing code that depends on the current date and time.

const timekeeper = require('timekeeper');
const frozenDate = new Date(2020, 0, 1);
timekeeper.freeze(frozenDate);
// Your code here will think the current date is January 1, 2020
timekeeper.reset(); // Reset to the real current date

Travel in Time

This feature allows you to travel to a specific date in the future or past. This is useful for testing how your code behaves at different points in time.

const timekeeper = require('timekeeper');
const futureDate = new Date(2025, 0, 1);
timekeeper.travel(futureDate);
// Your code here will think the current date is January 1, 2025
timekeeper.reset(); // Reset to the real current date

Reset Time

This feature allows you to reset the time back to the real current date and time. This is useful for cleaning up after tests that manipulate time.

const timekeeper = require('timekeeper');
timekeeper.reset();
// Your code here will use the real current date and time

Other packages similar to timekeeper

sinon

Sinon is a popular testing library that provides standalone test spies, stubs, and mocks for JavaScript. It also includes functionality for faking timers, which can be used to control the flow of time in your tests. Compared to timekeeper, Sinon offers a broader range of testing utilities beyond just time manipulation.

lolex

Lolex is a JavaScript library for creating fake timers. It allows you to control the flow of time by replacing the native timer functions such as setTimeout, setInterval, and Date. Lolex is similar to timekeeper in that it focuses on time manipulation, but it provides more granular control over timer functions.

mockdate

MockDate is a simple library for mocking the Date object in JavaScript. It allows you to set a specific date and time, which will be used by all Date instances in your code. MockDate is similar to timekeeper in that it allows you to control the current date and time, but it is more lightweight and focused solely on date manipulation.

README

timekeeper

This module mocks Date and Date.now in order to help you test time-dependent code. It provides travel and freeze functionality for your Node.js tests.

Installation

npm install --save-dev timekeeper

Synopsis

Freeze:

var tk = require('timekeeper');
var time = new Date(1330688329321);

tk.freeze(time);

// The time hasn't changed at all.

var date = new Date;
var ms = Date.now();

tk.reset(); // Reset.

Travel:

var tk = require('timekeeper');
var time = new Date(1893448800000); // January 1, 2030 00:00:00

tk.travel(time); // Travel to that date.

setTimeout(function() {
  // `time` + ~500 ms.

  var date = new Date;
  var ms = Date.now();

  tk.reset(); // Reset.
}, 500);

Note: If traveling when time is frozen, the time will be frozen to the new traveled time.

Reflection:

var tk = require('timekeeper');
var time = new Date(1893448800000); // January 1, 2030 00:00:00

assertFalse(tk.isKeepingTime());
tk.travel(time);
assertTrue(tk.isKeepingTime());

Credits

Inspired by the timecop ruby gem.

License

MIT License

Copyright (C) 2012 Veselin Todorov Copyright (C) 2018, 2019, 2023 Linus Unnebäck

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.