feat: Typesafe Global Formats

examples/example-app-router/global.d.ts

@@ -1,8 +1,11 @@
 import en from './messages/en.json';
+import {formats} from './src/i18n/request';
 
 type Messages = typeof en;
+type Formats = typeof formats;
 
 declare global {
  // Use type safe message keys with `next-intl`
  interface IntlMessages extends Messages {}
+ interface IntlFormats extends Formats {}
 }

examples/example-app-router/src/i18n/request.ts

@@ -1,7 +1,29 @@
 import {notFound} from 'next/navigation';
+import {Formats} from 'next-intl';
 import {getRequestConfig} from 'next-intl/server';
 import {routing} from './routing';
 
+export const formats = {
+ dateTime: {
+ short: {
+ day: 'numeric',
+ month: 'short',
+ year: 'numeric'
+ }
+ },
+ number: {
+ precise: {
+ maximumFractionDigits: 5
+ }
+ },
+ list: {
+ enumeration: {
+ style: 'long',
+ type: 'conjunction'
+ }
+ }
+} as const satisfies Partial<Formats>;
+
 export default getRequestConfig(async ({locale}) => {
  // Validate that the incoming `locale` parameter is valid
  if (!routing.locales.includes(locale as any)) notFound();
@@ -12,6 +34,7 @@ export default getRequestConfig(async ({locale}) => {
  ? // When using Turbopack, this will enable HMR for `en`
  import('../../messages/en.json')
  : import(`../../messages/${locale}.json`))
- ).default
+ ).default,
+ formats
  };
 });

packages/use-intl/src/core/createFormatter.tsx

@@ -163,7 +163,11 @@ export default function createFormatter({
  value: Date | number,
  /** If a time zone is supplied, the `value` is converted to that time zone.
  * Otherwise the user time zone will be used. */
- formatOrOptions?: string | DateTimeFormatOptions
+ formatOrOptions?:
+ | (keyof IntlFormats['dateTime'] extends string
+ ? IntlFormats['dateTime']
+ : string)
+ | DateTimeFormatOptions
  ) {
  return getFormattedValue(
  formatOrOptions,
@@ -183,7 +187,11 @@ export default function createFormatter({
  end: Date | number,
  /** If a time zone is supplied, the values are converted to that time zone.
  * Otherwise the user time zone will be used. */
- formatOrOptions?: string | DateTimeFormatOptions
+ formatOrOptions?:
+ | (keyof IntlFormats['dateTime'] extends string
+ ? IntlFormats['dateTime']
+ : string)
+ | DateTimeFormatOptions
  ) {
  return getFormattedValue(
  formatOrOptions,
@@ -200,7 +208,11 @@ export default function createFormatter({
 
  function number(
  value: number | bigint,
- formatOrOptions?: string | NumberFormatOptions
+ formatOrOptions?:
+ | (keyof IntlFormats['number'] extends string
+ ? IntlFormats['number']
+ : string)
+ | NumberFormatOptions
  ) {
  return getFormattedValue(
  formatOrOptions,
@@ -284,7 +296,11 @@ export default function createFormatter({
  type FormattableListValue = string | ReactElement;
  function list<Value extends FormattableListValue>(
  value: Iterable<Value>,
- formatOrOptions?: string | Intl.ListFormatOptions
+ formatOrOptions?:
+ | (keyof IntlFormats['list'] extends string
+ ? IntlFormats['list']
+ : string)
+ | Intl.ListFormatOptions
  ): Value extends string ? string : Iterable<ReactElement> {
  const serializedValue: Array<string> = [];
  const richValues = new Map<string, Value>();

packages/use-intl/types/index.d.ts

@@ -1,7 +1,15 @@
 // This type is intended to be overridden
-// by the consumer for optional type safety
+// by the consumer for optional type safety of messages
 declare interface IntlMessages extends Record<string, any> {}
 
+// This type is intended to be overridden
+// by the consumer for optional type safety of formats
+declare interface IntlFormats {
+ dateTime: any;
+ number: any;
+ list: any;
+}
+
 // Temporarly copied here until the "es2020.intl" lib is published.
 
 declare namespace Intl {