@hero-page/hero-date-time-utils

This entire repository was created completely with AI, using the hero-ai-package-creator, which is open-source, uses GPT-4, and is written & maintained by Sam Chahine ❣️🧞‍♀️

hero-date-time-utils

A collection of functions for handling dates and times, such as formatting, calculating differences, converting to different time zones, and more.

Functions

formatDate

Takes a Date object or Unix timestamp (milliseconds since January 1 1970) and a format string, and returns a formatted string. Format string may contain placeholders to insert parts of the date. For example, formatDate(new Date(), 'MMMM Do, YYYY') will return 'January 1st, 2022'. Should handle leap years and edge cases such as the year 2000 correctly. Rejects invalid inputs such as when the Unix timestamp is negative or the format string contains unrecognized placeholders.

calculateDifference

Takes two Date objects or Unix timestamps and returns the time difference between them in a specified unit (seconds, minutes, hours, days, months, years). Automatically handles leap years and daylight-saving time changes. Accepts negative differences (e.g., when the first input date is later than the second), but rejects non-Date or non-Unix timestamp inputs.

convertTimeZone

Takes a Date object or Unix timestamp, its current time zone (represented as UTC offset in minutes), and the desired time zone (represented as UTC offset in minutes), and converts the date to match its new time zone. Returns a new Date object with the converted time. Handles edge cases like crossing the International Date Line, but rejects non-Date or non-Unix timestamp inputs and non-integer time zones.

startOfDay

Takes a Date object or Unix timestamp and returns a new Date object set at the start of the day (00:00:00) for the input date. Rejects non-Date or non-Unix timestamp inputs.

endOfDay

Takes a Date object or Unix timestamp and returns a new Date object set at the end of the day (23:59:59) for the input date. Rejects non-Date or non-Unix timestamp inputs.

getUnixTimestamp

Takes a Date object and returns its Unix timestamp (milliseconds since January 1 1970). Rejects non-Date inputs or negative Unix timestamps.

getDateFromUnix

Takes a Unix timestamp (milliseconds since January 1 1970) and returns a Date object. Rejects non-Unix timestamp inputs or negative Unix timestamps.

isLeapYear

Takes a year number and returns a boolean value indicating whether it is a leap year. Handles edge cases like the year 2000 correctly. Rejects non-integer or negative year values.

daysInMonth

Takes a year number and a month number (1-12) and returns the number of days in that month, considering leap years. Rejects non-integer, negative, or out-of-range year and month values.

addTime

Takes a Date object or Unix timestamp, a value, and a time unit (seconds, minutes, hours, days, months, years), and returns a new Date object with the added time. Automatically handles leap years and daylight-saving time changes, but rejects non-Date or non-Unix timestamp inputs, non-integer values, or non-recognized time units.

---

Sam Chahine, at Hero

Tests for addTime

Tests for endOfDay

Tests for formatDate

Tests for convertTimeZone

Tests for getUnixTimestamp

Tests for isLeapYear

Tests for startOfDay

Tests for calculateDifference

Tests for getDateFromUnix

Tests for daysInMonth