README.md

chronokinesis

Mock time and date for traveling and freezing. Inspired and borrowed from timekeeper.

• Introduction
• API Reference
  • freeze([...args])
  • travel([...args])
  • defrost()
  • reset()
  • isKeepingTime()
  • timezone(timeZone[, ...args])
  • new TimeZoneTraveller(timeZone)
    • timezone.freeze([...args])
    • timezone.travel([...args])
    • timezone.reset()
    • timezone.defrost()
• Distributions
  • Nodejs require
  • Browser (UMD)
• Acknowledgements

Introduction

Mock Date and Date.now in order to help you test time-dependent code. Provides travel, freeze, and timezone functionality for your Node.js tests.

import * as ck from 'chronokinesis';

ck.freeze();

setTimeout(() => {
  // Frozen
  console.log(new Date());

  ck.reset();
}, 2000);

With arguments:

import * as ck from 'chronokinesis';
import assert from 'node:assert';

ck.freeze(1980, 0, 1);

assert.equal(true, ck.isKeepingTime());
assert.deepEqual(new Date(), new Date(1980, 0, 1));

or use with moment:

import moment from 'moment';
import * as ck from 'chronokinesis';

ck.travel(moment().add(1, 'year'));

setTimeout(() => {
  // Date traveled one year and some
  console.log(new Date());

  ck.reset();
}, 2000);

API Reference

freeze([...args])

Freeze point in time. Calls can be made with the same arguments as the Date constructor.

• ...args: Optional date constructor arguments, if empty stops time at now

import * as ck from 'chronokinesis';

ck.freeze('1942-01-08');

setTimeout(() => {
  // Frozen
  console.log(new Date());

  ck.reset();
}, 2000);

travel([...args])

Time travel to another era. Calls can be made with the same arguments as the Date constructor

• ...args: Optional date constructor arguments, pretty useless if empty but won´t crash

import * as ck from 'chronokinesis';
let date = new Date(2018, 0, 31);

ck.travel(date);

setTimeout(function () {
  console.log(new Date());
  ck.reset();
}, 1500);

When used in combination with freeze the time is still frozen but at the travelled time().

import * as ck from 'chronokinesis';
import moment from 'moment';

let date = new Date(2018, 0, 31);

ck.freeze(date);

ck.travel(moment().add(1, 'year'));

setTimeout(function () {
  console.log(`Still frozen but one year ahead ${new Date()}`);

  ck.reset();
}, 1500);

defrost()

Defrost a frozen point in time. Used in combination with travelling will start ticking the clock.

import * as ck from 'chronokinesis';

ck.freeze(1980, 0, 1);

// Travel one year
ck.travel(1981, 1, 1);

// Start ticking
ck.defrost();

setTimeout(() => {
  // Tick tack
  console.log(new Date());

  ck.reset();
}, 2000);

reset()

Resets Date to current glory.

import * as ck from 'chronokinesis';

ck.freeze(2060, 0, 1);
console.log(`end of time is reached at ${new Date()} according to Newton`);

ck.reset();

// Today
console.log(new Date());

isKeepingTime()

Utility function to see if we still travel or freeze time.

import * as ck from 'chronokinesis';

console.log(ck.isKeepingTime() ? 'Is' : 'Not', 'keeping time');
ck.travel(1893448800000);
console.log(ck.isKeepingTime() ? 'Is' : 'Not', 'keeping time');

timezone(timeZone[, ...args])

Travel to time zone.

• timeZone: IANA time zone string
• ...args: Optional travel to date arguments

Returns TimeZoneTraveller api

import * as ck from 'chronokinesis';

ck.reset();

const tz = ck.timezone('Asia/Shanghai');

console.log('Now in Shanghai', new Date());

tz.freeze();

new TimeZoneTraveller(timeZone)

Time zone traveller api.

import { TimeZoneTraveller } from 'chronokinesis';

const timezone = new TimeZoneTraveller('Asia/Shanghai');

timezone.freeze();

timezone.freeze([...args])

Freeze at the specific timezone.

timezone.travel([...args])

Start traveling in the specific timezone.

timezone.reset()

Same as #reset

timezone.defrost()

Same as #defrost

Distributions

The module is prepared for browser and nodejs.

Nodejs require

const ck = require('chronokinesis');

Browser (UMD)

Use dist/chronokinesis.cjs. Sets global property chronokinesis.

Acknowledgements

chronokinesis initial code is inspired and borrowed from timekeeper