Skip to main content

​
Constructor

constructor(initialDate: TimeResolvable = new Date())
Creates a new HolyTime instance.
​
initialDate
TimeResolvable
default:"new Date()"
The initial date/time value. Can be a HolyTime instance, Date object, number (timestamp), or string.

​
Static Properties

​
Units

static Units = TimeUnits
Object containing time unit constants in milliseconds.

​
TimeZones

static TimeZones = TIMEZONES
Array of all supported timezone strings.

​
Days

static Days = DAY_NAMES
Array of day names: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']

​
Months

static Months = MONTH_NAMES
Array of month names: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']

​
Static Methods

​
now()

static now(): HolyTime
Creates a HolyTime instance representing the current moment.
​
return
HolyTime
New HolyTime instance with current date/time

​
isValid()

static isValid(time: TimeResolvable): boolean
Checks if a time value is valid.
​
time
TimeResolvable
required
The time value to validate
​
return
boolean
True if the time is valid, false otherwise

​
add()

static add(time: TimeResolvable, amount: number, unit: HumanUnit = 'milliseconds'): HolyTime
Adds time to a given date and returns a new HolyTime instance.
​
time
TimeResolvable
required
The base time
​
amount
number
required
The amount to add
​
unit
HumanUnit
default:"'milliseconds'"
The unit of time (e.g., ‘seconds’, ‘minutes’, ‘hours’, ‘days’, ‘weeks’, ‘months’, ‘years’)
​
return
HolyTime
New HolyTime instance with the added time

​
subtract()

static subtract(time: TimeResolvable, amount: number, unit: HumanUnit = 'milliseconds'): HolyTime
Subtracts time from a given date and returns a new HolyTime instance.
​
time
TimeResolvable
required
The base time
​
amount
number
required
The amount to subtract
​
unit
HumanUnit
default:"'milliseconds'"
The unit of time
​
return
HolyTime
New HolyTime instance with the subtracted time

​
in()

static in(amount: number, unit: HumanUnit = 'milliseconds'): HolyTime
Creates a HolyTime instance representing a time in the future from now.
​
amount
number
required
The amount of time in the future
​
unit
HumanUnit
default:"'milliseconds'"
The unit of time
​
return
HolyTime
New HolyTime instance representing the future time

​
between()

static between(timeA: TimeResolvable, timeB: TimeResolvable): HolyDuration
Calculates the absolute duration between two times.
​
timeA
TimeResolvable
required
First time
​
timeB
TimeResolvable
required
Second time
​
return
HolyDuration
Duration between the two times

​
isSame()

static isSame(timeA: TimeResolvable, timeB: TimeResolvable, unit: IntervalUnit = 'millisecond'): boolean
Checks if two times are the same at the specified unit precision.
​
timeA
TimeResolvable
required
First time
​
timeB
TimeResolvable
required
Second time
​
unit
IntervalUnit
default:"'millisecond'"
Unit of precision (‘millisecond’, ‘second’, ‘minute’, ‘hour’, ‘day’, ‘week’, ‘month’, ‘year’)
​
return
boolean
True if times are the same at the specified precision

​
isWeekend()

static isWeekend(time: TimeResolvable): boolean
Checks if a given time falls on a weekend (Saturday or Sunday).
​
time
TimeResolvable
required
The time to check
​
return
boolean
True if the time is on a weekend

​
isLeapYear()

static isLeapYear(year: number): boolean
Checks if a given year is a leap year.
​
year
number
required
The year to check (must be a positive integer)
​
return
boolean
True if the year is a leap year

​
isAfter()

static isAfter(timeA: TimeResolvable, timeB: TimeResolvable): boolean
Checks if timeA is after timeB.
​
timeA
TimeResolvable
required
First time
​
timeB
TimeResolvable
required
Second time
​
return
boolean
True if timeA is after timeB

​
isBefore()

static isBefore(timeA: TimeResolvable, timeB: TimeResolvable): boolean
Checks if timeA is before timeB.
​
timeA
TimeResolvable
required
First time
​
timeB
TimeResolvable
required
Second time
​
return
boolean
True if timeA is before timeB

​
isFuture()

static isFuture(time: TimeResolvable): boolean
Checks if a time is in the future.
​
time
TimeResolvable
required
The time to check
​
return
boolean
True if the time is in the future

​
isPast()

