@nvnh/clock
is a small library without dependencies for mocking time in Javascript. It's inspired by this clock package for Go.
The goal is to resemble Javascript's Date & Time interface as closely as possible, so you can easily replace it in your existing code.
export interface Clock {
now(): number;
newDate(): Date;
setTimeout(callback: () => void, ms: number): TimeoutID;
clearTimeout(id: TimeoutID): void;
setInterval(callback: () => void, ms: number): IntervalID;
clearInterval(id: IntervalID): void;
}
@nvnh/clock
gives you more control over time:
- Use
Clock
in your application for default behavior. - Use
MockClock
in tests to have complete control over time. - Replace
Clock
byWarpClock
in your application to see how your application would behave at a different point in time. You can time travel and speed up or slow down time. Useful for debugging time-related problems, eg. using your application around midnight, year changes, leap years or use ofsetTimeout()
that would let you wait a long time.
Getting started
Installation
npm install @nvnh/clock
Get the current date
// Import default clock instance
import clock from "@nvnh/clock";
// use it just like Javascript's Date
console.log(clock.newDate().toISOString()); // eg. 2023-07-12T15:15:21.376Z
// will have the same output as
console.log(new Date().toISOString()); // eg. 2023-07-12T15:15:21.376Z
Use MockClock
import { createMockClock } from "@nvnh/clock/mock";
// Create a mock clock instance
const mockClock = createMockClock("2030-11-24T08:30:25Z");
// newDate() returns the initial date
console.log(mockClock.newDate().toISOString()) // 2030-11-24T08:30:25.000Z
// move time ahead by 2 seconds
mockClock.add(2000);
// newDate() returns the updated date & time
console.log(mockClock.newDate().toISOString()) // 2030-11-24T08:30:27.000Z
// move time ahead to the specified time
mockClock.goTo("2030-11-25T07:30:00Z");
// newDate() returns the new date & time
console.log(mockClock.newDate().toISOString()) // 2030-11-25T07:30:00.000Z
Example
Last week
The last week example implements a function with signature:
lastWeek(): { from: Date, to: Date }
Where:
-
from
is a Javascript date representing monday 00:00:00 of the previous week. -
to
is a Javascript date representing sunday 23:59:59 of the previous week.
The code is documented and shows how you can use @nvnh/clock
in your own code.