Skip to content

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 calendar modifier 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:

function lastSeen(c, when) {
  const ageDays = (Date.now() - when.getTime()) / 86_400_000;
  return ageDays < 7
    ? c.relativeDurationBetween(when)        // "3 days ago"
    : c.date(when, "medium");                // "2 Feb 2020"
}