@miloun/cosmo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Aiden Adrian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# Cosmo
+
+Ergonomic application localisation for JavaScript / Node, built entirely on the standard [`Intl`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl) API.
+
+Cosmo is a thin, ergonomic layer over the JavaScript engine's own
+[ICU](https://icu.unicode.org/), reached through the standard
+[`Intl`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl)
+API. Give it a locale (and optionally a time zone) and it formats numbers, money,
+dates, units, lists and messages exactly the way your users expect. There are **zero
+runtime dependencies and zero bundled locale data** — every result comes straight
+from ICU and [CLDR](https://cldr.unicode.org/), covering all languages, scripts,
+calendars and time zones.
+
+Cosmo is implemented consistently across four languages — the same concepts, method
+names and behaviour, each built directly on its platform's ICU:
+**JavaScript** ·
+[Python](https://github.com/cosmo-intl/cosmo-python) ([docs](https://cosmo.miloun.com/?lang=python)) ·
+[Java](https://github.com/cosmo-intl/cosmo-java) ([docs](https://cosmo.miloun.com/?lang=java)) ·
+[PHP](https://github.com/salarmehr/cosmopolitan) ([docs](https://cosmo.miloun.com/?lang=php)).
+
+📖 **Full documentation, API reference and live playground:** https://cosmo.miloun.com/?lang=js
+
+## Requirements
+
+- Node 20+ (Node 22+ for `duration()`), or any modern browser
+- ESM-only; ships TypeScript type definitions
+
+## Install
+
+```sh
+npm install @miloun/cosmo
+```
+
+## Quick start
+
+```ts
+import { Cosmo, cosmo } from "@miloun/cosmo";
+
+new Cosmo("es_ES").money(11000.4, "EUR");                    // "11.000,40 €"
+new Cosmo("tr").unit("temperature", "celsius", 26, "short"); // "26 °C"
+new Cosmo("en").percentage(0.2);                             // "20%"
+new Cosmo("fa").language("en");                             // "انگلیسی"
+
+// or the helper
+cosmo("en_AU").country();                                    // "Australia"
+```
+
+Underscore locales (`en_AU`) and [BCP-47](https://www.rfc-editor.org/info/bcp47) [Unicode
+extensions](https://unicode.org/reports/tr35/#u_Extension) (`fa-IR-u-nu-latn-ca-buddhist`)
+are both accepted.
+
+## What you get
+
+- **Locale display names** — languages, regions, scripts, calendars and currencies, plus emoji flags and writing direction.
+- **Numbers & money** — decimals, percentages, currencies, units, compact notation (`1.2M`), scientific, and number/money ranges.
+- **Dates & times** — locale formats in any calendar (Gregorian, Persian, Buddhist…), durations, date ranges, and relative times (`"3 days ago"`).
+- **Text** — locale-aware sort and search, word/sentence/grapheme segmentation, and case mapping.
+- **Lists** — `"A, B, and C"` conjunctions and disjunctions.
+- **Messages** — [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) (`plural`, `selectordinal`, `select`).
+
+See the [full API reference](https://cosmo.miloun.com/api-reference/?lang=js) for every method,
+the [platform notes](https://cosmo.miloun.com/platform-notes/) for what `Intl` does and
+doesn't expose to JavaScript, and [resources](https://cosmo.miloun.com/resources/) for ICU/CLDR references.
+
+## Errors
+
+Recoverable problems throw `CosmoError`, with `InvalidArgumentError` and
+`UnsupportedError` subclasses — an invalid currency in strict mode, an unsupported
+unit, an unsupported symbol name, a malformed message, and the like.
+
+## License
+
+MIT © Aiden Adrian

package/changelog.md

@@ -0,0 +1,31 @@
+Changelog
+=========
+* v0.1.0 — initial (unstable) JavaScript / Node port of [salarmehr/cosmopolitan](https://github.com/salarmehr/cosmopolitan)
+    - Built entirely on the standard `Intl` API (ICU) with **zero runtime dependencies** and **no bundled locale data**
+    - PHP-ported core: `language`, `country`, `script`, `calendar`, `currency` (name + symbol),
+      `direction`, `flag`, `number`, `percentage`, `money`, `symbol`, `unit`,
+      `message` (ICU MessageFormat subset), `duration`, `moment`, `date`, `time`
+    - Collation & search: `compare`, `sort`, `contains` (`Intl.Collator` / `Intl.Segmenter`)
+    - Text segmentation: `splitWords`, `splitSentences`, `splitGraphemes`, `ellipsize` (`Intl.Segmenter`)
+    - Locale-aware case: `upper`, `lower`
+    - Locale metadata: `pluralCategory`, `weekInfo`, `addLikelySubtags`,
+      `removeLikelySubtags`, `monthNames` (calendar-aligned), `weekdayNames`, `timeZoneName`,
+      `displayName` (generic `Intl.DisplayNames` lookup), `supportedValues` (`Intl.supportedValuesOf`)
+    - Directed-duration & range formatting (JS-only): `relativeDuration` (the
+      directed-duration counterpart of the undirected `duration`) +
+      `relativeDurationBetween(target, reference?)`, `join`, `compact`,
+      `scientific`, `numberRange`, `moneyRange`, `dateRange`
+    - `duration()` also accepts a unit breakdown (`{ days, hours, minutes, … }`) for multi-unit output
+    - `number`/`percentage`/`money` accept a `NumberOptions` bag (`roundingMode`, `roundingIncrement`,
+      `min`/`maxFractionDigits`, `useGrouping`); `compare`/`sort`/`contains` accept collation
+      tailoring (`{ numeric, caseFirst }`) — all restricted to settings the PHP and Python ports
+      also expose, so the contract stays identical across ports
+    - Terminology: a point in time is a `Moment`; `duration` is undirected,
+      `relativeDuration` is directed; `time`/`timeWidth`/`timeZone` always mean clock/zone
+    - `Cosmo.fromSubtags()` and `Cosmo.fromAcceptLanguage()` factories, plus the `cosmo()` helper
+    - TypeScript source, ships `.d.ts` types, ESM-only
+    - Intentionally **omitted** because they would require ICU facilities the `Intl`
+      API does not expose (and the library bundles no data of its own):
+      `spellout()` (RBNF), `ordinal()` text such as "1st" (RBNF / suffix data),
+      `quote()` (CLDR delimiters), `get()` (raw ICU resource bundles), and automatic
+      region→currency inference.

package/dist/cosmo.d.ts

@@ -0,0 +1,381 @@
+import { type MessageArgs } from "./message.js";
+/** Width of a formatted date, time, unit, … — mirrors ICU's length styles. */
+export type FormatWidth = "none" | "short" | "medium" | "long" | "full";
+/** Optional locale overrides applied on top of the locale identifier. */
+export interface Modifiers {
+    /** Calendar identifier, e.g. `"gregory"`, `"persian"`, `"buddhist"`. */
+    calendar?: string | null;
+    /** ISO 4217 currency code used as the default for {@link Cosmo.money}. */
+    currency?: string | null;
+    /** IANA time zone, e.g. `"Australia/Sydney"`. */
+    timeZone?: string | null;
+}
+/** Locale subtags parsed from the canonical locale. */
+export interface Subtags {
+    language: string;
+    script: string;
+    region: string;
+}
+/** A moment in time accepted by the date/time methods. Numbers are Unix milliseconds (JS-native). */
+export type Moment = Date | number;
+/** LDML plural category, as returned by `Intl.PluralRules#select`. */
+export type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
+/**
+ * Week metadata, mirroring `Intl.Locale#getWeekInfo()`. Days are 1 = Mon … 7 = Sun.
+ * `minimalDays` is omitted on runtimes (e.g. current V8) that don't expose it.
+ */
+export interface WeekInfo {
+    firstDay: number;
+    weekend: number[];
+    minimalDays?: number;
+}
+/** Time-zone name styles accepted by `Intl.DateTimeFormat`'s `timeZoneName`. */
+export type TimeZoneNameStyle = "short" | "long" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
+/** Kinds of list joins exposed by `Intl.ListFormat`. */
+export type ListType = "conjunction" | "disjunction" | "unit";
+/** Display-name categories accepted by {@link Cosmo.displayName}. */
+export type DisplayType = "language" | "region" | "script" | "calendar" | "currency";
+/** Keys accepted by {@link Cosmo.supportedValues} / `Intl.supportedValuesOf`. */
+export type SupportedKey = "calendar" | "collation" | "currency" | "numberingSystem" | "timeZone" | "unit";
+/**
+ * Number-formatting controls for {@link Cosmo.number}, {@link Cosmo.percentage}
+ * and {@link Cosmo.money}. Field names match `Intl.NumberFormat`'s options.
+ *
+ * Most fields map onto an ICU setting the PHP and Python ports expose too, so the
+ * contract is identical across all three ports. The exceptions are flagged inline
+ * as **JS port only**: these have no equivalent in the legacy ICU `NumberFormatter`
+ * (PHP) / `DecimalFormat` (Python) APIs those ports use, so they take effect in the
+ * JS port and are silently ignored by the others.
+ */
+export interface NumberOptions {
+    /** Minimum integer digits; zero-pads the whole part (`5` → `"005"` at 3). */
+    minimumIntegerDigits?: number;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    /** Minimum significant digits (ICU treats significant- and fraction-digit limits as mutually exclusive). */
+    minimumSignificantDigits?: number;
+    /** Maximum significant digits. */
+    maximumSignificantDigits?: number;
+    /** ICU-portable rounding modes (these have a direct ICU equivalent in every port). */
+    roundingMode?: "ceil" | "floor" | "expand" | "trunc" | "halfExpand" | "halfTrunc" | "halfEven";
+    roundingIncrement?: 1 | 2 | 5 | 10 | 20 | 25 | 50 | 100 | 200 | 250 | 500 | 1000 | 2000 | 2500 | 5000;
+    /** JS accepts the full union; the PHP and Python ports coerce any truthy value to "on". */
+    useGrouping?: "always" | "auto" | "min2" | boolean;
+    /** **JS port only** — ignored by the PHP and Python ports (legacy ICU formatters have no sign-display attribute). */
+    signDisplay?: "auto" | "always" | "exceptZero" | "negative" | "never";
+    /** **JS port only** — ignored by the PHP and Python ports. */
+    trailingZeroDisplay?: "auto" | "stripIfInteger";
+    /** **JS port only** — ignored by the PHP and Python ports. */
+    roundingPriority?: "auto" | "morePrecision" | "lessPrecision";
+    /** **JS port only** — ignored by PHP/Python; for those ports use the dedicated `compact()` / `scientific()` methods instead. */
+    notation?: "standard" | "scientific" | "engineering" | "compact";
+    /** Only meaningful with `notation: "compact"`. **JS port only** — ignored by the PHP and Python ports. */
+    compactDisplay?: "short" | "long";
+}
+/** Collation tailoring for {@link Cosmo.compare}, {@link Cosmo.sort}, {@link Cosmo.contains}. */
+export interface CollationOptions {
+    /** Sort numeric substrings by value (`"item2"` < `"item10"`). */
+    numeric?: boolean;
+    /** Whether upper- or lower-case sorts first. */
+    caseFirst?: "upper" | "lower" | "false";
+}
+/** A breakdown of a duration into units, accepted by {@link Cosmo.duration}. */
+export interface DurationParts {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+export declare class Cosmo {
+    /** Canonical BCP-47 locale identifier, e.g. `"en-AU"`. */
+    readonly locale: string;
+    /** Parsed language / script / region subtags. */
+    readonly subtags: Subtags;
+    /** Resolved modifiers (calendar / currency / timeZone). */
+    readonly modifiers: Required<Modifiers>;
+    private readonly intlLocale;
+    /**
+     * @param locale 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.
+     * @param modifiers Optional `calendar`, `currency`, and `timeZone` overrides.
+     */
+    constructor(locale?: string | null, modifiers?: Modifiers);
+    /**
+     * Builds a Cosmo from locale subtags instead of a string.
+     * @example Cosmo.fromSubtags({ language: "en", region: "AU" })
+     */
+    static fromSubtags(subtags: Partial<Subtags>, modifiers?: Modifiers): Cosmo;
+    /**
+     * Builds a Cosmo from an HTTP `Accept-Language` header, picking the
+     * highest-quality tag.
+     */
+    static fromAcceptLanguage(header: string, modifiers?: Modifiers): Cosmo;
+    private display;
+    /**
+     * 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.
+     */
+    language(code?: string | null): string;
+    /**
+     * Localised country/region name (e.g. `"AU"` → `"Australia"`).
+     * Accepts a region code or a locale containing one. Returns `""` when empty.
+     */
+    country(code?: string | null): string;
+    /**
+     * Localised script name (e.g. `"Latn"` → `"Latin"`). Defaults to the locale's
+     * script subtag. Returns `""` when there is no script.
+     */
+    script(code?: string | null): string;
+    /**
+     * Localised calendar name (e.g. `"buddhist"` → `"Buddhist Calendar"`).
+     * Returns `""` for an empty argument.
+     */
+    calendar(code: string): string;
+    /**
+     * Localised currency name (default) or symbol.
+     * @param code ISO 4217 code; defaults to the `currency` modifier.
+     * @param symbol When `true`, returns the standard (disambiguated) symbol — e.g.
+     *   `"A$"` for AUD in `en-US`, not the ambiguous narrow `"$"`.
+     * @param strict Throw on an unknown currency instead of echoing the code back.
+     */
+    currency(code?: string | null, symbol?: boolean, strict?: boolean): string;
+    /** Text direction of the locale (or a given language): `"rtl"` or `"ltr"`. */
+    direction(language?: 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.
+     */
+    flag(country?: string | null): string;
+    /**
+     * Formats a number using the locale's default decimal format.
+     * @param options Optional rounding/grouping controls ({@link NumberOptions}).
+     */
+    number(value: number, options?: NumberOptions): string;
+    /**
+     * Formats a fraction as a localised percentage (e.g. `0.2` → `"20%"`).
+     * @param precision Maximum fraction digits (default 3).
+     * @param options Optional rounding/grouping controls ({@link NumberOptions});
+     *   an explicit `maximumFractionDigits` here overrides `precision`.
+     */
+    percentage(value: number, precision?: number, options?: 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.
+     *
+     * @returns The formatted amount, or `""` when no currency is available
+     *   (unless `strict`, which throws).
+     */
+    money(value: number, code?: string | null, options?: {
+        precision?: number;
+        strict?: boolean;
+    } & NumberOptions): 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.
+     *
+     * @param name One of: `decimal`, `group`, `percent`, `minusSign`, `plusSign`,
+     *   `nan`, `infinity`, `currency` (case/`_`-insensitive; `_separator`/`_symbol`
+     *   suffixes are ignored).
+     */
+    symbol(name: string): string;
+    /**
+     * Formats a measurement with a localised unit (e.g. `2.19` gigabytes).
+     * @param category Informational unit category (e.g. `"digital"`); accepted for
+     *   descriptive grouping but not required by `Intl`.
+     * @param unit The unit identifier, e.g. `"gigabyte"`, `"celsius"`, `"gram"`.
+     *   Must be one of the units sanctioned by ECMA-402.
+     * @param value Numeric value.
+     * @param width `full`/`long` → long, `medium` → short, `short` → narrow.
+     * @throws CosmoError if the unit is not supported by `Intl`.
+     * @see https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers
+     */
+    unit(category: string, unit: string, value: number, width?: FormatWidth): string;
+    /** Formats an ICU MessageFormat pattern (subset: args, number, plural, select). */
+    message(pattern: string, args?: MessageArgs): 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 {@link Cosmo.relativeDuration}.
+     * @param withWords 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.
+     */
+    duration(value: number | DurationParts, withWords?: boolean): string;
+    private dateTimeFormat;
+    /**
+     * Formats a moment (date and/or time) using the locale's conventions.
+     * @param moment A `Date` or Unix-millisecond timestamp.
+     * @param dateWidth `none`/`short`/`medium`/`long`/`full` (default `short`).
+     * @param timeWidth `none`/`short`/`medium`/`long`/`full` (default `short`).
+     * @param calendar Pass `"gregorian"` to force Gregorian; otherwise the
+     *   locale/modifier calendar is used.
+     */
+    moment(moment: Moment, dateWidth?: FormatWidth, timeWidth?: FormatWidth, calendar?: string | null): string;
+    /** Formats just the date part of a moment. */
+    date(moment: Moment, width?: FormatWidth): string;
+    /** Formats just the time (clock) part of a moment. */
+    time(moment: Moment, width?: FormatWidth): string;
+    /**
+     * Locale-aware comparison of two strings, suitable for `Array#sort`.
+     * Returns a negative number, `0`, or a positive number.
+     */
+    compare(a: string, b: string, options?: CollationOptions): number;
+    /**
+     * Returns a new array sorted by the locale's collation rules.
+     * @param key Optional accessor returning the string to sort each item by.
+     * @param options Optional collation tailoring ({@link CollationOptions}).
+     */
+    sort<T>(items: readonly T[], key?: (item: T) => string, options?: CollationOptions): T[];
+    /**
+     * Locale-aware substring test that honours the locale's collation, so
+     * accents/case can be ignored.
+     * @param sensitivity `base` (ignore case & accents, default), `accent`,
+     *   `case`, or `variant` (exact). See `Intl.Collator`.
+     */
+    contains(haystack: string, needle: string, sensitivity?: "base" | "accent" | "case" | "variant", options?: CollationOptions): boolean;
+    /**
+     * 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`.
+     */
+    splitWords(text: string): string[];
+    /** Splits text into sentences using the locale's sentence-boundary rules. */
+    splitSentences(text: 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.
+     */
+    ellipsize(text: string, max: number, ellipsis?: string): string;
+    /**
+     * Splits text into grapheme clusters (user-perceived characters), so combining
+     * marks and emoji ZWJ sequences stay intact. Mirrors `Intl.Segmenter`
+     * `granularity:"grapheme"`.
+     */
+    splitGraphemes(text: string): string[];
+    /**
+     * 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`.
+     * @param ordinal Use ordinal rules (1st/2nd/3rd …) instead of cardinal.
+     */
+    pluralCategory(value: number, ordinal?: boolean): PluralCategory;
+    /**
+     * Week conventions for the locale: first day of the week, weekend days, and
+     * the minimal days in the first week. Mirrors `IntlCalendar` accessors.
+     * @throws CosmoError if the runtime lacks `Intl.Locale#getWeekInfo`.
+     */
+    weekInfo(): WeekInfo;
+    /**
+     * Returns a new Cosmo with likely subtags added (e.g. `"en"` → `"en-Latn-US"`).
+     * Uses `Intl.Locale#maximize`.
+     */
+    addLikelySubtags(): Cosmo;
+    /**
+     * Returns a new Cosmo with likely subtags removed (e.g. `"en-Latn-US"` → `"en"`).
+     * Uses `Intl.Locale#minimize`.
+     */
+    removeLikelySubtags(): Cosmo;
+    /**
+     * Localised month names (January … December), following the active calendar.
+     * Mirrors `IntlDateFormatter` month symbols.
+     */
+    monthNames(width?: FormatWidth): string[];
+    /**
+     * Localised weekday names, **Sunday first** (matching ICU symbol order).
+     * Mirrors `IntlDateFormatter` weekday symbols.
+     */
+    weekdayNames(width?: FormatWidth): 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.
+     * @param style `long` (default), `short`, `shortOffset`, `longOffset`,
+     *   `shortGeneric`, or `longGeneric`.
+     */
+    timeZoneName(style?: TimeZoneNameStyle): string;
+    /**
+     * Generic localised display name — a single entry point over the dedicated
+     * lookups. Mirrors `Intl.DisplayNames`.
+     * @param type `language`, `region`, `script`, `calendar`, or `currency`.
+     * @param code The code to translate (e.g. `"en"`, `"AU"`, `"Hans"`, `"buddhist"`, `"EUR"`).
+     */
+    displayName(type: DisplayType, code: string): string;
+    /**
+     * The values the runtime's ICU supports for a given key (e.g. all IANA time
+     * zones, calendars, currencies). Mirrors `Intl.supportedValuesOf`.
+     * @param key `calendar`, `collation`, `currency`, `numberingSystem`, `timeZone`, or `unit`.
+     */
+    supportedValues(key: SupportedKey): string[];
+    /** Locale-aware upper-casing (e.g. Turkish dotted/dotless I). */
+    upper(text: string): string;
+    /** Locale-aware lower-casing. */
+    lower(text: string): 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
+     * {@link Cosmo.duration}, which is undirected (magnitude only). Wraps
+     * `Intl.RelativeTimeFormat`.
+     * @param amount Signed amount: negative = past (`"… ago"`), positive = future
+     *   (`"in …"`).
+     * @param unit `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`.
+     * @param numeric `always` (default, "1 day ago") or `auto` (allows "yesterday").
+     */
+    relativeDuration(amount: number, unit: Intl.RelativeTimeFormatUnit, numeric?: "always" | "auto"): 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
+     * {@link Cosmo.relativeDuration}. JS-only.
+     * @param target The moment being described.
+     * @param reference 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"`).
+     * @param numeric `auto` (default, allows "yesterday") or `always`.
+     */
+    relativeDurationBetween(target: Moment, reference?: Moment, numeric?: "always" | "auto"): string;
+    /**
+     * Joins a list using the locale's conventions (e.g. `"A, B, and C"`).
+     * Mirrors `Intl.ListFormat`.
+     * @param type `conjunction` (and, default), `disjunction` (or), or `unit`.
+     * @param width maps to long/short/narrow list styles.
+     */
+    join(items: readonly string[], type?: ListType, width?: FormatWidth): string;
+    /**
+     * Compact number notation (e.g. `1200` → `"1.2K"`, or `"1.2 thousand"`).
+     * JS-only.
+     * @param width `full`/`long` → long words, otherwise short.
+     */
+    compact(value: number, width?: FormatWidth): string;
+    /** Scientific notation (e.g. `12345` → `"1.2345E4"`). Mirrors `NumberFormatter::SCIENTIFIC`. */
+    scientific(value: number): string;
+    /** Formats a numeric range (e.g. `"3–5"`). Uses `NumberFormat#formatRange`. JS-only. */
+    numberRange(start: number, end: number): string;
+    /**
+     * Formats a monetary range (e.g. `"$3.00 – $5.00"`). JS-only.
+     * @returns `""` when no currency is available (or throws if none and required).
+     */
+    moneyRange(start: number, end: number, code?: string | null): string;
+    /**
+     * Formats a moment range (e.g. `"2–5 Feb 2020"`). Uses `DateTimeFormat#formatRange`. JS-only.
+     * @param dateWidth Defaults to `medium` — `short` numeric dates read poorly as
+     *   a range, so this differs from {@link Cosmo.date} (which defaults to `short`).
+     */
+    dateRange(start: Moment, end: Moment, dateWidth?: FormatWidth, timeWidth?: FormatWidth): string;
+}
+//# sourceMappingURL=cosmo.d.ts.map

package/dist/cosmo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosmo.d.ts","sourceRoot":"","sources":["../src/cosmo.ts"],"names":[],"mappings":"AAUA,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAExE,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,uDAAuD;AACvD,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qGAAqG;AACrG,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;AAkBnC,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/E;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,MAAM,GACN,aAAa,GACb,YAAY,GACZ,cAAc,GACd,aAAa,CAAC;AAElB,wDAAwD;AACxD,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,CAAC;AAE9D,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAErF,iFAAiF;AACjF,MAAM,MAAM,YAAY,GACpB,UAAU,GACV,WAAW,GACX,UAAU,GACV,iBAAiB,GACjB,UAAU,GACV,MAAM,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,4GAA4G;IAC5G,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,kCAAkC;IAClC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;IAC/F,iBAAiB,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IACtG,2FAA2F;IAC3F,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACnD,qHAAqH;IACrH,WAAW,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;IACtE,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChD,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,eAAe,CAAC;IAC9D,gIAAgI;IAChI,QAAQ,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,aAAa,GAAG,SAAS,CAAC;IACjE,0GAA0G;IAC1G,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACnC;AAED,iGAAiG;AACjG,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;CACzC;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmDD,qBAAa,KAAK;IAChB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAExC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IAEzC;;;;;OAKG;gBACS,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,GAAE,SAAc;IAiB7D;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,GAAE,SAAc,GAAG,KAAK;IAU/E;;;OAGG;IACH,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,SAAc,GAAG,KAAK;IAe3E,OAAO,CAAC,OAAO;IAQf;;;;OAIG;IACH,QAAQ,CAAC,IAAI,GAAE,MAAM,GAAG,IAAkB,GAAG,MAAM;IAWnD;;;OAGG;IACH,OAAO,CAAC,IAAI,GAAE,MAAM,GAAG,IAA0B,GAAG,MAAM;IAc1D;;;OAGG;IACH,MAAM,CAAC,IAAI,GAAE,MAAM,GAAG,IAA0B,GAAG,MAAM;IAMzD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAK9B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,GAAE,MAAM,GAAG,IAA8B,EAAE,MAAM,UAAQ,EAAE,MAAM,UAAQ,GAAG,MAAM;IA+B/F,8EAA8E;IAC9E,SAAS,CAAC,QAAQ,GAAE,MAAM,GAAG,IAAkB,GAAG,MAAM;IAUxD;;;;OAIG;IACH,IAAI,CAAC,OAAO,GAAE,MAAM,GAAG,IAA0B,GAAG,MAAM;IAW1D;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM;IAI1D;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM;IAQ7E;;;;;;;;;OASG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAM,GAAG,IAA8B,EAC7C,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,aAAkB,GACrE,MAAM;IA4BT;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAiC5B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,WAAoB,GAAG,MAAM;IAYxF,mFAAmF;IACnF,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,MAAM;IAIxD;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,SAAS,UAAQ,GAAG,MAAM;IA0BlE,OAAO,CAAC,cAAc;IAgBtB;;;;;;;OAOG;IACH,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,WAAqB,EAChC,SAAS,GAAE,WAAqB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,MAAM;IAOT,8CAA8C;IAC9C,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,WAAqB,GAAG,MAAM;IAI1D,sDAAsD;IACtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,WAAqB,GAAG,MAAM;IAQ1D;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM;IAIrE;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,CAAC,EAAE;IAM5F;;;;;OAKG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAkB,EAC5D,OAAO,GAAE,gBAAqB,GAC7B,OAAO;IAgBV;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAKlC,6EAA6E;IAC7E,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAKtC;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,MAAM;IAiB5D;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAUtC;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,cAAc;IAM9D;;;;OAIG;IACH,QAAQ,IAAI,QAAQ;IAWpB;;;OAGG;IACH,gBAAgB,IAAI,KAAK;IAIzB;;;OAGG;IACH,mBAAmB,IAAI,KAAK;IAI5B;;;OAGG;IACH,UAAU,CAAC,KAAK,GAAE,WAAoB,GAAG,MAAM,EAAE;IAsBjD;;;OAGG;IACH,YAAY,CAAC,KAAK,GAAE,WAAoB,GAAG,MAAM,EAAE;IASnD;;;;;OAKG;IACH,YAAY,CAAC,KAAK,GAAE,iBAA0B,GAAG,MAAM;IAMvD;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAmBpD;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,EAAE;IAY5C,iEAAiE;IACjE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI3B,iCAAiC;IACjC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQ3B;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,CAAC,sBAAsB,EACjC,OAAO,GAAE,QAAQ,GAAG,MAAiB,GACpC,MAAM;IAIT;;;;;;;;;;OAUG;IACH,uBAAuB,CACrB,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAmB,EAC9B,OAAO,GAAE,QAAQ,GAAG,MAAe,GAClC,MAAM;IAsBT;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,GAAE,QAAwB,EAAE,KAAK,GAAE,WAAoB,GAAG,MAAM;IAKnG;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,WAAqB,GAAG,MAAM;IAK5D,gGAAgG;IAChG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOjC,wFAAwF;IACxF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAK/C;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,IAA8B,GAAG,MAAM;IAU7F;;;;OAIG;IACH,SAAS,CACP,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,WAAsB,EACjC,SAAS,GAAE,WAAoB,GAC9B,MAAM;CAQV"}