@formatjs/intl 2.3.1 → 2.3.2

package/src/utils.ts

@@ -0,0 +1,177 @@
+import {
+  IntlCache,
+  CustomFormats,
+  Formatters,
+  OnErrorFn,
+  OnWarnFn,
+  ResolvedIntlConfig,
+} from './types'
+import {IntlMessageFormat} from 'intl-messageformat'
+import memoize, {Cache, strategies} from '@formatjs/fast-memoize'
+import {UnsupportedFormatterError} from './error'
+import {DateTimeFormat, NumberFormatOptions} from '@formatjs/ecma402-abstract'
+
+export function filterProps<T extends Record<string, any>, K extends string>(
+  props: T,
+  allowlist: Array<K>,
+  defaults: Partial<T> = {}
+): Pick<T, K> {
+  return allowlist.reduce((filtered, name) => {
+    if (name in props) {
+      filtered[name] = props[name]
+    } else if (name in defaults) {
+      filtered[name] = defaults[name]!
+    }
+
+    return filtered
+  }, {} as Pick<T, K>)
+}
+
+const defaultErrorHandler: OnErrorFn = error => {
+  // @ts-ignore just so we don't need to declare dep on @types/node
+  if (process.env.NODE_ENV !== 'production') {
+    console.error(error)
+  }
+}
+
+const defaultWarnHandler: OnWarnFn = (warning: string) => {
+  // @ts-ignore just so we don't need to declare dep on @types/node
+  if (process.env.NODE_ENV !== 'production') {
+    console.warn(warning)
+  }
+}
+
+export const DEFAULT_INTL_CONFIG: Pick<
+  ResolvedIntlConfig<any>,
+  | 'fallbackOnEmptyString'
+  | 'formats'
+  | 'messages'
+  | 'timeZone'
+  | 'defaultLocale'
+  | 'defaultFormats'
+  | 'onError'
+  | 'onWarn'
+> = {
+  formats: {},
+  messages: {},
+  timeZone: undefined,
+
+  defaultLocale: 'en',
+  defaultFormats: {},
+
+  fallbackOnEmptyString: true,
+
+  onError: defaultErrorHandler,
+  onWarn: defaultWarnHandler,
+}
+
+export function createIntlCache(): IntlCache {
+  return {
+    dateTime: {},
+    number: {},
+    message: {},
+    relativeTime: {},
+    pluralRules: {},
+    list: {},
+    displayNames: {},
+  }
+}
+
+function createFastMemoizeCache<V>(store: Record<string, V>): Cache<string, V> {
+  return {
+    create() {
+      return {
+        get(key) {
+          return store[key]
+        },
+        set(key, value) {
+          store[key] = value
+        },
+      }
+    },
+  }
+}
+
+/**
+ * Create intl formatters and populate cache
+ * @param cache explicit cache to prevent leaking memory
+ */
+export function createFormatters(
+  cache: IntlCache = createIntlCache()
+): Formatters {
+  const RelativeTimeFormat = (Intl as any).RelativeTimeFormat
+  const ListFormat = (Intl as any).ListFormat
+  const DisplayNames = (Intl as any).DisplayNames
+  const getDateTimeFormat = memoize(
+    (...args) => new Intl.DateTimeFormat(...args) as DateTimeFormat,
+    {
+      cache: createFastMemoizeCache(cache.dateTime),
+      strategy: strategies.variadic,
+    }
+  )
+  const getNumberFormat = memoize((...args) => new Intl.NumberFormat(...args), {
+    cache: createFastMemoizeCache(cache.number),
+    strategy: strategies.variadic,
+  })
+  const getPluralRules = memoize((...args) => new Intl.PluralRules(...args), {
+    cache: createFastMemoizeCache(cache.pluralRules),
+    strategy: strategies.variadic,
+  })
+  return {
+    getDateTimeFormat,
+    getNumberFormat,
+    getMessageFormat: memoize(
+      (message, locales, overrideFormats, opts) =>
+        new IntlMessageFormat(message, locales, overrideFormats, {
+          formatters: {
+            getNumberFormat,
+            getDateTimeFormat,
+            getPluralRules,
+          },
+          ...(opts || {}),
+        }),
+      {
+        cache: createFastMemoizeCache(cache.message),
+        strategy: strategies.variadic,
+      }
+    ),
+    getRelativeTimeFormat: memoize(
+      (...args) => new RelativeTimeFormat(...args),
+      {
+        cache: createFastMemoizeCache(cache.relativeTime),
+        strategy: strategies.variadic,
+      }
+    ),
+    getPluralRules,
+    getListFormat: memoize((...args) => new ListFormat(...args), {
+      cache: createFastMemoizeCache(cache.list),
+      strategy: strategies.variadic,
+    }),
+    getDisplayNames: memoize((...args) => new DisplayNames(...args), {
+      cache: createFastMemoizeCache(cache.displayNames),
+      strategy: strategies.variadic,
+    }),
+  }
+}
+
+export function getNamedFormat<T extends keyof CustomFormats>(
+  formats: CustomFormats,
+  type: T,
+  name: string,
+  onError: OnErrorFn
+):
+  | NumberFormatOptions
+  | Intl.DateTimeFormatOptions
+  | Intl.RelativeTimeFormatOptions
+  | undefined {
+  const formatType = formats && formats[type]
+  let format
+  if (formatType) {
+    format = formatType[name]
+  }
+  if (format) {
+    return format
+  }
+
+  onError(new UnsupportedFormatterError(`No ${type} format named: ${name}`))
+}

