Skip to content

Pythonic dates, times, and deltas in JavaScript

Notifications You must be signed in to change notification settings

pavelsof/pythonic-datetime

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

datetime

Pythonic dates, times, and deltas in JavaScript. Advantages:

  • The same API as Python's datetime module (see below for differences).
  • Clear distinction between naive and aware datetimes.
  • All functions/methods return immutable (ok, frozen) objects.
  • Timedelta arithmetics.
  • Unix timestamps (i.e. seconds instead of milliseconds).
  • Lightweight (~3KB gzipped).

This is not a re-write of Python's datetime module in JavaScript; instead, it leverages the native Date functions wherever possible. In fact, you can think about pythonic-datetime as a wrapper.

Whetting your appetite:

var birthday = datetime.date(1989, 12, 5);  // ja, months start from 1
console.warn(birthday.year);  // 1989
birthday.year = 1431;  // raises TypeError in strict, simply fails otherwise

var partyDay = datetime.date(2016, 12, 5);  // presents are welcome
var yearsAlive = partyDay.subtract(birthday)  // returns timedelta object
                         .divide(datetime.timedelta({days: 365}));

var partyTime = datetime.time(21, 30);
datetime.datetime.combine(partyDay, partyTime).isoformat();  // 2016-12-05T21:30:00

Installation

bower install pythonic-datetime. Or you can git clone this repo as a submodule; the master branch will always contain the latest stable.

Differences with the original

  • The smallest time unit is milliseconds instead of microseconds. Wherever you see microseconds in Python's datetime API, replace it with milliseconds.
  • As there is no operator overloading in JavaScript, the following methods are used for datetime arithmetics:
    • delta.compare(another): returns one of -1, 0, 1
    • delta.add(addend)
    • delta.subtract(subtrahend)
    • delta.multiply(factor)
    • delta.divide(divisor)
  • If wrong arguments are provided, TypeError is raised. However, comprehensive argument validation is yet to be implemented.
  • No tzinfo, only timezone. This is more of a status-quo.
  • Other functions/methods which are not (yet?) implemented: ctime, fromordinal, timetuple, toordinal.
  • The following printf directives are currently not implemented: %j, %U, and %W. However, %a, %A, %b, %B, and %p are not localised.
  • Of the scanf directives, only %d, %m, %Y, %H, %M, %S, and %f are implemented.

TODO/Roadmap

  • To implement the proleptic Gregorian ordinals: toordinal, fromordinal.
  • To validate the constructor arguments.
  • To test, document, and improve datetime's interoperability with at least one of the JavaScript libraries that are synced with the Olson database. In other words, find the JavaScript pytz counter-part(s).

Licence

MIT. Do as you please and praise the snake gods.

About

Pythonic dates, times, and deltas in JavaScript

Resources

Stars

Watchers

Forks

Packages

No packages published