Date & Time

This module provides a collection of utility functions for working with dates and times. It extends functionality from the Effect-TS library.

Basic Operations

parseToDate(date: string): Date

Parses a date string to a Date object.

typescript
parseToDate("2025-03-05") // returns Date object

now(): Date

Gets the current time using Date.now.

typescript
now() // returns current Date

Date Comparisons

distance(self: Date, other: Date): number

Calculates the difference between two dates in milliseconds. Returns positive if other is after self.

typescript
distance(new Date("2025-01-01"), new Date("2025-01-02")) // returns 86400000 (1 day in ms)

min(self: Date, other: Date): Date

Returns the earlier of two dates.

typescript
min(new Date("2025-01-01"), new Date("2025-01-02")) // returns Date("2025-01-01")

max(self: Date, other: Date): Date

Returns the later of two dates.

typescript
max(new Date("2025-01-01"), new Date("2025-01-02")) // returns Date("2025-01-02")

greaterThan(self: Date, other: Date): boolean

Returns true if the first date is after the second.

typescript
greaterThan(new Date("2025-01-02"), new Date("2025-01-01")) // returns true

lessThan(self: Date, other: Date): boolean

Returns true if the first date is before the second.

typescript
lessThan(new Date("2025-01-01"), new Date("2025-01-02")) // returns true

between(self: Date, minimum: Date, maximum: Date): boolean

Returns true if the date is between the minimum and maximum dates.

typescript
between(new Date("2025-01-02"), new Date("2025-01-01"), new Date("2025-01-03")) // returns true

isPast(date: Date): boolean

Returns true if the date is in the past.

typescript
isPast(new Date("2020-01-01")) // returns true

isFuture(date: Date): boolean

Returns true if the date is in the future.

typescript
isFuture(new Date("2030-01-01")) // returns true

Date Mathematics

add(date: Date, parts: DateTime.PartsForMath): Date

Adds the specified duration to a date.

typescript
add(new Date("2025-01-01"), { days: 1 }) // returns Date("2025-01-02")

subtract(date: Date, parts: DateTime.PartsForMath): Date

Subtracts the specified duration from a date.

typescript
subtract(new Date("2025-01-02"), { days: 1 }) // returns Date("2025-01-01")

startOf(date: Date, unit: DateTime.UnitSingular, weekStartsOn?: 0-6): Date

Converts a date to the start of the given unit (year, month, week, day, etc.).

typescript
startOf(new Date("2025-01-15"), "month") // returns Date("2025-01-01")

endOf(date: Date, unit: DateTime.UnitSingular, weekStartsOn?: 0-6): Date

Converts a date to the end of the given unit.

typescript
endOf(new Date("2025-01-15"), "month") // returns Date("2025-01-31T23:59:59.999")

Date Formatting

format(date: Date, options: DateTimeFormatOptions): string

Formats a date to a string using the given options.

typescript
format(new Date("2025-01-15"), { year: 'numeric', month: 'long', day: 'numeric' })
// returns "January 15, 2025"

formatIso(date: Date): string

Formats a date to an ISO string.

typescript
formatIso(new Date("2025-01-15")) // returns "2025-01-15T00:00:00.000Z"

formatIsoDate(date: Date): string

Formats a date to an ISO date string.

typescript
formatIsoDate(new Date("2025-01-15")) // returns "2025-01-15"

Date Components

getDay(date: Date): number

Gets the day of the month from a Date object.

typescript
getDay(new Date("2025-01-15")) // returns 15

getMonth(date: Date): number

Gets the month from a Date object (1-12).

typescript
getMonth(new Date("2025-01-15")) // returns 1

getYear(date: Date): number

Gets the year from a Date object.

typescript
getYear(new Date("2025-01-15")) // returns 2025

getHours(date: Date): number

Gets the hours from a Date object.

typescript
getHours(new Date("2025-01-15T14:30:00")) // returns 14

getMinutes(date: Date): number

Gets the minutes from a Date object.

typescript
getMinutes(new Date("2025-01-15T14:30:00")) // returns 30

getSeconds(date: Date): number

Gets the seconds from a Date object.

typescript
getSeconds(new Date("2025-01-15T14:30:45")) // returns 45

getMilliseconds(date: Date): number

Gets the milliseconds from a Date object.

typescript
getMilliseconds(new Date("2025-01-15T14:30:45.123")) // returns 123