fix: improve type of values accepted by date/time/number formats (#2359)

Author: YarnSphere

packages/core/src/formats.ts

@@ -13,9 +13,14 @@ function normalizeLocales(locales: Locales): string[] {
 
 export type DateTimeFormatSize = "short" | "default" | "long" | "full"
 
+// These types vary depending on the TypeScript target (e.g., modern ES versions
+// support passing a bigint or string to `Intl.NumberFormat.prototype.format`)
+export type DateTimeFormatValue = Parameters<Intl.DateTimeFormat["format"]>[0]
+export type NumberFormatValue = Parameters<Intl.NumberFormat["format"]>[0]
+
 export function date(
   locales: Locales,
-  value: string | Date,
+  value: string | DateTimeFormatValue,
   format?: Intl.DateTimeFormatOptions | DateTimeFormatSize
 ): string {
   const _locales = normalizeLocales(locales)
@@ -60,7 +65,7 @@ export function date(
 
 export function time(
   locales: Locales,
-  value: string | Date,
+  value: string | DateTimeFormatValue,
   format?: Intl.DateTimeFormatOptions | DateTimeFormatSize
 ): string {
   let o: Intl.DateTimeFormatOptions
@@ -95,7 +100,7 @@ export function time(
 
 export function number(
   locales: Locales,
-  value: number,
+  value: NumberFormatValue,
   format?: Intl.NumberFormatOptions
 ): string {
   const _locales = normalizeLocales(locales)

packages/core/src/i18n.ts

@@ -1,6 +1,12 @@
 import { interpolate } from "./interpolate"
 import { isString, isFunction } from "./essentials"
-import { date, defaultLocale, number } from "./formats"
+import {
+  date,
+  type DateTimeFormatValue,
+  defaultLocale,
+  number,
+  type NumberFormatValue,
+} from "./formats"
 import { EventEmitter } from "./eventEmitter"
 import { compileMessage } from "@lingui/message-utils/compileMessage"
 import type { CompiledMessage } from "@lingui/message-utils/compileMessage"
@@ -312,11 +318,14 @@ Please compile your catalog first.
    */
   t: I18n["_"] = this._.bind(this)
 
-  date(value: string | Date, format?: Intl.DateTimeFormatOptions): string {
+  date(
+    value?: string | DateTimeFormatValue,
+    format?: Intl.DateTimeFormatOptions
+  ): string {
     return date(this._locales || this._locale, value, format)
   }
 
-  number(value: number, format?: Intl.NumberFormatOptions): string {
+  number(value: NumberFormatValue, format?: Intl.NumberFormatOptions): string {
     return number(this._locales || this._locale, value, format)
   }
 }

packages/core/src/interpolate.ts

@@ -2,7 +2,9 @@ import { CompiledMessage, Formats, Locales, Values } from "./i18n"
 import {
   date,
   DateTimeFormatSize,
+  type DateTimeFormatValue,
   number,
+  type NumberFormatValue,
   plural,
   type PluralOptions,
   time,
@@ -51,7 +53,7 @@ const getDefaultFormats = (
     select: selectFormatter,
 
     number: (
-      value: number,
+      value: NumberFormatValue,
       format: string | Intl.NumberFormatOptions
     ): string =>
       number(
@@ -61,11 +63,11 @@ const getDefaultFormats = (
       ),
 
     date: (
-      value: string,
+      value: string | DateTimeFormatValue,
       format: Intl.DateTimeFormatOptions | string
     ): string =>
       date(locales, value, style(format) || (format as DateTimeFormatSize)),
-    time: (value: string, format: string): string =>
+    time: (value: string | DateTimeFormatValue, format: string): string =>
       time(locales, value, style(format) || (format as DateTimeFormatSize)),
   } as const
 }

website/docs/ref/core.md

@@ -220,11 +220,12 @@ import { i18n } from "@lingui/core";
 i18n.t({ id: "Hello" });
 ```
 
-### `i18n.date(value: string | Date[, format: Intl.DateTimeFormatOptions])` {#i18n.date}
+### `i18n.date(value: string | Date | number[, format: Intl.DateTimeFormatOptions])` {#i18n.date}
 
 Format a date using the conventional format for the active language.
 
-- `date`: a `Date` object to be formatted. When `date` is a string, the `Date` object is created using `new Date(date)`.
+- `value`: the date to be formatted, as accepted by [`Intl.DateTimeFormat.prototype.format`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/format#parameters).
+  When `value` is a string, a `Date` object is created using `new Date(date)`.
 - `format`: an optional object that is passed to the `options` argument of the [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor. This allows for customization of the date formatting.
 
 ```ts
@@ -247,11 +248,11 @@ i18n.date(d);
 // Returns "23. 7. 2021"
 ```
 
-### `i18n.number(value: number[, format: Intl.NumberFormatOptions])` {#i18n.number}
+### `i18n.number(value: number | bigint | Intl.StringNumericLiteral[, format: Intl.NumberFormatOptions])` {#i18n.number}
 
 Format a number using the conventional format for the active language.
 
-- `number`: a number to be formatted.
+- `value`: the number to be formatted, as accepted by [`Intl.NumberFormat.prototype.format`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/format#parameters).
 - `format`: an optional object that is passed to the `options` argument of the [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) constructor. This allows for customization of the date formatting.
 
 ```ts