package/tests/__snapshots__/formatDate.test.ts.snap

@@ -0,0 +1,13 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`format API formatDate() options falls back and warns on invalid Intl.DateTimeFormat options 1`] = `
+Array [
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatDate() options handles missing named formats and warns 1`] = `
+Array [
+  "UNSUPPORTED_FORMATTER",
+]
+`;

package/tests/__snapshots__/formatMessage.test.ts.snap

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`format API formatMessage() fallbacks formats \`defaultMessage\` when message has a syntax error 1`] = `
+Array [
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatMessage() fallbacks formats \`defaultMessage\` when message has missing values 1`] = `
+Array [
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatMessage() fallbacks returns \`defaultMessage\` source when formatting errors and missing message 1`] = `
+Array [
+  "MISSING_TRANSLATION",
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatMessage() fallbacks returns message \`id\` when message and \`defaultMessage\` are empty 1`] = `
+Array [
+  "MISSING_TRANSLATION",
+]
+`;
+
+exports[`format API formatMessage() fallbacks returns message \`id\` when message and \`defaultMessage\` are missing 1`] = `
+Array [
+  "MISSING_TRANSLATION",
+]
+`;
+
+exports[`format API formatMessage() fallbacks returns message source when formatting error and missing \`defaultMessage\` 1`] = `
+Array [
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatMessage() fallbacks returns message source when message and \`defaultMessage\` have formatting errors 1`] = `
+Array [
+  "FORMAT_ERROR",
+  "FORMAT_ERROR",
+]
+`;

package/tests/__snapshots__/formatNumber.test.ts.snap

@@ -0,0 +1,13 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`format API formatNumber() options falls back and warns on invalid Intl.NumberFormat options 1`] = `
+Array [
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatNumber() options handles missing named formats and warns 1`] = `
+Array [
+  "UNSUPPORTED_FORMATTER",
+]
+`;

package/tests/__snapshots__/formatRelativeTime.test.ts.snap

@@ -0,0 +1,19 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`format API formatRelativeTime() falls back and warns when no value is provided 1`] = `
+Array [
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatRelativeTime() options falls back and warns on invalid IntlRelativeFormat options 1`] = `
+Array [
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatRelativeTime() options handles missing named formats and warns 1`] = `
+Array [
+  "UNSUPPORTED_FORMATTER",
+]
+`;

package/tests/__snapshots__/formatTime.test.ts.snap

