@marasuchus/kit

Everyday helpers, published as a public package on npmjs.com. ESM only, types included.

Installation

pnpm add @marasuchus/kit

date-fns is an optional peer: install it only if you use ./dates or ./ar (see table below).

Modules

Each module is imported via subpath, with no barrel loading everything:

import { formatDate } from "@marasuchus/kit/dates";

| Subpath | Status | Required peers | | -------------- | ----------- | -------------- | | ./ar | implemented | none | | ./dates | implemented | date-fns | | ./numbers | implemented | none | | ./intl-cache | implemented | none |

ar

Argentina presets (es-AR locale, ARS, America/Argentina/Buenos_Aires) over the generic dates / numbers helpers. Drop-in names for dashboard call sites.

import {
  AR,
  formatCurrency,
  formatDate,
  formatDateKey,
  relativeTime,
} from "@marasuchus/kit/ar";

formatCurrency(2_500_000); // "$2.5M" (switches to compact from one million up)
formatCurrency(999_999); // "$ 999.999,00" (table detail)
formatDate("2026-09-05T02:00:00Z"); // "4 sept 2026" (still the 4th in BA)
relativeTime(date); // "Hace 5 minutos" ("Nunca" when empty)

• Money: formatFullCurrency ($ 1.234, no decimals), formatTablePesos ($ 1.234,56), formatUsd / formatTableUsd, formatExchangeRate (3 decimals), formatCompactPesos ($600K chart labels).
• Dates: formatDate, formatDateTime and relativeTime, all defaulting to Buenos Aires time; pass overrides (e.g. { timeZone: "UTC" }, { dateStyle: "long" }) per call. formatDate takes dateStyle (ignores timeStyle); formatDateTime* take both.
• Months: formatMonthName(date) ("Mayo"), formatMonthNameISO("2025-05-01"), formatMonthShort(5) ("May"). The long names are monthLabel presets with es-AR baked in; the short list is explicit, not Intl (Intl renders "sept" and varies the trailing dot by runtime).

dates

Strict parsing for URL params and <input type="date">, plus Intl display that never shifts date-only strings across time zones.

• parseDateOnly / formatDateOnly: yyyy-MM-dd, rejecting rollovers (2026-02-30) and loose forms (2026-9-4).
• formatDateKey(date, timeZone = "UTC"): YYYY-MM-DD machine key in the given IANA zone (grouping keys, TO_CHAR matches); invalid → "".
• getLastDays(count, timeZone, now?) / getDateRangeForSummaryByDays(days, timeZone, now?): DST-safe day windows with explicit zone (bounds as UTC instants).
• parseMonthYear / formatMonthYear: yyyy-MM to the first of the month.
• parseDateRange / formatDateRange: { from, to } range helpers.
• formatDate / formatDateTime: date-only strings (2026-09-04, e.g. a SQL date column) are anchored at UTC midnight and always formatted in UTC, so server and browser agree; real timestamps use timeZone. Optional dateStyle ("medium" default) and — for formatDateTime* only — timeStyle ("short" / "medium" defaults); formatDate ignores timeStyle.
• relativeTime: "hace 5 minutos" / "dentro de 2 horas" via Intl.RelativeTimeFormat, with justNowLabel, emptyLabel and capitalize options.

import { formatDate, parseDateOnly, relativeTime } from "@marasuchus/kit/dates";

parseDateOnly("2026-09-04"); // Date at local midnight (or undefined)
formatDate("2026-09-04", { locale: "es-AR", timeZone: "America/Argentina/Buenos_Aires" });
relativeTime(date, { locale: "es", now: new Date() });

numbers

Intl-backed money and number formatting:

• formatMoney(amount, { locale, currency, decimals }): 2 decimals by default.
• formatNumber(value, { locale, decimals }): fixed fraction digits.
• formatCompact(amount, symbol?): chart labels ($600K, $1.2M, -$1.5K); suffixes are always K/M/B.

import { formatCompact, formatMoney } from "@marasuchus/kit/numbers";

formatMoney(1234.5, { locale: "en-US", currency: "USD" }); // "$1,234.50"
formatCompact(1_200_000, "$"); // "$1.2M"

intl-cache

Memoized Intl constructors (getNumberFormat, getDateTimeFormat, getRelativeTimeFormat): each distinct locale + options pair is built once. Used internally by dates and numbers.

License

MIT — see LICENSE.