frostdatetime v4.0.7

FrostDateTime

FrostDateTime is a free, open-source date manipulation library for JavaScript.

It is a lightweight (~7kb gzipped) and modern library, and features support for ICU formats, time zones and locales.

Table Of Contents

• Installation
• Date Creation
• Date Formatting
• Date Attributes
• Week Attributes
• Time Attributes
• Timestamps
• Time Zones
• Locales
• Utility Methods
• Static Methods

Installation

In Browser

<script type="text/javascript" src="/path/to/frost-datetime.min.js"></script>

Using NPM

npm i frostdatetime

In Node.js:

const { DateTime, DateTimeImmutable } = require('frostdatetime');

Date Creation

• dateString is a string representing the date, and will default to the current timestamp.
• options is an object containing properties to define the new date.
  • timeZone is a string representing the time zone of the date, and will default to the system time zone.
  • locale is a string representing the locale of the date, and will default to the system locale.

const date = new DateTime(dateString, options);

Immutable DateTime

By default, DateTime objects are mutable, but if you wish to create an immutable reference you can use the following syntax.

Immutable DateTime objects return a new DateTimeImmutable whenever they are modified.

const date = new DateTimeImmutable(dateString, options);

From Array

• dateArray is an array containing the year, month, date, hours, minutes, seconds and milliseconds.
• options is an object containing properties to define the new date.
  • timeZone is a string representing the time zone of the date, and will default to the system time zone.
  • locale is a string representing the locale of the date, and will default to the system locale.

const date = DateTime.fromArray(dateArray, options);

The month and date in the dateArray will default to 1 if not set. The hours, minutes, seconds and milliseconds will default to 0.

From Date

• dateObj is a native JS Date object.
• options is an object containing properties to define the new date.
  • timeZone is a string representing the time zone of the date, and will default to the system time zone.
  • locale is a string representing the locale of the date, and will default to the system locale.

const date = DateTime.fromDate(dateObj, options);

From Format

If you wish to parse a date string and you know the exact format, you can use the fromFormat static method.

• formatString is a string containing the format you wish to use for parsing.
• dateString is a string representing the date you are parsing.
• options is an object containing properties to define the new date.
  • timeZone is a string representing the time zone of the date, and will default to the system time zone.
  • locale is a string representing the locale of the date, and will default to the system locale.

The formatString supports a subset of the ICU specification described in Formats.

The isValid property on the created DateTime object can be used to determine whether a formatted string was a valid date.

const date = DateTime.fromFormat(formatString, dateString, options);

From ISO String

• dateString is a string representing the date you are parsing.
• options is an object containing properties to define the new date.
  • timeZone is a string representing the time zone of the date, and will default to the system time zone.
  • locale is a string representing the locale of the date, and will default to English.

The dateString must be in yyyy-MM-dd'T'HH:mm:ss.SSSxxx" format and in English.

If the timeZone option is also passed, the created DateTime will be converted to the new timeZone.

The isValid property on the created DateTime object can be used to determine whether a formatted string was a valid date.

const date = DateTime.fromISOString(dateString, options);

From Timestamp

• timestamp is the number of seconds since the UNIX epoch.
• options is an object containing properties to define the new date.
  • timeZone is a string representing the time zone of the date, and will default to the system time zone.
  • locale is a string representing the locale of the date, and will default to the system locale.

const date = DateTime.fromTimestamp(timestamp, options);

Now

• options is an object containing properties to define the new date.
  • timeZone is a string representing the time zone of the date, and will default to the system time zone.
  • locale is a string representing the locale of the date, and will default to the system locale.

const date = DateTime.now(options);

Date Formatting

Format

Once you have created a DateTime object, you can get a string representation using a specific format with the format method.

• formatString is a string containing the format you wish to output using.

The formatString supports a subset of the ICU specification described in Formats.

const dateString = date.format(formatString);

To String

Format the current date using "eee MMM dd yyyy HH:mm:ss xx (VV)".

const string = date.toString();

To Date String

Format the current date using "eee MMM dd yyyy".

const dateString = date.toDateString();

To ISO String

Format the current date using "yyyy-MM-dd'T'HH:mm:ss.SSSxxx" (in English and UTC time zone).

const isoString = date.toISOString();

To Time String

Format the current date using "HH:mm:ss xx (VV)".

const timeString = date.toTimeString();

To UTC String

Format the current date using "eee MMM dd yyyy HH:mm:ss xx (VV)" (in UTC time zone).

const utcString = date.toUTCString();

Date Attributes

Get Date

Get the date in current time zone.

const date = date.getDate();

Get Day

Get the day of the week in current time zone.

The day returned will be between 0 (Sunday) and 6 (Saturday).

const day = date.getDay();

Get Day Of Year

Get the day of the year in current time zone.

The dayOfYear returned will be between 0 and 365.

const dayOfYear = date.getDayOfYear();

Get Month

Get the month in current time zone.

The month returned will be between 1 (January) and 12 (December).

const month = date.getMonth();

Get Quarter

Get the quarter of the year in current time zone.

The quarter returned will be between 1 and 4.

const quarter = date.getQuarter();

Get Year

Get the year in current time zone.

const year = date.getYear();

Set Date

Set the date in current time zone.

• date is a number representing the date.

date.setDate(date);

Set Day

Set the day of the week in current time zone.

• day is a number representing the day of the week (between 0 and 6).

date.setDay(day);

Set Day Of Year

Set the day of the year in current time zone.

• dayOfYear is a number representing the day of the year (between 0 and 365).

date.setDayOfYear(dayOfYear);

Set Month

Set the month in current time zone.

• month is a number representing the month (between 1 and 12).
• date is a number representing the date, and will default to the current value.

If the date argument is omitted, and the new month contains less days than the current date, the date will be set to the last day of the new month.

To disable date clamping, use the method DateTime.setDateClamping() using false as the argument.

date.setMonth(month, date);

Set Quarter

Set the quarter of the year in current time zone.

• quarter is a number representing the quarter between 1 and 4.

date.setQuarter(quarter);

Set Year

Set the year in current time zone.

• year is a number representing the year.
• month is a number representing the month (between 1 and 12), and will default to the current value.
• date is a number representing the date, and will default to the current value.

If the date argument is omitted, and the new month contains less days than the current date, the date will be set to the last day of the new month.

To disable date clamping, use the method DateTime.setDateClamping() using false as the argument.

date.setYear(year, month, date);

Week Attributes

Get Week

Get the week of the year in current time zone.

The week returned will be between 1 and 53 (week starting on Monday).

const week = date.getWeek();

Get Week Day

Get the local day of the week in current time zone.

The weekDay returned will be between 1 and 7.

const weekDay = date.getWeekDay();

Get Week Day In Month

Get the day of the week in the month, in current time zone.

The weekDayInMonth returned will be between 1 and 5.

const weekDayInMonth = date.getWeekDayInMonth();

Get Week Of Month

Get the week of the month in current time zone.

The weekOfMonth returned will be between 1 and 5.

const weekOfMonth = date.getWeekOfMonth();

Get Week Year

Get the week year in current time zone.

This method is identical to getYear() except in cases where the week belongs to the previous or next year, then that value will be used instead.

const weekYear = date.getWeekYear();

Set Week

Set the week in current time zone.

• week is a number representing the week.
• weekDay is a number representing the day (between 1 and 7), and will default to the current value.

date.setWeek(week, weekDay);

Set Week Day

Set the local day of the week in current time zone.

• weekDay is a number representing the week day (between 1 and 7).

date.setWeekDay(weekDay);

Set Week Day In Month

Set the day of the week in the month, in current time zone.

• weekDayInMonth is a number representing the day of the week in month (between 1 and 5).

date.setWeekDayInMonth(weekDayInMonth);

Set Week Of Month

Set the week of the month in current time zone.

• weekOfMonth is a number representing the week of the month (between 1 and 5).

date.setWeekOfMonth(weekOfMonth);

Set Week Year

Set the week year in current time zone.

• weekYear is a number representing the year.
• week is a number representing the week, and will default to the current value.
• weekDay is a number representing the day (between 1 and 7), and will default to the current value.

date.setWeekYear(weekYear, week, weekDay);

Time Attributes

Get Hours

Get the hours of the day in current time zone.

The hours returned will be between 0 and 23.

const hours = date.getHours();

Get Milliseconds

Get the milliseconds of the second in current time zone.

The milliseconds returned will be between 0 and 999.

const milliseconds = date.getMilliseconds();

Get Minutes

Get the minutes of the hour in current time zone.

The minutes returned will be between 0 and 59.

const minutes = date.getMinutes();

Get Seconds

Get the seconds of the minute in current time zone.

The seconds returned will be between 0 and 59.

const seconds = date.getSeconds();

Set Hours

Set the hours of the day in current time zone.

• hours is a number representing the hours of the day (between 0 and 23).
• minutes is a number representing the minutes of the hour (between 0 and 59), and will default to the current value.
• seconds is a number representing the seconds of the minute (between 0 and 59), and will default to the current value.
• milliseconds is a number representing the milliseconds of the second (between 0 and 999), and will default to the current value.

date.setHours(hours, minutes, seconds, milliseconds);

Set Milliseconds

Set the milliseconds of the second in current time zone.

• milliseconds is a number representing the milliseconds of the second (between 0 and 999).

date.setMilliseconds(milliseconds);

Set Minutes

Set the minutes of the hour in current time zone.

