TypeScript API Reference

Complete API Reference

Comprehensive documentation for every function and type exported by daysafe (version 1.0.0). All functions are pure, non-mutating, zero-dependency, and strictly typed.

Parsing & Validation

parseDate

Try in Playground

Validates calendar dates between 0001-01-01 and 9999-12-31. Checks month limits (1-12) and day counts according to leap year rules. Timestamps (e.g. containing 'T'), non-strings, year 0000, and impossible calendar dates like February 30 are rejected without silent normalization.

TypeScript Signature

parseDate(input: unknown): DateOnly | null

Parameters

Name	Type	Description
input*	unknown	The raw value to parse and validate.

Return Type:

DateOnly | null

Invalid Input Behavior:

Returns null without throwing or silently shifting invalid calendar dates.

Code Example

example-parseDate.ts

400 font-semibold">import { parseDate } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
400 font-semibold">const valid = parseDate(400 font-semibold">class="text-emerald-400">"2026-11-02");
console.log(valid); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2026-11-02" (DateOnly)
400 font-semibold">const leap = parseDate(400 font-semibold">class="text-emerald-400">"2024-02-29");
console.log(leap); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2024-02-29"
400 font-semibold">const impossible = parseDate(400 font-semibold">class="text-emerald-400">"2026-02-30");
console.log(impossible); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">null

Parsing & Validation

isValidDate

Try in Playground

Checks whether an input string is a valid Gregorian calendar date in YYYY-MM-DD format. When true, TypeScript automatically narrows the variable to the branded DateOnly type.

TypeScript Signature

isValidDate(input: unknown): input is DateOnly

Parameters

Name	Type	Description
input*	unknown	Any value to test.

Return Type:

boolean (type guard)

Invalid Input Behavior:

Returns false for invalid values, non-strings, out-of-range years, or impossible days.

Code Example

example-isValidDate.ts

400 font-semibold">import { isValidDate } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
400 font-semibold">const userInput: unknown = 400 font-semibold">class="text-emerald-400">"2024-02-29";
400 font-semibold">if (isValidDate(userInput)) {
  // userInput is narrowed to DateOnly here
  console.log(400 font-semibold">class="text-emerald-400">"Valid leap day:", userInput);
} 400 font-semibold">else {
  console.error(400 font-semibold">class="text-emerald-400">"Invalid calendar date");
}

Parsing & Validation

isLeapYear

Try in Playground

Applies exact Gregorian rules: years divisible by 4 are leap years, except century years (ending in 00), which are only leap years if divisible by 400. For instance, 1900 is not a leap year, but 2000 is. Supports years 1 to 9999.

TypeScript Signature

isLeapYear(year: number): boolean

Parameters

Name	Type	Description
year*	number	Gregorian year integer (1 - 9999).

Return Type:

boolean

Invalid Input Behavior:

Returns false for non-integers, numbers outside 1..9999, and non-leap years.

Code Example

example-isLeapYear.ts

