@planningcenter/datetime-fmt

@planningcenter/datetime-fmt

@planningcenter/datetime-fmt offers consistent formatting of dates and times. It is built to format dates, times, and dates-with-times given a timestamp or a range of timestamps. Special care is given to dropping redundant date information in ranges.

Usage

There are three functions.

• date for formatting dates
• time for formatting times
• datetime for formatting a dates-with-times

These functions all have the same signature

    date(start, end = null, configuration = {})
    time(start, end = null, configuration = {})
datetime(start, end = null, configuration = {})

• start is required. It's is the timestamp that you'd like to format, or the beginning of a time range.
• end is optional. If present, it represents the end of a time range.
• configuration is used to deviate from the "standard" formatting.

Configuration

There are a few of configuration options. Most of the time, you won't need these. But if you ever do, it's good to know they exist.

const defaultConfiguration = {
  dateFirst: false,
  hour12: true,
  timeZone: "America/Los_Angeles",
  showTimeZone: 'automatic', // 'automatic'/true/false
  style: "standard",
  year: false,
  yearSeparator: ", ",
  truncateSameMonth: true,
  truncateSameYear: true,
  anchorDate: new Date("2020-08-01T15:16:23Z"), // very optional - only used to anchor relative dates from a date other than `moment()` (current datetime), primarily for tests
}

The most often used configuration options will be year and style.

If year is true, the year is appended to a date.

The valid values for style are:

standard
short
long
abbreviated
abbreviated-long
relative
relative-short

You can see an exhaustive list of how these styles apply to dates in the tests. For brevity, here's the gist of named style to the formatted date it produces.

const dateString = "2020-08-01T15:16:23Z"
expect(datetimeFmt.date(dateString, { style: "standard" })).toEqual("August 1")
expect(datetimeFmt.date(dateString, { style: "short" })).toEqual("8/1")
expect(datetimeFmt.date(dateString, { style: "long" })).toEqual("Saturday, August 1")
expect(datetimeFmt.date(dateString, { style: "abbreviated" })).toEqual("Aug 1")
expect(datetimeFmt.date(dateString, { style: "abbreviated-long" })).toEqual("Sat, Aug 1")
expect(datetimeFmt.date(dateString, { style: "relative", anchorDate: new Date(dateString) })).toEqual("Today")
expect(datetimeFmt.date(dateString, { style: "relative-short", anchorDate: new Date(dateString) })).toEqual("8:16am")

Setting configuration globally

For hour12 and dateFirst in particular, we'll probably want to configure the library globally with the current organization's settings.

The setGlobalConfiguration and resetGlobalConfiguration functions can be used to setup/teardown the global configuration.

What else

This README is intentionally short while we propose this API. The exhaustive tests are a great resource for digging into the finer details.

Running tests

yarn test

Cheat Sheet

The style and year options are the most heavily used. Here's a cheat sheet of how they can be used to format dates.

Desired format	style option	year option
August 1	standard	false
August 1, 2020	standard	true
8/1	short	false
8/1/2020	short	true
Aug 1	abbreviated	false
Aug 1, 2020	abbreviated	true
Saturday, August 1	long	false
Saturday, August 1, 2020	long	true
Sat, Aug 1	abbreviated-long	false
Sat, Aug 1, 2020	abbreviated-long	true

Relative Dates

Relative dates are a special snowflake, and thus deserve their own cheatsheet.

Note that while they do technically support date ranges, they've been built primarily for displaying single (start) dates - so there might be some extra work needed to display ranges in a usable fashion.

Assuming a current date of Saturday, August 1, 2020 at 8:16am PT:

	date(date, { style: "relative-short" })	date(date, { style: "relative" })	datetime(date, { style: "relative" })
More than a year ago	Aug 1, 2019	August 1, 2019	August 1, 2019 at 8:16am
Within the last year	Feb 1	Saturday, February 1	Saturday, February 1 at 8:16am
Within the last week	Wed	Wednesday	Wednesday at 8:16am
The day before	Fri	Yesterday	Yesterday at 8:16am
Same day	8:16am (yes, really)	Today	Today at 8:16am
The next day	Sun	Tomorrow	Tomorrow at 8:16am
Within the next week	Tue	Tuesday	Tuesday at 8:16am
Within the next year	Feb 1	Monday, February 1	Monday, February 1 at 8:16am
More than a year from now	Aug 1, 2022	August 1, 2022	August 1, 2022 at 8:16am

Time Zones

The showTimeZone option determines whether the configured timezone's abbreviation is appended to the time string:

• If true, the abbreviation is always appended to the time/datetime string (8:16am PDT)
• If false, the abbreviation is never appended (8:16am)
• If automatic, the abbreviation is appended to the time/datetime string if and only if the viewer's timezone differs from the configured timezone.