Date
Functions to manipulate immutable dates and durations with TheDate (class extending Date) and TheTime (immutable duration class).
The namespace also exposes serialized formats SerializedTheDate (date${number}${"-" | "+"}) and SerializedTheTime (time${number}${"-" | "+"}) for transport and text storage.
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";Core types
TheDate
Immutable class extending Date for date-time manipulation.
TheTime
Immutable duration class used in the date API context.
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 an instant approximately one day before now.
tomorrow
Returns an instant approximately one day after now.
Conversion & validation
toNative
Converts TheDate/TheTime values to native JavaScript Date/number.
toTimestamp
Exposes the timestamp in milliseconds and validates the coherence of the value.
getDifference
Returns the signed difference between two dates as a TheTime.
toTimeValue
Converts a TheTime into the requested unit while applying safe bounds.
computeTime
Converts a TheTime or SerializedTheTime to a selected unit.
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.
formatTime
Formats a TheTime using a custom format string.
isSafeTimestamp
Checks that a timestamp is between minTimestamp and maxTimestamp.
serialize
Converts TheDate/TheTime into SerializedTheDate/SerializedTheTime.
isSerializedTheDate
Checks whether a string is a valid SerializedTheDate.
isSerializedTheTime
Checks whether a string is a valid SerializedTheTime.
is
Checks whether a value is an instance of TheDate (type guard).
isTime
Checks whether a value is an instance of TheTime (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.
equal
Checks whether two dates represent the same timestamp.
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.