static isPast(time: TimeResolvable): boolean
Checks if a time is in the past.
​
time
TimeResolvable
required
The time to check
​
return
boolean
True if the time is in the past

​
since()

static since(time: TimeResolvable): HolyDuration
Calculates the duration since a given time until now.
​
time
TimeResolvable
required
The starting time
​
return
HolyDuration
Duration from the given time to now

​
max()

static max(...times: TimeResolvable[]): HolyTime
Returns the latest time from the provided times.
​
times
TimeResolvable[]
required
Variable number of times to compare
​
return
HolyTime
The latest time

​
min()

static min(...times: TimeResolvable[]): HolyTime
Returns the earliest time from the provided times.
​
times
TimeResolvable[]
required
Variable number of times to compare
​
return
HolyTime
The earliest time

​
startOf()

static startOf(unit: IntervalUnit, time: TimeResolvable = new Date(), timeZone?: TimeZone): HolyTime
Returns the start of the specified time unit.
​
unit
IntervalUnit
required
The unit (‘millisecond’, ‘second’, ‘minute’, ‘hour’, ‘day’, ‘week’, ‘month’, ‘year’)
​
time
TimeResolvable
default:"new Date()"
The reference time
​
timeZone
TimeZone
Optional timezone
​
return
HolyTime
Time representing the start of the unit

​
endOf()

static endOf(unit: IntervalUnit, time: TimeResolvable = new Date(), timeZone?: TimeZone): HolyTime
Returns the end of the specified time unit.
​
unit
IntervalUnit
required
The unit
​
time
TimeResolvable
default:"new Date()"
The reference time
​
timeZone
TimeZone
Optional timezone
​
return
HolyTime
Time representing the end of the unit

​
format()

static format(time: TimeResolvable, format: string | ((time: HolyTime) => string), timeZone?: TimeZone): string
Formats a time according to the specified format string or function.
​
time
TimeResolvable
required
The time to format
​
format
string | ((time: HolyTime) => string)
required
Format string (e.g., ‘YYYY-MM-DD HH:mm:ss’) or custom formatter function
​
timeZone
TimeZone
Optional timezone
​
return
string
Formatted time string
Format Tokens:
  • YYYY - 4-digit year
  • YY - 2-digit year
  • MMMM - Full month name
  • MMM - Short month name
  • MM - 2-digit month
  • M - Month number
  • DD - 2-digit day
  • D - Day number
  • DDDD - Full day name
  • HH - 2-digit hour (24h)
  • H - Hour (24h)
  • hh - 2-digit hour (12h)
  • h - Hour (12h)
  • mm - 2-digit minutes
  • m - Minutes
  • ss - 2-digit seconds
  • s - Seconds
  • A - AM/PM (uppercase)
  • a - am/pm (lowercase)
  • O - GMT offset (short)
  • OO - GMT offset (long)
  • TZ - Timezone name

​
relativeFromTo()

static relativeFromTo(timeA: TimeResolvable, timeB: TimeResolvable): string
Returns a human-readable relative time string between two times.
​
timeA
TimeResolvable
required
First time
​
timeB
TimeResolvable
required
Second time
​
return
string
Relative time string (e.g., ‘5 minutes ago’, ‘in 2 hours’)

​
next()

static next(unit: IntervalUnit, time: TimeResolvable = new Date(), timeZone?: TimeZone): HolyTime
Returns the start of the next time unit.
​
unit
IntervalUnit
required
The unit
​
time
TimeResolvable
default:"new Date()"
The reference time
​
timeZone
TimeZone
Optional timezone
​
return
HolyTime
Time representing the start of the next unit

​
duration()

static duration(amount: number, unit: HumanUnit = 'milliseconds'): HolyDuration
Creates a HolyDuration instance.
​
amount
number
required
The duration amount
​
unit
HumanUnit
default:"'milliseconds'"
The unit of time
​
return
HolyDuration
New HolyDuration instance

​
getTimeZone()

static getTimeZone(): TimeZone
Returns the system’s current timezone.
​
return
TimeZone
Current timezone string

​
Instance Methods

​
add()

add(amount: number, unit: HumanUnit = 'milliseconds'): this
Adds time to this instance (mutates).
​
amount
number
required
The amount to add
​
unit
HumanUnit
default:"'milliseconds'"
The unit of time
​
return
this
This instance for chaining

​
subtract()

