Skip to main content

Class: Time

Defined in: classes/Time.ts:61

A utility class for handling time durations with various units and operations.

The Time class provides a convenient way to work with time durations, offering conversion between different time units, arithmetic operations, and formatting capabilities. All internal calculations are done in milliseconds for precision.

Examples​

// Create time instances using static constructors
const oneSecond = Time.fromMilliseconds(1000);
const twoMinutes = Time.fromMinutes(2);
const oneHour = Time.fromHours(1);
// Parse time from string representations
const duration1 = Time.parse("1 hour 30 minutes"); // 1 hours, 30 minutes
const duration2 = Time.parse("2h 15m 30s"); // 2 hours, 15 minutes, 30 seconds
const duration3 = Time.parse("3 days 12 hrs"); // 3 days, 12 hours
const duration4 = Time.parse("4 wks 2 days"); // 4 weeks, 2 days
const duration6 = Time.parse("500 ms"); // 500 milliseconds
// Convert between units
const time = Time.fromMilliseconds(90000); // 90 seconds in milliseconds
console.log(time.toSeconds()); // 90
console.log(time.toMinutes()); // 1.5
console.log(time.toHours()); // 0.025
// Perform arithmetic operations
const time1 = Time.fromMilliseconds(1000);
const time2 = Time.fromMilliseconds(500);
time1.add(time2); // time1 is now 1500ms
time1.subtract(300); // time1 is now 1200ms
// String representation and JSON conversion
const duration = Time.fromMilliseconds(3661000); // 1 hour, 1 minute, 1 second
console.log(duration.toString()); // "1 hour, 1 minute, 1 second"
console.log(duration.toJSON()); // { ms: 3661000, seconds: 3661, minutes: 61.02, ... }
// Using valueOf for mathematical operations
const time = Time.fromMilliseconds(1000);
const doubled = time * 2; // 2000
const sum = time + 500; // 1500

// Note: When using TypeScript, you may need to explicitly convert the Time class to its value with the `+` operator or the `valueOf` method.

const doubled = +time * 2; // 2000
const sum = time.valueOf() + 500; // 1500
// Copying a Time instance
const original = Time.fromMilliseconds(5000);
const copy = Time.fromMilliseconds(original.valueOf()); // Creates a copy with the same duration

Methods​

add()​

add(time): Time

Defined in: classes/Time.ts:279

Adds a time duration to this instance.

Parameters​

time​

The time duration to add. Must be a Time instance or a number in milliseconds.

number | Time

Returns​

Time

The updated Time instance.

Example​

const time = new Time(1000);

// Add another Time instance
time.add(new Time(500)); // Adds 500 ms
console.log(time.ms); // 1500

// Add a number in milliseconds
time.add(2000); // Adds 2000 ms
console.log(time.ms); // 3500

subtract()​

subtract(time): Time

Defined in: classes/Time.ts:308

Subtracts a time duration from this instance.

Parameters​

time​

The time duration to subtract. Must be a Time instance or a number in milliseconds.

number | Time

Returns​

Time

The updated Time instance.

Example​

const time = new Time(2000);

// Subtract another Time instance
time.subtract(new Time(500)); // Subtracts 500 ms
console.log(time.ms); // 1500

// Subtract a number in milliseconds
time.subtract(1000); // Subtracts 1000 ms
console.log(time.ms); // 500

toDays()​

toDays(): number

Defined in: classes/Time.ts:240

Converts the time duration to days.

Returns​

number

The time duration in days.

toHours()​

toHours(): number

Defined in: classes/Time.ts:231

Converts the time duration to hours.

Returns​

number

The time duration in hours.

toJSON()​

toJSON(): TimeJson

Defined in: classes/Time.ts:403

Converts the class instance to a JSON representation.

Returns​

TimeJson

A JSON representation of the class instance.

Example​

const time = new Time(60000);

// Convert to JSON
console.log(time.toJSON()); // { ms: 60000, seconds: 60, minutes: 1, ... }

toMilliseconds()​

