feat(intl-messageformat): allow passing in formatters (#107)

Author: longlho

packages/babel-plugin-react-intl/CHANGELOG.md

@@ -7,10 +7,6 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 **Note:** Version bump only for package babel-plugin-react-intl
 
-
-
-
-
 # [3.4.0](https://github.com/formatjs/formatjs/compare/[email protected]@3.4.0) (2019-06-27)
 
 ### Features

packages/formatjs-extract-cldr-data/CHANGELOG.md

@@ -7,10 +7,6 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 **Note:** Version bump only for package formatjs-extract-cldr-data
 
-
-
-
-
 # [9.1.0](https://github.com/formatjs/formatjs/compare/[email protected]@9.1.0) (2019-06-27)
 
 ### Features

packages/intl-format-cache/CHANGELOG.md

@@ -7,10 +7,6 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 **Note:** Version bump only for package intl-format-cache
 
-
-
-
-
 # [3.2.0](https://github.com/formatjs/formatjs/compare/[email protected]@3.2.0) (2019-06-27)
 
 ### Features

packages/intl-locales-supported/CHANGELOG.md

@@ -7,10 +7,6 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 **Note:** Version bump only for package intl-locales-supported
 
-
-
-
-
 # [1.2.0](https://github.com/formatjs/formatjs/compare/[email protected]@1.2.0) (2019-06-27)
 
 ### Features

packages/intl-messageformat-parser/CHANGELOG.md

@@ -5,14 +5,9 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 ## [1.7.1](https://github.com/formatjs/formatjs/compare/[email protected]@1.7.1) (2019-06-26)
 
-
 ### Bug Fixes
 
-* **intl-messageformat-parser:** Escape double-' to a single ' ([#103](https://github.com/formatjs/formatjs/issues/103)) ([4d0cd1f](https://github.com/formatjs/formatjs/commit/4d0cd1f))
-
-
-
-
+- **intl-messageformat-parser:** Escape double-' to a single ' ([#103](https://github.com/formatjs/formatjs/issues/103)) ([4d0cd1f](https://github.com/formatjs/formatjs/commit/4d0cd1f))
 
 # [1.7.0](https://github.com/formatjs/formatjs/compare/[email protected]@1.7.0) (2019-06-27)
 

packages/intl-messageformat/CHANGELOG.md

@@ -7,10 +7,6 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 **Note:** Version bump only for package intl-messageformat
 
-
-
-
-
 # [4.2.0](https://github.com/formatjs/formatjs/compare/[email protected]@4.2.0) (2019-06-27)
 
 ### Features

packages/intl-messageformat/README.md

@@ -23,7 +23,7 @@ _Note: This `IntlMessageFormat` API may change to stay in sync with ECMA-402, bu
 Messages are provided into the constructor as a `String` message, or a [pre-parsed AST][parser] object.
 
 ```js
-var msg = new IntlMessageFormat(message, locales, [formats]);
+var msg = new IntlMessageFormat(message, locales, [formats], [opts]);
 ```
 
 The string `message` is parsed, then stored internally in a compiled form that is optimized for the `format()` method to produce the formatted string for displaying to the user.
@@ -122,6 +122,9 @@ To create a message to format, use the `IntlMessageFormat` constructor. The cons
 
 - **[formats]** - _{Object}_ - Optional object with user defined options for format styles.
 
+- **[opts]** - `{ formatters?: Formatters }`: Optional options.
+  - `formatters`: Map containing memoized formatters for performance.
+
 ```js
 var msg = new IntlMessageFormat('My name is {name}.', 'en-US');
 ```
@@ -178,6 +181,8 @@ In this example, we're defining a `USD` number format style which is passed to t
 
 ## Advanced Usage
 
+### Core entry point
+
 We also expose another entry point via `intl-messageformat/core` that does not contain the parser from `intl-messageformat-parser`. This is significantly smaller than the regular package but expects the message passed in to be in `AST` form instead of string. E.g:
 
 ```ts
@@ -193,6 +198,25 @@ new IntlMessageFormat(parser.parse('hello')).format(); // prints out hello
 
 This helps performance for cases like SSR or preload/precompilation-supported platforms since `AST` can be cached.
 
+### Formatters
+
+For complex messages, initializing `Intl.*` constructors can be expensive. Therefore, we allow user to pass in `formatters` to provide memoized instances of these `Intl` objects. This opts combines with passing in AST + using [core entry point](#core-entry-point) and `intl-format-cache` can speed things up by 30x per the benchmark down below.
+
+For example:
+
+```ts
+import IntlMessageFormat from 'intl-messageformat';
+import memoizeIntlConstructor from 'intl-format-cache';
+const formatters = {
+  getNumberFormat: memoizeIntlConstructor(Intl.NumberFormat),
+  getDateTimeFormat: memoizeIntlConstructor(Intl.DateTimeFormat),
+  getPluralRules: memoizeIntlConstructor(Intl.PluralRules)
+};
+new IntlMessageFormat('hello {number, number}', 'en', undefined, {
+  formatters
+}).format({ number: 3 }); // prints out `hello, 3`
+```
+
 ## Examples
 
 ### Plural Label
@@ -222,6 +246,19 @@ console.log(msg.format({numPhotos: 1000})); // => "You have 1,000 photos."
 
 _Note: how when `numPhotos` was `1000`, the number is formatted with the correct thousands separator._
 
+## Benchmark
+
+```
+format_cached_complex_msg x 539,674 ops/sec ±1.87% (87 runs sampled)
+format_cached_string_msg x 99,311,640 ops/sec ±2.15% (87 runs sampled)
+new_complex_msg_preparsed x 1,490 ops/sec ±8.37% (54 runs sampled)
+new_complex_msg x 836 ops/sec ±31.96% (67 runs sampled)
+new_string_msg x 27,752 ops/sec ±8.25% (65 runs sampled)
+complex msg format x 799 ops/sec ±9.38% (55 runs sampled)
+complex msg w/ formatters format x 1,878 ops/sec ±16.63% (64 runs sampled)
+complex preparsed msg w/ formatters format x 26,482 ops/sec ±2.55% (84 runs sampled)
+```
+
 ## License
 
 This software is free to use under the Yahoo! Inc. BSD license.

packages/intl-messageformat/src/compiler.ts

@@ -18,6 +18,18 @@ export interface Formats {
   time: Record<string, Intl.DateTimeFormatOptions>;
 }
 
+export interface Formatters {
+  getNumberFormat(
+    ...args: ConstructorParameters<typeof Intl.NumberFormat>
+  ): Intl.NumberFormat;
+  getDateTimeFormat(
+    ...args: ConstructorParameters<typeof Intl.DateTimeFormat>
+  ): Intl.DateTimeFormat;
+  getPluralRules(
+    ...args: ConstructorParameters<typeof Intl.PluralRules>
+  ): Intl.PluralRules;
+}
+
 export type Pattern =
   | string
   | PluralOffsetString
@@ -35,10 +47,16 @@ export default class Compiler {
   private pluralNumberFormat: Intl.NumberFormat | null = null;
   private currentPlural: ArgumentElement | null | undefined = null;
   private pluralStack: Array<ArgumentElement | null | undefined> = [];
+  private formatters: Formatters;
 
-  constructor(locales: string | string[], formats: Formats) {
+  constructor(
+    locales: string | string[],
+    formats: Formats,
+    formatters: Formatters
+  ) {
     this.locales = locales;
     this.formats = formats;
+    this.formatters = formatters;
   }
 
   compile(ast: MessageFormatPattern): Pattern[] {
@@ -96,6 +114,7 @@ export default class Compiler {
 
   compileArgument(element: ArgumentElement) {
     const { format, id } = element;
+    const { formatters } = this;
 
     if (!format) {
       return new StringFormat(id);
@@ -106,31 +125,38 @@ export default class Compiler {
       case 'numberFormat':
         return {
           id,
-          format: new Intl.NumberFormat(locales, formats.number[format.style])
-            .format
+          format: formatters.getNumberFormat(
+            locales,
+            formats.number[format.style]
+          ).format
         };
 
       case 'dateFormat':
         return {
           id,
-          format: new Intl.DateTimeFormat(locales, formats.date[format.style])
-            .format
+          format: formatters.getDateTimeFormat(
+            locales,
+            formats.date[format.style]
+          ).format
         };
 
       case 'timeFormat':
         return {
           id,
-          format: new Intl.DateTimeFormat(locales, formats.time[format.style])
-            .format
+          format: formatters.getDateTimeFormat(
+            locales,
+            formats.time[format.style]
+          ).format
         };
 
       case 'pluralFormat':
         return new PluralFormat(
           id,
-          format.ordinal,
           format.offset,
           this.compileOptions(element),
-          locales
+          formatters.getPluralRules(locales, {
+            type: format.ordinal ? 'ordinal' : 'cardinal'
+          })
         );
 
       case 'selectFormat':
@@ -176,7 +202,7 @@ abstract class Formatter {
   abstract format(value: string | number): string;
 }
 
-export class StringFormat extends Formatter {
+class StringFormat extends Formatter {
   format(value: number | string) {
     if (!value && typeof value !== 'number') {
       return '';
@@ -186,24 +212,21 @@ export class StringFormat extends Formatter {
   }
 }
 
-export class PluralFormat {
+class PluralFormat {
   public id: string;
   private offset: number;
   private options: Record<string, Pattern[]>;
   private pluralRules: Intl.PluralRules;
   constructor(
     id: string,
-    useOrdinal: boolean,
     offset: number,
     options: Record<string, Pattern[]>,
-    locales: string | string[]
+    pluralRules: Intl.PluralRules
   ) {
     this.id = id;
     this.offset = offset;
     this.options = options;
-    this.pluralRules = new Intl.PluralRules(locales, {
-      type: useOrdinal ? 'ordinal' : 'cardinal'
-    });
+    this.pluralRules = pluralRules;
   }
 
   getOption(value: number) {