Skip to main content

​
Date Manipulation

Holy Time provides powerful methods for manipulating dates with a clean, chainable API.

​
Adding Time

The add() method allows you to add time units to a date. It supports both static and instance usage.

​
Basic Usage

import HolyTime from 'holy-time'

const date = new HolyTime('2023-01-01T00:00:00.000Z')
date.add(2, 'hours')
// Result: 2023-01-01T02:00:00.000Z

​
Static Method

const result = HolyTime.add('2023-01-01', 2, 'weeks')
The add() instance method modifies the original object and returns this, allowing for method chaining.

​
Supported Units

You can add any of these time units:
  • 'milliseconds'
  • 'seconds'
  • 'minutes'
  • 'hours'
  • 'days'
  • 'weeks'
  • 'months'
  • 'years'

​
Boundary Handling

const date = new HolyTime('2023-01-01T23:00:00.000Z')
date.add(2, 'hours')
// Result: 2023-01-02T01:00:00.000Z

​
Subtracting Time

The subtract() method works identically to add(), but subtracts time instead. 
const date = new HolyTime('2023-01-01T01:00:00.000Z')
date.subtract(60, 'minutes')
// Result: 2023-01-01T00:00:00.000Z

​
Static Method

const result = HolyTime.subtract('2023-01-01', 2, 'weeks')
Negative values in add() work the same as subtract(), and vice versa.

​
Future Dates with in()

Create a date in the future from the current moment: 
const futureDate = HolyTime.in(4, 'days')
// Creates a date 4 days from now
This is equivalent to: 
const futureDate = HolyTime.now().add(4, 'days')

​
Next Period

Get the next occurrence of a time period: 
const nextWeek = HolyTime.next('week')
const nextMonth = HolyTime.next('month')
const nextYear = HolyTime.next('year')

​
Instance Method

const date = new HolyTime('2023-01-15')
const nextMonth = date.next('month')
// Returns start of next month after Jan 15

​
With Timezone

const next = HolyTime.next('day', new Date(), 'America/New_York')

​
Start and End of Period

​
Start of Period

Get the beginning of a time period: 
const date = new HolyTime('2023-01-15T14:30:45.000Z')

date.startOf('hour')   // 2023-01-15T14:00:00.000Z
date.startOf('day')    // 2023-01-15T00:00:00.000Z
date.startOf('week')   // 2023-01-15T00:00:00.000Z (Sunday)
date.startOf('month')  // 2023-01-01T00:00:00.000Z
date.startOf('year')   // 2023-01-01T00:00:00.000Z

​
End of Period

Get the last moment of a time period: 
const date = new HolyTime('2023-01-01T01:02:03.000Z')

const endOfDay = date.endOf('day')
// Returns: 2023-01-01T23:59:59.999Z

​
Timezone Support

Both methods support timezone parameters: 
const date = new HolyTime('2023-01-01T01:02:03.000Z')
const start = date.startOf('day', 'America/New_York')
start.format('YYYY-MM-DD HH:mm:ss', 'Europe/London')
// Result: 2022-12-31 05:00:00

​
Chaining Operations

1

Create a base date

const date = HolyTime.in(4, 'days')
2

Add more time

date.add(2, 'weeks')
3

Subtract time

date.subtract(4, 'minutes')
4

Check the result

date.isWeekend() // true or false
Complete example: 
HolyTime
  .in(4, 'days')
  .add(2, 'weeks')
  .subtract(4, 'minutes')
  .isWeekend()

​
Setting Specific Values

Directly set a specific unit value: 
const date = new HolyTime('2023-01-15T14:30:00.000Z')

date.set('hour', 9)    // Sets hour to 9
date.set('day', 1)     // Sets day to 1st
date.set('month', 6)   // Sets month to June (1-indexed)
date.set('year', 2024) // Sets year to 2024

​
Getting Values

Retrieve specific date components: 
const date = new HolyTime('2023-06-15T14:30:45.123Z')

date.get('year')        // 2023
date.get('month')       // 6
date.get('day')         // 15
date.get('hour')        // 14
date.get('minute')      // 30
date.get('second')      // 45
date.get('millisecond') // 123

​
Get All Values

const all = date.get('object')
// Returns: {
//   year: 2023,
//   month: 6,
//   day: 15,
//   hour: 14,
//   minute: 30,
//   second: 45,
//   millisecond: 123,
//   week: 24
// }
All get() operations support an optional timezone parameter: date.get('hour', 'America/New_York')

Build docs developers (and LLMs) love

Get started for freeTalk to us