• minutes is a number representing the minutes of the hour (between 0 and 59).
• seconds is a number representing the seconds of the minute (between 0 and 59), and will default to the current value.
• milliseconds is a number representing the milliseconds of the second (between 0 and 999), and will default to the current value.

date.setMinutes(minutes, seconds, milliseconds);

Set Seconds

Set the seconds of the minute in current time zone.

• seconds is a number representing the seconds of the minute (between 0 and 59).
• milliseconds is a number representing the milliseconds of the second (between 0 and 999), and will default to the current value.

date.setSeconds(seconds, milliseconds);

Timestamps

Get Milliseconds

Get the number of milliseconds since the UNIX epoch.

const time = date.getTime();

Get Seconds

Get the number of seconds since the UNIX epoch.

const timestamp = date.getTimestamp();

Set Milliseconds

Set the number of milliseconds since the UNIX epoch.

date.setTime(time);

Set Seconds

Set the number of seconds since the UNIX epoch.

date.setTimestamp(timestamp);

Time Zones

Get Time Zone

Get the name of the current time zone.

const timeZone = date.getTimeZone();

Get Time Zone Offset

Get the UTC offset (in minutes) of the current time zone.

const offset = date.getTimeZoneOffset();

Set Time Zone

Set the current time zone.

• timeZone is the name of the new time zone, which can be either "UTC", a supported value from the IANA timeZone database or an offset string.

date.setTimeZone(timeZone);

Set Time Zone Offset

Set the UTC offset (in minutes).

• offset is the UTC offset (in minutes).

date.setTimeZoneOffset(offset);

Locales

Get Locale

Get the name of the current locale.

const locale = date.getLocale();

Set Locale

Set the current locale.

• locale is the name of the new locale.

date.setLocale(locale);

Manipulation

Add

Add a duration to the date.

• amount is a number representing the amount of the timeUnit to add.
• timeUnit is a string representing the unit of time to add, and can be one of either "year", "month", "week", "day", "hour", "minute" or "second", or their pluralized versions.

date.add(amount, timeUnit);

End Of

Set the date to the end of a unit of time in current time zone.

• timeUnit is a string representing the unit of time to use, and can be one of either "year", "quarter", "month", "week", "day", "hour", "minute" or "second".

date.endOf(timeUnit);

Start Of

Set the date to the start of a unit of time in current time zone.

• timeUnit is a string representing the unit of time to use, and can be one of either "year", "quarter", "month", "week", "day", "hour", "minute" or "second".

date.startOf(timeUnit);

Subtract

• amount is a number representing the amount of the timeUnit to subtract.
• timeUnit is a string representing the unit of time to subtract, and can be one of either "year", "month", "week", "day", "hour", "minute" or "second", or their pluralized versions.

date.sub(amount, timeUnit);

Utility Methods

Clone

Create a new DateTime using the current date and time zone.

const clone = date.clone();

Day Name

Get the name of the day of the week in current time zone and locale.

• type can be either "long", "short" or "narrow", and will default to "long" if it is not set.

const dayName = date.dayName(type);

Day Period

Get the day period in current time zone and locale.

• type can be either "long" or "short", and will default to "long" if it is not set.

const dayPeriod = date.dayPeriod(type);

Days In Month

Get the number of days in the current month.

const daysInMonth = date.daysInMonth();

Days In Year

Get the number of days in the current year.

const daysInYear = date.daysInYear();

Difference

Get the difference between two Dates.

• other is the DateTime object to compare to.
• timeUnit is a string representing the unit of time to return, and can be one of either "year", "month", "week", "day", "hour", "minute" or "second", or their pluralized versions.
• relative is a boolean indicating whether to return the relative difference, and will default to true.

If the timeUnit is omitted, this method will return the difference in milliseconds.

const diff = date.diff(other, timeUnit, relative);

If relative is true (default) the value returned will be the difference in the specified timeUnit, ignoring less significant values.

DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2018-12-31'), 'years', true); // 1
DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2018-12-31'), 'years', false); // 0
DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2017-12-31'), 'years', true); // 2
DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2017-12-31'), 'years', false); // 1

Era

Get the era in current time zone and locale.

• type can be either "long", "short" or "narrow", and will default to "long" if it is not set.

const era = date.era(type);

Human Difference

Get the relative difference between two Dates in a human readable format using the current locale.

• other is the DateTime object to compare to.
• timeUnit is a string representing the unit of time to return, and can be one of either "year", "month", "week", "day", "hour", "minute" or "second", or their pluralized versions.

If the timeUnit is omitted, this method will use the (relative) most significant non-zero value.

const diff = date.humanDiff(other, timeUnit);

The most significant non-zero value is determined where the unit of time has a non-relative difference, or the next relative difference value is greater than or equal to the unit of time.

DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').humanDiff(DateTime.fromFormat('yyyy-MM-dd', '2018-12-31')); // "tomorrow"
DateTime.fromFormat('yyyy-MM-dd', '2019-02-27').humanDiff(DateTime.fromFormat('yyyy-MM-dd', '2019-01-31')); // "in 27 days"
DateTime.fromFormat('yyyy-MM-dd', '2019-02-28').humanDiff(DateTime.fromFormat('yyyy-MM-dd', '2019-01-31')); // "next month"
DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').humanDiff(DateTime.fromFormat('yyyy-MM-dd', '2018-06-01')); // "in 6 months"
DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').humanDiff(DateTime.fromFormat('yyyy-MM-dd', '2018-01-31')); // "next year"
DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').humanDiff(DateTime.fromFormat('yyyy-MM-dd', '2017-12-31')); // "in 2 years"

Is After?

Return true if the DateTime is after another date.

• other is the DateTime object to compare to.
• granularity is a string specifying the level of granularity to use when comparing the dates, and can be one of either "year", "month", "day", "hour", "minute" or "second".

const isAfter = date.isAfter(other, granularity);

If a granularity is not specified, this method will compare the dates in milliseconds.

Is Before?

Return true if the DateTime is before another date.

• other is the DateTime object to compare to.
• granularity is a string specifying the level of granularity to use when comparing the dates, and can be one of either "year", "month", "day", "hour", "minute" or "second".

const isBefore = date.isBefore(other, granularity);

If a granularity is not specified, this method will compare the dates in milliseconds.

Is Between?

Return true if the DateTime is between two other dates.

• start is the starting DateTime object to compare to.
• end is the ending DateTime object to compare to.
• granularity is a string specifying the level of granularity to use when comparing the dates, and can be one of either "year", "month", "day", "hour", "minute" or "second".

const isBetween = date.isBetween(start, end, granularity);

If a granularity is not specified, this method will compare the dates in milliseconds.

Is DST?

Return true if the DateTime is in daylight savings.

const isDST = date.isDST();

Is Leap Year?

Return true if the year is a leap year.

const isLeapYear = date.isLeapYear();

Is Same?

Return true if the DateTime is the same as another date.

• other is the DateTime object to compare to.
• granularity is a string specifying the level of granularity to use when comparing the dates, and can be one of either "year", "month", "day", "hour", "minute" or "second".

const isSame = date.isSame(other, granularity);

If a granularity is not specified, this method will compare the dates in milliseconds.

Is Same Or After?

Return true if the DateTime is the same or after another date.

• other is the DateTime object to compare to.
• granularity is a string specifying the level of granularity to use when comparing the dates, and can be one of either "year", "month", "day", "hour", "minute" or "second".

const isSameOrAfter = date.isSameOrAfter(other, granularity);

If a granularity is not specified, this method will compare the dates in milliseconds.

Is Same Or Before?

Return true if the DateTime is the same or before another date.

• other is the DateTime object to compare to.
• granularity is a string specifying the level of granularity to use when comparing the dates, and can be one of either "year", "month", "day", "hour", "minute" or "second".

const isSameOrBefore = date.isSameOrBefore(other, granularity);

If a granularity is not specified, this method will compare the dates in milliseconds.

Month Name

Get the name of the month in current time zone and locale.

• type can be either "long", "short" or "narrow", and will default to "long" if it is not set.

const monthName = date.monthName(type);

Time Zone Name

Get the name of the current time zone and locale.

• type can be either "long" or "short", and will default to "long" if it is not set.

const timeZoneName = date.timeZoneName(type);

Weeks In Year

Get the number of weeks in the current year.

const weeksInYear = date.weeksInYear();

Static Methods

Day Of Year

Get the day of the year for a year, month and date.

• year is a number representing the year.
• month is a number representing the month (between 1 and 12).
• date is a number representing the date.

const dayOfYear = DateTime.dayOfYear(year, month, date);

Days In Month

Get the number of days in a month, from a year and month.

• year is a number representing the year.
• month is a number representing the month (between 1 and 12).

const daysInMonth = DateTime.daysInMonth(year, month);

Days In Year

Get the number of days in a year.

• year is a number representing the year.

const daysInYear = DateTime.daysInYear(year);

Is Leap Year?

Return true if the year is a leap year.

• year is a number representing the year.

const isLeapYear = DateTime.isLeapYear(year);

Set Date Clamping

Set whether dates will be clamped when changing months.

• clampDates is a boolean indicating whether to clamp dates.

DateTime.setDateClamping(clampDates);

Set Default Locale

Set the default locale.

• locale is the name of the locale.

DateTime.setDefaultLocale(locale);

Set Default Time Zone

Set the default time zone.

• timeZone is the name of the time zone, which can be either "UTC", a supported value from the IANA timeZone database or an offset string.

DateTime.setDefaultTimeZone(timeZone);