API / Classes

`CalendarDate` class

A calendar date with no time of day and no time zone.

import { CalendarDate } from 'native-dates'core 7.3 kB min+br

Creating a CalendarDate

Create an instance from an ISO string, year-month-day numbers, or an existing value with date(), or read the current day with today(). Helpers for tomorrow and yesterday work the same way, and every method returns a new immutable instance.

create.js

import { date, today, tomorrow } from 'native-dates';

const birthday = date('2026-05-10');
const launch = date(2026, 11, 16);
const current = today();
const nextDay = tomorrow('America/New_York');

Because a calendar date has no clock or time zone, May 10 stays May 10 for every user regardless of where they live. You can also read the local calendar date off any DateTime:

import { datetime } from 'native-dates';

const flight = datetime('2026-11-16T23:30:00Z', 'Asia/Tokyo');
flight.date.toString(); // '2026-11-17'

Properties

Properties read the ISO calendar fields directly.

Property	Type	Description
`text`	`string`	Locale-formatted calendar date, such as `'Nov 16, 2026'`.
`year`, `month`, `day`	`number`	Calendar year, month (1–12), and day of month (1–31).
`weekday`	`number`	ISO day of the week, from 1 for Monday through 7 for Sunday.
`quarter`	`number`	Calendar quarter (1–4).
`weekOfYear`, `dayOfYear`	`number`	ISO week number (1–53) and day of the year (1–366).
`daysInMonth`, `daysInYear`	`number`	Number of days in the current month (28–31) and year (365 or 366).

Combining and fields

Attach a time of day in a time zone to create a specific moment, or replace individual calendar fields.

`at()`

d.at(time?, zone?): DateTime

Combines this calendar date with a time of day in a time zone and returns a DateTime. Omitting the time defaults to midnight at the start of the day.

Parameters

timeTimeInputdefault '00:00'

Time string such as '9:30am', Time instance, fields object, or Date.

zoneZone

IANA time zone name, fixed UTC offset, or 'UTC'. Defaults to the configured zone.

Returns

DateTime

A new DateTime on this date at time in zone.

const day = date('2026-11-16');

day.at('9:30am', 'America/Los_Angeles').toString(); // '2026-11-16T17:30:00.000Z'
day.at(undefined, 'UTC').toString(); // '2026-11-16T00:00:00.000Z'

`set()`

d.set(fields): CalendarDate
d.set(unit, value): CalendarDate

Returns a new CalendarDate with one or more calendar fields replaced. Out-of-range dates such as February 30 throw a RangeError instead of rolling into the next month.

Parameters

fieldsDateTimeFields | DateUnitrequired

Object with year, month, or day fields, or a single unit name.

valuenumber

Whole-number value for the given unit.

Returns

CalendarDate

A new CalendarDate with updated calendar fields.

const due = date('2026-11-16');

due.set('day', 1).toString(); // '2026-11-01'
due.set({ month: 12, day: 31 }).toString(); // '2026-12-31'

Arithmetic and boundaries

Step across calendar units, snap to period boundaries, or move to a nearby weekday. Clock units such as hours and minutes throw a RangeError because a calendar date has no clock.

Month-end clamping

Adding months or years clamps to the last valid day of the target month rather than overflowing into the next one. Adding one month to January 31 lands on February 28, or February 29 in a leap year.

`plus()`

d.plus(amount, unit?): CalendarDate
d.add(amount, unit?): CalendarDate

Moves forward by years, quarters, months, weeks, or days and returns a new CalendarDate. Also aliased as add().

Parameters

amountDurationInputrequired

Count paired with unit, Duration instance, duration string, or fields object.

unitDateUnit

Calendar unit name when amount is a number, such as 'days' or 'months'.

Returns

CalendarDate

A new CalendarDate shifted forward on the calendar.

const billing = date('2026-01-31');

billing.plus(1, 'month').toString(); // '2026-02-28'
billing.plus('2 weeks').toString(); // '2026-02-14'

`minus()`

d.minus(amount, unit?): CalendarDate
d.subtract(amount, unit?): CalendarDate
d.remove(amount, unit?): CalendarDate

