an.hour.ago
an.hour.ago is a small utility which enables wonderfully expressive date and time manipulation in JavaScript.
Before we proceed, let me be clear that if supporting Internet Explorer is a requirement, you'd best turn back now. If, on the other hand, you're writing server-side JavaScript (or CoffeeScript) and desire an elegant means of expressing relative dates and times, read on!
Let's start with a simple example...
# CoffeeScript # JavaScript 3daysago # 3..days.ago
This produces a Date
instance representing 72 hours before the present.
Neat. What about the future?
1minutefrom_now # 1..minute.from_now
Easy! Note the use of minute
rather than minutes
. The two are synonymous;
singular and plural properties exist for each of the supported units.
Decimals? You betcha:
1.5hoursago # 1.5.hours.ago
In fact, the JavaScript is identical to the CoffeeScript in this case as the awkward double dot is not required.
What about dates relative to other points in time?
tomorrow = 1dayfrom_now # var tomorrow = 1..day.from_now halloween = '31 October 2011' # var halloween = new Date('31 October 2011') christmas = '25 December 2011' # var christmas = new Date('25 December 2011') # 1weekfrom tomorrow # 1..week.from(tomorrow) # 2daysafter halloween # 2..days.after(halloween) # 1weekbefore christmas # 1..week.before(christmas)
from
and after
are synonymous; use whichever reads better.
This is pleasing, you may be thinking, but I'd never say “one week from tomorrow” – it sounds a bit stiff.
Well, if you must...
a = an = 1 # var a = 1, an = 1 # aweekfrom tomorrow # a.week.from(tomorrow) # afortnightfrom_now # a.fortnight.from_now # anhourago # an.hour.ago
Oh, and I should mention, you can add NaturalDate
instances using the and
method:
anhourand58minutesfrom_now # an.hour.and(58..minutes).from_now # 11hoursand36minutesand9secondsago # 11..hours.and(36..minutes).and(9..seconds).ago
Can you help me with date comparison? To determine whether an event occurred more than a week ago I have to ask whether its numeric representation is less than that of "a week ago". It makes my head hurt.
Perhaps you find this more natural?
event_occurredmore_thanaweekago
A practical example:
user_registered = dbgetidregistration_date $'#tips'show if user_registeredless_than15minutesago
before
/after
can follow less_than
/more_than
:
apply_late_fee if costume_returnedmore_than2daysafter halloween
There's also an either_side_of
method which does what it says on the tin:
unfortunate = birthdayless_than3dayseither_side_of christmas
That just about covers it.
Running the test suite
make setup
make test
One last thing...
To be clear, an.hour.ago fiddles with Date.prototype
and Number.prototype
.
Two properties are added to Date.prototype
:
less_than
more_than
The following properties are added to Number.prototype
:
day
days
hour
hours
millisecond
milliseconds
minute
minutes
second
seconds
week
weeks
Each of these properties has a "getter" which returns a NaturalDate
object.
The rest of the methods (before
, after
/from
, and and
) are attached to
NaturalDate.prototype
(which is not exposed).