Introducing Time Traveller, date library for node.js (and javascript).

Published on Nov 07, 2011

Javascript has the Date object that exposes a series of methods to create new dates, modify them and get the different “parts” of a date. It’s not bad but is certainly fairly limited.

I wanted to create a simpler, easier way to work with dates.

Introducing Time Traveller

Time traveller is my attempt to provide a better api to work with date and time operations. My hope is to grow this library to make working with dates as enjoyable as possible.

You can get time traveller using npm:


    npm install timeTraveller

Or you can get the code from the github repo

Objects

TimeTraveller

Factory object that returns an extended Date with some utility methods to do comparison and perform common operations on dates.

As of version 0.2.1 only has a now() factory method that’s equivalent to doing new Date().

The returned date object is enhanced with some utility methods as described below.

	var TimeTraveller = require('timeTraveller).TimeTraveller;
	var ttDate = new TimeTraveller().now();

view raw 1tt.js hosted with ❤ by GitHub

Add methods

The available add methods are:

	d.addYears(100);
	d.addMonths(1);
	d.addDays(10);
	d.addHours(2);
	d.addMinutes(75); // Will roll over an hour
	d.addSeconds(2);
	d.addMilliseconds(1000);

view raw 2tt.js hosted with ❤ by GitHub

These methods can take either a positive or a negative number. A negative number will result in the substraction of the given period.

For example:

	var d = new TimeTraveller().now();
	console.log(d); //Mon, 04 Jul 2011 23:03:22 GMT
	d.addYears(2);
	console.log(d); //Thu, 04 Jul 2013 23:03:22 GMT
	d.addYears(-4);
	console.log(d); //Thu, 04 Jul 2009 23:03:22 GMT

view raw 3tt.js hosted with ❤ by GitHub

The add* methods are chainable, so you could call

d.addYears(2).addMonths(6).addHours(12);

view raw 4tt.js hosted with ❤ by GitHub

isSame** methods

There is a main isSame() method that takes a date and can also have a single character that indicates precision.

There are also methods for every precision that make a cleaner API.

	var d = new TimeTraveller().now();

	d.isSameSecond(secondDate);
	d.isSameMinute(secondDate);
	d.isSameHour(secondDate);
	d.isSameDay(secondDate);
	d.isSameMonth(secondDate);
	d.isSameYear(secondDate);
	d.isSame(secondDate, 'm'); //Same as calling isSameMinute();
	d.isSame(secondDate); //Will compare both dates to the millisecond, same as doing ((d - secondDate) === 0);

view raw 5tt.js hosted with ❤ by GitHub

TimeSpan

A simple object tha represents a period of time. As of version 0.2.1 a TimeSpan object can be created in 3 ways.
Calling the differenceFrom(secondDate) method on an enhanced Date object, passing milliseconds into the constructor, or passing two dates into the contructor

	//Difference
	var d = new TimeTraveller().now();
	var ts = d.differenceFrom(new Date());

	//Milliseconds
	var ts = new TimeSpan(1300);

	//Two dates
	var ts = new TimeSpan(date, secondDate);
	//Returns the diff in milliseconds between the two dates

view raw 6tt.js hosted with ❤ by GitHub

Coming

Sometime in the near future I will have to add formatting capabilities and string date parsing capabilities to the main object.