@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.