TimeSpan

The eridu-tech/time-span component provides an easy way for defining, manipulating, and comparing durations. Furthermore, it is designed for easy integration with external time libraries like Luxon and Dayjs.

TimeSpan class

The TimeSpan class is used for representing time interval.

info

Note TimeSpan cannot be negative.

Creating a TimeSpan

Creating TimeSpan from milliseconds:

./samples/creating-from-milliseconds.ts

import { TimeSpan } from "eridu-tech/time-span";

export const timeSpan = TimeSpan.fromMilliseconds(100);

Creating TimeSpan from seconds:

./samples/creating-from-seconds.ts

import { TimeSpan } from "eridu-tech/time-span";

const timeSpan = TimeSpan.fromSeconds(30);

Creating TimeSpan from minutes:

./samples/creating-from-minutes.ts

import { TimeSpan } from "eridu-tech/time-span";

const timeSpan = TimeSpan.fromMinutes(15);

Creating TimeSpan from hours:

./samples/creating-from-hours.ts

import { TimeSpan } from "eridu-tech/time-span";

const timeSpan = TimeSpan.fromHours(1);

Creating TimeSpan from days:

./samples/creating-from-days.ts

import { TimeSpan } from "eridu-tech/time-span";

const timeSpan = TimeSpan.fromDays(1);

Creating TimeSpan from date range:

./samples/creating-from-date-range.ts

import { TimeSpan } from "eridu-tech/time-span";

const timeSpan = TimeSpan.fromDateRange({
    start: new Date("2000-01-01"),
    end: new Date("2010-01-01"),
});

Creating TimeSpan from string:

./samples/creating-from-str.ts

import { TimeSpan } from "eridu-tech/time-span";

const timeSpan = TimeSpan.fromStr("5s");

info

Under the hood, this method leverages @lukeed/ms package to convert various time formats into milliseconds. Refer to its documentation for a complete list of supported time formats and units.

Adding time to TimeSpan

You can add milliseconds to a TimeSpan:

./samples/adding-milliseconds.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.addMilliseconds(200);

You can add seconds to a TimeSpan:`

./samples/adding-seconds.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.addSeconds(30);

You can add minutes to a TimeSpan:

./samples/adding-minutes.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.addMinutes(20);

You can add hours to a TimeSpan:

./samples/adding-hours.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.addHours(2);

You can add days to a TimeSpan:

./samples/adding-days.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.addDays(14);

You can add 2 TimeSpan together:

./samples/adding-time-span.ts

import { timeSpan } from "./creating-from-milliseconds.js";
import { TimeSpan } from "eridu-tech/time-span";

timeSpan.addTimeSpan(TimeSpan.fromDays(14).addHours(20));

Subtracting time from TimeSpan

You can subtract milliseconds from a TimeSpan:

./samples/subtracting-milliseconds.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.subtractMilliseconds(200);

You can subtract seconds from a TimeSpan:`

./samples/subtracting-seconds.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.subtractSeconds(30);

You can subtract minutes from a TimeSpan:

./samples/subtracting-minutes.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.subtractMinutes(20);

You can subtract hours from a TimeSpan:

./samples/subtracting-hours.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.subtractHours(2);

You can subtract days from a TimeSpan:

./samples/subtracting-days.ts

import { timeSpan } from "./creating-from-milliseconds.js";

timeSpan.subtractDays(14);

You can subtract 2 TimeSpan together:

./samples/subtracting-time-span.ts

import { timeSpan } from "./creating-from-milliseconds.js";
import { TimeSpan } from "eridu-tech/time-span";

timeSpan.subtractTimeSpan(TimeSpan.fromDays(14).addHours(20));

Multiplying and dividing a TimeSpan

Dividing a timespan:

./samples/dividing.ts

import { TimeSpan } from "eridu-tech/time-span";

// Will be now 100 milliseconds
TimeSpan.fromMilliseconds(200).divide(2);

Multiplying a timespan:

./samples/multiplying.ts

import { TimeSpan } from "eridu-tech/time-span";

// Will be now 400 milliseconds
TimeSpan.fromMilliseconds(200).multiply(2);

Comparing TimeSpan:s

Equals:

./samples/comparing-equal.ts

import { TimeSpan } from "eridu-tech/time-span";