@@ -0,0 +1,13 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`format API formatTime() options falls back and warns on invalid Intl.DateTimeFormat options 1`] = `
+Array [
+  "FORMAT_ERROR",
+]
+`;
+
+exports[`format API formatTime() options handles missing named formats and warns 1`] = `
+Array [
+  "UNSUPPORTED_FORMATTER",
+]
+`;

package/tests/create-intl.test.ts

@@ -0,0 +1,60 @@
+import {createIntl} from '../src/create-intl'
+
+test('createIntl', function () {
+  const intl = createIntl({
+    locale: 'en',
+    messages: {
+      foo: 'bar',
+    },
+  })
+  expect(
+    intl.formatMessage({
+      id: 'foo',
+    })
+  ).toBe('bar')
+})
+
+test('should warn when defaultRichTextElements is used with messages', function () {
+  const onWarn = jest.fn()
+  createIntl({
+    locale: 'en',
+    messages: {
+      foo: 'bar',
+    },
+    defaultRichTextElements: {},
+    onWarn,
+  })
+  expect(onWarn).toHaveBeenCalledWith(
+    expect.stringContaining(
+      `defaultRichTextElements" was specified but "message" was not pre-compiled.`
+    )
+  )
+})
+
+test('should not warn when defaultRichTextElements is not used', function () {
+  const onWarn = jest.fn()
+  createIntl({
+    locale: 'en',
+    messages: {
+      foo: 'bar',
+    },
+    onWarn,
+  })
+  expect(onWarn).not.toHaveBeenCalled()
+})
+
+test('should use the default warn handler when none is passed', function () {
+  const warnFn = jest.spyOn(console, 'warn')
+  createIntl({
+    locale: 'en',
+    messages: {
+      foo: 'bar',
+    },
+    defaultRichTextElements: {},
+  })
+  expect(warnFn).toHaveBeenCalledWith(
+    expect.stringContaining(
+      `defaultRichTextElements" was specified but "message" was not pre-compiled.`
+    )
+  )
+})

package/tests/error.test.ts

@@ -0,0 +1,25 @@
+import {MissingTranslationError} from '../src/error'
+
+describe('MissingTranslationError', () => {
+  it('records the actual default message', () => {
+    const e = new MissingTranslationError(
+      {defaultMessage: 'some message'},
+      'en'
+    )
+    expect(e.toString()).toMatch(/default message \(some message\)/)
+  })
+
+  it('records the actual default message for MessageFormatElement[]', () => {
+    // this works for all `MessageFormatElement` except for `PoundElement`
+    const e = new MissingTranslationError(
+      {defaultMessage: [{type: 0, value: 'some message'}]},
+      'en'
+    )
+    expect(e.toString()).toMatch(/default message \(some message\)/)
+  })
+
+  it('records the actual default message for PoundElement[]', () => {
+    const e = new MissingTranslationError({defaultMessage: [{type: 7}]}, 'en')
+    expect(e.toString()).toMatch(/default message \(\{"type":7\}\)/)
+  })
+})

package/tests/formatDate.test.ts

