@gobrand/tiempo 2.2.2 → 2.2.3

package/README.md

@@ -120,6 +120,84 @@ console.log(iso2); // "2025-01-20T20:00:00Z"
 
 ### Formatting
 
+#### `intlFormatDistance(laterDate, earlierDate, options?)`
+
+Format the distance between two dates as a human-readable, internationalized string using `Intl.RelativeTimeFormat`. Automatically selects the most appropriate unit (seconds, minutes, hours, days, weeks, months, years) based on the distance.
+
+**Parameters:**
+- `laterDate` (Temporal.Instant | Temporal.ZonedDateTime): The later date to compare
+- `earlierDate` (Temporal.Instant | Temporal.ZonedDateTime): The earlier date to compare with
+- `options` (IntlFormatDistanceOptions, optional): Formatting options
+  - `unit` (Intl.RelativeTimeFormatUnit): Force a specific unit instead of automatic selection
+  - `locale` (string | string[]): Locale for formatting (default: system locale)
+  - `numeric` ('always' | 'auto'): Use numeric values always or allow natural language like "tomorrow" (default: 'auto')
+  - `style` ('long' | 'short' | 'narrow'): Formatting style (default: 'long')
+  - `localeMatcher` ('best fit' | 'lookup'): Locale matching algorithm
+
+**Returns:** `string` - Formatted relative time string
+
+**Automatic unit selection:**
+- < 60 seconds → "in X seconds" / "X seconds ago"
+- < 60 minutes → "in X minutes" / "X minutes ago"
+- < 24 hours → "in X hours" / "X hours ago"
+- < 7 days → "tomorrow" / "yesterday" / "in X days" / "X days ago"
+- < 4 weeks → "next week" / "last week" / "in X weeks" / "X weeks ago"
+- < 12 months → "next month" / "last month" / "in X months" / "X months ago"
+- ≥ 12 months → "next year" / "last year" / "in X years" / "X years ago"
+
+**Example:**
+```typescript
+import { intlFormatDistance } from '@gobrand/tiempo';
+
+const later = Temporal.Instant.from('2025-01-20T12:00:00Z');
+const earlier = Temporal.Instant.from('2025-01-20T11:00:00Z');
+
+// Basic usage
+intlFormatDistance(later, earlier);
+// => "in 1 hour"
+
+intlFormatDistance(earlier, later);
+// => "1 hour ago"
+
+// With different locales
+intlFormatDistance(later, earlier, { locale: 'es' });
+// => "dentro de 1 hora"
+
+intlFormatDistance(later, earlier, { locale: 'ja' });
+// => "1 時間後"
+
+// Force numeric format
+const tomorrow = Temporal.Instant.from('2025-01-21T00:00:00Z');
+const today = Temporal.Instant.from('2025-01-20T00:00:00Z');
+
+intlFormatDistance(tomorrow, today, { numeric: 'auto' });
+// => "tomorrow"
+
+intlFormatDistance(tomorrow, today, { numeric: 'always' });
+// => "in 1 day"
+
+// Different styles
+const future = Temporal.Instant.from('2027-01-20T00:00:00Z');
+const now = Temporal.Instant.from('2025-01-20T00:00:00Z');
+
+intlFormatDistance(future, now, { style: 'long' });
+// => "in 2 years"
+
+intlFormatDistance(future, now, { style: 'short' });
+// => "in 2 yr."
+
+intlFormatDistance(future, now, { style: 'narrow' });
+// => "in 2y"
+
+// Force specific units
+intlFormatDistance(future, now, { unit: 'quarter' });
+// => "in 8 quarters"
+
+const dayLater = Temporal.Instant.from('2025-01-21T00:00:00Z');
+intlFormatDistance(dayLater, today, { unit: 'hour' });
+// => "in 24 hours"
+```
+
 #### `format(input, formatStr, options?)`
 
 Format a Temporal.Instant or ZonedDateTime using date-fns-like format tokens.

package/dist/chunk-NL5LWPJI.js

@@ -0,0 +1,94 @@
+import {
+  differenceInWeeks
+} from "./chunk-PVAOUYXF.js";
+import {
+  differenceInYears
+} from "./chunk-CHW2EN2O.js";
+import {
+  differenceInDays
+} from "./chunk-6IP245MS.js";
+import {
+  differenceInHours
+} from "./chunk-PIDXROVB.js";
+import {
+  differenceInMinutes
+} from "./chunk-RJY62CDU.js";
+import {
+  differenceInMonths
+} from "./chunk-BIAPE4MR.js";
+import {
+  differenceInSeconds
+} from "./chunk-ZHRMURYP.js";
+import {
+  normalizeTemporalInput
+} from "./chunk-MJSZNWCV.js";
+
+// src/intlFormatDistance.ts
+function intlFormatDistance(laterDate, earlierDate, options) {
+  const zoned1 = normalizeTemporalInput(laterDate);
+  const zoned2 = normalizeTemporalInput(earlierDate);
+  let unit = options?.unit;
+  if (!unit) {
+    const absSeconds = Math.abs(differenceInSeconds(zoned1, zoned2));
+    const absMinutes = Math.abs(differenceInMinutes(zoned1, zoned2));
+    const absHours = Math.abs(differenceInHours(zoned1, zoned2));
+    const absDays = Math.abs(differenceInDays(zoned1, zoned2));
+    const absWeeks = Math.abs(differenceInWeeks(zoned1, zoned2));
+    const absMonths = Math.abs(differenceInMonths(zoned1, zoned2));
+    if (absSeconds < 60) {
+      unit = "second";
+    } else if (absMinutes < 60) {
+      unit = "minute";
+    } else if (absHours < 24) {
+      unit = "hour";
+    } else if (absDays < 7) {
+      unit = "day";
+    } else if (absWeeks < 4) {
+      unit = "week";
+    } else if (absMonths < 12) {
+      unit = "month";
+    } else {
+      unit = "year";
+    }
+  }
+  let value;
+  switch (unit) {
+    case "second":
+      value = differenceInSeconds(zoned1, zoned2);
+      break;
+    case "minute":
+      value = differenceInMinutes(zoned1, zoned2);
+      break;
+    case "hour":
+      value = differenceInHours(zoned1, zoned2);
+      break;
+    case "day":
+      value = differenceInDays(zoned1, zoned2);
+      break;
+    case "week":
+      value = differenceInWeeks(zoned1, zoned2);
+      break;
+    case "month":
+      value = differenceInMonths(zoned1, zoned2);
+      break;
+    case "quarter":
+      value = Math.round(differenceInMonths(zoned1, zoned2) / 3);
+      break;
+    case "year":
+      value = differenceInYears(zoned1, zoned2);
+      break;
+    default:
+      value = differenceInSeconds(zoned1, zoned2);
+  }
+  const formatter = new Intl.RelativeTimeFormat(options?.locale, {
+    localeMatcher: options?.localeMatcher,
+    numeric: options?.numeric ?? "auto",
+    style: options?.style
+  });
+  return formatter.format(value, unit);
+}
+
+export {
+  intlFormatDistance
+};
+//# sourceMappingURL=chunk-NL5LWPJI.js.map

