Time Objects The HolyTime class is the core of the Holy Time library, providing a type-safe wrapper around JavaScript’s Date object with a rich, chainable API.
Creating HolyTime Instances Constructor Create a new HolyTime instance from various input types:
import HolyTime from 'holy-time' ; // Current time const now = new HolyTime (); // From a Date object const fromDate = new HolyTime ( new Date ()); // From a timestamp const fromTimestamp = new HolyTime ( 1609459200000 ); // From another HolyTime instance const cloned = new HolyTime ( now );
Static Factory Methods Returns a new HolyTime instance representing the current moment.
const now = HolyTime . now ();
HolyTime.in()
(amount: number, unit?: HumanUnit) => HolyTime
Creates a HolyTime instance for a future time relative to now.
// 5 minutes from now const future = HolyTime . in ( 5 , 'minutes' ); // 2 hours from now const later = HolyTime . in ( 2 , 'hours' );
Instance vs Static Methods HolyTime provides both instance and static versions of most methods, allowing flexible usage patterns:
Instance Methods (Chainable) Instance methods modify the object in place and return this, enabling method chaining:
const time = new HolyTime () . add ( 5 , 'days' ) . subtract ( 2 , 'hours' ) . startOf ( 'day' );
Static Methods (Pure) Static methods accept a time parameter and return a new HolyTime instance:
const date = new Date (); const future = HolyTime . add ( date , 5 , 'days' ); const past = HolyTime . subtract ( date , 2 , 'hours' );
Instance methods are mutable and return the same object. Use clone() if you need to preserve the original instance.
Chainable API The instance API is designed for chaining operations:
const result = new HolyTime () . startOf ( 'month' ) . add ( 15 , 'days' ) . set ( 'hour' , 12 ) . set ( 'minute' , 0 ) . set ( 'second' , 0 );
Arithmetic Operations add()
(amount: number, unit?: HumanUnit) => this
Adds time to the current instance. Default unit is milliseconds.
subtract()
(amount: number, unit?: HumanUnit) => this
Subtracts time from the current instance. Default unit is milliseconds.
const time = new HolyTime () . add ( 1 , 'years' ) . add ( 3 , 'months' ) . subtract ( 5 , 'days' );
Getting and Setting Values get()
<T extends 'object' | GetUnit>(unit: T, timeZone?: TimeZone) => number | Record<GetUnit, number>
Gets a specific unit value or all values as an object.
const hour = time . get ( 'hour' ); const month = time . get ( 'month' ); // Get all values const all = time . get ( 'object' ); // { millisecond: 0, second: 30, minute: 45, hour: 14, day: 15, week: 3, month: 3, year: 2024 }
set()
(unit: GetUnit, value: number) => this
Sets a specific unit to the given value.
time . set ( 'year' , 2025 ) . set ( 'month' , 12 ) . set ( 'day' , 31 );
Comparison Methods All comparison methods have both instance and static versions:
// Instance methods const isBefore = time . isBefore ( otherTime ); const isAfter = time . isAfter ( otherTime ); const isSame = time . isSame ( otherTime , 'day' ); // Static methods const before = HolyTime . isBefore ( timeA , timeB ); const after = HolyTime . isAfter ( timeA , timeB ); const same = HolyTime . isSame ( timeA , timeB , 'month' );
Checks if the time is after the current moment.
Checks if the time is before the current moment.
Checks if the time falls on Saturday or Sunday.
isLeapYear()
(time: TimeResolvable) => boolean
Checks if the year is a leap year.
Utility Methods Creates a copy of the current instance.
const original = HolyTime . now (); const copy = original . clone (); copy . add ( 5 , 'days' ); // original is unchanged
Returns the underlying JavaScript Date object.
Returns the timestamp in milliseconds since Unix epoch.
Returns the timestamp in seconds since Unix epoch.
Returns the ISO 8601 string representation.
const time = HolyTime . now (); time . getDate (); // Date object time . getTime (); // 1709568000000 time . getUnixTime (); // 1709568000 time . getISOString (); // '2024-03-04T12:00:00.000Z'
Static Utility Methods HolyTime.isValid()
(time: TimeResolvable) => boolean
Checks if a time value is valid.
HolyTime . isValid ( new Date ()); // true HolyTime . isValid ( 'invalid' ); // false HolyTime . isValid ( 1709568000000 ); // true
HolyTime.max()
(...times: TimeResolvable[]) => HolyTime
Returns the latest time from the provided arguments.
HolyTime.min()
(...times: TimeResolvable[]) => HolyTime
Returns the earliest time from the provided arguments.
const latest = HolyTime . max ( new Date ( '2024-01-01' ), new Date ( '2024-12-31' ), new Date ( '2024-06-15' ) ); const earliest = HolyTime . min ( HolyTime . now (), HolyTime . in ( 5 , 'days' ), HolyTime . in ( - 2 , 'weeks' ) );
HolyTime.isLeapYear()
(year: number) => boolean
Static method to check if a specific year is a leap year.
HolyTime . isLeapYear ( 2024 ); // true HolyTime . isLeapYear ( 2023 ); // false HolyTime . isLeapYear ( 2000 ); // true HolyTime . isLeapYear ( 1900 ); // false
The static isLeapYear() method requires a positive integer. It will throw a TypeError for invalid inputs.
Constants HolyTime exposes useful constants as static properties:
HolyTime . Units ; // { YEAR: 31536000000, MONTH: 2678400000, ... } HolyTime . TimeZones ; // Array of supported IANA timezone identifiers HolyTime . Days ; // ['Sunday', 'Monday', 'Tuesday', ...] HolyTime . Months ; // ['January', 'February', 'March', ...]
Next Steps
Durations Learn about HolyDuration for time intervals
Formatting Format dates with custom patterns