@@ -0,0 +1,167 @@
+/* eslint-disable @typescript-eslint/camelcase */
+import {formatDate as formatDateFn} from '../src/dateTime'
+import {IntlConfig, IntlFormatters} from '../src/types'
+
+describe('format API', () => {
+  const {NODE_ENV} = process.env
+
+  let config: IntlConfig<any>
+
+  let getDateTimeFormat: any
+  beforeEach(() => {
+    config = {
+      locale: 'en',
+
+      messages: {},
+
+      formats: {
+        date: {
+          'year-only': {
+            year: 'numeric',
+          },
+          missing: undefined,
+        },
+      } as any,
+
+      defaultLocale: 'en',
+      defaultFormats: {},
+
+      onError: jest.fn(),
+    }
+
+    getDateTimeFormat = jest
+      .fn()
+      .mockImplementation((...args) => new Intl.DateTimeFormat(...args))
+  })
+
+  afterEach(() => {
+    process.env.NODE_ENV = NODE_ENV
+  })
+
+  describe('formatDate()', () => {
+    let df: Intl.DateTimeFormat
+    let formatDate: IntlFormatters['formatDate']
+
+    beforeEach(() => {
+      df = new Intl.DateTimeFormat(config.locale)
+
+      // @ts-ignore
+      formatDate = formatDateFn.bind(null, config, getDateTimeFormat)
+    })
+
+    it('no value should render today', () => {
+      // @ts-ignore
+      expect(formatDate()).toBe(df.format())
+    })
+
+    it('falls back and warns when a non-finite value is provided', () => {
+      expect(formatDate(NaN)).toBe('NaN')
+      expect(config.onError as jest.Mock).toHaveBeenCalledTimes(1)
+    })
+
+    it('formats falsy finite values', () => {
+      // @ts-ignore
+      expect(formatDate(null)).toBe(df.format(null))
+      expect(formatDate(0)).toBe(df.format(0))
+    })
+
+    it('formats date instance values', () => {
+      expect(formatDate(new Date(0))).toBe(df.format(new Date(0)))
+    })
+
+    it('formats date string values', () => {
+      expect(formatDate(new Date(0).toString())).toBe(df.format(0))
+    })
+
+    it('formats date ms timestamp values', () => {
+      const timestamp = Date.now()
+      expect(formatDate(timestamp)).toBe(df.format(timestamp))
+    })
+
+    it('uses the time zone specified by the provider', () => {
+      const timestamp = Date.now()
+      config.timeZone = 'Pacific/Wake'
+      // @ts-ignore
+      formatDate = formatDateFn.bind(null, config, getDateTimeFormat)
+      const wakeDf = new Intl.DateTimeFormat(config.locale, {
+        timeZone: 'Pacific/Wake',
+      })
+      expect(formatDate(timestamp)).toBe(wakeDf.format(timestamp))
+      config.timeZone = 'Asia/Shanghai'
+
+      // @ts-ignore
+      formatDate = formatDateFn.bind(null, config, getDateTimeFormat)
+      const shanghaiDf = new Intl.DateTimeFormat(config.locale, {
+        timeZone: 'Asia/Shanghai',
+      })
+      expect(formatDate(timestamp)).toBe(shanghaiDf.format(timestamp))
+    })
+
+    describe('options', () => {
+      it('accepts empty options', () => {
+        expect(formatDate(0, {})).toBe(df.format(0))
+      })
+
+      it('accepts valid Intl.DateTimeFormat options', () => {
+        expect(() => formatDate(0, {year: 'numeric'})).not.toThrow()
+      })
+
+      it('falls back and warns on invalid Intl.DateTimeFormat options', () => {
+        // @ts-expect-error invalid year just for testing
+        expect(formatDate(0, {year: 'invalid'})).toBe('0')
+        expect(
+          (config.onError as jest.Mock).mock.calls.map(c => c[0].code)
+        ).toMatchSnapshot()
+      })
+
+      it('uses configured named formats', () => {
+        const date = new Date()
+        const format = 'year-only'
+
+        const {locale, formats} = config
+        df = new Intl.DateTimeFormat(locale, formats!.date![format])
+
+        expect(formatDate(date, {format})).toBe(df.format(date))
+      })
+
+      it('uses named formats as defaults', () => {
+        const date = new Date()
+        const opts: Intl.DateTimeFormatOptions = {month: 'numeric'}
+        const format = 'year-only'
+
+        const {locale, formats} = config
+        df = new Intl.DateTimeFormat(locale, {
+          ...opts,
+          ...formats!.date![format],
+        })
+
+        expect(formatDate(date, {...opts, format})).toBe(df.format(date))
+      })
+
+      it('handles missing named formats and warns', () => {
+        const date = new Date()
+        const format = 'missing'
+
+        df = new Intl.DateTimeFormat(config.locale)
+
+        expect(formatDate(date, {format})).toBe(df.format(date))
+        expect(
+          (config.onError as jest.Mock).mock.calls.map(c => c[0].code)
+        ).toMatchSnapshot()
+      })
+
+      it('uses time zone specified in options over the one passed through by the provider', () => {
+        const timestamp = Date.now()
+        config.timeZone = 'Pacific/Wake'
+        // @ts-ignore
+        formatDate = formatDateFn.bind(null, config, getDateTimeFormat)
+        const shanghaiDf = new Intl.DateTimeFormat(config.locale, {
+          timeZone: 'Asia/Shanghai',
+        })
+        expect(formatDate(timestamp, {timeZone: 'Asia/Shanghai'})).toBe(
+          shanghaiDf.format(timestamp)
+        )
+      })
+    })
+  })
+})