Moves backward by a calendar duration. Accepts the same inputs as plus(), and is also aliased as subtract() and remove().

Parameters

amountDurationInputrequired

Count paired with unit, Duration instance, duration string, or fields object.

unitDateUnit

Calendar unit name when amount is a number.

Returns

CalendarDate

A new CalendarDate shifted backward on the calendar.

const launch = date('2026-03-01');

launch.minus(1, 'day').toString(); // '2026-02-28'
launch.minus({ weeks: 2, days: 1 }).toString(); // '2026-02-14'

`startOf()`

d.startOf(unit, firstDay?): CalendarDate

Returns the first day of the calendar unit containing this date. Week boundaries begin on Monday unless configured otherwise with configure() or overridden with firstDay.

Parameters

unitDateUnitrequired

Calendar unit from 'year' down to 'day'.

firstDayWeekday

First day of the week when rounding to a week, such as 'sunday' or 7.

Returns

CalendarDate

The first calendar day of unit.

const wed = date('2026-11-18');

wed.startOf('month').toString(); // '2026-11-01'
wed.startOf('quarter').toString(); // '2026-10-01'
wed.startOf('week').toString(); // '2026-11-16'
wed.startOf('week', 'sunday').toString(); // '2026-11-15'

`endOf()`

d.endOf(unit, firstDay?): CalendarDate

Returns the final day of the calendar unit containing this date.

Parameters

unitDateUnitrequired

Calendar unit from 'year' down to 'day'.

firstDayWeekday

First day of the week when unit is 'week'.

Returns

CalendarDate

The last calendar day of unit.

date('2026-02-10').endOf('month').toString(); // '2026-02-28'
date('2028-02-10').endOf('month').toString(); // '2028-02-29'

`next()`

d.next(weekday): CalendarDate

Moves forward to the next given weekday after this date. If it is already that weekday, it advances a full week.

Parameters

weekdayWeekdayrequired

Weekday name such as 'friday', three-letter prefix, or ISO number (1–7).

Returns

CalendarDate

A new CalendarDate 1 to 7 days later.

const mon = date('2026-11-16');

mon.next('friday').toString(); // '2026-11-20'
mon.next('monday').toString(); // '2026-11-23'

`previous()`

d.previous(weekday): CalendarDate

Moves back to the most recent given weekday before this date. If it is already that weekday, it steps back a full week.

Parameters

weekdayWeekdayrequired

Weekday name, three-letter prefix, or ISO number (1–7).

Returns

CalendarDate

A new CalendarDate 1 to 7 days earlier.

date('2026-11-16').previous('friday').toString(); // '2026-11-13'

Comparing dates

Compare calendar dates directly or pass any input accepted by date().

Avoid numeric comparison operators

A calendar date is not a timestamp, so numeric operators throw a RangeError rather than coercing to milliseconds. Compare dates with methods like isBefore(), or sort arrays with compare().

`equals()`

d.equals(other): boolean

Returns true when both values represent the same calendar year, month, and day.

Parameters

otherCalendarDateInputrequired

Another CalendarDate or any input accepted by date().

Returns

boolean

true if both values represent the same calendar day.

const due = date('2026-11-16');

due.equals('2026-11-16'); // true
due.equals(date(2026, 11, 16)); // true

`isBefore()`

d.isBefore(other): boolean

Returns true if this date is earlier on the calendar than the other.

date('2026-11-15').isBefore('2026-11-16'); // true

`isAfter()`

d.isAfter(other): boolean

Returns true if this date is later on the calendar than the other.

date('2026-11-17').isAfter('2026-11-16'); // true

`isSame()`

d.isSame(other, unit?, firstDay?): boolean

Checks whether another date falls in the same calendar unit, such as the same month or week. Calling isSame() without a unit checks whether both values are the exact same day.

Parameters

otherCalendarDateInputrequired

Date to compare against.

unitDateUnit

Calendar unit to compare, from 'year' down to 'day'.

firstDayWeekday

First day of the week when unit is 'week'.

Returns

boolean

true when both dates fall in the same unit.

const wed = date('2026-09-09');

wed.isSame('2026-09-30', 'month'); // true
wed.isSame('2026-09-06', 'week'); // false
wed.isSame('2026-09-06', 'week', 'sunday'); // true

Calendar predicates

Relative day checks accept an optional time zone because which calendar day is today depends on where you stand. When omitted, they use the default zone from configure().

Method	Type	Description
`isToday(zone?)`, `isTomorrow(zone?)`, `isYesterday(zone?)`	`boolean`	Whether this date matches today, tomorrow, or yesterday in the given or configured zone.
`isPast(zone?)`, `isFuture(zone?)`	`boolean`	Whether this date is earlier or later than today in the given or configured zone.
`isWeekday()`, `isWeekend()`	`boolean`	Monday through Friday vs. Saturday and Sunday.
`isLeapYear()`	`boolean`	Whether this date’s year has 366 days.

Measuring spans

`until()`

d.until(other): Duration
d.until(other, unit): number

Measures the calendar span from this date to another, returning a negative duration when the target is earlier. The returned Duration remembers this starting date so months and years can be totaled accurately.

Parameters

otherCalendarDateInputrequired

Target date to measure toward.

unitUnit

Unit to return the total length in as a floating-point number.

Returns

Duration | number

A Duration balanced up to years, or a number when unit is given.

const start = date('2026-01-01');

start.until('2027-04-05').toString(); // 'P1Y3M4D'
start.until('2027-04-05', 'days'); // 459
start.until('2026-07-01').total('months'); // 6

`since()`

d.since(other): Duration
d.since(other, unit): number

Measures the calendar span elapsed since an earlier date. Pass a unit name to get the total as a number.

date('2026-11-16').since('2026-11-02', 'weeks'); // 2

Formatting and conversion

`format()`

d.format(spec?, locale?): string

Formats the date using Intl.DateTimeFormat. Accepts a preset style, an options object, or a token pattern when @native-dates/plugins/tokens is loaded.

Parameters

specFormatSpecdefault 'medium'

Date preset such as 'medium' or 'month', Intl.DateTimeFormatOptions object, or token pattern.

localestring

BCP 47 locale tag overriding the configured default for this call.

Returns

string

Locale-formatted date string.

const day = date('2026-11-16');

day.format('short', 'en-US'); // '11/16/26'
day.format('medium', 'en-US'); // 'Nov 16, 2026'
day.format('long', 'en-US'); // 'November 16, 2026'
day.format('full', 'en-US'); // 'Monday, November 16, 2026'
day.format('month', 'en-US'); // 'November 2026'
day.format({ weekday: 'long' }, 'en-US'); // 'Monday'

`toString()`

d.toString(): string
d.toJSON(): string

Returns the date as an ISO 8601 YYYY-MM-DD string. toJSON() returns the same string for JSON.stringify().

Returns

string

ISO 8601 date string, such as '2026-11-16'.

const due = date('2026-11-16');

due.toString(); // '2026-11-16'
JSON.stringify({ due }); // '{"due":"2026-11-16"}'

`toJSDate()`

d.toJSDate(zone?): Date

Returns a native JavaScript Date at midnight on this date in the given or configured time zone.

`toTemporal()`

d.toTemporal(): Temporal.PlainDate

Returns the underlying Temporal.PlainDate instance.

`valueOf()`

d.valueOf(): never

Throws a RangeError so numeric operators never silently coerce a calendar date to a number.

Edit this pageUpdated Nov 12, 2026

CalendarDate class

Creating a CalendarDate

Properties

Combining and fields

at()

set()

Arithmetic and boundaries

plus()

minus()

startOf()

endOf()

next()

previous()

Comparing dates

equals()

isBefore()

isAfter()

isSame()

Calendar predicates

Measuring spans

until()

since()

Formatting and conversion

format()

toString()

toJSDate()

toTemporal()

valueOf()

`CalendarDate` class

`at()`

`set()`

`plus()`

`minus()`

`startOf()`

`endOf()`

`next()`

`previous()`

`equals()`

`isBefore()`

`isAfter()`

`isSame()`

`until()`

`since()`

`format()`

`toString()`

`toJSDate()`

`toTemporal()`

`valueOf()`