@discord/intl-loader-core 0.10.0 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl-loader-core",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "license": "MIT",
   "description": "Core utilities for writing loaders and transformers using @discord/intl",
   "author": "Jon Egeland",
@@ -29,7 +29,7 @@
     "chokidar": "^3.6.0",
     "debug": "^4.3.6",
     "fast-glob": "^3.3.2",
-    "@discord/intl-message-database": "0.10.0"
+    "@discord/intl-message-database": "0.10.2"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",

package/src/transformer.js

@@ -110,11 +110,31 @@ class MessageDefinitionsTransformer {
     ];
   }
 
+  /**
+   * Return a map of key names to bound message getter functions. If `preGenerateBinds` is
+   * configured to be `true`, the binds will be created as a constant object in the output.
+   * Otherwise, the generation will be done at runtime through the `getBinds` method on the loader.
+   */
+  createBindsObject() {
+    if (this.options.preGenerateBinds) {
+      /** @type {string[]} */
+      const bindLines = [];
+      for (const bind of Object.keys(this.options.messageKeys)) {
+        bindLines.push(`"${bind}"(locale) { return ${this.loaderName}.get("${bind}", locale) }`);
+      }
+      return `{${bindLines.join(',')}}`;
+    } else {
+      return `${this.loaderName}.getBinds()`;
+    }
+  }
+
   /**
    * Return the lines to export fields from this module, as determined by the `exportMode` on this
    * transformer.
+   *
+   * @param {string} bindsName Name of the identifier to be exported as the default binds object.
    */
-  exportFields() {
+  exportFields(bindsName) {
     switch (this.options.exportMode ?? 'esm') {
       case 'esm':
         return [`export {${this.loaderName}};`, `export default binds;`];
@@ -137,16 +157,16 @@ class MessageDefinitionsTransformer {
    * @returns {string}
    */
   getOutput() {
+    const bindsObject = this.createBindsObject();
     return [
       this.options.getPrelude?.() ?? '// No additional prelude was configured.',
       `const {createLoader} = require('@discord/intl');`,
-      `const _keys = ${JSON.stringify(Object.keys(this.options.messageKeys))};`,
+      `const binds = ${bindsObject}`,
       `const _locales = ${this.getLocaleRequireMap()};`,
       `const _defaultLocale = ${JSON.stringify(this.options.defaultLocale)};`,
-      `const ${this.loaderName} = createLoader(_keys, _locales, _defaultLocale);`,
+      `const ${this.loaderName} = createLoader(Object.keys(binds), _locales, _defaultLocale);`,
       ...this.debugModeSetup(),
-      `const binds = ${this.loaderName}.getBinds();`,
-      ...this.exportFields(),
+      ...this.exportFields('binds'),
     ].join('\n');
   }
 }

package/types/src/transformer.d.ts

@@ -90,11 +90,19 @@ export class MessageDefinitionsTransformer {
      * @returns {string[]}
      */
     debugModeSetup(): string[];
+    /**
+     * Return a map of key names to bound message getter functions. If `preGenerateBinds` is
+     * configured to be `true`, the binds will be created as a constant object in the output.
+     * Otherwise, the generation will be done at runtime through the `getBinds` method on the loader.
+     */
+    createBindsObject(): string;
     /**
      * Return the lines to export fields from this module, as determined by the `exportMode` on this
      * transformer.
+     *
+     * @param {string} bindsName Name of the identifier to be exported as the default binds object.
      */
-    exportFields(): string[];
+    exportFields(bindsName: string): string[];
     /**
      * Returns the reduced, transformed output for this file. Currently not
      * configurable, but could be told to include default messages or preserve

package/types/types.d.ts

@@ -53,6 +53,22 @@ export interface MessageDefinitionsTransformerOptions {
    * @default esm
    */
   exportMode?: 'esm' | 'commonjs' | 'transpiledEsModule';
+  /**
+   * Control how loader binds are generated by the transformer. When `false` (the default), binds
+   * will be created at runtime using `messagesLoader.getBinds()`. This mode saves space, at the
+   * cost of runtime overhead to iterate and create bound functions. When `true`, the iteration of
+   * messages will be done at bundle time to create a constant JS object containing all the message
+   * keys as inline functions that act as binds. This mode is much faster for runtimes to
+   * initialize, at the cost of a relatively large space increase (~70% larger than using the
+   * runtime bind mode). However, this mode can be compressed substantially when compiled to
+   * bytecode, as is the case when creating mobile bundles with Hermes. In that case, pre-generating
+   * binds gains the speed increase while still staying relatively small in the output bundle.
+   * Because of this, `metro-intl-transformer` will instead default to `true` for this option and
+   * can be disabled when not using Hermes.
+   *
+   * @default false
+   */
+  preGenerateBinds?: boolean;
 }
 
 /**

package/types.d.ts

@@ -53,6 +53,22 @@ export interface MessageDefinitionsTransformerOptions {
    * @default esm
    */
   exportMode?: 'esm' | 'commonjs' | 'transpiledEsModule';
+  /**
+   * Control how loader binds are generated by the transformer. When `false` (the default), binds
+   * will be created at runtime using `messagesLoader.getBinds()`. This mode saves space, at the
+   * cost of runtime overhead to iterate and create bound functions. When `true`, the iteration of
+   * messages will be done at bundle time to create a constant JS object containing all the message
+   * keys as inline functions that act as binds. This mode is much faster for runtimes to
+   * initialize, at the cost of a relatively large space increase (~70% larger than using the
+   * runtime bind mode). However, this mode can be compressed substantially when compiled to
+   * bytecode, as is the case when creating mobile bundles with Hermes. In that case, pre-generating
+   * binds gains the speed increase while still staying relatively small in the output bundle.
+   * Because of this, `metro-intl-transformer` will instead default to `true` for this option and
+   * can be disabled when not using Hermes.
+   *
+   * @default false
+   */
+  preGenerateBinds?: boolean;
 }
 
 /**