@discord/intl-loader-core 0.18.0 → 0.19.1-canary.f6592a8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl-loader-core",
-  "version": "0.18.0",
+  "version": "0.19.1-canary.f6592a8",
   "license": "MIT",
   "description": "Core utilities for writing loaders and transformers using @discord/intl",
   "author": "Jon Egeland",
@@ -28,7 +28,7 @@
   "dependencies": {
     "chokidar": "^3.6.0",
     "debug": "^4.3.6",
-    "@discord/intl-message-database": "0.18.0"
+    "@discord/intl-message-database": "0.19.1-canary.f6592a8"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",

package/src/transformer.js

@@ -18,18 +18,19 @@
  *
  * // SomeConsumer.tsx
  * import someModuleMessages from 'SomeModule.messages.js';
- * i18n.format(someModuleMessages.THIS_IS_A_MESSAGE, {values: "I'm a value!"});
+ * intl.format(someModuleMessages.THIS_IS_A_MESSAGE, {values: "I'm a value!"});
  * ```
  *
  * This transformer will only handle `SomeModule.messages.js`, and will output
  * something like:
  *
  * ```typescript
- * const {i18n} = require('@discord/intl');
- * const _keys = ["a9fn23"];
- * const _locales = {"en-US": () => require('./messages/en-US.messages.json')};
- * export const messagesLoader = createLoader(_keys, _locales);
- * export default messagesLoader.getBinds();
+ * const {createLoader} = require('@discord/intl');
+ * const _localeMap = {"en-US": () => require('./messages/en-US.messages.json')};
+ * export const messagesLoader = createLoader(_localeMap);
+ * export default {
+ *   a9fn23(locale) => messagesLoader.get("a9fn23", locale)
+ * };
  * ```
  *
  * Notice how the message keys have been hashed into short keys, and the
@@ -41,7 +42,7 @@
  *
  * ```typescript
  * import someModuleMessages from 'SomeModule.messages.js';
- * i18n.format(someModuleMessages["a9fn23"], {values: "i'm a value!"});
+ * intl.format(someModuleMessages["a9fn23"], {values: "i'm a value!"});
  * ```
  *
  * The transformed file also contains a named export for `messagesLoader`,
@@ -87,9 +88,8 @@ class MessageDefinitionsTransformer {
   getLocaleRequireMap() {
     const localeProperties = [];
     for (const [locale, importPath] of Object.entries(this.options.localeMap)) {
-      // This assumes that the author has specified `importPath`
-      // as a properly-resolvable path for the bundler, which we can't easily
-      // enforce, unfortunately.
+      // This assumes that the author has specified `importPath` as a properly-resolvable path for
+      // the bundler, which we can't easily enforce, unfortunately.
       localeProperties.push(`"${locale}": () => ${this.options.getTranslationImport(importPath)}`);
     }
 
@@ -111,81 +111,55 @@ class MessageDefinitionsTransformer {
   }
 
   /**
-   * When `options.pregenerateBinds` is set to 'proxy', this method is invoked to create it.
+   * When `option.proxyBinds` is set to true, this method is invoked to create it.
    *
    * The binds proxy is a plain `Proxy` object with configuration applied to make it act and
    * function like a complete object, but without having to instantiate potentially thousands of
-   * binds during initialization. The Proxy supports `key in proxy` queries, getter access,
-   * spreads, and more.
+   * binds during initialization. The proxy intentionally does _not_ support iteration nor `key in`
+   * queries, as they require up-front initialization that is too costly when multiple thousands
+   * of message keys are included.
    *
-   * @param {string} keyArrayName Name of an Array to use for `keys` queries.
-   * @param {string} keySetName Name of a Set to use for `has` queries.
-   * @param {string} bindFunc Code expression that creates a getter bind
-   * @returns {string}
+   * However, the proxy _does_ implement `ownKeys`, such that the returned list of keys represents
+   * all of the messages that have been _accessed_ through this proxy so far. This is generally
+   * more of a debugging utility than anything else, but can be useful for diagnosing when messages
+   * are used in critical paths or otherwise.
+   *
+   * @returns {string[]}
    */
-  createBindsProxy(keyArrayName, keySetName, bindFunc) {
-    return `new Proxy({},
-      {
-        has(self, prop) {
-          return ${keySetName}.has(prop);
-        },
-        ownKeys(self) {
-          return ${keyArrayName};
-        },
-        getOwnPropertyDescriptor(self, prop) {
-          return {
-            value: self[prop] ||= ${bindFunc},
-            configurable: true,
-            enumerable: true,
-            writable: false,
-          };
-        },
-        get(self, prop) {
-          if (prop === '$$typeof') {
-            return 'object';
-          }
-          if (prop === Symbol.toStringTag) {
-            return 'proxyAssign';
-          }
-          
-          if(!${keySetName}.has(prop)) return undefined;
-          
-          self[prop] ||= ${bindFunc};
-          return self[prop];
-        },
-      },
-    )`;
+  createBindsProxy() {
+    return [
+      `const {makeMessagesProxy} = require('@discord/intl');`,
+      `const binds = makeMessagesProxy(${this.loaderName});`,
+    ];
   }
 
   /**
-   * Return a map of key names to bound message getter functions. If `preGenerateBinds` is
+   * Return a map of key names to bound message getter functions. If `proxyBinds` 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.
    *
    * @returns {string[]}
    */
   createLoaderAndBinds() {
-    if (this.options.preGenerateBinds === 'proxy') {
-      return [
-        `const _keys = ${JSON.stringify(Object.keys(this.options.messageKeys))};`,
-        'const _keySet = new Set(_keys);',
-        `const ${this.loaderName} = createLoader(_keys, _locales, _defaultLocale);`,
-        `const binds = ${this.createBindsProxy('_keys', '_keySet', `(locale) => ${this.loaderName}.get(prop, locale)`)};`,
-      ];
-    } else if (this.options.preGenerateBinds === true) {
-      const bindLines = Object.keys(this.options.messageKeys).map(
-        (bind) => `"${bind}"(locale) { return ${this.loaderName}.get("${bind}", locale) }`,
-      );
-      return [
-        `const binds = {${bindLines.join(',')}};`,
-        `const ${this.loaderName} = createLoader(Object.keys(binds), _locales, _defaultLocale);`,
-      ];
-    } else {
-      return [
-        `const _keys = ${JSON.stringify(Object.keys(this.options.messageKeys))};`,
-        `const ${this.loaderName} = createLoader(_keys, _locales, _defaultLocale);`,
-        `const binds = ${this.loaderName}.getBinds();`,
-      ];
+    switch (this.options.bindMode ?? 'proxy') {
+      case 'proxy':
+        return [
+          `const ${this.loaderName} = createLoader(_localeMap, _defaultLocale);`,
+          ...this.createBindsProxy(),
+        ];
+      case 'literal': {
+        const bindLines = Object.keys(this.options.messageKeys).map(
+          (bind) => `"${bind}"(locale) { return ${this.loaderName}.get("${bind}", locale) }`,
+        );
+        return [
+          `const binds = {${bindLines.join(',')}};`,
+          `const ${this.loaderName} = createLoader(_localeMap, _defaultLocale);`,
+        ];
+      }
+      default:
+        throw new Error(
+          `Unknown value for intl transformer option 'bindMode': ${this.options.bindMode}`,
+        );
     }
   }
 
@@ -221,7 +195,7 @@ class MessageDefinitionsTransformer {
     return [
       this.options.getPrelude?.() ?? '// No additional prelude was configured.',
       `const {createLoader} = require('@discord/intl');`,
-      `const _locales = ${this.getLocaleRequireMap()};`,
+      `const _localeMap = ${this.getLocaleRequireMap()};`,
       `const _defaultLocale = ${JSON.stringify(this.options.defaultLocale)};`,
       ...this.createLoaderAndBinds(),
       ...this.debugModeSetup(),

package/types/src/transformer.d.ts

@@ -18,18 +18,19 @@
  *
  * // SomeConsumer.tsx
  * import someModuleMessages from 'SomeModule.messages.js';
- * i18n.format(someModuleMessages.THIS_IS_A_MESSAGE, {values: "I'm a value!"});
+ * intl.format(someModuleMessages.THIS_IS_A_MESSAGE, {values: "I'm a value!"});
  * ```
  *
  * This transformer will only handle `SomeModule.messages.js`, and will output
  * something like:
  *
  * ```typescript
- * const {i18n} = require('@discord/intl');
- * const _keys = ["a9fn23"];
- * const _locales = {"en-US": () => require('./messages/en-US.messages.json')};
- * export const messagesLoader = createLoader(_keys, _locales);
- * export default messagesLoader.getBinds();
+ * const {createLoader} = require('@discord/intl');
+ * const _localeMap = {"en-US": () => require('./messages/en-US.messages.json')};
+ * export const messagesLoader = createLoader(_localeMap);
+ * export default {
+ *   a9fn23(locale) => messagesLoader.get("a9fn23", locale)
+ * };
  * ```
  *
  * Notice how the message keys have been hashed into short keys, and the
@@ -41,7 +42,7 @@
  *
  * ```typescript
  * import someModuleMessages from 'SomeModule.messages.js';
- * i18n.format(someModuleMessages["a9fn23"], {values: "i'm a value!"});
+ * intl.format(someModuleMessages["a9fn23"], {values: "i'm a value!"});
  * ```
  *
  * The transformed file also contains a named export for `messagesLoader`,
@@ -91,21 +92,24 @@ export class MessageDefinitionsTransformer {
      */
     debugModeSetup(): string[];
     /**
-     * When `options.pregenerateBinds` is set to 'proxy', this method is invoked to create it.
+     * When `option.proxyBinds` is set to true, this method is invoked to create it.
      *
      * The binds proxy is a plain `Proxy` object with configuration applied to make it act and
      * function like a complete object, but without having to instantiate potentially thousands of
-     * binds during initialization. The Proxy supports `key in proxy` queries, getter access,
-     * spreads, and more.
+     * binds during initialization. The proxy intentionally does _not_ support iteration nor `key in`
+     * queries, as they require up-front initialization that is too costly when multiple thousands
+     * of message keys are included.
      *
-     * @param {string} keyArrayName Name of an Array to use for `keys` queries.
-     * @param {string} keySetName Name of a Set to use for `has` queries.
-     * @param {string} bindFunc Code expression that creates a getter bind
-     * @returns {string}
+     * However, the proxy _does_ implement `ownKeys`, such that the returned list of keys represents
+     * all of the messages that have been _accessed_ through this proxy so far. This is generally
+     * more of a debugging utility than anything else, but can be useful for diagnosing when messages
+     * are used in critical paths or otherwise.
+     *
+     * @returns {string[]}
      */
-    createBindsProxy(keyArrayName: string, keySetName: string, bindFunc: string): string;
+    createBindsProxy(): string[];
     /**
-     * Return a map of key names to bound message getter functions. If `preGenerateBinds` is
+     * Return a map of key names to bound message getter functions. If `proxyBinds` 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.
      *

package/types/types.d.ts

@@ -54,21 +54,22 @@ export interface MessageDefinitionsTransformerOptions {
    */
   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.
+   * Control how loader binds are generated by the transformer. When the value is `'proxy'` (the
+   * default), no binds will actually be created directly. Instead, the transformer creates and
+   * exports a Proxy object that intercepts all unique requests for messages and creates loader
+   * binds on the fly. For projects with thousands of keys in messages files, this can save time
+   * and processing power when loading the application, and is especially beneficial for lower-end
+   * mobile devices that struggle to create such large objects quickly. Note that this proxy does
+   * not act exactly like a normal object and will not work with some expected language features,
+   * like `key in messages` queries and `{...messages}` spreads.
    *
-   * @default false
+   * When set to `'literal'`, the transformer instead exports an object literal with every compiled
+   * message key as a property defined directly on it. For smaller messages files, this reduces some
+   * of the runtime access overhead in exchange for more time spent during module initialization.
+   *
+   * @default 'proxy'
    */
-  preGenerateBinds?: boolean | 'proxy';
+  bindMode?: 'proxy' | 'literal';
 }
 
 /**

package/types.d.ts

@@ -54,21 +54,22 @@ export interface MessageDefinitionsTransformerOptions {
    */
   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.
+   * Control how loader binds are generated by the transformer. When the value is `'proxy'` (the
+   * default), no binds will actually be created directly. Instead, the transformer creates and
+   * exports a Proxy object that intercepts all unique requests for messages and creates loader
+   * binds on the fly. For projects with thousands of keys in messages files, this can save time
+   * and processing power when loading the application, and is especially beneficial for lower-end
+   * mobile devices that struggle to create such large objects quickly. Note that this proxy does
+   * not act exactly like a normal object and will not work with some expected language features,
+   * like `key in messages` queries and `{...messages}` spreads.
    *
-   * @default false
+   * When set to `'literal'`, the transformer instead exports an object literal with every compiled
+   * message key as a property defined directly on it. For smaller messages files, this reduces some
+   * of the runtime access overhead in exchange for more time spent during module initialization.
+   *
+   * @default 'proxy'
    */
-  preGenerateBinds?: boolean | 'proxy';
+  bindMode?: 'proxy' | 'literal';
 }
 
 /**