package/tests/formatDisplayNames.test.ts

@@ -0,0 +1,63 @@
+/* eslint-disable @typescript-eslint/camelcase */
+import '@formatjs/intl-displaynames/polyfill'
+import '@formatjs/intl-displaynames/locale-data/en'
+import '@formatjs/intl-displaynames/locale-data/zh-Hans-SG'
+import {formatDisplayName as formatDisplayNameFn} from '../src/displayName'
+import {IntlConfig, IntlFormatters} from '../src/types'
+
+describe('format API', () => {
+  const {NODE_ENV} = process.env
+
+  let config: IntlConfig<any>
+  let getDisplayNames: any
+  beforeEach(() => {
+    config = {
+      locale: 'en',
+
+      messages: {},
+
+      defaultLocale: 'en',
+      defaultFormats: {},
+
+      onError: jest.fn(),
+    }
+
+    getDisplayNames = jest
+      .fn()
+      .mockImplementation((...args) => new (Intl as any).DisplayNames(...args))
+  })
+
+  afterEach(() => {
+    process.env.NODE_ENV = NODE_ENV
+  })
+
+  describe('formatDisplayNames()', function () {
+    let formatDisplayName!: IntlFormatters['formatDisplayName']
+
+    beforeEach(() => {
+      // @ts-ignore
+      formatDisplayName = formatDisplayNameFn.bind(
+        null,
+        config,
+        getDisplayNames
+      )
+    })
+
+    it('should return locale display name as string', function () {
+      expect(formatDisplayName('zh-Hans-SG', {type: 'language'})).toBe(
+        'Simplified Chinese (Singapore)'
+      )
+    })
+
+    it('will return undefined if Intl.DisplayName would return undefined', function () {
+      const displayName = new (Intl as any).DisplayNames('en', {
+        type: 'language',
+        fallback: 'none',
+      })
+      expect(displayName.of('xx-XX')).toBeUndefined()
+      expect(
+        formatDisplayName('xx-XX', {type: 'language', fallback: 'none'})
+      ).toBeUndefined()
+    })
+  })
+})

package/tests/formatList.test.ts

@@ -0,0 +1,51 @@
+/* eslint-disable @typescript-eslint/camelcase */
+import {formatList as formatListFn} from '../src/list'
+
+import {IntlConfig, IntlFormatters} from '../src/types'
+
+describe('format API', () => {
+  const {NODE_ENV} = process.env
+
+  let config: IntlConfig<any>
+  let getListFormat: any
+  beforeEach(() => {
+    config = {
+      locale: 'en',
+
+      messages: {},
+
+      defaultLocale: 'en',
+      defaultFormats: {},
+
+      onError: jest.fn(),
+    }
+
+    getListFormat = jest
+      .fn()
+      .mockImplementation((...args) => new Intl.ListFormat(...args))
+  })
+
+  afterEach(() => {
+    process.env.NODE_ENV = NODE_ENV
+  })
+
+  describe('formatList()', function () {
+    let formatList: IntlFormatters['formatList']
+
+    beforeEach(() => {
+      // @ts-ignore
+      formatList = formatListFn.bind(null, config, getListFormat)
+    })
+
+    it('should handle regular element', function () {
+      expect(formatList(['me', 'myself', 'I'])).toBe('me, myself, and I')
+    })
+    it('should handle regular element', function () {
+      expect(formatList(['me', {foo: 'myself'}, 'I'])).toEqual([
+        'me, ',
+        {foo: 'myself'},
+        ', and I',
+      ])
+    })
+  })
+})