Handy library of utility functions for working with timetables (such as flight or train schedules).
Installation
npm install timetable-fns --save
or yarn add timetable-fns
Usage
const timetable = // Simple difference in calendar datestimetable// ==> 11 // Can also be negativetimetable// ==> -11
Dates must be provided in YYYY-MM-DD
format, no other formats are provided. A coerce
function is provided, which accepts either a String
or moment
object, and converts to the proper format.
a = timetableb = timetabletimetable
Historical dates are handled correctly, back to the year 0, although using Gregorian rules (the Gregorian calendar was not established until October 1582).
// Handles historical dates correctly// => -1 (moment.js gives unexpected result)> timetable// => -2 (what most people would expect) // Supports dates back to establishment of Gregorian calendartimetable// => 152398
You can also do simple math, or obtain the day numbers and operate on those directly.
// Simple date mathtimetable// => '2017-05-18'timetable// ==> '2017-05-12' // You can also do your own date math directlyconst dn = timetable 1 2 3 // => [ '2000-01-02', '2000-01-03', '2000-01-04' ]
Performance
A benchmark is included, which compares timetable to moment.js for computing the difference between two dates. On a 2.9 Ghz i7 running node 11.6.0, this yields:
benchmarking diff performance ...
timetable x 1,334,060 ops/sec ±1.23% (88 runs sampled)
moment x 61,841 ops/sec ±0.57% (95 runs sampled)
moment (reuse) x 591,905 ops/sec ±1.90% (86 runs sampled)
date-fns x 375,733 ops/sec ±0.60% (92 runs sampled)
timetable was fastest
moment (reuse) was 55.9% ops/sec slower (factor 2.3)
date-fns was 71.7% ops/sec slower (factor 3.5)
moment was 95.3% ops/sec slower (factor 21.4)
Even when reusing the same moment objects (whereas timetable
is re-parsing the provided dates every time), moment.js
is still 2.5x slower. Of course, moment.js
is doing a lot more work, because it supports time, but if you need to only perform date calculations timetable
is a much faster choice.
You can also run the benchmark yourself, with: yarn bench
(or npm run bench
).
How does it work?
All date operations are based on the concept of an integer day number, similar to the concept of the Julian Day Number. The algorithms to compute a Gregorian-based day number (and back) are from:
https://alcor.concordia.ca/~gpkatch/gdate-algorithm.html Archived Version