v2.0.0-alpha.27 is out and along with many fixes and improvements, it brings an important breaking change. From now on functions will accept only dates and numbers as arguments. Strings should be parsed beforehand. This change enabled us to bring the minimal library build down to 300 B which makes date-fns the smallest date library out there (*). We also introduced a new lightFormat function that allows formatting dates using the most popular tokens, and its size is just 900 B. I hope this will be last alpha version before beta release.

(*) I'm actually didn't check every existing JavaScript library, but it's smaller than Day.js and definitely way smaller than Moment.js.

In v1 we relied on new Date() for parsing date strings. Unfortunately, the ECMAScript spec isn't strict about how engines should parse strings, and that resulted in subtle differences between browsers. These differences caused many nasty hard-to-track bugs that made us write our own ISO 8601 parser. That increased minimal library build size up to 1.5 KB. For reference, in v1 addDays was 1 KB in before v2.0.0-alpha.27 it was 1.6 KB. Now it's 385 B. Many choose date-fns because it's lightweight and we have to keep it lean, so we removed the ability to pass strings. If you used ISO 8601 to keep dates, you'd have to parse them new parseISO function:

// Before
addDays('2016-01-01', 1)

// Now
addDays(parseISO('2016-01-01'), 1)

Please help us to test this release and tell what you think! See the full change log: https://git.io/fhZp5

I with Lesha are going on vacation in Sri Lanka so you won't hear for us in the upcoming two weeks.

Gist

date-fns v2 pre-releases change log

date-fns v2 pre-releases change log. GitHub Gist: instantly share code, notes, and snippets.

A new v2 alpha is out. It introduces an important DST fix along with many other improvements and additions. See the full changelog below.

Hopefully, it will be the last alpha release as the current goal is to ship a beta version and start preparing for the final release. Stay tuned!

- Fixed DST issue. See #972 and #992 for more details.

- id locale was updated for v2. Credits go to @Imballinst!

- Updated Swedish locale to better reflect how relative weekdays are spoken in Swedish. Thanks to @Neorth!

A year after v1.29.0 we've shipped a new v1 version. It includes a fix for a DST issue, new Serbian and Belarusian locales and also fixes for Thai and Japanese locales. See the full change log below.

It was a long time coming release. We had few pull-requests waiting for months for the merge, but because of complication with the build system, we never had the chance to approach them. The DST fix that we've introduced in v2 and backported to v1 gave us needed motivation.

This release will also be the last minor release of v1. From now on we'll be only publishing bug and security fixes, but no more new features, locales, and improvements.

- Fixed DST issue. See #972 and #992 for more details. This fix was backported from v2.

- Fix a few bugs that appear in timezones with offsets that include seconds (e.g. GMT+00:57:44). See PR #789. This fix was backported from v2.

- Fix misspelled January in the Thai locale. Thanks to @ratchapol-an!

- Added Serbian locale. Kudos to @mawi12345!

- Added Belarusian locale. Kudos to @mawi12345 again!

- Improve Japanese translation of distanceInWords. Thanks to @kudohamu!

One of the most important changes in v2 is the new API design. We carefully refined every function to make date-fns consistent, predictable and reliable. This post is the third post on API design where I tell about our decision to stick to existing standards.

You can read the opening post here: https://blog.date-fns.org/post/date-fns-v2-goals-and-values-3q4uj0mon4lhp

date-fns v2 introduces many new features and breaking changes, and this post is a part of a series #date_fns_v2 where we describe in detail most notable ones.

v2 started with the change of the filenames naming scheme. I come from the Ruby world, so I thought it's a good idea to have file names in underscore format. JavaScript renaissance just started, so there wasn't a common standard. Initially, it was irritating to see so many JavaScript'ers using the camel case format for files. But eventually, I accepted the difference and decided to prioritize common practices over personal taste and adopted camel case as well.

// v1
const addDays = require('date-fns/add_days')

// v2
const addDays = require('date-fns/addDays')

This breaking change was a turning point that allowed us to abstract from our points of views and habits and embrace existing standards and well-established practices.

One of the most significant changes was adopting Unicode Technical Standard #35 for format and parse. It caused a lot of confusion, but I believe it's worth it. You can read about that in a dedicated post:

Another standard that caused us to revisit naming schema was ISO 8601. Starting with isWithinRange function we used the word "range" for time spans:

const isWithinRange = require('date-fns/is_within_range')
isWithinRange(
  new Date(2014, 0, 3), // the date to check
  new Date(2014, 0, 1), // start
  new Date(2014, 0, 7) // end
)
//=> true

It turned out that ISO 8601:2004 defines term "interval":

time interval: part of the time axis limited by two instants

We adopted this terminology and made interval a separate entity:

import { isWithinInterval } from 'date-fns'
isWithinInterval(new Date(2014, 0, 3), {
  start: new Date(2014, 0, 1),
  end: new Date(2014, 0, 7)
})

It also made the code easier to read!

When a string is passed to new Date(), the JavaScript engine tries to do its best parsing it. In v1 we relied on the mechanism but then quickly learned that different browsers have different parsers and it leads to bugs that hard to find.

Starting with v2, whenever a string represents a date it must be a valid ISO 8601 string overwise you'll get Invalid Date.