Handy library of utility functions for working with timetables (such as flight or train schedules).
npm install timetable-fns --save or
yarn add timetable-fns
const timetable = require('timetable-fns') // Simple difference in calendar dates timetable.diff('2018-12-25', '2019-01-05') // ==> 11 // Can also be negative timetable.diff('2019-01-05', '2018-12-25') // ==> -11
Dates must be provided in
YYYY-MM-DD format, no other formats are provided. A
coerce function is provided, which accepts either a
moment object, and converts to the proper format.
a = timetable.coerce(moment('Mar 5', 'MMM D')) b = timetable.coerce(moment('Mar 8', 'MMM D')) timetable.diff(a, b)
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 moment('1883-11-18').diff(moment('1883-11-20'), 'days') // => -1 (moment.js gives unexpected result) > timetable.diff('1883-11-20', '1883-11-18') // => -2 (what most people would expect) // Supports dates back to establishment of Gregorian calendar timetable.diff('1582-10-01', '2000-01-01') // => 152398
You can also do simple math, or obtain the day numbers and operate on those directly.
// Simple date math timetable.plus('2017-05-15', 3) // => '2017-05-18' timetable.minus('2017-05-15', 3) // ==> '2017-05-12' // You can also do your own date math directly const dn = timetable.dayNumber('2000-01-01') [ 1, 2, 3 ].map(x => timetable.calendarDate(dn + x)) // => [ '2000-01-02', '2000-01-03', '2000-01-04' ]
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: