# Date

These are extensions to JavaScript's Date. [See this documentation for all standard Date methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#).

### Static properties

#### MS\_IN\_SECOND *number*

The number of milliseconds in a second.

#### MS\_IN\_MINUTE *number*

The number of milliseconds in a minute.

#### MS\_IN\_HOUR *number*

The number of milliseconds in an hour.

#### MS\_IN\_DAY *number*

The number of milliseconds in a day.

#### SECONDS\_IN\_MINUTE *number*

The number of seconds in a minute.

#### SECONDS\_IN\_HOUR *number*

The number of seconds in a hour.

#### SECONDS\_IN\_DAY *number*

The number of seconds in a day.

#### MINUTES\_IN\_HOUR *number*

The number of minutes in a hour.

#### MINUTES\_IN\_DAY *number*

The number of minutes in a day.

#### HOURS\_IN\_DAY *number*

The number of hours in a day.

#### DAYS\_IN\_WEEK *number*

The number of days in a week.

#### MONTHS\_IN\_QUARTER *number*

The number of months in a quarter.

#### QUARTERS\_IN\_YEAR *number*

The number of quarters in a year.

#### MONTHS\_IN\_YEAR *number*

The number of months in a year.

#### SUNDAY *number*

The day index for Sunday.

#### MONDAY *number*

The day index for Monday.

#### TUESDAY *number*

The day index for Tuesday.

#### WEDNESDAY *number*

The day index for Wednesday.

#### THURSDAY *number*

The day index for Thursday.

#### FRIDAY *number*

The day index for Friday.

#### SATURDAY *number*

The day index for Saturday.

### Methods

#### firstDayOfMonth

```javascript
firstDayOfMonth(year: number, month: number, dayIdx: number)
```

Returns the first day (of the week) of the month for the given year and month.

**Parameters**

    **year *****number***

        The year to use.

    **month *****number***

        The month to use. 1 = January, 2 = February, etc. (1-12)

    **dayIdx *****number***

        The day index to use. 0 = Sunday, 1 = Monday, etc. (0-6)

**Return type**

    Date

**Examples**

```javascript
Date.firstDayOfMonth(2025, 1, Date.MONDAY)   // => (Date) 2025-01-06
Date.firstDayOfMonth(2025, 1, Date.SATURDAY) // => (Date) 2025-01-04
```

#### lastDayOfMonth

```javascript
lastDayOfMonth(year: number, month: number, dayIdx: number)
```

Returns the last day (of the week) of the month for the given year and month.

**Parameters**

    **year *****number***

        The year to use.

    **month *****number***

        The month to use. 1 = January, 2 = February, etc. (1-12)

    **dayIdx *****number***

        The day index to use. 0 = Sunday, 1 = Monday, etc. (0-6)

**Return type**

    Date

**Examples**

```javascript
Date.lastDayOfMonth(2025, 1, Date.MONDAY)   // => (Date) 2025-01-27
Date.lastDayOfMonth(2025, 1, Date.SATURDAY) // => (Date) 2025-01-25
```

#### getHolidays

```javascript
getHolidays(cultureName: string)
```

Returns the holidays for the given year and culture.

**Parameters**

    **cultureName *****string***

        The culture name or object to use for determining weekends and holidays.

**Return type**

    CultureSpecificNonWorkingDays

**Examples**

```javascript
Date.getHolidays('NL')  // => { dates: { newYearsDay: '01-01', ... } }
```

#### addYears

```javascript
addYears(yearOffset: number)
```

Offset the date by the given amount of years. Returns a new Date and leaves the original the same.

**Parameters**

    **yearOffset *****number***

        The number of years to subtract from or add to the Date.

**Return type**

    Date

**Examples**

```javascript
DATE("2025-01-01").addYears(1)       // => (Date) 2026-01-01
DATE("2025-01-01").addYears(-10)     // => (Date) 2015-01-01
```

#### addQuarters

```javascript
addQuarters(quarterOffset: number)
```

Offset the date by the given amount of quarters. Returns a new Date and leaves the original the same.

**Parameters**

    **quarterOffset *****number***

        The number of quarters to subtract from or add to the Date.

**Return type**

    Date

**Examples**

```javascript
DATE("2000-01-01").addQuarters(1)      // => (Date) 2000-04-01
DATE("2000-01-01").addQuarters(-8)     // => (Date) 1998-01-01
DATE("2000-01-31").addQuarters(1)      // => (Date) 2000-04-30
```

#### addMonths

```javascript
addMonths(monthOffset: number)
```

Offset the date by the given amount of months. Returns a new Date and leaves the original the same.

**Parameters**

    **monthOffset *****number***

        The number of months to subtract from or add to the Date.

**Return type**

    Date

**Examples**

```javascript
DATE("2000-01-01").addMonths(1)      // => (Date) 2000-02-01
DATE("2000-01-01").addMonths(-10)    // => (Date) 1999-03-01
DATE("2000-01-31").addMonths(1)      // => (Date) 2000-02-29
```

#### addDays

```javascript
addDays(dayOffset: number)
```

Offset the date by the given amount of days. Returns a new Date and leaves the original the same.

**Parameters**

    **dayOffset *****number***

        The number of days to subtract from or add to the Date.

**Return type**

    Date

**Examples**

```javascript
DATE("2025-01-01").addDays(14)      // => (Date) 2025-01-15
DATE("2025-01-01").addDays(-1)      // => (Date) 2024-12-31
```

#### addWorkDays

```javascript
addWorkDays(workdayOffset: number, cultureName?: string | CultureSpecificNonWorkingDays)
```

Offset the date by the given amount of workdays. Will skip over weekends by default and a culture name or object may be specified. Returns a new Date and leaves the original the same.

**Parameters**

    **workdayOffset *****number***

        The number of workdays to subtract from or add to the Date.

    **cultureName *****string | CultureSpecificNonWorkingDays***

        (optional) The culture name or object to use for determining weekends and holidays.

**Return type**

    Date

**Examples**

```javascript
DATE("2000-01-01").addWorkDays(14)       // => (Date) 2000-01-20
DATE("2025-05-04").addWorkDays(1, 'NL')  // => (Date) 2025-05-06 (Dutch Liberation Day was skipped)

// Determining the working days is very culture-specific and even within a company it can be different.
// For flexibility, you can also specify an entirely new culture-specific object.
// In the example below, we defining a culture that only has one holiday (Jan. 2nd):
DATE("2025-01-01").addWorkDays(1, { dates: { myCustomHoliday: '01-02' } })  // => (Date) 2025-01-03

// But, in most cases you will want to derive the culture-specific object from an existing preset.
// In the example below, we are adding Good Friday to a copy of the Dutch holidays and remove King's Day
const nlHolidays = Date.getHolidays('NL')
nlHolidays.dates.goodFriday = function (year) {
    return nlHolidays.dates.easterMonday(year).addDays(-3)
}
delete nlHolidays.dates.kingsDay // Remove King's Day
DATE("2025-04-17").addWorkDays(1, nlHolidays)  // => (Date) 2025-04-22 (Good Friday, weekend and Easter Monday were skipped)
DATE("2023-04-26").addWorkDays(1, nlHolidays)  // => (Date) 2023-04-27 (King's Day was not skipped)
```

#### addHours

```javascript
addHours(hourOffset: number)
```

Offset the date by the given amount of hours. Returns a new Date and leaves the original the same.

**Parameters**

    **hourOffset *****number***

        The number of hours to subtract from or add to the Date.

**Return type**

    Date

**Examples**

```javascript
DATE("2025-01-01T12:30:00Z").addHours(1)      // => (Date) 2025-01-01 13:30:00
DATE("2025-01-01T12:00:00Z").addHours(-14)    // => (Date) 2024-12-31 22:00:00
```

#### addMinutes

```javascript
addMinutes(minuteOffset: number)
```

Offset the date by the given amount of minutes. Returns a new Date and leaves the original the same.

**Parameters**

    **minuteOffset *****number***

        The number of minutes to subtract from or add to the Date.

**Return type**

    Date

**Examples**

```javascript
DATE("2025-01-01T12:30:00Z").addMinutes(15)     // => (Date) 2025-01-01 12:45:00
DATE("2025-01-01T00:00:00Z").addMinutes(-15)    // => (Date) 2024-12-31 23:45:00
```

#### addSeconds

```javascript
addSeconds(secondOffset: number)
```

Offset the date by the given amount of seconds. Returns a new Date and leaves the original the same.

**Parameters**

    **secondOffset *****number***

        The number of seconds to subtract from or add to the Date.

**Return type**

    Date

**Examples**

```javascript
DATE("2025-01-01T12:30:00Z").addSeconds(15)     // => (Date) 2025-01-01 12:30:15
DATE("2025-01-01T00:00:00Z").addSeconds(-15)    // => (Date) 2024-12-31 23:59:45
```

#### addMilliseconds

```javascript
addMilliseconds(msOffset: number)
```

Offset the date by the given amount of seconds. Returns a new Date and leaves the original the same.

**Parameters**

    **msOffset *****number***

        The number of milliseconds to subtract from or add to the Date.

**Return type**

    Date

**Examples**

```javascript
DATE("2025-01-01T12:30:00Z").addMilliseconds(15)     // => (Date) 2025-01-01 12:30:00.015
DATE("2025-01-01T00:00:00Z").addMilliseconds(-15)    // => (Date) 2024-12-31 23:59:59.985
```

#### clone

```javascript
clone()
```

Creates a duplicate of the Date object.

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2025-01-01T12:30:00Z").clone()     // => (Date) 2025-01-01 12:30:00
```

#### daysInMonth

```javascript
daysInMonth(year?: number, month?: number)
```

Returns the number of days in the given year and month.

**Parameters**

    **year *****number***

        (optional) The year.

    **month *****number***

        (optional) The month. 1 = January, 12 = December.

**Return type**

    Date

**Examples**

```javascript
DATE("2000-02-01").daysInMonth()       // => 29 (the number of days in February 2000)
DATE("2001-01-01").daysInMonth(2)      // => 28 (the number of days in February 2001)
TODAY().daysInMonth(1)                  // => 31 (the number of days in January of the current (or any) year)
TODAY().daysInMonth(2000, 2)            // => 29 (the number of days in February 2000)
```

#### diff

```javascript
diff(otherDate: Date | string, absolute?: boolean)
```

Calculates the difference with another Date.

**Parameters**

    **otherDate *****Date | string***

        A JavaScript Date object or an ISO 8601 formatted string.

    **absolute *****boolean***

        (optional) If true, will return a positive value for the difference.

**Return type**

    DateDiffResult

**Examples**

```javascript
DATE("2000-02-01T12:30:45.999").diff("2020-10-31T13:00:00")   // => 
        {   
            totalMilliseconds: 654740954001,
            totalSeconds: 654740954.001,
            totalMinutes: 10912349.23335,
            totalHours: 181872.4872225,
            totalDays: 7578.0203009375,
            totalMonths: 248,
            totalYears: 20,
            totalFullSeconds: 654740954,
            totalFullMinutes: 10912349,
            totalFullHours: 181872,
            totalFullDays: 7578,
            totalFullMonths: 248,
            totalFullYears: 20
        }
```

#### diffAbs

```javascript
diffAbs(otherDate: Date | string)
```

Calculates the difference with another Date. Always returns a positive value, no matter what the order of comparison is (Future with Past or Past with Future). It is similar to calling 'diff' with the second parameter set to true.

**Parameters**

    **otherDate *****Date | string***

        A JavaScript Date object or an ISO 8601 formatted string.

**Return type**

    DateDiffResult

**Examples**

```javascript
DATE("2020-10-31T13:00:00").diffAbs("2000-02-01T12:30:45.999")  // See the example for diff() for the output.
```

#### isWeekend

```javascript
isWeekend(cultureNameOrObject?: string | CultureSpecificNonWorkingDays)
```

Returns whether the date is a weekend. By default, this will use the default of Saturday and Sunday. You can also specify a culture name or object to use for determining weekends.

**Parameters**

    **cultureNameOrObject *****string | CultureSpecificNonWorkingDays***

        (optional) The culture name or object to use for determining weekends.

**Return type**

    boolean

**Examples**

```javascript
DATE("2025-05-18").isWeekend()              // => true (Sunday the 18th of May 2025)
DATE("2025-05-18").isWeekend('NL')          // => true (Sunday the 18th of May 2025)
DATE("2025-05-18").isWeekend({ weekend: [Date.FRIDAY, Date.SATURDAY]})   // => false (Sunday was not a weekend in this culture)
```

#### isHoliday

```javascript
isHoliday(cultureNameOrObject?: string | CultureSpecificNonWorkingDays)
```

Returns whether the date is a holiday. By default this will return false, unless a culture name or object is specified and the date is a holiday in that culture.

**Parameters**

    **cultureNameOrObject *****string | CultureSpecificNonWorkingDays***

        (optional) The culture name or object to use for determining weekends and holidays.

**Return type**

    boolean

**Examples**

```javascript
DATE("2025-12-25").isHoliday()              // => false (Christmas is not a holiday in an unspecified culture)
DATE("2025-12-25").isHoliday('NL')          // => true (Christmas is a holiday in the Netherlands)
DATE("2025-01-02").isHoliday({ dates: { myCustomHoliday: '01-02' } })   // => true (Jan 2nd is a holiday in this imaginary culture)
```

#### isSameDay

```javascript
isSameDay(otherDate: Date | string)
```

Returns whether another Date is on the exact same day. This basically compares the year, month and day, but not the time part.

**Parameters**

    **otherDate *****Date | string***

        A JavaScript Date object or an ISO 8601 formatted string.

**Return type**

    boolean

**Examples**

```javascript
DATE("2020-10-31T00:00:00Z").isSameDay("2020-10-31T23:59:59.999Z")  // => true
DATE("2020-10-31").isSameDay("2021-10-31")                          // => false (The year is different)
```

#### isFuture

```javascript
isFuture()
```

Returns whether the Date object is in the future relative to the present date.

**Parameters**

**Return type**

    boolean

**Examples**

```javascript
TODAY().addDays(1).isFuture()               // => true (tomorrow is in the future)
TODAY().addSeconds(-1).isFuture()           // => false (1 second ago is not the future)
```

#### isPast

```javascript
isPast()
```

Returns whether the Date object is in the past relative to the present date.

**Parameters**

**Return type**

    boolean

**Examples**

```javascript
TODAY().addDays(1).isPast()                 // => false (tomorrow is in not in the past)
TODAY().addSeconds(-1).isPast()             // => true (1 second ago is in the past)
```

#### isBetween

```javascript
isBetween(dateFrom: Date | string, dateTo: Date | string)
```

Returns whether the Date object is between two given dates.

**Parameters**

    **dateFrom *****Date | string***

        A JavaScript Date object or an ISO 8601 formatted string.

    **dateTo *****Date | string***

        A JavaScript Date object or an ISO 8601 formatted string.

**Return type**

    boolean

**Examples**

```javascript
TODAY().isBetween(TODAY().addDays(-1), TODAY().addDays(1))         // => true (today is between yesterday and tomorrow)
DATE('2000-01-01').isBetween(DATE('1900-01-01'), TODAY())  // => true (Jan 1st 2000 is between 1900 and today)
```

#### startOfYear

```javascript
startOfYear()
```

Returns a duplicate of the Date object, with the time set to the start of the year (Jan 1st at 00:00:00)

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-06-04").startOfYear()   // => (Date) 2001-01-01T00:00
```

#### endOfYear

```javascript
endOfYear()
```

Returns a duplicate of the Date object, with the time set the end of the year (Dec 31st at 23:59:59)

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-05-11").endOfYear()    // => (Date) 2001-12-31T23:59:59.999
```

#### startOfQuarter

```javascript
startOfQuarter()
```

Returns a duplicate of the Date object, with the time set to the start of the quarter (1st of Jan/Apr/Jul/Oct at 00:00:00)

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-06-04").startOfQuarter()   // => (Date) 2001-04-01T00:00
```

#### endOfQuarter

```javascript
endOfQuarter()
```

Returns a duplicate of the Date object, with the time set the end of the quarter (31st of Mar/Jun/Sep/Dec at 23:59:59)

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-05-11").endOfQuarter()    // => (Date) 2001-06-30T23:59:59.999
```

#### startOfMonth

```javascript
startOfMonth()
```

Returns a duplicate of the Date object, with the time set to the start of the month (Day 1 at 00:00:00)

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-10-31").startOfMonth()   // => (Date) 2001-10-01T00:00
```

#### endOfMonth

```javascript
endOfMonth()
```

Returns a duplicate of the Date object, with the time set the end of the month (Day 28/29/30/31 at 23:59:59)

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-01-01").endOfMonth()    // => (Date) 2001-01-31T23:59:59.999
```

#### startOfDay

```javascript
startOfDay()
```

Returns a duplicate of the Date object, with the time set to the start of the day (00:00:00)

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-01-31T13:30:59.890Z").startOfDay()   // => (Date) 2001-01-31T00:00
```

#### endOfDay

```javascript
endOfDay()
```

Returns a duplicate of the Date object, with the time set the end of the day (23:59:59)

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-01-31T13:30:59.890Z").endOfDay()   // => (Date) 2001-01-31T23:59:59.999
```

#### toShortDateString

```javascript
toShortDateString()
```

Returns a string representation of the date in the format YYYY-MM-DD

**Parameters**

**Return type**

    string

**Examples**

```javascript
NOW().toShortDateString()                                  // => 2025-11-10
DATE("2001-01-31T13:30:00.000Z").toShortDateString()   // => 2001-01-31
```

#### toYear

```javascript
toYear(yearOrDate?: Date | number | string)
```

Returns a duplicate of the Date object, with a specified year. If no parameter is specified, will set the date to the present year.

**Parameters**

    **yearOrDate *****Date | number | string***

        (optional) The year to change the date to.

**Return type**

    Date

**Examples**

```javascript
DATE("2001-01-31").toYear()                         // => (Date) 2025-01-31
DATE("2001-01-31").toYear(2003)                     // => (Date) 2003-01-31
DATE("2001-01-31").toYear(DATE('2011-01-01'))   // => (Date) 2011-01-31
```

#### toPresentYear

```javascript
toPresentYear()
```

Returns a duplicate of the Date object, set to the present year.

**Parameters**

**Return type**

    Date

**Examples**

```javascript
DATE("2001-01-31").toPresentYear()                  // => (Date) 2025-01-31
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rulecube.com/language-reference/date.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.