@snps/datetime

Zero-dependency date and time library with duration support.

Installation

pnpm install @snps/datetime

API

DateTime

The DateTime class provides an immutable way to work with dates and times.

Constructor

Creates a new DateTime instance. If no date is provided, it defaults to the current date and time.

import { DateTime } from '@snps/datetime';

const now = new DateTime();
const specificDate = new DateTime(new Date('2023-10-27T10:00:00.000Z'));

now()

Creates a new DateTime instance for the current date and time.

const now = DateTime.now();

fromTimestamp(ms: number)

Creates a new DateTime instance from a timestamp in milliseconds.

const dt = DateTime.fromTimestamp(1609459200000);

parse(dateString: string)

Creates a new DateTime instance from an ISO 8601 string.

const dt = DateTime.parse('2021-01-01T00:00:00.000Z');

fromDate(year: number, month: number, day: number = 1)

Creates a new DateTime instance from year, month, and day components.

const dt = DateTime.fromDate(2021, 1, 15);

format(formatString: string)

Formats the DateTime instance as a string.

const dt = DateTime.fromDate(2021, 3, 15);
dt.format('YYYY-MM-DD'); // '2021-03-15'

toISO()

Formats the DateTime instance as an ISO 8601 string.

const dt = DateTime.parse('2021-03-15T14:30:45.123Z');
dt.toISO(); // '2021-03-15T14:30:45.123Z'

relative(from?: DateTime)

Returns the relative time from the DateTime instance to the from date (or now).

const past = DateTime.fromTimestamp(Date.now() - 30000);
past.relative(); // '30 seconds ago'

add(duration: DateDuration)

Adds a duration to the DateTime instance.

const dt = DateTime.fromDate(2021, 1, 1);
const newDt = dt.add({ years: 1, months: 2, days: 3 });

subtract(duration: DateDuration)

Subtracts a duration from the DateTime instance.

const dt = DateTime.fromDate(2021, 5, 15);
const newDt = dt.subtract({ years: 1, months: 2, days: 3 });

startOfDay()

Returns a new DateTime instance set to the start of the day.

const dt = DateTime.parse('2021-01-15T14:30:45.123Z');
const start = dt.startOfDay();

endOfDay()

Returns a new DateTime instance set to the end of the day.

const dt = DateTime.parse('2021-01-15T14:30:45.123Z');
const end = dt.endOfDay();

isBefore(other: DateTime)

Checks if the DateTime instance is before another DateTime instance.

const dt1 = DateTime.fromDate(2021, 1, 1);
const dt2 = DateTime.fromDate(2021, 1, 2);
dt1.isBefore(dt2); // true

isAfter(other: DateTime)

Checks if the DateTime instance is after another DateTime instance.

const dt1 = DateTime.fromDate(2021, 1, 1);
const dt2 = DateTime.fromDate(2021, 1, 2);
dt2.isAfter(dt1); // true

isSame(other: DateTime)

Checks if the DateTime instance is the same as another DateTime instance.

const dt1 = DateTime.fromTimestamp(1609459200000);
const dt2 = DateTime.fromTimestamp(1609459200000);
dt1.isSame(dt2); // true

Getters

• getYear(): number
• getMonth(): number
• getDay(): number
• getHours(): number
• getMinutes(): number
• getSeconds(): number
• valueOf(): number
• toDate(): Date