Dates & times¶
Format dates, times, durations, and calendar metadata using the locale's own calendar and conventions. The width argument controls how much detail appears in the formatted result:
width |
date() in en-GB |
time() in en-GB |
|---|---|---|
none |
(omits this part) | (omits this part) |
short |
02/02/2020 |
09:25 |
medium |
2 Feb 2020 |
09:25:30 |
long |
2 February 2020 |
09:25:30 GMT |
full |
Sunday, 2 February 2020 |
09:25:30 Greenwich Mean Time |
What's a moment?
A moment is a single point on the timeline. Accepted values are
a Date or Unix milliseconds. See Terminology for the distinction
between moments, durations, and ranges.
Date, time, and both¶
moment() formats a date and a time; date() and time() are thin shortcuts
that set the other width to none.
| Method | Parameters | Defaults |
|---|---|---|
moment(value, dateWidth, timeWidth, calendar?) |
both widths + optional calendar | short, short |
date(value, width) |
date width only | short |
time(value, width) |
time width only | short |
const c = new Cosmo("en-GB", { timeZone: "Europe/London" });
const d = new Date("2020-02-02T09:25:30");
c.date(d, "full"); // "Sunday, 2 February 2020"
c.time(d, "short"); // "09:25"
c.moment(d); // date + time, both 'short'
c.moment(d, "long", "none"); // long date, no time
Calendars¶
The calendar follows the locale automatically — fa_IR renders in the Persian
calendar, th can render Buddhist. Two ways to control it:
- set the
calendarmodifier on the instance ({ calendar: "buddhist" }), or - pass a calendar to
moment()for a one-off.
Pass the special value "gregorian" to force the proleptic Gregorian calendar even
when the locale would imply another:
const fa = new Cosmo("fa-IR");
fa.date(new Date("2020-02-02"), "long"); // Persian calendar
fa.moment(new Date("2020-02-02"), "long", "none", "gregorian"); // forced Gregorian
new Cosmo("en", { calendar: "buddhist" }).date(d, "full");
Duration¶
duration() formats an undirected span — magnitude only, no past/future. For
"3 days ago" you want the directed relative time.
It takes either a scalar number of seconds or a unit breakdown, and a
withWords flag that switches between the digital-clock form and the spelled form:
| Input | withWords |
Result |
|---|---|---|
1222060 (seconds) |
false (default) |
"339:27:40" |
1222060 (seconds) |
true |
"339 hours, 27 minutes, 40 seconds" |
{hours: 3, minutes: 5} |
false |
"3 hr, 5 min" |
{hours: 3, minutes: 5} |
true |
"3 hours, 5 minutes" |
new Cosmo("en").duration(1222060); // "339:27:40"
new Cosmo("en").duration(1222060, true); // spelled-out form
new Cosmo("en").duration({ hours: 3, minutes: 5 }); // unit breakdown
The breakdown keys are years, months, weeks, days, hours, minutes,
seconds, milliseconds. Scalar input is always interpreted as
seconds and split into the hours/minutes/seconds clock form.
Runtime requirement
duration() requires Intl.DurationFormat (Node.js 23.0.0+). See
Getting started for browser requirements.
Time-zone name¶
timeZoneName() returns the localised display name of the instance's timeZone
modifier (falling back to the runtime zone). The style chooses the form:
style |
Example (Australia/Sydney, en) |
|---|---|
long (default) |
Australian Eastern Standard Time |
short |
AEST |
shortOffset |
GMT+10 |
longOffset |
GMT+10:00 |
shortGeneric |
Sydney Time |
longGeneric |
Australian Eastern Time |
const c = new Cosmo("en", { timeZone: "Australia/Sydney" });
c.timeZoneName(); // "Australian Eastern Standard Time"
c.timeZoneName("shortOffset"); // "GMT+10"
The generic styles drop the standard/daylight distinction (good for labelling a zone in settings); the offset styles reflect the offset at the current instant, so they swing with daylight saving.
Calendar names¶
Localised month and weekday names, aligned to the active calendar. Both take a
width: full (default), long, medium, short.
Weekdays are Sunday-first (ICU symbol order) regardless of the locale's first
day — use weekInfo() to find where the week actually starts.
new Cosmo("en").monthNames()[0]; // "January"
new Cosmo("en").weekdayNames("medium"); // ["Sun", "Mon", … "Sat"]
new Cosmo("fa-IR").monthNames()[0]; // "فروردین"
Week information¶
weekInfo() returns the locale's week conventions — the first day of the week and
the minimal-days-in-first-week rule, plus the weekend days:
new Cosmo("en-US").weekInfo(); // { firstDay: 7, weekend: [6, 7], minimalDays: 1 }
new Cosmo("fr-FR").weekInfo(); // { firstDay: 1, weekend: [6, 7], ... }
Days are 1 = Monday … 7 = Sunday.
Date ranges¶
Use these methods to format date intervals:
dateRange(start, end, dateWidth?, timeWidth?)formats an interval, collapsing the shared parts ("Feb 2 – 5, 2020").
// formatMoment() is unavailable — Intl has no raw-pattern API.
new Cosmo("en").dateRange(start, end); // "Feb 2 – 5, 2020"
new Cosmo("en").dateRange(start, end, "long"); // "February 2 – 5, 2020"
Practical examples¶
A "last seen" label that degrades gracefully. Use relative time for recent moments and an absolute date for older ones: