Querying Methods
Methods for comparing dates, calculating differences, and extracting date components.
.isBefore()
Checks if the current instance is before another date.
isBefore(other: DateInput): boolean
The date to compare against
true if the current instance is before the other date, false otherwise
Examples
const date1 = atemporal('2024-01-15');
const date2 = atemporal('2024-01-20');
date1.isBefore(date2); // true
date2.isBefore(date1); // false
date1.isBefore('2024-02-01'); // true
.isAfter()
Checks if the current instance is after another date.
isAfter(other: DateInput): boolean
The date to compare against
true if the current instance is after the other date, false otherwise
Examples
const date1 = atemporal('2024-01-15');
const date2 = atemporal('2024-01-20');
date1.isAfter(date2); // false
date2.isAfter(date1); // true
date2.isAfter('2024-01-10'); // true
.isSame()
Checks if the current instance is the same as another date, optionally to a specific unit.
isSame(otherDate: DateInput, unit?: 'year' | 'month' | 'day'): boolean
The date to compare against
If provided, compares only up to this unit. If omitted, compares to the millisecond.
true if the dates are the same (within the specified unit), false otherwise
Examples
const date1 = atemporal('2024-01-15T10:30:00Z');
const date2 = atemporal('2024-01-15T14:30:00Z');
const date3 = atemporal('2024-01-15T10:30:00Z');
// Exact comparison (millisecond precision)
date1.isSame(date3); // true
date1.isSame(date2); // false
// Compare by unit
date1.isSame(date2, 'day'); // true (same day)
date1.isSame(date2, 'month'); // true (same month)
date1.isSame(date2, 'year'); // true (same year)
date1.isSame('2024-02-15', 'year'); // true
date1.isSame('2024-02-15', 'month'); // false
.isSameDay()
Checks if the current instance is on the same calendar day as another date in their respective timezones.
isSameDay(other: DateInput): boolean
The date to compare against
true if they are on the same calendar day, false otherwise
Examples
const date1 = atemporal('2024-01-15T10:00:00Z');
const date2 = atemporal('2024-01-15T23:59:59Z');
const date3 = atemporal('2024-01-16T00:00:00Z');
date1.isSameDay(date2); // true
date1.isSameDay(date3); // false
.isSameOrBefore()
Checks if the current instance is the same as or before another date.
isSameOrBefore(other: DateInput): boolean
The date to compare against
true if the current instance is the same as or before the other date
Examples
const date1 = atemporal('2024-01-15');
const date2 = atemporal('2024-01-15');
const date3 = atemporal('2024-01-20');
date1.isSameOrBefore(date2); // true (same)
date1.isSameOrBefore(date3); // true (before)
date3.isSameOrBefore(date1); // false
.isSameOrAfter()
Checks if the current instance is the same as or after another date.
isSameOrAfter(other: DateInput): boolean
The date to compare against
true if the current instance is the same as or after the other date
Examples
const date1 = atemporal('2024-01-20');
const date2 = atemporal('2024-01-20');
const date3 = atemporal('2024-01-15');
date1.isSameOrAfter(date2); // true (same)
date1.isSameOrAfter(date3); // true (after)
date3.isSameOrAfter(date1); // false
.isBetween()
Checks if the current instance is between two other dates.
isBetween(start: DateInput, end: DateInput, inclusivity?: '()' | '[]' | '(]' | '[)'): boolean
Defines if the start and end dates are inclusive:
'[]' - Both inclusive (default)'()' - Both exclusive'[)' - Start inclusive, end exclusive'(]' - Start exclusive, end inclusive
true if the current instance is within the range
Examples
const date = atemporal('2024-06-15');
const start = atemporal('2024-01-01');
const end = atemporal('2024-12-31');
// Inclusive (default)
date.isBetween(start, end); // true
date.isBetween(start, end, '[]'); // true
// Boundary cases
start.isBetween(start, end); // true (inclusive)
start.isBetween(start, end, '()'); // false (exclusive)
start.isBetween(start, end, '[)'); // true (start inclusive)
end.isBetween(start, end); // true (inclusive)
end.isBetween(start, end, '()'); // false (exclusive)
end.isBetween(start, end, '(]'); // true (end inclusive)
.diff()
Calculates the difference between the current instance and another date.
diff(other: DateInput, unit?: TimeUnit, float?: boolean): number
The date to compare against
The unit of time to calculate the difference in. Defaults to 'millisecond'.
Accepts: ‘year’, ‘month’, ‘week’, ‘day’, ‘hour’, ‘minute’, ‘second’, ‘millisecond’
If true, returns the exact floating-point difference. If false (default), returns a truncated integer.
The difference in the specified unit, or NaN if the operation is invalid
Examples
const d1 = atemporal('2024-01-01T12:00:00Z');
const d2 = atemporal('2024-01-02T18:00:00Z'); // 30 hours later
// Integer differences (default)
d2.diff(d1, 'day'); // 1
d2.diff(d1, 'hour'); // 30
d2.diff(d1, 'minute'); // 1800
// Floating-point differences
d2.diff(d1, 'day', true); // 1.25
d2.diff(d1, 'week', true); // 0.17857142857142858
// Negative differences
d1.diff(d2, 'day'); // -1
// Different units
const future = atemporal('2025-01-01');
const now = atemporal('2024-01-01');
future.diff(now, 'year'); // 1
future.diff(now, 'month'); // 12
future.diff(now, 'week'); // 52
future.diff(now, 'day'); // 366 (2024 is a leap year)
.get()
Gets the value of a specific unit of time.
get(unit: SettableUnit): number
The unit to retrieve: ‘year’, ‘month’, ‘day’, ‘hour’, ‘minute’, ‘second’, ‘millisecond’, or ‘quarter’
The numeric value of the unit, or NaN if the instance is invalid
Examples
const date = atemporal('2024-06-15T14:30:45.500Z');
date.get('year'); // 2024
date.get('month'); // 6
date.get('day'); // 15
date.get('hour'); // 14
date.get('minute'); // 30
date.get('second'); // 45
date.get('millisecond'); // 500
date.get('quarter'); // 2 (Q2)
.isValid()
Checks if the Atemporal instance holds a valid date.
true if the date is valid, false otherwise
Examples
const valid = atemporal('2024-01-15');
const invalid = atemporal('invalid-date');
valid.isValid(); // true
invalid.isValid(); // false
// Check before operations
if (date.isValid()) {
console.log(date.format('YYYY-MM-DD'));
}
.isLeapYear()
Checks if the year of the current instance is a leap year.
true if it is a leap year, false otherwise
Examples
atemporal('2024-01-01').isLeapYear(); // true (2024 is a leap year)
atemporal('2023-01-01').isLeapYear(); // false
atemporal('2000-01-01').isLeapYear(); // true
atemporal('1900-01-01').isLeapYear(); // false
Getters
Convenient property accessors for date components.
.year
The 4-digit year.
.month
The month of the year (1-12).
.day
The day of the month (1-31).
.hour
The hour of the day (0-23).
.minute
The minute of the hour (0-59).
.second
The second of the minute (0-59).
.millisecond
The millisecond of the second (0-999).
.dayOfWeekName
The full name of the day of the week, based on the default locale.
date.dayOfWeekName; // 'Saturday'
.weekOfYear
The ISO week number of the year (1-53).
.daysInMonth
The number of days in the current month.
atemporal('2024-02-01').daysInMonth; // 29 (leap year)
atemporal('2023-02-01').daysInMonth; // 28
atemporal('2024-06-01').daysInMonth; // 30
.timeZoneName / .timeZoneId
The IANA time zone identifier.
date.timeZoneName; // 'America/New_York'
date.timeZoneId; // 'America/New_York'
Example Usage
const date = atemporal('2024-06-15T14:30:45.500Z');
console.log(`Year: ${date.year}`);
console.log(`Month: ${date.month}`);
console.log(`Day: ${date.day}`);
console.log(`Hour: ${date.hour}`);
console.log(`Minute: ${date.minute}`);
console.log(`Second: ${date.second}`);
console.log(`Millisecond: ${date.millisecond}`);
console.log(`Day of week: ${date.dayOfWeekName}`);
console.log(`Week of year: ${date.weekOfYear}`);
console.log(`Days in month: ${date.daysInMonth}`);
.range()
Generates an array of dates within a given date range. Can return either Atemporal instances or formatted strings.
range(endDate: DateInput, unit: TimeUnit, options?: { inclusivity?: '()' | '[]' | '(]' | '[)' }): TemporalWrapper[]
range(endDate: DateInput, unit: TimeUnit, options: { inclusivity?: '()' | '[]' | '(]' | '[)', format: string | Intl.DateTimeFormatOptions }): string[]
The end date of the range
The unit to increment by: ‘year’, ‘month’, ‘week’, ‘day’, ‘hour’, ‘minute’, ‘second’, or ‘millisecond’
Controls whether start and end dates are included:
'[]' - Both inclusive (default)'()' - Both exclusive'[)' - Start inclusive, end exclusive'(]' - Start exclusive, end inclusive
options.format
string | Intl.DateTimeFormatOptions
If provided, returns an array of formatted strings instead of Atemporal instances. Can be a format string (e.g., ‘YYYY-MM-DD’) or Intl options
return
TemporalWrapper[] | string[]
Array of Atemporal instances or formatted strings covering the range
Examples
const start = atemporal('2023-01-01');
const end = atemporal('2023-01-05');
// Array of Atemporal instances
const days = start.range(end, 'day');
// [Atemporal('2023-01-01'), Atemporal('2023-01-02'), ..., Atemporal('2023-01-05')]
// Array of formatted strings
const formatted = start.range(end, 'day', { format: 'YYYY-MM-DD' });
// ['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05']
// Exclusive range
const exclusive = start.range(end, 'day', { inclusivity: '()' });
// Excludes both start and end dates
// Weekly range
const weeks = start.range(atemporal('2023-02-01'), 'week', { format: 'MMM DD' });
// ['Jan 01', 'Jan 08', 'Jan 15', 'Jan 22', 'Jan 29']
// Using Intl options for formatting
const intl = start.range(end, 'day', {
format: { month: 'long', day: 'numeric' }
});
// ['January 1', 'January 2', 'January 3', 'January 4', 'January 5']