400 font-semibold">import { isLeapYear } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(isLeapYear(2024)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true
console.log(isLeapYear(1900)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">false (century rule: 1900 % 100 === 0 && 1900 % 400 !== 0)
console.log(isLeapYear(2000)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true (century rule: 2000 % 400 === 0)
console.log(isLeapYear(2026)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">false

Parsing & Validation

getDaysInMonth

Try in Playground

Calculates the exact day count for any month (1-indexed: 1 = January, 12 = December). Accurately returns 29 for February in leap years and 28 in common years.

TypeScript Signature

getDaysInMonth(year: number, month: number): number

Parameters

Name	Type	Description
year*	number	Gregorian year integer (1 - 9999).
month*	number	Calendar month index (1 - 12).

Return Type:

number

Invalid Input Behavior:

Throws TypeError if inputs are non-integers. Throws RangeError if month < 1 or > 12, or year outside 1..9999.

Code Example

example-getDaysInMonth.ts

400 font-semibold">import { getDaysInMonth } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(getDaysInMonth(2024, 2)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 29 (leap year February)
console.log(getDaysInMonth(2026, 2)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 28 (common year February)
console.log(getDaysInMonth(2026, 11)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 30 (November)

Date Arithmetic

addDays

Try in Playground

Performs pure civil calendar arithmetic. Because calculations run on calendar day numbers rather than millisecond timestamps, transitions into or out of Daylight Saving Time (23h or 25h days) never distort the result.

TypeScript Signature

addDays(date: DateInput, amount: number): DateOnly

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD) or DateOnly.
amount*	number	Signed integer days to add (positive) or subtract (negative).

Return Type:

DateOnly

Invalid Input Behavior:

Throws TypeError if date is invalid or amount is not an integer. Throws RangeError if resulting year is outside 0001..9999.

Code Example

example-addDays.ts

400 font-semibold">import { addDays } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(addDays(400 font-semibold">class="text-emerald-400">"2026-11-02", 7));  400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2026-11-09"
console.log(addDays(400 font-semibold">class="text-emerald-400">"2026-11-02", -5)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2026-10-28"
console.log(addDays(400 font-semibold">class="text-emerald-400">"2024-02-28", 1));  400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2024-02-29" (leap year)

Date Arithmetic

addMonths

Try in Playground

Adds or subtracts months safely. When the target month has fewer days than the starting day (e.g. adding 1 month to January 31), DaySafe clamps the day to the last valid day of that month (February 28 or 29). Never rolls over into March.

TypeScript Signature

addMonths(date: DateInput, amount: number): DateOnly

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD) or DateOnly.
amount*	number	Signed integer months to add (positive) or subtract (negative).

Return Type:

DateOnly

Invalid Input Behavior:

Throws TypeError if date is invalid or amount is not an integer. Throws RangeError if resulting year is outside 0001..9999.

Code Example

example-addMonths.ts

400 font-semibold">import { addMonths } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
// Predictable end-of-month clamping:
console.log(addMonths(400 font-semibold">class="text-emerald-400">"2026-01-31", 1)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2026-02-28" (clamped to end of Feb)
console.log(addMonths(400 font-semibold">class="text-emerald-400">"2024-01-31", 1)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2024-02-29" (clamped to leap day)
console.log(addMonths(400 font-semibold">class="text-emerald-400">"2026-03-31", -1)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2026-02-28"

Date Arithmetic

addYears

Try in Playground

Calculates year addition or subtraction. If the start date is February 29 and the destination year is not a leap year, DaySafe clamps to February 28. If the destination year is also a leap year (e.g. +4 years), February 29 is preserved.

TypeScript Signature

addYears(date: DateInput, amount: number): DateOnly

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD) or DateOnly.
amount*	number	Signed integer years to add (positive) or subtract (negative).

Return Type:

DateOnly

Invalid Input Behavior:

Throws TypeError if date is invalid or amount is not an integer. Throws RangeError if resulting year is outside 0001..9999.

Code Example

example-addYears.ts

400 font-semibold">import { addYears } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(addYears(400 font-semibold">class="text-emerald-400">"2024-02-29", 1)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2025-02-28" (clamped 400 font-semibold">from leap day)
console.log(addYears(400 font-semibold">class="text-emerald-400">"2024-02-29", 4)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2028-02-29" (target year is leap)
console.log(addYears(400 font-semibold">class="text-emerald-400">"2026-11-02", 2)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2028-11-02"

Date Arithmetic

daysBetween

Try in Playground

Computes end - start in exact calendar days. Because this uses pure civil day arithmetic rather than dividing millisecond timestamps by 86,400,000, it is 100% immune to DST transitions (23h or 25h days) and timezone skew.

TypeScript Signature

daysBetween(start: DateInput, end: DateInput): number

Parameters

Name	Type	Description
start*	DateInput	Start calendar date string (YYYY-MM-DD).
end*	DateInput	End calendar date string (YYYY-MM-DD).

Return Type:

number

Invalid Input Behavior:

Throws TypeError if either date is invalid.

Code Example

example-daysBetween.ts

400 font-semibold">import { daysBetween } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(daysBetween(400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-08")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 7
console.log(daysBetween(400 font-semibold">class="text-emerald-400">"2026-11-08", 400 font-semibold">class="text-emerald-400">"2026-11-01")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// -7
console.log(daysBetween(400 font-semibold">class="text-emerald-400">"2024-02-28", 400 font-semibold">class="text-emerald-400">"2024-03-01")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 2 (leap year February 29 included)

Date Arithmetic

compareDates

Try in Playground

Returns -1 if a < b, 0 if a === b, and 1 if a > b. Perfect for use directly as a comparator function with Array.prototype.sort().

TypeScript Signature

compareDates(a: DateInput, b: DateInput): ComparisonResult

Parameters

Name	Type	Description
a*	DateInput	First calendar date.
b*	DateInput	Second calendar date.

Return Type:

-1 | 0 | 1

Invalid Input Behavior:

Throws TypeError if either date is invalid.

Code Example

example-compareDates.ts

400 font-semibold">import { compareDates } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(compareDates(400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-05")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// -1
console.log(compareDates(400 font-semibold">class="text-emerald-400">"2026-11-05", 400 font-semibold">class="text-emerald-400">"2026-11-01")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 1
console.log(compareDates(400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-01")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 0
// Sorting an array of dates:
400 font-semibold">const list = [400 font-semibold">class="text-emerald-400">"2026-12-01", 400 font-semibold">class="text-emerald-400">"2026-01-15", 400 font-semibold">class="text-emerald-400">"2026-06-20"];
list.sort(compareDates); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// [400 font-semibold">class="text-emerald-400">"2026-01-15", 400 font-semibold">class="text-emerald-400">"2026-06-20", 400 font-semibold">class="text-emerald-400">"2026-12-01"]

Calendar Utilities

getDayOfWeek

Try in Playground

Calculates the day of the week using pure civil calendar math, completely independent of local timezone or locale conventions. Conforms to ISO 8601 standard numbering: Monday is 1, Sunday is 7.

TypeScript Signature

getDayOfWeek(date: DateInput): number

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD).

Return Type:

number (1..7)

Invalid Input Behavior:

Throws TypeError if date is invalid.

Code Example

example-getDayOfWeek.ts

400 font-semibold">import { getDayOfWeek } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(getDayOfWeek(400 font-semibold">class="text-emerald-400">"2026-11-02")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 1 (Monday)
console.log(getDayOfWeek(400 font-semibold">class="text-emerald-400">"2026-11-01")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 7 (Sunday)
console.log(getDayOfWeek(400 font-semibold">class="text-emerald-400">"2026-10-31")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 6 (Saturday)

Calendar Utilities

isWeekend

Try in Playground

Convenience helper that returns true if getDayOfWeek(date) is 6 (Saturday) or 7 (Sunday). Timezone-safe.

TypeScript Signature

isWeekend(date: DateInput): boolean

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD).

Return Type:

boolean

Invalid Input Behavior:

Throws TypeError if date is invalid.

Code Example

example-isWeekend.ts

400 font-semibold">import { isWeekend } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(isWeekend(400 font-semibold">class="text-emerald-400">"2026-11-01")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true (Sunday)
console.log(isWeekend(400 font-semibold">class="text-emerald-400">"2026-10-31")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true (Saturday)
console.log(isWeekend(400 font-semibold">class="text-emerald-400">"2026-11-02")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">false (Monday)

Calendar Utilities

startOfMonth

Try in Playground

Returns a branded DateOnly representing day 01 of the same year and month.

TypeScript Signature

startOfMonth(date: DateInput): DateOnly

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD).

Return Type:

DateOnly

Invalid Input Behavior:

Throws TypeError if date is invalid.

Code Example

example-startOfMonth.ts

400 font-semibold">import { startOfMonth } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(startOfMonth(400 font-semibold">class="text-emerald-400">"2026-11-15")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2026-11-01"
console.log(startOfMonth(400 font-semibold">class="text-emerald-400">"2024-02-29")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2024-02-01"

Calendar Utilities

endOfMonth

Try in Playground

Calculates the final day of the month for the given date. Returns 29 for February in leap years, 28 in common years, 30 for 30-day months, and 31 for 31-day months.

TypeScript Signature

endOfMonth(date: DateInput): DateOnly

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD).

Return Type:

DateOnly

Invalid Input Behavior:

Throws TypeError if date is invalid.

Code Example

example-endOfMonth.ts

400 font-semibold">import { endOfMonth } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(endOfMonth(400 font-semibold">class="text-emerald-400">"2026-11-15")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2026-11-30"
console.log(endOfMonth(400 font-semibold">class="text-emerald-400">"2024-02-10")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2024-02-29" (leap year)
console.log(endOfMonth(400 font-semibold">class="text-emerald-400">"2025-02-10")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2025-02-28" (common year)

Formatting

formatDate

Try in Playground

Standard JavaScript Intl.DateTimeFormat shifts calendar dates when evaluated in negative timezones. formatDate locks formatting to the exact UTC calendar date, preventing off-by-one shifts anywhere in the world. Also avoids the legacy year 0001-0099 Date.UTC year-1900 quirk.

TypeScript Signature

formatDate(date: DateInput, options?: FormatDateOptions): string

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD).
options(optional)	FormatDateOptions	Locale and style configuration (e.g. { locale: 'en-US', style: 'long' }).

Return Type:

string

Invalid Input Behavior:

Throws TypeError if date is invalid.

Code Example

example-formatDate.ts

400 font-semibold">import { formatDate } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
// Long style:
console.log(formatDate(400 font-semibold">class="text-emerald-400">"2026-11-02", { locale: 400 font-semibold">class="text-emerald-400">"en-US", style: 400 font-semibold">class="text-emerald-400">"long" }));
// "November 2, 2026"
// German locale medium:
console.log(formatDate(400 font-semibold">class="text-emerald-400">"2026-11-02", { locale: 400 font-semibold">class="text-emerald-400">"de-DE", style: 400 font-semibold">class="text-emerald-400">"medium" }));
// "02.11.2026"
// Custom components:
console.log(formatDate(400 font-semibold">class="text-emerald-400">"2026-11-02", {
  locale: 400 font-semibold">class="text-emerald-400">"en-US",
  weekday: 400 font-semibold">class="text-emerald-400">"long",
  year: 400 font-semibold">class="text-emerald-400">"numeric",
  month: 400 font-semibold">class="text-emerald-400">"long",
  day: 400 font-semibold">class="text-emerald-400">"numeric"
})); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"Monday, November 2, 2026"

Date Helpers

minDate

Try in Playground

Strictly validates all passed calendar dates and returns the chronologically earliest date as a DateOnly branded string.

TypeScript Signature

minDate(...dates: DateInput[]): DateOnly

Parameters

Name	Type	Description
dates*	...DateInput[]	One or more calendar date strings.

Return Type:

DateOnly

Invalid Input Behavior:

Throws TypeError if no dates are passed or if any date is invalid.

Code Example

example-minDate.ts

400 font-semibold">import { minDate } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(minDate(400 font-semibold">class="text-emerald-400">"2026-11-05", 400 font-semibold">class="text-emerald-400">"2026-11-02", 400 font-semibold">class="text-emerald-400">"2026-11-08"));
// "2026-11-02"
console.log(minDate(400 font-semibold">class="text-emerald-400">"2024-02-29", 400 font-semibold">class="text-emerald-400">"2024-03-01"));
// "2024-02-29"

Date Helpers

maxDate

Try in Playground

Strictly validates all passed calendar dates and returns the chronologically latest date as a DateOnly branded string.

TypeScript Signature

maxDate(...dates: DateInput[]): DateOnly

Parameters

Name	Type	Description
dates*	...DateInput[]	One or more calendar date strings.

Return Type:

DateOnly

Invalid Input Behavior:

Throws TypeError if no dates are passed or if any date is invalid.

Code Example

example-maxDate.ts

400 font-semibold">import { maxDate } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(maxDate(400 font-semibold">class="text-emerald-400">"2026-11-05", 400 font-semibold">class="text-emerald-400">"2026-11-02", 400 font-semibold">class="text-emerald-400">"2026-11-08"));
// "2026-11-08"

Date Helpers

isBefore

Try in Playground

Returns true if calendar date a occurs before calendar date b in civil time.

TypeScript Signature

isBefore(a: DateInput, b: DateInput): boolean

Parameters

Name	Type	Description
a*	DateInput	First calendar date.
b*	DateInput	Second calendar date.

Return Type:

boolean

Invalid Input Behavior:

Throws TypeError if either date is invalid.

Code Example

example-isBefore.ts

400 font-semibold">import { isBefore } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(isBefore(400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-02")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true
console.log(isBefore(400 font-semibold">class="text-emerald-400">"2026-11-02", 400 font-semibold">class="text-emerald-400">"2026-11-02")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">false

Date Helpers

isAfter

Try in Playground

Returns true if calendar date a occurs after calendar date b in civil time.

TypeScript Signature

isAfter(a: DateInput, b: DateInput): boolean

Parameters

Name	Type	Description
a*	DateInput	First calendar date.
b*	DateInput	Second calendar date.

Return Type:

boolean

Invalid Input Behavior:

Throws TypeError if either date is invalid.

Code Example

example-isAfter.ts

400 font-semibold">import { isAfter } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(isAfter(400 font-semibold">class="text-emerald-400">"2026-11-05", 400 font-semibold">class="text-emerald-400">"2026-11-02")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true
console.log(isAfter(400 font-semibold">class="text-emerald-400">"2026-11-02", 400 font-semibold">class="text-emerald-400">"2026-11-02")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">false

Date Helpers

isSame

Try in Playground

Validates both inputs and returns true if both dates represent the identical calendar day.

TypeScript Signature

isSame(a: DateInput, b: DateInput): boolean

Parameters

Name	Type	Description
a*	DateInput	First calendar date.
b*	DateInput	Second calendar date.

Return Type:

boolean

Invalid Input Behavior:

Throws TypeError if either date is invalid.

Code Example

example-isSame.ts

400 font-semibold">import { isSame } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(isSame(400 font-semibold">class="text-emerald-400">"2026-11-02", 400 font-semibold">class="text-emerald-400">"2026-11-02")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true
console.log(isSame(400 font-semibold">class="text-emerald-400">"2026-11-02", 400 font-semibold">class="text-emerald-400">"2026-11-03")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">false

Date Helpers

isBetween

Try in Playground

Determines if target date falls between start and end. The boundary order is automatically sorted (start <= end). By default, inclusive is true.

TypeScript Signature

isBetween(date: DateInput, start: DateInput, end: DateInput, inclusive?: boolean): boolean

Parameters

Name	Type	Description
date*	DateInput	The target date to evaluate.
start*	DateInput	Boundary start date.
end*	DateInput	Boundary end date.
inclusive(optional)	boolean	Whether boundary dates match (default: true).

Return Type:

boolean

Invalid Input Behavior:

Throws TypeError if any date is invalid.

Code Example

example-isBetween.ts

400 font-semibold">import { isBetween } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
console.log(isBetween(400 font-semibold">class="text-emerald-400">"2026-11-05", 400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-10")); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true
console.log(isBetween(400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-10", 400 font-semibold">true)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">true
console.log(isBetween(400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-01", 400 font-semibold">class="text-emerald-400">"2026-11-10", 400 font-semibold">false)); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">false

Date Helpers

toDateParts

Try in Playground

Validates the date and extracts numeric year (1-9999), month (1-12), and day (1-31) in civil calendar units.

TypeScript Signature

toDateParts(date: DateInput): DateParts

Parameters

Name	Type	Description
date*	DateInput	Calendar date string (YYYY-MM-DD).

Return Type:

DateParts ({ year: number, month: number, day: number })

Invalid Input Behavior:

Throws TypeError if date is invalid.

Code Example

example-toDateParts.ts

400 font-semibold">import { toDateParts } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
400 font-semibold">const parts = toDateParts(400 font-semibold">class="text-emerald-400">"2026-11-02");
console.log(parts);
// { year: 2026, month: 11, day: 2 }

Date Helpers

fromDateParts

Try in Playground

Validates integer components and constructs a strict YYYY-MM-DD string with zero-padding. Rejects impossible days (e.g. Feb 30) or out-of-range years.

TypeScript Signature

fromDateParts(parts: DateParts): DateOnly

Parameters

Name	Type	Description
parts*	DateParts	Object containing { year: number, month: number, day: number }.

Return Type:

DateOnly

Invalid Input Behavior:

Throws TypeError if any part is not an integer. Throws RangeError if parts form an invalid calendar date.

Code Example

example-fromDateParts.ts

400 font-semibold">import { fromDateParts } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
400 font-semibold">const date = fromDateParts({ year: 2026, month: 11, day: 2 });
console.log(date); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// 400 font-semibold">class="text-emerald-400">"2026-11-02"
// Out of bounds throws:
// fromDateParts({ year: 2026, month: 2, day: 30 }); // throws RangeError

Date Helpers

todayUtc

Try in Playground

Eliminates machine timezone variance by evaluating the current calendar date strictly at UTC. Ideal for server-rendered consistency.

TypeScript Signature

todayUtc(): DateOnly

Return Type:

DateOnly

Invalid Input Behavior:

Never throws; returns the current UTC calendar date.

Code Example

example-todayUtc.ts

400 font-semibold">import { todayUtc } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"daysafe";
400 font-semibold">const today = todayUtc();
console.log(400 font-semibold">class="text-emerald-400">"Current UTC Calendar Date:", today); 400 font-semibold">class=400 font-semibold">class="text-emerald-400">"text-slate-500 italic">// e.g. 400 font-semibold">class="text-emerald-400">"2026-11-02"