Class Cosmo

constructor

• new Cosmo(locale?: string | null, modifiers?: Modifiers): Cosmo

  Parameters

  • Optionallocale: string | null

    BCP-47 (or underscore-separated en_AU) locale identifier. Unicode extensions such as -u-nu-latn-ca-buddhist are honoured. Defaults to the runtime locale.

  • modifiers: Modifiers = {}

    Optional calendar, currency, and timeZone overrides.

  Returns Cosmo

Readonlylocale

Readonlymodifiers

Readonlysubtags

addLikelySubtags

• addLikelySubtags(): Cosmo

  Returns a new Cosmo with likely subtags added (e.g. "en" → "en-Latn-US"). Uses Intl.Locale#maximize.

  Returns Cosmo

calendar

• calendar(code: string): string

  Localised calendar name (e.g. "buddhist" → "Buddhist Calendar"). Returns "" for an empty argument.

  Parameters

  • code: string

  Returns string

compact

• compact(value: number, width?: FormatWidth): string

  Compact number notation (e.g. 1200 → "1.2K", or "1.2 thousand"). JS-only.

  Parameters

  • value: number
  • width: FormatWidth = "short"

    full/long → long words, otherwise short.

  Returns string

compare

• compare(a: string, b: string, options?: CollationOptions): number

  Locale-aware comparison of two strings, suitable for Array#sort. Returns a negative number, 0, or a positive number.

  Parameters

  • a: string
  • b: string
  • options: CollationOptions = {}

  Returns number

contains

• contains(
      haystack: string,
      needle: string,
      sensitivity?: "base" | "accent" | "case" | "variant",
      options?: CollationOptions,
  ): boolean

  Locale-aware substring test that honours the locale's collation, so accents/case can be ignored.

  Parameters

  • haystack: string
  • needle: string
  • sensitivity: "base" | "accent" | "case" | "variant" = "base"

    base (ignore case & accents, default), accent, case, or variant (exact). See Intl.Collator.

  • options: CollationOptions = {}

  Returns boolean

country

• country(code?: string | null): string

  Localised country/region name (e.g. "AU" → "Australia"). Accepts a region code or a locale containing one. Returns "" when empty.

  Parameters

  • code: string | null = ...

  Returns string

currency

• currency(code?: string | null, symbol?: boolean, strict?: boolean): string

  Localised currency name (default) or symbol.

  Parameters

  • code: string | null = ...

    ISO 4217 code; defaults to the currency modifier.

  • symbol: boolean = false

    When true, returns the standard (disambiguated) symbol — e.g. "A$" for AUD in en-US, not the ambiguous narrow "$".

  • strict: boolean = false

    Throw on an unknown currency instead of echoing the code back.

  Returns string

date

• date(moment: Moment, width?: FormatWidth): string

  Formats just the date part of a moment.

  Parameters

  • moment: Moment
  • width: FormatWidth = "short"

  Returns string

dateRange

• dateRange(
      start: Moment,
      end: Moment,
      dateWidth?: FormatWidth,
      timeWidth?: FormatWidth,
  ): string

  Formats a moment range (e.g. "2–5 Feb 2020"). Uses DateTimeFormat#formatRange. JS-only.

  Parameters

  • start: Moment
  • end: Moment
  • dateWidth: FormatWidth = "medium"

    Defaults to medium — short numeric dates read poorly as a range, so this differs from Cosmo.date (which defaults to short).

  • timeWidth: FormatWidth = "none"

  Returns string

direction

• direction(language?: string | null): string

  Text direction of the locale (or a given language): "rtl" or "ltr".

  Parameters

  • language: string | null = ...

  Returns string

displayName

• displayName(type: DisplayType, code: string): string

  Generic localised display name — a single entry point over the dedicated lookups. Mirrors Intl.DisplayNames.

  Parameters

  • type: DisplayType

    language, region, script, calendar, or currency.

  • code: string

    The code to translate (e.g. "en", "AU", "Hans", "buddhist", "EUR").

  Returns string

