Skip to main content

​
Durations

The HolyDuration class represents a length of time, providing methods for duration arithmetic and formatting.

​
Creating Durations

​
Using HolyTime.duration()

The recommended way to create durations is through the static HolyTime.duration() method: 
import HolyTime from 'holy-time';

// Create a 5-minute duration
const fiveMinutes = HolyTime.duration(5, 'minutes');

// Create a 2-hour duration
const twoHours = HolyTime.duration(2, 'hours');

// Create a 30-second duration
const thirtySeconds = HolyTime.duration(30, 'seconds');

// Default unit is milliseconds
const milliseconds = HolyTime.duration(5000);

​
From the Constructor

You can also create durations directly using the HolyDuration constructor: 
import { HolyDuration } from 'holy-time';

// From milliseconds
const duration = new HolyDuration(60000); // 1 minute

// From another duration
const copy = new HolyDuration(duration);

​
From Time Differences

Calculate durations between two times:
​
HolyTime.between()
(timeA: TimeResolvable, timeB: TimeResolvable) => HolyDuration
Returns the absolute duration between two times.
const start = new Date('2024-01-01');
const end = new Date('2024-12-31');

const duration = HolyTime.between(start, end);
​
HolyTime.since()
(time: TimeResolvable) => HolyDuration
Returns the duration from the given time until now.
const birthday = new Date('2000-01-01');
const age = HolyTime.since(birthday);

console.log(age.in('years')); // Age in years

​
Duration Arithmetic

​
Adding Durations

​
add()
(duration: HolyDuration) => this
Adds another duration to this duration.
​
add()
(amount: number, unit?: HumanUnit) => this
Adds a specific amount of time to this duration.
const duration = HolyTime.duration(1, 'hours');

// Add another duration
const other = HolyTime.duration(30, 'minutes');
duration.add(other); // 1.5 hours total

// Add amount and unit
duration.add(15, 'minutes'); // 1.75 hours total

​
Subtracting Durations

​
subtract()
(duration: HolyDuration) => this
Subtracts another duration from this duration.
​
subtract()
(amount: number, unit?: HumanUnit) => this
Subtracts a specific amount of time from this duration.
const duration = HolyTime.duration(2, 'hours');

// Subtract another duration
const toRemove = HolyTime.duration(30, 'minutes');
duration.subtract(toRemove); // 1.5 hours

// Subtract amount and unit
duration.subtract(15, 'minutes'); // 1.25 hours
Both add() and subtract() methods are chainable and modify the duration in place.

​
Converting Between Units

​
in()
(unit: HumanUnit) => number
Converts the duration to the specified unit and returns the numeric value.
const duration = HolyTime.duration(90, 'minutes');

duration.in('hours');        // 1.5
duration.in('minutes');      // 90
duration.in('seconds');      // 5400
duration.in('milliseconds'); // 5400000

​
Supported Units

All methods accept these human-readable units:
  • 'milliseconds'
  • 'seconds'
  • 'minutes'
  • 'hours'
  • 'days'
  • 'weeks'
  • 'months'
  • 'years'
Month and year durations use approximate values: 1 month = 2,678,400,000ms (~31 days), 1 year = 31,536,000,000ms (365 days).

​
Formatting Durations

​
format()
(type?: 'short' | 'long', allowedSegments?: Partial<Record<HumanUnit, boolean>>) => string
Formats the duration as a human-readable string.

​
Short Format

The short format uses abbreviated units: 
const duration = HolyTime.duration(3725, 'seconds');

duration.format('short');
// '1h 2m 5s'

​
Long Format

The long format uses full unit names with proper pluralization: 
const duration = HolyTime.duration(3725, 'seconds');

duration.format('long');
// '1 hour, 2 minutes and 5 seconds'

​
Filtering Segments

You can control which time units appear in the output: 
const duration = HolyTime.duration(3661, 'seconds');

// Only show hours and minutes
duration.format('short', {
  hours: true,
  minutes: true,
  seconds: false
});
// '1h 1m'

// Only show days and hours
const longDuration = HolyTime.duration(100, 'hours');
longDuration.format('long', {
  days: true,
  hours: true,
  minutes: false,
  seconds: false
});
// '4 days and 4 hours'

const d1 = HolyTime.duration(125, 'seconds');
d1.format('short'); // '2m 5s'

const d2 = HolyTime.duration(2, 'days');
d2.format('short'); // '2d'

const d3 = HolyTime.duration(90, 'minutes');
d3.format('short'); // '1h 30m'

​
Cloning Durations

​
clone()
() => HolyDuration
Creates a copy of the current duration.
const original = HolyTime.duration(1, 'hours');
const copy = original.clone();

copy.add(30, 'minutes');
// original is still 1 hour
// copy is now 1.5 hours
Duration methods like add() and subtract() are mutable. Use clone() if you need to preserve the original duration.

​
Practical Examples

​
Calculate Age

const birthday = new Date('1990-05-15');
const age = HolyTime.since(birthday);

console.log(`You are ${Math.floor(age.in('years'))} years old`);

​
Track Session Duration

const sessionStart = HolyTime.now();

// ... some time passes ...

const sessionDuration = HolyTime.since(sessionStart);
console.log(`Session lasted: ${sessionDuration.format('long')}`);

​
Calculate Time Until Event

const event = new Date('2024-12-31T23:59:59');
const now = new Date();
const timeLeft = HolyTime.between(now, event);

console.log(`Event starts in: ${timeLeft.format('long', {
  days: true,
  hours: true,
  minutes: false,
  seconds: false
})}`);

​
Sum Multiple Durations

const workout = HolyTime.duration(45, 'minutes');
const commute = HolyTime.duration(30, 'minutes');
const meeting = HolyTime.duration(2, 'hours');

const total = HolyTime.duration(0)
  .add(workout)
  .add(commute)
  .add(meeting);

console.log(`Total time: ${total.format('long')}`);
// 'Total time: 3 hours and 15 minutes'

​
Next Steps

Time Objects

Learn about creating and manipulating times

Formatting

Format dates with custom patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us