Date

An extended Date class with support for relative time formatting, time zone shifting, and a powerful token-based formatting system.

Installation

npm install @superhero/date

Usage

Relative Time Difference

import Date from '@superhero/date'

const past    = new Date('2024-01-05T12:00:00Z')
const future  = new Date('2024-01-10T12:00:00Z')

future.timeDifference(past) // "5 days ago"

Time Zone Shifting

const date  = new Date('2024-01-01T12:00:00Z')
const paris = date.getTime()
date.shiftTimeZone({ origin: 'Europe/Paris', target: 'America/New_York' })
date.timeDifference(paris) // "in 6 hours"

Format Tokens

The formatter supports rich token-based customization.

const date = new Date('2024-07-04T14:04:05.006+07:00')
date.config.timeZoneOrigin = '+07:00'

date.format('YYYY-MM-DD HH:ii:ss')  // "2024-07-04 14:04:05"
date.format('DATETIME+-')           // "Thursday, July 4, 2024 at 2:04:05 PM GMT+7"
date.format('TZ')                   // "GMT+07:00"
date.format('mm')                   // "04"

Format Options

| Token | Example | Description | | ------------ | ------------------------------------------ | ------------------------------------------------------ | | DATETIME+- | Thursday, July 4, 2024 at 2:04:05 PM GMT+7 | Full long date and time with numeric time zone offset. | | DATETIME | Thursday, July 4, 2024 at 2:04:05 PM | Full long date and time without time zone. | | Datetime+- | Jul 4, 2024, 2:04:05 PM GMT+7 | Short date with time and numeric time zone. | | Datetime | Jul 4, 2024, 2:04:05 PM | Short date with time, no time zone. | | datetime+- | 7/4/24, 2:04:05 PM GMT+7 | Numeric date with time and numeric time zone. | | datetime | 7/4/24, 2:04:05 PM | Compact numeric date and time. | | DATE | Thursday, July 4, 2024 | Full long date only. | | Date | Jul 4, 2024 | Short-form date only. | | date | 7/4/24 | Numeric short date. | | TIME+- | 2:04:05 PM GMT+07:00 | Time with full numeric time zone format. | | TIME | 2:04:05 PM GMT+7 | Time with simplified numeric time zone. | | Time | 2:04:05 PM | Time with seconds, no time zone. | | time | 2:04 PM | Short time without seconds. | | TIMEZONE | GMT+07:00 | Standard uppercase full time zone. | | TIMEZONE+- | GMT+07:00 | Full numeric time zone with +- label. | | Timezone | GMT+7 | Simplified mixed-case time zone. | | timezone | GMT+7 | Lowercase simplified time zone. | | timezone+- | GMT+7 | Lowercase simplified time zone with +- label. | | TZ | GMT+07:00 | Abbreviated uppercase time zone. | | tz | GMT+7 | Abbreviated lowercase time zone. | | +- | +07:00 | Pure numeric offset only. | | YYYY | 2024 | Four-digit year. | | yy | 24 | Two-digit year. | | MONTH | July | Full month name. | | month | Jul | Abbreviated month name. | | Month1 | J | First letter of month name. | | MM | 07 | Two-digit month number. | | MM1 | 7 | One-digit month number if applicable. | | WEEKDAY | Thursday | Full weekday name. | | weekday | Thu | Abbreviated weekday name. | | Weekday1 | T | First letter of weekday. | | DAY | Thursday | Alias for full weekday name. | | day | Thu | Alias for abbreviated weekday name. | | Day1 | T | Alias for first letter of weekday. | | DD | 04 | Two-digit day of month. | | DD1 | 4 | One-digit day of month if applicable. | | HH | 14 | 24-hour clock, two digits. | | HH1 | 14 | 24-hour clock, one digit if applicable. | | H11 | 02 PM | 12-hour clock, two digits, with meridiem. | | h11 | 2 PM | 12-hour clock, one digit, with meridiem. | | H12 | 02 PM | Alias for H11. | | h12 | 2 PM | Alias for h11. | | H23 | 14 | 24-hour clock without meridiem. | | h23 | 14 | Alias for H23. | | H24 | 14 | Alias for H23. | | h24 | 14 | Alias for H23. | | mm | 04 | Two-digit minute. | | mm1 | 4 | One-digit minute if applicable. | | ii | 04 | Alias for minute (alternative token). | | ii1 | 4 | One-digit minute (alias). | | ss | 05 | Two-digit second. | | ss1 | 5 | One-digit second if applicable. | | ms | 006 | Milliseconds, padded. | | sss | 006 | Alias for milliseconds. | | sss1 | 6 | One-digit millisecond. | | ms1 | 6 | Alias for sss1. |

Configuration

date.config.locale           = 'en-US'
date.config.numeric          = 'auto'
date.config.timeZoneOrigin   = 'UTC'
date.config.timeZoneTarget   = 'Europe/Paris'
date.config.style            = 'long'
date.config.localeMatcher    = 'best fit'

Error Handling

• E_DATE_INVALID_ARGUMENT — When .timeDifference() is passed a non-Date.
• E_DATE_INVALID_SEGMENT — When .format() receives an unknown token.

Test Suite

Run tests using:

npm test

Test Coverage

────────────────────────────────── ⋅⋆ Suite ⋆⋅ ─────────────────────────────────


@superhero/date
├─ should calculate past time difference in days
│  └─ ✔ passed 102.345399ms
├─ should calculate future time difference in hours
│  └─ ✔ passed 0.562409ms
├─ should throw if invalid date passed to timeDifference
│  └─ ✔ passed 2.396263ms
├─ should shift time zone and change timestamp
│  └─ ✔ passed 9.967997ms
├─ should format with default configuration
│  └─ ✔ passed 5.700188ms
├─ should format with given locale and timeZone
│  └─ ✔ passed 5.322643ms
├─ should pad and display all mapped keys
│  └─ ✔ passed 17.852539ms
├─ should handle invalid format gracefully
│  └─ ✔ passed 0.455545ms
└─ ✔ suite passed 148.142275ms


──────────────────────────────── ⋅⋆ Coverage ⋆⋅ ────────────────────────────────


Files                                            Coverage   Branches   Functions
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
index.js                                              89%        92%         66%
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
index.test.js                                        100%       100%        100%
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Total                                                 92%        93%         76%


───────────────────────────────── ⋅⋆ Summary ⋆⋅ ────────────────────────────────


Suites                                                                         1
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Tests                                                                          8
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Passed                                                                         8
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Failed                                                                         0
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Cancelled                                                                      0
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Skipped                                                                        0
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Todo                                                                           0

License

This project is licensed under the MIT License.

Contributing

Feel free to submit issues or pull requests for improvements or additional features.