duration

• duration(value: number | DurationParts, withWords?: boolean): string

  Formats an undirected duration (magnitude only) given in seconds. For the directed form (with a past/future orientation, e.g. "3 days ago") see Cosmo.relativeDuration.

  Parameters

  • value: number | DurationParts
  • withWords: boolean = false

    When true, spells out the units ("339 hours, …"), otherwise uses the digital clock form ("339:27:40").

    Requires Intl.DurationFormat (Node 22+). Both forms are produced entirely by ICU.

  Returns string

ellipsize

• ellipsize(text: string, max: number, ellipsis?: string): string

  Truncates text to at most max graphemes, breaking on a word boundary and appending ellipsis. Grapheme- and word-aware via Intl.Segmenter, so it never splits a combining sequence. Returns the original text if it already fits.

  Parameters

  • text: string
  • max: number
  • ellipsis: string = "…"

  Returns string

flag

• flag(country?: string | null): string

  Country flag emoji for a region (e.g. "AU" → "🇦🇺"). Defaults to the locale's region. Uses the Unicode regional-indicator transform, so no data table is involved.

  Parameters

  • country: string | null = ...

  Returns string

join

• join(items: readonly string[], type?: ListType, width?: FormatWidth): string

  Joins a list using the locale's conventions (e.g. "A, B, and C"). Mirrors Intl.ListFormat.

  Parameters

  • items: readonly string[]
  • type: ListType = "conjunction"

    conjunction (and, default), disjunction (or), or unit.

  • width: FormatWidth = "full"

    maps to long/short/narrow list styles.

  Returns string

language

• language(code?: string | null): string

  Localised language name (e.g. "en" → "English", in fa → "انگلیسی"). Accepts a bare language code or a full locale (the language subtag is used). Returns "" for an empty/nullish argument.

  Parameters

  • code: string | null = ...

  Returns string

lower

• lower(text: string): string

  Locale-aware lower-casing.

  Parameters

  • text: string

  Returns string

message

• message(pattern: string, args?: MessageArgs): string

  Formats an ICU MessageFormat pattern (subset: args, number, plural, select).

  Parameters

  • pattern: string
  • args: MessageArgs = {}

  Returns string

moment

• moment(
      moment: Moment,
      dateWidth?: FormatWidth,
      timeWidth?: FormatWidth,
      calendar?: string | null,
  ): string

  Formats a moment (date and/or time) using the locale's conventions.

  Parameters

  • moment: Moment

    A Date or Unix-millisecond timestamp.

  • dateWidth: FormatWidth = "short"

    none/short/medium/long/full (default short).

  • timeWidth: FormatWidth = "short"

    none/short/medium/long/full (default short).

  • Optionalcalendar: string | null

    Pass "gregorian" to force Gregorian; otherwise the locale/modifier calendar is used.

  Returns string

money

• money(
      value: number,
      code?: string | null,
      options?: { precision?: number; strict?: boolean } & NumberOptions,
  ): string

  Formats a monetary value.

  No currency is inferred from the region: the Intl API exposes no region→currency mapping, and this library bundles no data. Provide a currency code or set the currency modifier.

  Parameters

  • value: number
  • code: string | null = ...
  • options: { precision?: number; strict?: boolean } & NumberOptions = {}

  Returns string

  The formatted amount, or "" when no currency is available (unless strict, which throws).

moneyRange

• moneyRange(start: number, end: number, code?: string | null): string

  Formats a monetary range (e.g. "$3.00 – $5.00"). JS-only.

  Parameters

  • start: number
  • end: number
  • code: string | null = ...

  Returns string

  "" when no currency is available (or throws if none and required).

monthNames

• monthNames(width?: FormatWidth): string[]

  Localised month names (January … December), following the active calendar. Mirrors IntlDateFormatter month symbols.

  Parameters

  • width: FormatWidth = "full"

  Returns string[]

number

