@leaderty/utils 2.0.1 → 2.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @leaderty/utils
+
+Argentine number and date formatting. Every function returns the same output on any system: none of them uses `Intl`, `toLocaleString()` or the system time zone, so a WebView in English still shows `350.000` and `dd/mm/aaaa`.
+
+## Setup
+
+```bash
+npm install @leaderty/utils
+```
+
+## Functions
+
+### `numberToMoney(amount, options?)`
+
+Formats a money amount with `.` for thousands and `,` for decimals, optionally prefixed with the currency.
+
+**Behavior:**
+- Rounds half away from zero on the decimal value: `1.005` gives `1,01`, and float noise such as `2309.9999999999995` gives `2.310,00`.
+- Puts the minus sign before the currency (`-$ 1.234,50`). An amount that rounds to zero has no sign.
+- Returns `'-'` for `null`, `undefined`, `NaN` and infinite amounts.
+
+**Parameters:**
+- `amount` - `number | null | undefined`
+- `options.decimals` - `0 | 2`. Defaults to `0`.
+- `options.currency` - `'ARS' | 'USD'`. Omit it for a bare number.
+- `options.currencyDisplay` - `'code'` (default) prints `ARS` / `USD`; `'symbol'` prints `$` / `US$`. Ignored without `currency`.
+
+**Returns:** `string`
+
+**Examples:**
+```typescript
+numberToMoney(350000)                                                       // "350.000"
+numberToMoney(350000, { currency: 'ARS' })                                  // "ARS 350.000"
+numberToMoney(350000, { currency: 'ARS', currencyDisplay: 'symbol' })       // "$ 350.000"
+numberToMoney(350000, { currency: 'ARS', currencyDisplay: 'symbol', decimals: 2 }) // "$ 350.000,00"
+numberToMoney(1500, { currency: 'USD', currencyDisplay: 'symbol', decimals: 2 })   // "US$ 1.500,00"
+numberToMoney(-1234.5, { decimals: 2 })                                     // "-1.234,50"
+numberToMoney(undefined, { currency: 'ARS' })                               // "-"
+```
+
+### `dateToShort(value, options?)`
+
+Formats a date as `dd/mm/aaaa`, or `dd/mm/aaaa hh:mm` (24-hour) with `time: true`.
+
+**Behavior:**
+- `'aaaa-mm-dd'` strings, and date-time strings without a time zone (`'2026-10-01T00:00:00'`), are read as written. `'2026-10-11'` gives `11/10/2026`, even though `new Date('2026-10-11')` is midnight UTC, which is still October 10 in Argentina.
+- `Date` objects and ISO strings with a time zone (`Z` or `±hh:mm`, as in `'2026-10-22T22:05:36.036Z'`) are shown in `America/Argentina/Buenos_Aires` time (UTC-3, no daylight saving time).
+- Any other string gives `'-'` (`'11/10/2026'`, `'2026-10'`, `'Oct 11 2026'`): `new Date()` would read it in the system time zone or guess the day/month order.
+- Also returns `'-'` for `null`, `undefined`, invalid dates and impossible dates such as `'2026-02-30'`.
+
+**Parameters:**
+- `value` - `Date | string | null | undefined`
+- `options.time` - Appends the time. Defaults to `false`.
+
+**Returns:** `string`
+
+**Examples:**
+```typescript
+dateToShort('2026-10-11')                               // "11/10/2026"
+dateToShort('2026-10-01T00:00:00')                      // "01/10/2026"
+dateToShort(new Date('2026-10-22T22:05:36Z'))           // "22/10/2026"
+dateToShort('2026-10-22T02:05:36Z', { time: true })     // "21/10/2026 23:05"
+dateToShort('11/10/2026')                               // "-"
+```
+
+### `dateToYMD(value)`
+
+Formats a date as `aaaa-mm-dd`, the value of an `<input type="date">`. Reads `value` like `dateToShort`, so `'2026-10-11'` stays the 11th and a `Date` is taken in Buenos Aires time.
+
+**Parameters:**
+- `value` - `Date | string | null | undefined`
+
+**Returns:** `string`. `''` (not `'-'`, so a date input stays empty) when `value` is missing or not a valid date.
+
+**Examples:**
+```typescript
+dateToYMD('2026-10-11')                       // "2026-10-11"
+dateToYMD(new Date('2026-10-22T02:05:36Z'))   // "2026-10-21"
+dateToYMD('11/10/2026')                       // ""
+```
+
+### `dateToMonthYearLong(value)`
+
+Formats the month and year in Spanish, lowercase. Also accepts `'aaaa-mm'` strings (the `MonthSelector` value of `@leaderty/react-month-selector`); otherwise reads `value` like `dateToShort`.
+
+**Parameters:**
+- `value` - `Date | string | null | undefined`
+
+**Returns:** `string`, or `'-'` when the date is missing or invalid
+
+**Examples:**
+```typescript
+dateToMonthYearLong('2026-10')      // "octubre de 2026"
+dateToMonthYearLong('2026-10-11')   // "octubre de 2026"
+dateToMonthYearLong('2026-10-01')   // "octubre de 2026" (not September)
+```
+
+### `numberToDecimalString(numero)`
+
+Formats a number with two decimals and thousands separators. Rounds with `toFixed(2)`, so `1.005` gives `1,00`; prefer `numberToMoney(n, { decimals: 2 })` in new code. Formerly `numberToStringWithDecimals`, which stays as a deprecated alias.
+
+**Parameters:**
+- `numero` - `number`
+
+**Returns:** `string`
+
+**Examples:**
+```typescript
+numberToDecimalString(1234.56)   // "1.234,56"
+```
+
+## Types
+
+`Currency`, `NumberToMoneyOptions` and `DateToShortOptions` are exported for consumers.

