- §1. Synopsis
- §2. Installation Instructions
- §3. Build & Test Instructions
- §4. Quick API Reference
- §5. Support
- §6. Change Log
- §7. Credits
- §8. License
- §9. Notes
Anyone who’s been working long enough with JavaScript’s Date
object would
probably agree that it’s badly designed and buggy. I’d rather not dive into
the messy details, except where absolutely needed, in the
§4. Quick API Reference section.
tau.js1 is a JavaScript date library, that I’ve built so that I could scratch this itch.
It’s minimal: It solely supports UTC dates, for now, and the only formatting
option is the ISO 8601 extended format. tau.js is not a wrapper around the
native Date
, and here’s the point where it diverges from other established
solutions2. This means that the date mutation functions,
otherwise provided by Date
, had to be re-written from scratch and thoroughly
tested. It also means the library is notably slower than alternatives, for now.
Download
dist/tau.min.js
.
Or, with Bower:
Fire up a terminal window, and type the following command:
bower install tau.js
Then:
<script src="path/to/tau.js"></script>
Fire up a terminal window, and type the following command:
npm install tau.js
Then:
var Tau = require("path/to/tau.js");
Fire up a terminal window, and type the following commands:
git clone https://github.com/CristianTincu/tau.js.git
cd tau.js
npm install
npm run-script grunt
First, build the library (see above).
Then, if you want to run the tests server-side, with Node.js, fire up a terminal window, and type the following command:
npm run-script test
If you want to run the tests client-side, open test/test-runner.html
in
whatever browser you want to test against.
tau.js exposes the Tau
pseudo-class to the environment on “load”, if the
environment is a browser, or on “require”, if the environment supports CommonJS
modules (e.g. Node.js).
Tau()
Unlike the native Date
, tau.js provides only one humble constructor.
Calling the constructor simply creates instances referencing the Unix epoch
(00:00:00 UTC on the 1st of January, 1970).
Tau#setUtcYear()
Tau#setUtcMonth()
Tau#setUtcDate()
Tau#setUtcHours()
Tau#setUtcMinutes()
Tau#setUtcSeconds()
Tau#setUtcMilliseconds()
These methods allow you to manipulate Tau
instances, with respect to UTC.
Unlike native Date
’s equivalent methods, they support “chaining”.
This apparently minor detail can compensate—to a certain degree—the
constructor’s intentional lack of flexibility:
var tau = new Tau().setUtcYear(2013).setUtcMonth(4).setUtcDate(3);
There’s one extremely important point, concerning these methods, that you
should be aware of.
Let’s consider the following example:
var date = new Date(2013, 0, 30);
date.setUTCMonth(1);
The native Date
moves the date
reference to the 2nd of March, as
there’s no such thing as the 30th of February. In a more general
context, such a decision might cause trouble, as a naïve API consumer might not
be aware that a call to Date#setUTCMonth()
could, in fact, modify the month
day, also. JavaScript’s Date
object doesn’t provide any help in treating such
cases.
In contrast:
var tau = new Tau().setUtcYear(2013).setUtcMonth(0).setUtcDate(30);
tau.setUtcMonth(1);
tau.js moves the tau
reference to the 30th of February, although
that would be an invalid date. But you can check that, via the Tau#isValid()
method.
Note that tau.js does handle date overflow, though, when its outcome is
100% predicatable. That happens when change might propagate “upwards”:
Tau#setUtcMonth()
might impact years, Tau#setUtcDate()
might impact months,
years, Tau#setUtcHour()
might impact month days, months, years, and so on.
Tau#isValid()
This method allows you to check if a Tau
instance is valid.
Tau#setUtcYear()
and Tau#setUtcMonth()
are the only two methods that may
produce invalid dates.
Tau#getUtcYear()
Tau#getUtcMonth()
Tau#getUtcDate()
Tau#getUtcHours()
Tau#getUtcMinutes()
Tau#getUtcSeconds()
Tau#getUtcMilliseconds()
This methods behave pretty much like you’d probably expect.
Tau#getUtcIsoString()
You can use this method to obtain a serialization of a Tau
instance in the
ISO 8601 extended format, with respect to UTC.
Tau.getMaxDate()
This is a helper function that allows you to find the last valid month day, given a day and a month.
Tau.VERSION
This property can be queried to find out the current tau.js release.
tau.js is semantically versioned3. See
§6. Change Log for a brief release history.
Tau.noConflict()
If the environment is a browser, this method would—if called—throw tau.js into
“no conflict” mode4, and restore Tau
to its previous owner,
if any.
§5. Support5
I’ve tested tau.js on the following environments:
-
Chrome “latest” (26.0.1410.63)
-
Chrome 4
-
Firefox “latest” (20.0.1)
-
Firefox 3.6
-
IE 10
-
IE 8
-
IE 7
-
IE 6
-
Safari “latest” (6.0.4) on OS X
-
Safari “latest” (5.1.7) on Windows
-
Mobile Safari on iOS 6
-
Opera “latest” (12.15)
-
Node.js “latest” (0.10.5)
- 0.1.0 (2013-05-14)
Initial development release of tau.js.
- Cristian Tincu (@CristianTincu on GitHub and Twitter)
I made tau.js as an exercise, and as an experiment. You’re free to use it in your own exercises, experiments, or projects, whether they’re “closed” or “open”, commercial or non-commercial, “good” or “evil”, subject to the terms of the MIT License6.
See Tau on Wikipedia.
See Semantic Versioning.
I’ve borrowed this trick—as well as others—from Underscore.js.
See Underscore.js’s noConflict()
.
“Latest” means the current stable version of the respective environment, at the time I’m writing this text.
See LICENSE.md.