• number(value: number, options?: NumberOptions): string

  Formats a number using the locale's default decimal format.

  Parameters

  • value: number
  • options: NumberOptions = {}

    Optional rounding/grouping controls (NumberOptions).

  Returns string

numberRange

• numberRange(start: number, end: number): string

  Formats a numeric range (e.g. "3–5"). Uses NumberFormat#formatRange. JS-only.

  Parameters

  • start: number
  • end: number

  Returns string

percentage

• percentage(value: number, precision?: number, options?: NumberOptions): string

  Formats a fraction as a localised percentage (e.g. 0.2 → "20%").

  Parameters

  • value: number
  • precision: number = 3

    Maximum fraction digits (default 3).

  • options: NumberOptions = {}

    Optional rounding/grouping controls (NumberOptions); an explicit maximumFractionDigits here overrides precision.

  Returns string

pluralCategory

• pluralCategory(value: number, ordinal?: boolean): PluralCategory

  The LDML plural category a number falls into for this locale (e.g. 1 → "one", 2 → "other" in English). Mirrors the category selection inside ICU MessageFormat.

  Parameters

  • value: number
  • ordinal: boolean = false

    Use ordinal rules (1st/2nd/3rd …) instead of cardinal.

  Returns PluralCategory

relativeDuration

• relativeDuration(
      amount: number,
      unit: RelativeTimeFormatUnit,
      numeric?: "auto" | "always",
  ): string

  Renders a directed duration — a signed amount carrying a past/future orientation — in the locale's words (e.g. (-3, "day") → "3 days ago", (2, "hour") → "in 2 hours"). The directed counterpart of Cosmo.duration, which is undirected (magnitude only). Wraps Intl.RelativeTimeFormat.

  Parameters

  • amount: number

    Signed amount: negative = past ("… ago"), positive = future ("in …").

  • unit: RelativeTimeFormatUnit

    second, minute, hour, day, week, month, quarter, year.

  • numeric: "auto" | "always" = "always"

    always (default, "1 day ago") or auto (allows "yesterday").

  Returns string

relativeDurationBetween

• relativeDurationBetween(
      target: Moment,
      reference?: Moment,
      numeric?: "auto" | "always",
  ): string

  Renders the directed duration between two moments as relative text, auto-selecting the largest sensible unit (e.g. "in 5 days", "3 days ago"). Computes target − reference, then formats via Cosmo.relativeDuration. JS-only.

  Parameters

  • target: Moment

    The moment being described.

  • reference: Moment = ...

    The moment target is measured against. Defaults to now. When target is after reference the result is future ("in …"); when before, it is past ("… ago").

  • numeric: "auto" | "always" = "auto"

    auto (default, allows "yesterday") or always.

  Returns string

removeLikelySubtags

• removeLikelySubtags(): Cosmo

  Returns a new Cosmo with likely subtags removed (e.g. "en-Latn-US" → "en"). Uses Intl.Locale#minimize.

  Returns Cosmo

scientific

• scientific(value: number): string

  Scientific notation (e.g. 12345 → "1.2345E4"). Mirrors NumberFormatter::SCIENTIFIC.

  Parameters

  • value: number

  Returns string

script

• script(code?: string | null): string

  Localised script name (e.g. "Latn" → "Latin"). Defaults to the locale's script subtag. Returns "" when there is no script.

  Parameters

  • code: string | null = ...

  Returns string

sort

• sort<T>(
      items: readonly T[],
      key?: (item: T) => string,
      options?: CollationOptions,
  ): T[]

  Returns a new array sorted by the locale's collation rules.

  Type Parameters

  • T

  Parameters

  • items: readonly T[]
  • Optionalkey: (item: T) => string

    Optional accessor returning the string to sort each item by.

  • options: CollationOptions = {}

    Optional collation tailoring (CollationOptions).

  Returns T[]

splitGraphemes

• splitGraphemes(text: string): string[]

  Splits text into grapheme clusters (user-perceived characters), so combining marks and emoji ZWJ sequences stay intact. Mirrors Intl.Segmenter granularity:"grapheme".

  Parameters

  • text: string

  Returns string[]