package/dist/format.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Argentine display formatters that never depend on the system locale or `Intl`:
+ * the WebView formats `toLocaleString()` with the OS language, so an English
+ * system shows "350,000" where an Argentine user reads 350 pesos.
+ */
+export type Currency = 'ARS' | 'USD';
+export interface NumberToMoneyOptions {
+    /** Decimal places. Defaults to `0`. */
+    decimals?: 0 | 2;
+    /** Prefixes the amount with the currency. Omit it for a bare number. */
+    currency?: Currency;
+    /** `'code'` (default) prints `ARS` / `USD`; `'symbol'` prints `$` / `US$`. Ignored without `currency`. */
+    currencyDisplay?: 'code' | 'symbol';
+}
+export interface DateToShortOptions {
+    /** Appends the 24-hour time as `hh:mm`. Defaults to `false`. */
+    time?: boolean;
+}
+/**
+ * Formats a money amount the Argentine way: `.` for thousands and `,` for decimals.
+ * Rounds half away from zero on the decimal value, so `1.005` gives `1,01` and float noise
+ * such as `2309.9999999999995` gives `2.310,00`.
+ *
+ * @param amount - Amount to format
+ * @param options - Decimals and currency prefix
+ * @returns The formatted amount, or `'-'` when `amount` is `null`, `undefined`, `NaN` or infinite
+ *
+ * @example
+ * numberToMoney(350000)                                                      // "350.000"
+ * numberToMoney(350000, { currency: 'ARS' })                                 // "ARS 350.000"
+ * numberToMoney(350000, { currency: 'ARS', currencyDisplay: 'symbol', decimals: 2 }) // "$ 350.000,00"
+ * numberToMoney(-1234.5, { currency: 'USD', currencyDisplay: 'symbol', decimals: 2 }) // "-US$ 1.234,50"
+ */
+export declare function numberToMoney(amount: number | null | undefined, options?: NumberToMoneyOptions): string;
+/**
+ * Formats a date as `dd/mm/aaaa`, optionally with the time as `dd/mm/aaaa hh:mm`.
+ *
+ * - `'aaaa-mm-dd'` strings, and date-time strings without a time zone (`'2026-10-01T00:00:00'`),
+ *   are read as written: `'2026-10-11'` is the 11th, never the 10th
+ *   (`new Date('2026-10-11')` is midnight UTC, which is still the 10th in Argentina).
+ * - `Date` objects and ISO strings with a time zone (`'2026-10-22T22:05:36.036Z'`) are shown in
+ *   `America/Argentina/Buenos_Aires` time.
+ * - Any other string (`'11/10/2026'`, `'2026-10'`, `'Oct 11 2026'`) gives `'-'`: the engine would parse it
+ *   in the system time zone, or guess the day/month order.
+ *
+ * @param value - Date to format
+ * @param options - Whether to append the time
+ * @returns The formatted date, or `'-'` when `value` is missing or not a valid date
+ *
+ * @example
+ * dateToShort('2026-10-11')                                    // "11/10/2026"
+ * dateToShort(new Date('2026-10-22T22:05:36Z'))                // "22/10/2026"
+ * dateToShort('2026-10-22T02:05:36Z', { time: true })          // "21/10/2026 23:05"
+ */
+export declare function dateToShort(value: Date | string | null | undefined, options?: DateToShortOptions): string;
+/**
+ * Formats a date as `aaaa-mm-dd`, the value of an `<input type="date">`. Reads `value` like {@link dateToShort}.
+ *
+ * @param value - Date to format
+ * @returns The date as `aaaa-mm-dd`, or `''` (not `'-'`, so a date input stays empty) when `value` is missing or not a valid date
+ *
+ * @example
+ * dateToYMD('2026-10-11')                       // "2026-10-11"
+ * dateToYMD('2026-10-11T00:00:00')              // "2026-10-11"
+ * dateToYMD(new Date('2026-10-22T02:05:36Z'))   // "2026-10-21"
+ * dateToYMD('11/10/2026')                       // ""
+ */
+export declare function dateToYMD(value: Date | string | null | undefined): string;
+/**
+ * Formats the month and year of a date in Spanish, lowercase: `octubre de 2026`.
+ * Also accepts `'aaaa-mm'` strings (the `MonthSelector` value). Otherwise reads `value` like {@link dateToShort}.
+ *
+ * @param value - Date to format
+ * @returns The month and year, or `'-'` when `value` is missing or not a valid date
+ *
+ * @example
+ * dateToMonthYearLong('2026-10')            // "octubre de 2026"
+ * dateToMonthYearLong('2026-10-11')         // "octubre de 2026"
+ * dateToMonthYearLong(new Date(2027, 0, 11)) // "enero de 2027"
+ */
+export declare function dateToMonthYearLong(value: Date | string | null | undefined): string;

