js-joda has a lightweight footprint, only 43 kB minified and compressed, no third party dependencies.
js-joda supports ECMAScript 5 browsers down to ie9.
js-joda is a port of the threeten backport, that is the base for JSR-310 implementation of the Java SE 8 java.time package. Threeten is inspired by Joda-Time, having similar concepts and the same author.
js-joda is robust and stable. We ported more then 1700 test-cases with a lots of test-permutations from the threetenbp project. We run the automated karma test-suite against Firefox, Chrome, Node and phantomjs.
The API has a domain-driven design with classes for the different use cases, like LocalDate, ZonedDateTime or Period. For examples LocalDate allows to handle dates like birthdays or holidays in a clean and error-safe way, especially if these dates are persisted to an external server.
js-joda is immutable. Immutability aligns well with pure functions and with the architecture of frameworks like React and Flux.
The threeten domain models
Dates and Times
LocalDate represents a date without a time and time-zone in the ISO-8601 calendar system, such as 2007-12-24.
LocalTime represents a time without time-zone in the ISO-8601 calendar system such as ‘11:55:00’.
LocalDateTime is a description of the date (LocalDate), as used for birthdays, combined with the local time (LocalTime) as seen on a wall clock.
ZonedDateTime is a date-time with a time-zone in the ISO-8601 calendar system, such as 2007-12-24T16:15:30+01:00 UTC+01:00.
Instant is an instantaneous point on the time-line measured from the epoch of 1970-01-01T00:00:00Z in epoch-seconds and nanosecond-of-second.
Duration and Period
Duration is a time-based amount of time, such as ‘34.5 seconds’.
Period is a date-based amount of time in the ISO-8601 calendar system, such as ‘2 years, 3 months and 4 days’.
Additional value types
Year represents a year in the ISO-8601 calendar system, such as ‘2016’.
YearMonth represents a year and a month in the ISO-8601 calendar system, such as ‘2016-01’.
Month represents a month-of-year in the ISO-8601 calendar system, such as ‘July’.
MonthDay represents a month-day in the ISO-8601 calendar system, such as ‘–12-03’. Could be used to represent e.g. Birthdays.
DayOfWeek represents a day-of-week in the ISO-8601 calendar system, such as ‘Tuesday’.
Install joda using npm
npm install js-joda
Then require it to any module
var LocalDate = require('js-joda').LocalDate; var d = LocalDate.parse('2012-12-24').atStartOfDay().plusMonths(2); // 2013-02-24T00:00:00
To use js-joda from a browser, download either dist/js-joda.min.js or dist/js-joda.js (with sourcemaps for development)
Then add it as a script tag to your page
<script src="js-joda.min.js"></script> <script> var LocalDate = JSJoda.LocalDate; var d = LocalDate.parse('2012-12-24').atStartOfDay().plusMonths(2); // 2013-02-24T00:00:00 </script>
- Cheat Sheet Quick start guide
- API ESDoc generated API documentation
- js-joda Homepage Project homepage
Milestone 1 core domains (reached with version v1.0.0)
Support for the domain models LocalDate, LocalDateTime, ZonedDateTime, Instant, Duration and Period converting from and to ISO8601. ZonedDateTime (without support for loading iana time-zone databases) currently supports only fixed offsets like UTC or UTC+02:00 and the system default time zone.
Milestone 2 iana timezone support (reached with version v1.2.0)
Add iana timezone database support to js-joda. Implement handling of Daylight saving transitions mainly in ZonedDateTime.
Milestone 3 locale support
Add locale support.
Extend pattern parser/ formatter for text with locale support.
- Reduce library size be removing redundant code, especially by refactoring code for formatting/ parsing dates.
- Increase test coverage (ongoing task)
- Cleanup documentation (ongoing task)
- simplify temporal adjusters (amount, etc) by using functions instead of classes or objects
Contributions are always welcome. Before contributing please read the code of conduct & search the issue tracker. We use GitHub issues. Your issue may have already been discussed or fixed. To contribute, fork js-joda, commit your changes, & send a pull request.
By contributing to js-joda, you agree that your contributions will be licensed under its BSD license.
Note that pull requests and issues will only be considered so far as matching the threeten backport API. Additional requested features will be rejected.
Joda time is the base for JSR-310 that became part of Java SE 8 in the java.time package. JSR-310 is a new implementation with an API ‘inspired by Joda-Time’ but improvements on some design flaws (see http://blog.joda.org/2009/11/why-jsr-310-isn-joda-time_4941.html)
js-joda is released under the BSD 3-clause license:
our implementation reference base ThreeTen-Backport (http://www.threeten.org/threetenbp/) is also released under the BSD 3-clause license
Joda-Time is under Apache 2.0 licence.
OpenJDK is under GNU GPL+linking exception.
The author of joda time and the lead architect of the JSR-310 is Stephen Colebourne.