Date Utilities

Timezone-aware date helpers, locale configuration, calendar grids, and arithmetic.

import {
  date, setLocale, setTimezoneOffset, getLocale,
  getMonths, getCalendar, getAllTimezones,
} from 'mates';

const now = date();                         // now
const birthday = date('1990-06-15');        // parse ISO / common strings
const fromParts = date({ year: 2025, month: 7, day: 18 });

now.format('MMM D, YYYY');                  // "Jul 18, 2025"
now.formatLongAgo();                        // "just now" / "2 hours ago"…
now.values;                                 // { year, month, dayName, iso, … }
birthday.add(1, 'days');                    // mutates in place; returns itself
birthday.subtract(1, 'months');
birthday.isBefore(now);                     // boolean
birthday.isToday();                         // boolean
birthday.getAge();                          // whole years
birthday.getDifference(now, 'years');       // signed integer in that unit

setLocale('fr');
setTimezoneOffset(330);                     // minutes east of UTC
getLocale();                                // "fr"
getMonths();                                // [{ number, name, shortName }, …]
getCalendar(2025, 7);                       // MatesDate[][] weeks (Sun start)
getAllTimezones();                          // IANA list with offsets

Overview

date(input?) returns a MatesDate — a branded timestamp with methods for formatting, relative time, arithmetic, age, and predicates. No external date library required.

Configure locale and timezone with setLocale, setTimezone, and setTimezoneOffset. Calendar helpers getMonths / getCalendar build locale-aware month labels and week grids.

Factory vs calendar helpers

API	Returns	Notes
`date(input?)`	MatesDate	Format, arithmetic, predicates
`getCalendar(y, m)`	MatesDate[][]	Sunday-start week rows
`getMonths()`	MonthInfo[]	Localised month names

Live date() demo

Pick any date to see formatting, relative time, and arithmetic update in real time.

import { html, atom, renderApp, date } from 'mates';

const App = () => {

const selected = atom(date().format('YYYY-MM-DD'));

return () => {

const d = date(selected() + 'T12:00:00');

const yesterday = date(selected() + 'T12:00:00').subtract(1, 'days');

const tomorrow = date(selected() + 'T12:00:00').add(1, 'days');

const nextWeek = date(selected() + 'T12:00:00').add(7, 'days');

return html`

Pick a date:

<input type="date"

.value=${selected()}

@change=${e => selected.set(e.target.value)}

</label>

<span class="overline">Formatted</span>

<span class="card-title">${d.format('MMM D, YYYY')}</span>

</div>

<span class="overline">Relative</span>

<span class="card-title">${d.formatLongAgo()}</span>

</div>

<span class="overline">Is today?</span>

<span class="card-title">${d.isToday() ? '✓ Yes' : '✗ No'}</span>

</div>

getCalendar month grid

Week rows of MatesDate for the selected month — today highlighted.

import { html, atom, renderApp, date, getMonths, getCalendar } from 'mates';

const App = () => {

const month = atom(date().values.month);

const year = atom(date().values.year);

return () => {

const months = getMonths();

const weeks = getCalendar(year(), month());

const label = months[month() - 1]?.name ?? '';

return html`

<button @click=${() => month.set(m => m === 1 ? 12 : m - 1)}>‹</button>

<span class="muted">${label} ${year()}</span>

<button @click=${() => month.set(m => m === 12 ? 1 : m + 1)}>›</button>

</div>

${weeks.map(week => html`

${week.map(d => html`

${d.values.date}

</span>

`)}

</div>

`)}

</div>

};

renderApp(App, document.getElementById('app'));

API — date()

import { date, setLocale, setTimezone, setTimezoneOffset, getLocale, getTimezoneOffset, getAllTimezones, getMonths, getCalendar } from 'mates';

Prop / Option	Type	Default	Description
`date(input?)`	`MatesDate`	—	Build a MatesDate from now, a timestamp, ISO/string, Date, another MatesDate, or `{ year, month, day, … }` parts.
`.format(fmt)`	`string`	—	Format with tokens such as YYYY, YY, MMMM, MMM, MM, D, DD, HH, mm, ss.
`.formatLongAgo(opts?)`	`string`	—	Relative time via Intl — e.g. "2 hours ago", "yesterday". Options: `now`, `numeric`, `style`.
`.add(amount, unit) / .subtract(amount, unit)`	`MatesDate`	—	Mutates this instance by amount of unit (`days`, `months`, `years`, `hours`, …) and returns itself.
`.isBefore / .isAfter / .isFuture / .isPresent`	`boolean`	—	Ordering / relative predicates vs another input or now.
`.isToday / .isYesterday / .isTomorrow`	`boolean`	—	Calendar-day predicates in the configured timezone offset.
`.getDifference(other, unit)`	`number`	—	Signed whole-unit difference between this and other.
`.getAge(at?)`	`number`	—	Whole years of age from this date to `at` (default now).
`.values`	`DateValues`	—	Structured parts: year, month, monthName, dayName, hours, iso, timestamp, …
`setLocale / getLocale`	`config`	—	Global Intl locale for formatting and month names.
`setTimezone / setTimezoneOffset / getTimezoneOffset`	`config`	—	IANA timezone entry or fixed offset (minutes east of UTC) for calendar math.
`getAllTimezones()`	`TimezoneEntry[]`	—	IANA zones with name, long/short labels, and offset.
`getMonths(locale?)`	`MonthInfo[]`	—	Twelve months with number, name, shortName.
`getCalendar(year, month)`	`MatesDate[][]`	—	Weeks of MatesDate (Sunday week start) for a 1-based month.