toMilliseconds(): number

Defined in: classes/Time.ts:204

Converts the time duration to milliseconds.

Returns​

number

The time duration in milliseconds.

toMinutes()​

toMinutes(): number

Defined in: classes/Time.ts:222

Converts the time duration to minutes.

Returns​

number

The time duration in minutes.

toSeconds()​

toSeconds(): number

Defined in: classes/Time.ts:213

Converts the time duration to seconds.

Returns​

number

The time duration in seconds.

toString()​

toString(): string

Defined in: classes/Time.ts:350

Returns a string representation of the time duration in milliseconds.

Returns​

string

A string representation of the time.

Example​

const time = new Time(70000);

// Convert to string
console.log(time.toString()); // "1 minute, 10 seconds"

toWeeks()​

toWeeks(): number

Defined in: classes/Time.ts:249

Converts the time duration to weeks.

Returns​

number

The time duration in weeks.

toYears()​

toYears(): number

Defined in: classes/Time.ts:258

Converts the time duration to years.

Returns​

number

The time duration in years.

valueOf()​

valueOf(): number

Defined in: classes/Time.ts:335

Returns the time duration in milliseconds.

Returns​

number

The time duration.

Example​

const time = new Time(1000);

// Get the time duration in milliseconds
console.log(time.valueOf()); // 1000

// You can use it in math operations
// (in TypeScript, you may need to explicitly convert it with the `+` operator or the `valueOf` method)
console.log(time + +500); // 1500

fromDays()​

static fromDays(days): Time

Defined in: classes/Time.ts:122

Creates a Time instance from days.

Parameters​

days​

number

The time duration in days. Must be a non-negative number.

Returns​

Time

A new Time instance.

fromHours()​

static fromHours(hours): Time

Defined in: classes/Time.ts:109

Creates a Time instance from hours.

Parameters​

hours​

number

The time duration in hours. Must be a non-negative number.

Returns​

Time

A new Time instance.

fromMilliseconds()​

static fromMilliseconds(ms): Time

Defined in: classes/Time.ts:70

Creates a Time instance from milliseconds.

Parameters​

ms​

number

The time duration in milliseconds. Must be a non-negative number.

Returns​

Time

A new Time instance.

fromMinutes()​

static fromMinutes(minutes): Time

Defined in: classes/Time.ts:96

Creates a Time instance from minutes.

Parameters​

minutes​

number

The time duration in minutes. Must be a non-negative number.

Returns​

Time

A new Time instance.

fromSeconds()​

static fromSeconds(seconds): Time

Defined in: classes/Time.ts:83

Creates a Time instance from seconds.

Parameters​

seconds​

number

The time duration in seconds. Must be a non-negative number.

Returns​

Time

A new Time instance.

fromWeeks()​

static fromWeeks(weeks): Time

Defined in: classes/Time.ts:135

Creates a Time instance from weeks.

Parameters​

weeks​

number

The time duration in weeks. Must be a non-negative number.

Returns​

Time

A new Time instance.

fromYears()​

static fromYears(years): Time

Defined in: classes/Time.ts:148

Creates a Time instance from years.

Parameters​

years​

number

The time duration in years. Must be a non-negative number.

Returns​

Time

A new Time instance.

parse()​

static parse(time): Time

Defined in: classes/Time.ts:176

Creates a Time instance from a string representation of time.

The string should be in the format: {number} {unit_key} {number} {unit_key} ..., where unit_key can be one of the following: ms, msec, msecs, second, seconds, sec, s, minute, minutes, min, m, hour, hours, hr, h, day, days, week, weeks, year, years.

Parameters​

time​

string

The time duration as a string.

Returns​

Time

A new Time instance.

Examples​

Time.parse("1 hour 30 minutes"); // 1 hour 30 minutes
Time.parse("2h 15m"); // 2 hours 15 minutes
Time.parse("3 days 12 hrs"); // 3 days 12 hours
Time.parse("4 wks 2 days"); // 4 weeks 2 days