package/dist/chunk-NL5LWPJI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/intlFormatDistance.ts"],"sourcesContent":["import type { Temporal } from '@js-temporal/polyfill';\nimport { differenceInDays } from './differenceInDays.js';\nimport { differenceInHours } from './differenceInHours.js';\nimport { differenceInMinutes } from './differenceInMinutes.js';\nimport { differenceInMonths } from './differenceInMonths.js';\nimport { differenceInSeconds } from './differenceInSeconds.js';\nimport { differenceInWeeks } from './differenceInWeeks.js';\nimport { differenceInYears } from './differenceInYears.js';\nimport { normalizeTemporalInput } from './shared/normalizeTemporalInput.js';\n\nexport interface IntlFormatDistanceOptions {\n  /**\n   * The unit to force formatting in. If not specified, the unit will be automatically selected.\n   */\n  unit?: Intl.RelativeTimeFormatUnit;\n  /**\n   * The locale to use for formatting. Defaults to the system locale.\n   */\n  locale?: string | string[];\n  /**\n   * The locale matching algorithm to use.\n   */\n  localeMatcher?: 'best fit' | 'lookup';\n  /**\n   * Whether to use numeric values always, or use special strings like \"yesterday\", \"tomorrow\", etc.\n   * Defaults to 'auto'.\n   */\n  numeric?: 'always' | 'auto';\n  /**\n   * The formatting style to use.\n   */\n  style?: 'long' | 'short' | 'narrow';\n}\n\n/**\n * Formats the distance between two dates as a human-readable, internationalized string.\n *\n * The function automatically picks the most appropriate unit based on the distance between dates.\n * For example, if the distance is a few hours, it returns \"in X hours\". If the distance is a few\n * months, it returns \"in X months\".\n *\n * You can force a specific unit using the `options.unit` parameter.\n *\n * @param laterDate - The later date to compare\n * @param earlierDate - The earlier date to compare with\n * @param options - Formatting options\n * @returns The formatted distance string\n *\n * @example\n * ```typescript\n * const later = Temporal.Instant.from('2024-01-01T12:00:00Z');\n * const earlier = Temporal.Instant.from('2024-01-01T11:00:00Z');\n *\n * intlFormatDistance(later, earlier);\n * // => 'in 1 hour'\n *\n * intlFormatDistance(earlier, later);\n * // => '1 hour ago'\n * ```\n *\n * @example\n * ```typescript\n * // Force a specific unit\n * const later = Temporal.Instant.from('2025-01-01T00:00:00Z');\n * const earlier = Temporal.Instant.from('2024-01-01T00:00:00Z');\n *\n * intlFormatDistance(later, earlier, { unit: 'quarter' });\n * // => 'in 4 quarters'\n * ```\n *\n * @example\n * ```typescript\n * // Use a different locale\n * const later = Temporal.Instant.from('2024-01-01T12:00:00Z');\n * const earlier = Temporal.Instant.from('2024-01-01T11:00:00Z');\n *\n * intlFormatDistance(later, earlier, { locale: 'es' });\n * // => 'dentro de 1 hora'\n * ```\n *\n * @example\n * ```typescript\n * // Use numeric: 'always' to avoid special strings\n * const later = Temporal.Instant.from('2024-01-02T00:00:00Z');\n * const earlier = Temporal.Instant.from('2024-01-01T00:00:00Z');\n *\n * intlFormatDistance(later, earlier, { numeric: 'auto' });\n * // => 'tomorrow'\n *\n * intlFormatDistance(later, earlier, { numeric: 'always' });\n * // => 'in 1 day'\n * ```\n */\nexport function intlFormatDistance(\n  laterDate: Temporal.Instant | Temporal.ZonedDateTime,\n  earlierDate: Temporal.Instant | Temporal.ZonedDateTime,\n  options?: IntlFormatDistanceOptions\n): string {\n  const zoned1 = normalizeTemporalInput(laterDate);\n  const zoned2 = normalizeTemporalInput(earlierDate);\n\n  // Determine unit if not specified\n  let unit = options?.unit;\n  if (!unit) {\n    const absSeconds = Math.abs(differenceInSeconds(zoned1, zoned2));\n    const absMinutes = Math.abs(differenceInMinutes(zoned1, zoned2));\n    const absHours = Math.abs(differenceInHours(zoned1, zoned2));\n    const absDays = Math.abs(differenceInDays(zoned1, zoned2));\n    const absWeeks = Math.abs(differenceInWeeks(zoned1, zoned2));\n    const absMonths = Math.abs(differenceInMonths(zoned1, zoned2));\n\n    if (absSeconds < 60) {\n      unit = 'second';\n    } else if (absMinutes < 60) {\n      unit = 'minute';\n    } else if (absHours < 24) {\n      unit = 'hour';\n    } else if (absDays < 7) {\n      unit = 'day';\n    } else if (absWeeks < 4) {\n      unit = 'week';\n    } else if (absMonths < 12) {\n      unit = 'month';\n    } else {\n      unit = 'year';\n    }\n  }\n\n  // Calculate value for the selected unit\n  let value: number;\n  switch (unit) {\n    case 'second':\n      value = differenceInSeconds(zoned1, zoned2);\n      break;\n    case 'minute':\n      value = differenceInMinutes(zoned1, zoned2);\n      break;\n    case 'hour':\n      value = differenceInHours(zoned1, zoned2);\n      break;\n    case 'day':\n      value = differenceInDays(zoned1, zoned2);\n      break;\n    case 'week':\n      value = differenceInWeeks(zoned1, zoned2);\n      break;\n    case 'month':\n      value = differenceInMonths(zoned1, zoned2);\n      break;\n    case 'quarter':\n      value = Math.round(differenceInMonths(zoned1, zoned2) / 3);\n      break;\n    case 'year':\n      value = differenceInYears(zoned1, zoned2);\n      break;\n    default:\n      // For any other unit type, try to use it directly\n      value = differenceInSeconds(zoned1, zoned2);\n  }\n\n  // Format using Intl.RelativeTimeFormat\n  const formatter = new Intl.RelativeTimeFormat(options?.locale, {\n    localeMatcher: options?.localeMatcher,\n    numeric: options?.numeric ?? 'auto',\n    style: options?.style,\n  });\n\n  return formatter.format(value, unit);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA6FO,SAAS,mBACd,WACA,aACA,SACQ;AACR,QAAM,SAAS,uBAAuB,SAAS;AAC/C,QAAM,SAAS,uBAAuB,WAAW;AAGjD,MAAI,OAAO,SAAS;AACpB,MAAI,CAAC,MAAM;AACT,UAAM,aAAa,KAAK,IAAI,oBAAoB,QAAQ,MAAM,CAAC;AAC/D,UAAM,aAAa,KAAK,IAAI,oBAAoB,QAAQ,MAAM,CAAC;AAC/D,UAAM,WAAW,KAAK,IAAI,kBAAkB,QAAQ,MAAM,CAAC;AAC3D,UAAM,UAAU,KAAK,IAAI,iBAAiB,QAAQ,MAAM,CAAC;AACzD,UAAM,WAAW,KAAK,IAAI,kBAAkB,QAAQ,MAAM,CAAC;AAC3D,UAAM,YAAY,KAAK,IAAI,mBAAmB,QAAQ,MAAM,CAAC;AAE7D,QAAI,aAAa,IAAI;AACnB,aAAO;AAAA,IACT,WAAW,aAAa,IAAI;AAC1B,aAAO;AAAA,IACT,WAAW,WAAW,IAAI;AACxB,aAAO;AAAA,IACT,WAAW,UAAU,GAAG;AACtB,aAAO;AAAA,IACT,WAAW,WAAW,GAAG;AACvB,aAAO;AAAA,IACT,WAAW,YAAY,IAAI;AACzB,aAAO;AAAA,IACT,OAAO;AACL,aAAO;AAAA,IACT;AAAA,EACF;AAGA,MAAI;AACJ,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,cAAQ,oBAAoB,QAAQ,MAAM;AAC1C;AAAA,IACF,KAAK;AACH,cAAQ,oBAAoB,QAAQ,MAAM;AAC1C;AAAA,IACF,KAAK;AACH,cAAQ,kBAAkB,QAAQ,MAAM;AACxC;AAAA,IACF,KAAK;AACH,cAAQ,iBAAiB,QAAQ,MAAM;AACvC;AAAA,IACF,KAAK;AACH,cAAQ,kBAAkB,QAAQ,MAAM;AACxC;AAAA,IACF,KAAK;AACH,cAAQ,mBAAmB,QAAQ,MAAM;AACzC;AAAA,IACF,KAAK;AACH,cAAQ,KAAK,MAAM,mBAAmB,QAAQ,MAAM,IAAI,CAAC;AACzD;AAAA,IACF,KAAK;AACH,cAAQ,kBAAkB,QAAQ,MAAM;AACxC;AAAA,IACF;AAEE,cAAQ,oBAAoB,QAAQ,MAAM;AAAA,EAC9C;AAGA,QAAM,YAAY,IAAI,KAAK,mBAAmB,SAAS,QAAQ;AAAA,IAC7D,eAAe,SAAS;AAAA,IACxB,SAAS,SAAS,WAAW;AAAA,IAC7B,OAAO,SAAS;AAAA,EAClB,CAAC;AAED,SAAO,UAAU,OAAO,OAAO,IAAI;AACrC;","names":[]}

package/dist/index.d.ts

@@ -27,4 +27,5 @@ export { differenceInDays } from './differenceInDays';
 export { differenceInWeeks } from './differenceInWeeks';
 export { differenceInMonths } from './differenceInMonths';
 export { differenceInYears } from './differenceInYears';
+export { intlFormatDistance, type IntlFormatDistanceOptions, } from './intlFormatDistance';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,3 +1,6 @@
+import {
+  startOfMonth
+} from "./chunk-TU2UNOOW.js";
 import {
   startOfWeek
 } from "./chunk-2WMXB7QL.js";
@@ -16,6 +19,9 @@ import {
 import {
   today
 } from "./chunk-67QHALIG.js";
+import {
+  intlFormatDistance
+} from "./chunk-NL5LWPJI.js";
 import {
   isAfter
 } from "./chunk-BBNNR2QH.js";
@@ -37,9 +43,6 @@ import {
 import {
   startOfDay
 } from "./chunk-TW5EV3DH.js";
-import {
-  startOfMonth
-} from "./chunk-TU2UNOOW.js";
 import {
   differenceInWeeks
 } from "./chunk-PVAOUYXF.js";
@@ -103,6 +106,7 @@ export {
   endOfWeek,
   endOfYear,
   format,
+  intlFormatDistance,
   isAfter,
   isBefore,
   isFuture,

package/dist/intlFormatDistance.d.ts

@@ -0,0 +1,85 @@
+import type { Temporal } from '@js-temporal/polyfill';
+export interface IntlFormatDistanceOptions {
+    /**
+     * The unit to force formatting in. If not specified, the unit will be automatically selected.
+     */
+    unit?: Intl.RelativeTimeFormatUnit;
+    /**
+     * The locale to use for formatting. Defaults to the system locale.
+     */
+    locale?: string | string[];
+    /**
+     * The locale matching algorithm to use.
+     */
+    localeMatcher?: 'best fit' | 'lookup';
+    /**
+     * Whether to use numeric values always, or use special strings like "yesterday", "tomorrow", etc.
+     * Defaults to 'auto'.
+     */
+    numeric?: 'always' | 'auto';
+    /**
+     * The formatting style to use.
+     */
+    style?: 'long' | 'short' | 'narrow';
+}
+/**
+ * Formats the distance between two dates as a human-readable, internationalized string.
+ *
+ * The function automatically picks the most appropriate unit based on the distance between dates.
+ * For example, if the distance is a few hours, it returns "in X hours". If the distance is a few
+ * months, it returns "in X months".
+ *
+ * You can force a specific unit using the `options.unit` parameter.
+ *
+ * @param laterDate - The later date to compare
+ * @param earlierDate - The earlier date to compare with
+ * @param options - Formatting options
+ * @returns The formatted distance string
+ *
+ * @example
+ * ```typescript
+ * const later = Temporal.Instant.from('2024-01-01T12:00:00Z');
+ * const earlier = Temporal.Instant.from('2024-01-01T11:00:00Z');
+ *
+ * intlFormatDistance(later, earlier);
+ * // => 'in 1 hour'
+ *
+ * intlFormatDistance(earlier, later);
+ * // => '1 hour ago'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Force a specific unit
+ * const later = Temporal.Instant.from('2025-01-01T00:00:00Z');
+ * const earlier = Temporal.Instant.from('2024-01-01T00:00:00Z');
+ *
+ * intlFormatDistance(later, earlier, { unit: 'quarter' });
+ * // => 'in 4 quarters'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use a different locale
+ * const later = Temporal.Instant.from('2024-01-01T12:00:00Z');
+ * const earlier = Temporal.Instant.from('2024-01-01T11:00:00Z');
+ *
+ * intlFormatDistance(later, earlier, { locale: 'es' });
+ * // => 'dentro de 1 hora'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use numeric: 'always' to avoid special strings
+ * const later = Temporal.Instant.from('2024-01-02T00:00:00Z');
+ * const earlier = Temporal.Instant.from('2024-01-01T00:00:00Z');
+ *
+ * intlFormatDistance(later, earlier, { numeric: 'auto' });
+ * // => 'tomorrow'
+ *
+ * intlFormatDistance(later, earlier, { numeric: 'always' });
+ * // => 'in 1 day'
+ * ```
+ */
+export declare function intlFormatDistance(laterDate: Temporal.Instant | Temporal.ZonedDateTime, earlierDate: Temporal.Instant | Temporal.ZonedDateTime, options?: IntlFormatDistanceOptions): string;
+//# sourceMappingURL=intlFormatDistance.d.ts.map

package/dist/intlFormatDistance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intlFormatDistance.d.ts","sourceRoot":"","sources":["../src/intlFormatDistance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAUtD,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC,sBAAsB,CAAC;IACnC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B;;OAEG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC,aAAa,EACpD,WAAW,EAAE,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC,aAAa,EACtD,OAAO,CAAC,EAAE,yBAAyB,GAClC,MAAM,CAuER"}

package/dist/intlFormatDistance.js

@@ -0,0 +1,15 @@
+import {
+  intlFormatDistance
+} from "./chunk-NL5LWPJI.js";
+import "./chunk-PVAOUYXF.js";
+import "./chunk-CHW2EN2O.js";
+import "./chunk-6IP245MS.js";
+import "./chunk-PIDXROVB.js";
+import "./chunk-RJY62CDU.js";
+import "./chunk-BIAPE4MR.js";
+import "./chunk-ZHRMURYP.js";
+import "./chunk-MJSZNWCV.js";
+export {
+  intlFormatDistance
+};
+//# sourceMappingURL=intlFormatDistance.js.map

package/dist/intlFormatDistance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/intlFormatDistance.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=intlFormatDistance.test.d.ts.map

package/dist/intlFormatDistance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intlFormatDistance.test.d.ts","sourceRoot":"","sources":["../src/intlFormatDistance.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobrand/tiempo",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Lightweight utility functions for converting between UTC and timezone-aware datetimes using the Temporal API",
   "private": false,
   "publishConfig": {