Date

Functions to manipulate dates and times via the proprietary type TheDate (``type TheDate = `date${number}${"-" | "+"}```). This serializable format encodes a safe Unix timestamp, travels through HTTP protocols without loss, and guarantees immutable manipulation.

How to import ?

The library exposes the DDate and D namespaces from the main entry or via direct import (tree-shaking friendly), which lets you only load what you need.

import { DDate, D } from "@duplojs/utils";
import * as DDate from "@duplojs/utils/date";
import * as D from "@duplojs/utils/date";

Creation

create

Builds a TheDate from a Date, a timestamp, or another TheDate and returns an Either (MayBe).

createOrThrow

Strict version of create that throws CreateTheDateError when the input is invalid.

createTime

Builds a TheTime from milliseconds or a structured time object.

createTimeOrThrow

Strict version of createTime that throws on invalid input.

now

Returns the exact timestamp of the current moment as a TheDate.

today

Generates the start of the day (midnight) as a TheDate.

yesterday

Returns the start of the previous day.

tomorrow

Returns the start of the next day.

Conversion & validation

toNative

Converts a TheDate to a JavaScript Date.

toTimestamp

Exposes the timestamp in milliseconds and validates the coherence of the value.

toTimeValue

Converts a TheTime into milliseconds while applying safe bounds.

isSafeTimeValue

Checks that a time value is a safe integer within bounds.

getTimezoneOffset

Returns the timezone offset in milliseconds for a TheDate.

applyTimezone

Applies a timezone offset to a TheDate.

toISOString

Returns the ISO 8601 representation of a TheDate.

format

Displays a TheDate with a custom format and timezone.

isSafeTimestamp

Checks that a timestamp is between minTimestamp and maxTimestamp.

is

Checks that a string matches the TheDate format (type guard).

isTime

Checks that a string matches the TheTime format (type guard).

Component reading

getYear

Returns the year of a TheDate.

getMonth

Returns the month (1-12) of a TheDate.

getDayOfMonth

Returns the day of the month (1-31) of a TheDate.

getDayOfWeek

Returns the day of the week (1-7) of a TheDate, where 1 = Monday and 7 = Sunday.

getWeekOfYear

Returns the week of the year (1-53) of a TheDate according to ISO 8601.

getDayOfYear

Returns the day of the year (1-366) of a TheDate.

getHour

Returns the hour (0-23) of a TheDate.

getMinute

Returns the minutes (0-59) of a TheDate.

getSecond

Returns the seconds (0-59) of a TheDate.

getMilliseconds

Returns the milliseconds (0-999) of a TheDate.

getFirstDayOfWeek

Returns the first day of the week (Monday) for a TheDate.

getLastDayOfWeek

Returns the last day of the week (Sunday) for a TheDate.

getFirstDayOfMonth

Returns the first day of the month for a TheDate.

getLastDayOfMonth

Returns the last day of the month for a TheDate.

Time operations

Additions

addYears

Adds a positive number of years to a TheDate.

addMonths

Adds months while taking leap years into account.

addWeeks

Shifts a date by multiples of 7 days.

addDays

Adds a positive number of days.

addHours

Adds hours without manually converting to milliseconds.

addMinutes

Adds minutes.

addSeconds

Adds seconds.

addMilliseconds

Adds milliseconds while staying type-safe.

addTime

Adds a TheTime duration to a TheDate or TheTime.

Subtractions

subtractYears

Subtracts a number of years.

subtractMonths

Subtracts months while keeping day coherence.

subtractWeeks

Subtracts weeks.

subtractDays

Subtracts days.

subtractHours

Subtracts hours.

subtractMinutes

Subtracts minutes.

subtractSeconds

Subtracts seconds.

subtractMilliseconds

Subtracts milliseconds.

subtractTime

Subtracts a TheTime duration from a TheDate or TheTime.

Comparison

greater

Checks whether a date is strictly greater than another.

greaterThan

Compares while including equality.

less

Checks whether a date is strictly less than another.

lessThan

Compares while including equality for less-than.

between

Checks membership in an open interval.

betweenThan

Variant that includes bounds.

Comparison (TheTime)

greaterTime

Checks if a duration is strictly greater than another.

greaterThanTime

Inclusive comparison for TheTime.

lessTime

Checks if a duration is strictly less than another.

lessThanTime

Inclusive comparison for lower bound on TheTime.

betweenTime

Checks if a TheTime is within an open interval.

betweenThanTime

Inclusive range comparison for TheTime.

sort

Sorts an array of dates in ascending or descending order.

sortTimes

Sorts an array of durations in ascending or descending order.

max

Returns the most recent date of a tuple.

maxTime

Returns the largest duration of a tuple.

minTime

Returns the smallest duration of a tuple.

min

Returns the oldest date of a tuple.

Other utilities

round

Rounds a date to the chosen unit (day, month, etc.).

each

Generates all dates in an interval according to a granularity (Unit).

closestTo

Finds the closest date to a target in an iterable.

Constants & types

constants

Exposes minTimestamp, maxTimestamp, and common durations (day, week, etc.).

types/timezone

Complete enumeration of IANA time zones.

types/unit

List of units available for round, each, etc.

types/time

Describes time components (Hour, Minute, Second, ...).

types/isLeapYear

Provides the utility type to determine whether a year is a leap year.