Date Utilities

date() formatting, relative time, arithmetic, and calendar grids.

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.

Month names, weekday names, and relative phrases follow the locale and timezone settings. Those setters are shared module state, not atoms.

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.