Consistent formatting of dates on Church Center
npm install @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.
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
``javascript`
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.
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.
`javaScriptmoment()
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 (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.
`javascript`
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.
This README is intentionally short while we propose this API.
The exhaustive tests are a great resource for digging into the finer details.
`
yarn test
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 |standard
|-|-|-|
|August 1||false|standard
|August 1, 2020||true|short
|8/1||false|short
|8/1/2020||true|abbreviated
|Aug 1||false|abbreviated
|Aug 1, 2020||true|long
|Saturday, August 1||false|long
|Saturday, August 1, 2020||true|abbreviated-long
|Sat, Aug 1||false|abbreviated-long
|Sat, Aug 1, 2020||true|
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 |
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)false
If , the abbreviation is never* appended (8:16am)automatic`, the abbreviation is appended to the time/datetime string if and only if the viewer's timezone differs from the configured timezone.
* If