package/dist/format.js

@@ -0,0 +1,157 @@
+/**
+ * Argentine display formatters that never depend on the system locale or `Intl`:
+ * the WebView formats `toLocaleString()` with the OS language, so an English
+ * system shows "350,000" where an Argentine user reads 350 pesos.
+ */
+/** Shown instead of a value that is missing or not a valid number/date. */
+const PLACEHOLDER = '-';
+const CURRENCY_SYMBOLS = { ARS: '$', USD: 'US$' };
+/** Argentina is UTC-3 all year (no daylight saving time since 2009). */
+const BUENOS_AIRES_OFFSET_MS = -3 * 60 * 60 * 1000;
+/** `aaaa-mm-dd`, optionally followed by a time and no time zone: a calendar date or Argentine wall-clock time. */
+const WALL_CLOCK_PATTERN = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?)?$/;
+/** ISO 8601 date-time with an explicit time zone (`Z` or `±hh:mm`): an instant, the same in any system time zone. */
+const ZONED_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
+/** `aaaa-mm`, the month format of `@leaderty/react-month-selector` (same pattern as its `YEAR_MONTH_PATTERN`). */
+const YEAR_MONTH_PATTERN = /^(\d{4})-(0[1-9]|1[0-2])$/;
+const MONTH_NAMES = [
+    'enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio',
+    'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre',
+];
+/**
+ * Formats a money amount the Argentine way: `.` for thousands and `,` for decimals.
+ * Rounds half away from zero on the decimal value, so `1.005` gives `1,01` and float noise
+ * such as `2309.9999999999995` gives `2.310,00`.
+ *
+ * @param amount - Amount to format
+ * @param options - Decimals and currency prefix
+ * @returns The formatted amount, or `'-'` when `amount` is `null`, `undefined`, `NaN` or infinite
+ *
+ * @example
+ * numberToMoney(350000)                                                      // "350.000"
+ * numberToMoney(350000, { currency: 'ARS' })                                 // "ARS 350.000"
+ * numberToMoney(350000, { currency: 'ARS', currencyDisplay: 'symbol', decimals: 2 }) // "$ 350.000,00"
+ * numberToMoney(-1234.5, { currency: 'USD', currencyDisplay: 'symbol', decimals: 2 }) // "-US$ 1.234,50"
+ */
+export function numberToMoney(amount, options = {}) {
+    if (amount === null || amount === undefined || !Number.isFinite(amount))
+        return PLACEHOLDER;
+    const { decimals = 0, currency, currencyDisplay = 'code' } = options;
+    const absolute = Math.abs(amount);
+    // Shifting the exponent in the string avoids binary noise: 1.005 * 100 === 100.49999999999999
+    const shifted = String(absolute).includes('e')
+        ? absolute * 10 ** decimals
+        : Number(`${absolute}e${decimals}`);
+    const digits = String(Math.round(shifted)).padStart(decimals + 1, '0');
+    const integerPart = digits.slice(0, digits.length - decimals).replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+    const decimalPart = digits.slice(digits.length - decimals);
+    const number = decimals > 0 ? `${integerPart},${decimalPart}` : integerPart;
+    // An amount that rounds to zero has no sign: -0.001 gives "0,00", not "-0,00"
+    const sign = amount < 0 && /[1-9]/.test(digits) ? '-' : '';
+    if (!currency)
+        return `${sign}${number}`;
+    const prefix = currencyDisplay === 'symbol' ? CURRENCY_SYMBOLS[currency] : currency;
+    return `${sign}${prefix} ${number}`;
+}
+/**
+ * Formats a date as `dd/mm/aaaa`, optionally with the time as `dd/mm/aaaa hh:mm`.
+ *
+ * - `'aaaa-mm-dd'` strings, and date-time strings without a time zone (`'2026-10-01T00:00:00'`),
+ *   are read as written: `'2026-10-11'` is the 11th, never the 10th
+ *   (`new Date('2026-10-11')` is midnight UTC, which is still the 10th in Argentina).
+ * - `Date` objects and ISO strings with a time zone (`'2026-10-22T22:05:36.036Z'`) are shown in
+ *   `America/Argentina/Buenos_Aires` time.
+ * - Any other string (`'11/10/2026'`, `'2026-10'`, `'Oct 11 2026'`) gives `'-'`: the engine would parse it
+ *   in the system time zone, or guess the day/month order.
+ *
+ * @param value - Date to format
+ * @param options - Whether to append the time
+ * @returns The formatted date, or `'-'` when `value` is missing or not a valid date
+ *
+ * @example
+ * dateToShort('2026-10-11')                                    // "11/10/2026"
+ * dateToShort(new Date('2026-10-22T22:05:36Z'))                // "22/10/2026"
+ * dateToShort('2026-10-22T02:05:36Z', { time: true })          // "21/10/2026 23:05"
+ */
+export function dateToShort(value, options = {}) {
+    const parts = toDateParts(value);
+    if (!parts)
+        return PLACEHOLDER;
+    const date = `${pad(parts.day)}/${pad(parts.month)}/${parts.year}`;
+    return options.time ? `${date} ${pad(parts.hours)}:${pad(parts.minutes)}` : date;
+}
+/**
+ * Formats a date as `aaaa-mm-dd`, the value of an `<input type="date">`. Reads `value` like {@link dateToShort}.
+ *
+ * @param value - Date to format
+ * @returns The date as `aaaa-mm-dd`, or `''` (not `'-'`, so a date input stays empty) when `value` is missing or not a valid date
+ *
+ * @example
+ * dateToYMD('2026-10-11')                       // "2026-10-11"
+ * dateToYMD('2026-10-11T00:00:00')              // "2026-10-11"
+ * dateToYMD(new Date('2026-10-22T02:05:36Z'))   // "2026-10-21"
+ * dateToYMD('11/10/2026')                       // ""
+ */
+export function dateToYMD(value) {
+    const parts = toDateParts(value);
+    if (!parts)
+        return '';
+    return `${parts.year}-${pad(parts.month)}-${pad(parts.day)}`;
+}
+/**
+ * Formats the month and year of a date in Spanish, lowercase: `octubre de 2026`.
+ * Also accepts `'aaaa-mm'` strings (the `MonthSelector` value). Otherwise reads `value` like {@link dateToShort}.
+ *
+ * @param value - Date to format
+ * @returns The month and year, or `'-'` when `value` is missing or not a valid date
+ *
+ * @example
+ * dateToMonthYearLong('2026-10')            // "octubre de 2026"
+ * dateToMonthYearLong('2026-10-11')         // "octubre de 2026"
+ * dateToMonthYearLong(new Date(2027, 0, 11)) // "enero de 2027"
+ */
+export function dateToMonthYearLong(value) {
+    const yearMonth = typeof value === 'string' ? YEAR_MONTH_PATTERN.exec(value) : null;
+    const parts = yearMonth ? { year: Number(yearMonth[1]), month: Number(yearMonth[2]) } : toDateParts(value);
+    if (!parts)
+        return PLACEHOLDER;
+    return `${MONTH_NAMES[parts.month - 1]} de ${parts.year}`;
+}
+function toDateParts(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string') {
+        const match = WALL_CLOCK_PATTERN.exec(value);
+        if (match) {
+            const [year, month, day, hours, minutes] = match.slice(1).map((part) => Number(part ?? 0));
+            if (!isCalendarDate(year, month, day) || hours > 23 || minutes > 59)
+                return null;
+            return { year, month, day, hours, minutes };
+        }
+        if (!ZONED_PATTERN.test(value))
+            return null;
+        // The engine rolls 2026-02-30T10:00Z over to March 2
+        const [year, month, day] = value.slice(0, 10).split('-').map(Number);
+        if (!isCalendarDate(year, month, day))
+            return null;
+    }
+    const time = new Date(value).getTime();
+    if (Number.isNaN(time))
+        return null;
+    const buenosAires = new Date(time + BUENOS_AIRES_OFFSET_MS);
+    return {
+        year: buenosAires.getUTCFullYear(),
+        month: buenosAires.getUTCMonth() + 1,
+        day: buenosAires.getUTCDate(),
+        hours: buenosAires.getUTCHours(),
+        minutes: buenosAires.getUTCMinutes(),
+    };
+}
+/** Rejects impossible dates such as 2026-02-30, which Date.UTC would roll over to March. */
+function isCalendarDate(year, month, day) {
+    const check = new Date(Date.UTC(year, month - 1, day));
+    return check.getUTCFullYear() === year && check.getUTCMonth() === month - 1 && check.getUTCDate() === day;
+}
+function pad(value) {
+    return String(value).padStart(2, '0');
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 /**
  * Formatea un número a una cadena con dos decimales y separadores de miles.
  */
-export declare function numberToStringWithDecimals(numero: number): string;
+export declare function numberToDecimalString(numero: number): string;
+/** @deprecated Renamed to {@link numberToDecimalString}. */
+export declare const numberToStringWithDecimals: typeof numberToDecimalString;
+export { numberToMoney, dateToShort, dateToYMD, dateToMonthYearLong, type Currency, type NumberToMoneyOptions, type DateToShortOptions, } from './format.js';

package/dist/index.js

@@ -1,9 +1,12 @@
 /**
  * Formatea un número a una cadena con dos decimales y separadores de miles.
  */
-export function numberToStringWithDecimals(numero) {
+export function numberToDecimalString(numero) {
     const formatted = numero.toFixed(2);
     const [integerPart, decimalPart] = formatted.split('.');
     const withThousandsSeparator = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, '.');
     return `${withThousandsSeparator},${decimalPart}`;
 }
+/** @deprecated Renamed to {@link numberToDecimalString}. */
+export const numberToStringWithDecimals = numberToDecimalString;
+export { numberToMoney, dateToShort, dateToYMD, dateToMonthYearLong, } from './format.js';

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@leaderty/utils",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.test*"
   ],
   "publishConfig": {
     "access": "public"

package/dist/index.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/index.test.js

@@ -1,7 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { numberToStringWithDecimals } from "./index";
-describe("numberToStringWithDecimals", () => {
-    it("should format number with two decimals and thousand separators", () => {
-        expect(numberToStringWithDecimals(1234.56)).toBe("1.234,56");
-    });
-});