@js-joda/core
Advanced tools
@js-joda/core is a JavaScript library for working with dates and times. It is a port of the Joda-Time library from Java, providing a comprehensive and immutable date and time API for JavaScript. The library is designed to be easy to use and to provide a consistent and reliable way to handle date and time operations.
Creating Dates and Times
This feature allows you to create instances of LocalDate, LocalTime, and LocalDateTime representing the current date, time, and date-time respectively.
const { LocalDate, LocalTime, LocalDateTime } = require('@js-joda/core');
const date = LocalDate.now();
const time = LocalTime.now();
const dateTime = LocalDateTime.now();
console.log(date.toString()); // e.g., 2023-10-05
console.log(time.toString()); // e.g., 14:30:00.123
console.log(dateTime.toString()); // e.g., 2023-10-05T14:30:00.123Parsing and Formatting
This feature allows you to parse date strings into LocalDate objects using a specified pattern and format LocalDate objects back into strings.
const { LocalDate, DateTimeFormatter } = require('@js-joda/core');
const dateString = '2023-10-05';
const formatter = DateTimeFormatter.ofPattern('yyyy-MM-dd');
const date = LocalDate.parse(dateString, formatter);
console.log(date.toString()); // 2023-10-05Date Arithmetic
This feature allows you to perform arithmetic operations on dates, such as adding or subtracting days, weeks, months, or years.
const { LocalDate } = require('@js-joda/core');
const date = LocalDate.of(2023, 10, 5);
const nextWeek = date.plusWeeks(1);
const previousMonth = date.minusMonths(1);
console.log(nextWeek.toString()); // 2023-10-12
console.log(previousMonth.toString()); // 2023-09-05Comparing Dates and Times
This feature allows you to compare dates and times to determine if one is before, after, or equal to another.
const { LocalDate } = require('@js-joda/core');
const date1 = LocalDate.of(2023, 10, 5);
const date2 = LocalDate.of(2023, 10, 6);
console.log(date1.isBefore(date2)); // true
console.log(date1.isAfter(date2)); // false
console.log(date1.equals(date2)); // falseMoment.js is a widely-used library for parsing, validating, manipulating, and formatting dates in JavaScript. It is known for its ease of use and extensive functionality. However, Moment.js is mutable and has a larger footprint compared to @js-joda/core, which is immutable and more lightweight.
date-fns is a modern JavaScript date utility library that provides a comprehensive set of functions for working with dates. It is modular, allowing you to import only the functions you need, which can result in smaller bundle sizes. date-fns is similar to @js-joda/core in terms of immutability and functional programming style.
Luxon is a modern JavaScript library for working with dates and times, created by one of the Moment.js developers. It offers a more modern API and better support for internationalization compared to Moment.js. Luxon is similar to @js-joda/core in that it provides immutable date-time objects and a comprehensive API.
js-joda is an immutable date and time library for JavaScript. It provides a simple, domain-driven and clean API based on the ISO calendar system, which is the de facto world calendar following the proleptic Gregorian rules.
js-joda has a lightweight footprint, only 43 kB minified and compressed, no third party dependencies.
js-joda is fast. It is about 2 to 10 times faster than other JavaScript date libraries.
js-joda comes with built-in parsers/ formatters for ISO 8601 as specified in RFC 3339, that can be easily customized.
js-joda supports ECMAScript 5 browsers down to IE11.
js-joda is a port of the threeten backport, which 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.
Popular JavaScript date libraries like moment or date-utils are wrappers around the native JavaScript Date object, providing syntactic sugar. The native Date object always consist of a date, time and a timezone part. In contrast, js-joda is a standalone date and time implementation.
The API has a domain-driven design with classes for each of the different use cases, like LocalDate, ZonedDateTime or Period. For example, LocalDate allows you to handle dates without times (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.
LocalDate represents a date without a time and timezone in the ISO-8601 calendar system, such as 2007-12-24.
LocalTime represents a time without timezone 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 timezone 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 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'.
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/core
Then require it to any module
var LocalDate = require('@js-joda/core').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>
js-joda consist of four packages:
| package name | description | path |
|---|---|---|
@js-joda/core | Implementation of the ThreeTen Classes and API | /packages/core |
@js-joda/timezone | Implementation of timezone calculation based on the iana Time Zone Database | /packages/timezone |
@js-joda/locale | Implementation of locale specific functionality for js-joda, especially for formatting and parsing locale specific dates | /packages/locale |
@js-joda/extra | Implementation of the ThreeTen-Extra Classes and API | /packages/extra |
The @js-joda/examples package is for testing the different build artifacts in different context, like webpack, browser node, etc.
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 only pull requests and issues that match the threeten backport API will be considered. Additional requested features will be rejected.
js-joda is released under the BSD 3-clause license.
js-joda uses the ThreeTen-Backport implementation (http://www.threeten.org/threetenbp/) as a reference base for implementation. This allows us to release js-joda under the BSD License while the OpenJDK java.time implementation is under GNU GPL+linking exception. The API of the ThreeTen-Backport is mostly identical to the official Java SE 8 API from the view of our JavaScript port.
Our implementation reference base ThreeTen-Backport (http://www.threeten.org/threetenbp/) is also released under the BSD 3-clause license
OpenJDK is under GNU GPL+linking exception.
The author of Joda-Time and the lead architect of the JSR-310 is Stephen Colebourne.
The API of this project (as far as possible with JavaScript), a lot of implementation details and documentation are just copied but never equalled.
LocalDate, LocalDateTime, ZonedDateTime, Instant, Duration and Period converting to and from ISO8601.ZonedDateTime (without support for loading iana timezone databases) currently supports only fixed offsets like UTC or UTC+02:00 and the system default time zone.ZonedDateTime.see the plugin @js-joda/locale
FAQs
a date and time library for javascript
We found that @js-joda/core demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.