subtract(amount: number, unit: HumanUnit = 'milliseconds'): this
Subtracts time from this instance (mutates).
​
amount
number
required
The amount to subtract
​
unit
HumanUnit
default:"'milliseconds'"
The unit of time
​
return
this
This instance for chaining

​
isSame()

isSame(time: TimeResolvable, unit: IntervalUnit = 'millisecond'): boolean
Checks if this time is the same as another time at the specified precision.
​
time
TimeResolvable
required
The time to compare
​
unit
IntervalUnit
default:"'millisecond'"
Unit of precision
​
return
boolean
True if times are the same

​
isWeekend()

isWeekend(): boolean
Checks if this time falls on a weekend.
​
return
boolean
True if this time is on a weekend

​
isLeapYear()

isLeapYear(time: TimeResolvable): boolean
Checks if this time’s year is a leap year.
​
time
TimeResolvable
required
The time to check
​
return
boolean
True if the year is a leap year

​
isAfter()

isAfter(time: TimeResolvable): boolean
Checks if this time is after another time.
​
time
TimeResolvable
required
The time to compare
​
return
boolean
True if this time is after the given time

​
isBefore()

isBefore(time: TimeResolvable): boolean
Checks if this time is before another time.
​
time
TimeResolvable
required
The time to compare
​
return
boolean
True if this time is before the given time

​
isFuture()

isFuture(): boolean
Checks if this time is in the future.
​
return
boolean
True if this time is in the future

​
isPast()

isPast(): boolean
Checks if this time is in the past.
​
return
boolean
True if this time is in the past

​
startOf()

startOf(unit: IntervalUnit, timeZone?: TimeZone): HolyTime
Returns the start of the specified time unit for this instance.
​
unit
IntervalUnit
required
The unit
​
timeZone
TimeZone
Optional timezone
​
return
HolyTime
Time representing the start of the unit

​
endOf()

endOf(unit: IntervalUnit, timeZone?: TimeZone): HolyTime
Returns the end of the specified time unit for this instance.
​
unit
IntervalUnit
required
The unit
​
timeZone
TimeZone
Optional timezone
​
return
HolyTime
Time representing the end of the unit

​
format()

format(format: string, timeZone?: TimeZone): string
Formats this time according to the specified format string.
​
format
string
required
Format string
​
timeZone
TimeZone
Optional timezone
​
return
string
Formatted time string

​
next()

next(unit: IntervalUnit, timeZone?: TimeZone): HolyTime
Returns the start of the next time unit for this instance.
​
unit
IntervalUnit
required
The unit
​
timeZone
TimeZone
Optional timezone
​
return
HolyTime
Time representing the start of the next unit

​
get()

get<T extends 'object' | GetUnit>(unit: T, timeZone?: TimeZone): T extends 'object' ? Record<GetUnit, number> : number
Gets a specific time component or all components as an object.
​
unit
'object' | GetUnit
required
The unit to get (‘millisecond’, ‘second’, ‘minute’, ‘hour’, ‘day’, ‘week’, ‘month’, ‘year’, or ‘object’ for all)
​
timeZone
TimeZone
Optional timezone
​
return
number | Record<GetUnit, number>
The component value or object with all components

​
set()

set(unit: GetUnit, value: number): this
Sets a specific time component (mutates).
​
unit
GetUnit
required
The unit to set
​
value
number
required
The value to set
​
return
this
This instance for chaining

​
getDate()

getDate(): Date
Returns the underlying Date object.
​
return
Date
The underlying Date instance

​
getTime()

getTime(): number
Returns the timestamp in milliseconds.
​
return
number
Timestamp in milliseconds

​
getUnixTime()

getUnixTime(): number
Returns the Unix timestamp in seconds.
​
return
number
Unix timestamp in seconds

​
getISOString()

getISOString(): string
Returns the ISO 8601 string representation.
​
return
string
ISO 8601 formatted string

​
clone()

clone(): HolyTime
Creates a copy of this HolyTime instance.
​
return
HolyTime
New HolyTime instance with the same time

​
getRelativeTo()

getRelativeTo(time: TimeResolvable): string
Returns a human-readable relative time string from this time to another time.
​
time
TimeResolvable
required
The target time
​
return
string
Relative time string

​
getRelativeFrom()

getRelativeFrom(time: TimeResolvable): string
Returns a human-readable relative time string from another time to this time.
​
time
TimeResolvable
required
The source time
​
return
string
Relative time string

Build docs developers (and LLMs) love

Get started for freeTalk to us