splitSentences

• splitSentences(text: string): string[]

  Splits text into sentences using the locale's sentence-boundary rules.

  Parameters

  • text: string

  Returns string[]

splitWords

• splitWords(text: string): string[]

  Splits text into words using the locale's word-boundary rules, keeping only word-like segments (drops whitespace and punctuation). Mirrors ICU's word BreakIterator.

  Parameters

  • text: string

  Returns string[]

supportedValues

• supportedValues(key: SupportedKey): string[]

  The values the runtime's ICU supports for a given key (e.g. all IANA time zones, calendars, currencies). Mirrors Intl.supportedValuesOf.

  Parameters

  • key: SupportedKey

    calendar, collation, currency, numberingSystem, timeZone, or unit.

  Returns string[]

symbol

• symbol(name: string): string

  Returns a single localised number symbol that the Intl API exposes via formatToParts (decimal/group separators, percent, sign symbols, nan, infinity). Symbols ICU keeps internal (permille, pad escape, …) are not available and throw.

  Parameters

  • name: string

    One of: decimal, group, percent, minusSign, plusSign, nan, infinity, currency (case/_-insensitive; _separator/_symbol suffixes are ignored).

  Returns string

time

• time(moment: Moment, width?: FormatWidth): string

  Formats just the time (clock) part of a moment.

  Parameters

  • moment: Moment
  • width: FormatWidth = "short"

  Returns string

timeZoneName

• timeZoneName(style?: TimeZoneNameStyle): string

  Localised display name of a time zone (e.g. "Australian Eastern Standard Time"). Defaults to the timeZone modifier, falling back to the runtime zone.

  Parameters

  • style: TimeZoneNameStyle = "long"

    long (default), short, shortOffset, longOffset, shortGeneric, or longGeneric.

  Returns string

unit

• unit(category: string, unit: string, value: number, width?: FormatWidth): string

  Formats a measurement with a localised unit (e.g. 2.19 gigabytes).

  Parameters

  • category: string

    Informational unit category (e.g. "digital"); accepted for descriptive grouping but not required by Intl.

  • unit: string

    The unit identifier, e.g. "gigabyte", "celsius", "gram". Must be one of the units sanctioned by ECMA-402.

  • value: number

    Numeric value.

  • width: FormatWidth = "full"

    full/long → long, medium → short, short → narrow.

  Returns string

  Throws

  CosmoError if the unit is not supported by Intl.

  See

  https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers

upper

• upper(text: string): string

  Locale-aware upper-casing (e.g. Turkish dotted/dotless I).

  Parameters

  • text: string

  Returns string

weekdayNames

• weekdayNames(width?: FormatWidth): string[]

  Localised weekday names, Sunday first (matching ICU symbol order). Mirrors IntlDateFormatter weekday symbols.

  Parameters

  • width: FormatWidth = "full"

  Returns string[]

weekInfo

• weekInfo(): WeekInfo

  Week conventions for the locale: first day of the week, weekend days, and the minimal days in the first week. Mirrors IntlCalendar accessors.

  Returns WeekInfo

  Throws

  CosmoError if the runtime lacks Intl.Locale#getWeekInfo.

StaticfromAcceptLanguage

• fromAcceptLanguage(header: string, modifiers?: Modifiers): Cosmo

  Builds a Cosmo from an HTTP Accept-Language header, picking the highest-quality tag.

  Parameters

  • header: string
  • modifiers: Modifiers = {}

  Returns Cosmo

StaticfromSubtags

• fromSubtags(subtags: Partial<Subtags>, modifiers?: Modifiers): Cosmo

  Builds a Cosmo from locale subtags instead of a string.

  Parameters

  • subtags: Partial<Subtags>
  • modifiers: Modifiers = {}

  Returns Cosmo

  Example

  Cosmo.fromSubtags({ language: "en", region: "AU" })
  Copy