localdate
v3.0.2
Published
JS library to provide an immutable date object that represents an ISO-8601 date (year-month-day)
Downloads
84
Maintainers
Readme
LocalDate
LocalDate is a JS library to provide an immutable date object that represents an ISO-8601 date (year-month-day). LocalDate does not store a time or time-zone.
Installation
Add LocalDate as a dependency to package.json:
$ npm install --save localdate
Or via bower
$ bower install localdate
Usage
Creating a LocalDate object
var today = new LocalDate();
var epoch = new LocalDate(1970, 1, 1);
A LocalDate can be instantiated with a String, Date or Julian day.
new LocalDate('1984-05-02');
new LocalDate(new Date(1984, 4, 2));
new LocalDate(2445823);
The basic value of LocalDate tracks the Julian Day. Think of it like the Unix epoch, number of (milli)seconds since 1.1.1970, except for days since 4714 BC.
The Julian Day is the integer assigned to a whole solar day in the Julian day count starting from noon Greenwich Mean Time, with Julian day number 0 assigned to the day starting at noon on January 1, 4713 BC, proleptic Julian calendar (November 24, 4714 BC, in the proleptic Gregorian calendar).
For whole (integer) Julian days the time is assumed to be 12:00 GMT. LocalDate doesn't keep time or timezones, so the Julian day value is not representative of the point in time (noon), rather the whole solar day.
Converters
today.toDate();
epoch.toString();
today.toJulianDay(); //same as today.valueOf()
Clone
var another = today.clone();
Getters & Setters
Setters return new LocalDate instances, they do not modify the existing instance;
today.getYear();
today.getMonth();
today.getDay();
var past = today.setYear(2000).setMonth(2).setDay(29);
Comparators
You can compare two LocalDate objects, or a LocalDate to a String.
birth.isBefore(today); // true
today.isAfter(past); // true
today.equals(new Date); // true
past.isBefore('1923-02-22'); // false
Utility
There are lots of utility methods.
today.getDayOfWeek();
today.getDayOfYear();
birth.isLeapYear();
birth.isValid();
today.lengthOfMonth();
today.lengthOfYear();
Add & Subtract
You can add or subtract years, months and days.
var again = another.addMonths(22).subtractDays(10);
When adding months, if the original day of the month is greater than the number of days in the final month, the day will become the last day in the calculated month.