// Returns false
TimeSpan.fromSeconds(1).equals(TimeSpan.fromSeconds(2));

Greater than:

./samples/comparing-gt.ts

import { TimeSpan } from "eridu-tech/time-span";

// Returns false
TimeSpan.fromSeconds(1).gt(TimeSpan.fromSeconds(2));

Greater than or equals:

./samples/comparing-gte.ts

import { TimeSpan } from "eridu-tech/time-span";

// Returns false
TimeSpan.fromSeconds(1).gte(TimeSpan.fromSeconds(2));

Less than:

./samples/comparing-lt.ts

import { TimeSpan } from "eridu-tech/time-span";

// Returns true
TimeSpan.fromSeconds(1).lt(TimeSpan.fromSeconds(2));

Less than or equals:

./samples/comparing-lte.ts

import { TimeSpan } from "eridu-tech/time-span";

// Returns true
TimeSpan.fromSeconds(1).lte(TimeSpan.fromSeconds(2));

Converting a TimeSpan

You can get amount of milliseconds contained in the TimeSpan:

./samples/converting-to-milliseconds.ts

import { TimeSpan } from "eridu-tech/time-span";

TimeSpan.fromSeconds(1).toMilliseconds();

You can get amount of seconds contained in the TimeSpan:

./samples/converting-to-seconds.ts

import { TimeSpan } from "eridu-tech/time-span";

TimeSpan.fromMinutes(1).toSeconds();

You can get amount of minutes contained in the TimeSpan:

./samples/converting-to-minutes.ts

import { TimeSpan } from "eridu-tech/time-span";

TimeSpan.fromHours(1).toMinutes();

You can get amount of hours contained in the TimeSpan:

./samples/converting-to-hours.ts

import { TimeSpan } from "eridu-tech/time-span";

TimeSpan.fromDays(1).toHours();

You can get amount of days contained in the TimeSpan:

./samples/converting-to-days.ts

import { TimeSpan } from "eridu-tech/time-span";

TimeSpan.fromHours(48).toDays();

You can get end date relative to a start date:

./samples/converting-to-end-date.ts

import { TimeSpan } from "eridu-tech/time-span";

// Will return date of "2002-01-01"
TimeSpan.fromDays(365).toEndDate(new Date("2001-01-01"));

You can get start date relative to a end date:

./samples/converting-to-start-date.ts

import { TimeSpan } from "eridu-tech/time-span";

// Will return date of "2000-01-01"
TimeSpan.fromDays(365).toStartDate(new Date("2001-01-01"));

Serialization and deserialization of TimeSpan

The TimeSpan class supports serialization and deserialization, allowing you to easily convert instances to and from serialized formats. However, registration is required first:

./samples/serde-serialization.ts

import { Serde } from "eridu-tech/serde";
import { SuperJsonSerdeAdapter } from "eridu-tech/serde/super-json-serde-adapter";
import { TimeSpan } from "eridu-tech/time-span";

const serde = new Serde(new SuperJsonSerdeAdapter());

serde.registerCustom(TimeSpan.serdeTransformer);

const timeSpan = TimeSpan.fromSeconds(12);
const serializedTimeSpan = serde.serialize(timeSpan);
const deserializedTimeSpan = serde.deserialize(serializedTimeSpan);

// logs false
console.log(serializedTimeSpan === deserializedTimeSpan);

ITimeSpan contract

The ITimeSpan contract provides a standardized way to express a duration as milliseconds.

Key components, including Cache and Lock, rely on this contract, ensuring they are not tightly coupled to a specific duration implementation.

This decoupling is crucial for interoperability, allowing seamless integration with external time libraries like Luxon or Dayjs. To integrate a new library, its duration objects must simply implement the ITimeSpan contract.

info

Note TimeSpan class implements ITimeSpan contract.

The ITimeSpan contract requires you to implement the TO_MILLISECONDS method on the duration object, which must return the duration in milliseconds.

./samples/implementing-itimespan.ts

import {
    type ITimeSpan,
    TO_MILLISECONDS,
} from "eridu-tech/time-span/contracts";

export class Duration implements ITimeSpan {
    constructor(private readonly timeInMs: number) {}

    [TO_MILLISECONDS](): number {
        return this.timeInMs;
    }
}

Further information

For further information refer to eridu-tech/time-span API docs.