Timetravel

A tiny module that simulates time in JavaScript.

var c = Timetravel.Clock();
c.time(0).speed(10);
setTimeout(function () {
    console.log('The simulated time is', c.time());
    //=> The simulated time is 420
}, 42);

Timetravel works as a general-purpose counter that increments by a set amount each millisecond. It can be set, sped up, paused and restarted. There are no “moving parts”; the time is only calculated when needed. While you’re not using it, the clock does absolutely nothing.

Timetravel is tiny (1.5 KB minified), fully tested, has no dependencies, and works just about anywhere. You can require it Node- or AMD-style or embed it the old-fashioned way with a <script> tag.

Is Timetravel right for me?

Timetravel works really well for models that can be expressed as a function of time, e.g. planet constellations or public transport networks.

It’s near-useless for iterative simulations that work in ‘ticks’ where the state at any point in time depends on what happened before, e.g. Conway’s Game of Life.

How do I use Timetravel?

If you’re using a packet manager (you are, aren’t you?), you can install it with npm install timetravel or bower install timetravel. Otherwise you can download it manually.

To include it in your project, require it (Node and AMD style are supported) on the server or in the browser or keep polluting that global namespace and use a <script> tag if you must.

// Node style:
var Clock = require('timetravel').Clock;
// Or if you're using global variables:
// var Clock = Timetravel.Clock;

// Make a new clock
var c = Clock();

// It's already running, let's stop it
c.stop();

// Set it to 1000 times real time and one year back:
c.speed(1000).time(c.time() - 3.16e10);

// Start it up again
c.start();

// Periodically log the current time
setInterval(function () {
    console.log('The time is', new Date(c.time()));
}, 1000);

You can find a complete documentation at the bottom of this document.

Who made this?

Timetravel is written and maintained by Philipp Bock from OpenDataCity.

timetravel → object

• timetravel → object
  • class: .Clock
    • new Clock([options])
    • instance
      • .speed() ⇒ Number
      • .speed(speed) ⇒ Clock
      • .start() ⇒ Clock
      • .stop() ⇒ Clock
      • .isStopped() ⇒ Boolean
      • .isRunning() ⇒ Boolean
      • .time() ⇒ Number
      • .time(time) ⇒ Clock
      • .earliest() ⇒ Number
      • .earliest(minTime) ⇒ Clock
      • .latest() ⇒ Number
      • .latest(maxTime) ⇒ Clock
      • .on(events, callback)

class: timetravel.Clock

• class: .Clock
  • new Clock([options])
  • instance
    • .speed() ⇒ Number
    • .speed(speed) ⇒ Clock
    • .start() ⇒ Clock
    • .stop() ⇒ Clock
    • .isStopped() ⇒ Boolean
    • .isRunning() ⇒ Boolean
    • .time() ⇒ Number
    • .time(time) ⇒ Clock
    • .earliest() ⇒ Number
    • .earliest(minTime) ⇒ Clock
    • .latest() ⇒ Number
    • .latest(maxTime) ⇒ Clock
    • .on(events, callback)

new Clock([options])

Creates a new simulation clock. The constructor is currently optimised for ease-of-use rather than performance, and while there is nothing stopping you from creating a million clock instances, it is inadvisable.

Param	Type	Description
[options]	Object
[options.time]	Number	The time at which the clock starts. Defaults to the current system time.
[options.speed]	Number	The value by which the time will be incremented for each real-time millisecond, i.e. how much faster the simulated clock advances compared to a real clock. A speed of 1 is real-time; 10 is ten times real-time; -1 reverses time; etc. Defaults to 1.
[options.earliest]	Number	The lower bound for the simulated time. Defaults to -Infinity.
[options.latest]	Number	The upper bound for the simulated time. Defaults to Infinity.

clock.speed() ⇒ Number

Returns the current speed.

Returns: Number - The current speed of the clock

clock.speed(speed) ⇒ Clock

Sets the speed of the simulation, i.e. the value by which the simulated clock will be incremented for each real-time millisecond.

Returns: Clock - The clock instance itself (chainable)
Emits: event:speedchange

Param	Type
speed	Number

clock.start() ⇒ Clock

Starts the clock if it has been stopped before.

Returns: Clock - The clock instance itself (chainable)
Emits: event:start

clock.stop() ⇒ Clock

Stops the clock. Equivalent to calling Clock.speed(0), except that the current speed will be remembered and can be resumed later on.

Returns: Clock - The clock instance itself (chainable)
Emits: event:stop

clock.isStopped() ⇒ Boolean

Returns true if the clock is currently stopped, otherwise false.

clock.isRunning() ⇒ Boolean

Returns true if the clock is currently running, otherwise false.

clock.time() ⇒ Number

Returns the current simulated time as a unix timestamp.

clock.time(time) ⇒ Clock

Sets the simulated time.

Returns: Clock - The clock instance itself (chainable)
Emits: event:timechange

Param	Type
time	Number

clock.earliest() ⇒ Number

Returns the current lower bound of the clock.

Returns: Number - The current lower bound of the clock.

clock.earliest(minTime) ⇒ Clock

Sets the current lower bound of the clock.

Returns: Clock - The clock instance itself (chainable)

Param	Type
minTime	Number

clock.latest() ⇒ Number

Returns the current upper bound of the clock.

Returns: Number - The current upper bound of the clock.

clock.latest(maxTime) ⇒ Clock

Sets the current upper bound of the clock.

Returns: Clock - The clock instance itself (chainable)

Param	Type
maxTime	Number

clock.on(events, callback)

Attaches an event handler.

Param	Type	Description
events	String	The event(s) to listen to. Possible values are start, stop, speedchange, timechange. A list of events can be an array or a space- or comma-separated string.
callback	function	A function that will be called when the event is fired.