@discord/intl-loader-core 0.18.0-canary.fa54f84 → 0.18.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl-loader-core",
-  "version": "0.18.0-canary.fa54f84",
+  "version": "0.18.0-rc.0",
   "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.18.0-rc.0"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",

package/src/transformer.js

@@ -18,19 +18,18 @@
  *
  * // SomeConsumer.tsx
  * import someModuleMessages from 'SomeModule.messages.js';
- * intl.format(someModuleMessages.THIS_IS_A_MESSAGE, {values: "I'm a value!"});
+ * i18n.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 {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)
- * };
+ * 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();
  * ```
  *
  * Notice how the message keys have been hashed into short keys, and the
@@ -42,7 +41,7 @@
  *
  * ```typescript
  * import someModuleMessages from 'SomeModule.messages.js';
- * intl.format(someModuleMessages["a9fn23"], {values: "i'm a value!"});
+ * i18n.format(someModuleMessages["a9fn23"], {values: "i'm a value!"});
  * ```
  *
  * The transformed file also contains a named export for `messagesLoader`,
@@ -88,8 +87,9 @@ 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,27 +111,26 @@ class MessageDefinitionsTransformer {
   }
 
   /**
-   * When `option.proxyBinds` is set to true, this method is invoked to create it.
+   * When `options.pregenerateBinds` is set to 'proxy', 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 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.
-   *
-   * 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.
+   * binds during initialization. The Proxy supports `key in proxy` queries, getter access,
+   * spreads, and more.
    *
+   * @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}
    */
-  createBindsProxy(bindFunc) {
+  createBindsProxy(keyArrayName, keySetName, bindFunc) {
     return `new Proxy({},
       {
+        has(self, prop) {
+          return ${keySetName}.has(prop);
+        },
         ownKeys(self) {
-          return Reflect.ownKeys(self);
+          return ${keyArrayName};
         },
         getOwnPropertyDescriptor(self, prop) {
           return {
@@ -146,9 +145,11 @@ class MessageDefinitionsTransformer {
             return 'object';
           }
           if (prop === Symbol.toStringTag) {
-            return 'IntlMessagesProxy';
+            return 'proxyAssign';
           }
           
+          if(!${keySetName}.has(prop)) return undefined;
+          
           self[prop] ||= ${bindFunc};
           return self[prop];
         },
@@ -157,32 +158,34 @@ class MessageDefinitionsTransformer {
   }
 
   /**
-   * Return a map of key names to bound message getter functions. If `proxyBinds` is
+   * 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.
    *
    * @returns {string[]}
    */
   createLoaderAndBinds() {
-    switch (this.options.bindMode) {
-      case 'proxy':
-        return [
-          `const ${this.loaderName} = createLoader(_localeMap, _defaultLocale);`,
-          `const binds = ${this.createBindsProxy(`(locale) => ${this.loaderName}.get(prop, locale)`)};`,
-        ];
-      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}`,
-        );
+    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();`,
+      ];
     }
   }
 
@@ -218,7 +221,7 @@ class MessageDefinitionsTransformer {
     return [
       this.options.getPrelude?.() ?? '// No additional prelude was configured.',
       `const {createLoader} = require('@discord/intl');`,
-      `const _localeMap = ${this.getLocaleRequireMap()};`,
+      `const _locales = ${this.getLocaleRequireMap()};`,
       `const _defaultLocale = ${JSON.stringify(this.options.defaultLocale)};`,
       ...this.createLoaderAndBinds(),
       ...this.debugModeSetup(),

package/types/src/transformer.d.ts

@@ -18,19 +18,18 @@
  *
  * // SomeConsumer.tsx
  * import someModuleMessages from 'SomeModule.messages.js';
- * intl.format(someModuleMessages.THIS_IS_A_MESSAGE, {values: "I'm a value!"});
+ * i18n.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 {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)
- * };
+ * 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();
  * ```
  *
  * Notice how the message keys have been hashed into short keys, and the
@@ -42,7 +41,7 @@
  *
  * ```typescript
  * import someModuleMessages from 'SomeModule.messages.js';
- * intl.format(someModuleMessages["a9fn23"], {values: "i'm a value!"});
+ * i18n.format(someModuleMessages["a9fn23"], {values: "i'm a value!"});
  * ```
  *
  * The transformed file also contains a named export for `messagesLoader`,
@@ -92,25 +91,21 @@ export class MessageDefinitionsTransformer {
      */
     debugModeSetup(): string[];
     /**
-     * When `option.proxyBinds` is set to true, this method is invoked to create it.
+     * When `options.pregenerateBinds` is set to 'proxy', 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 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.
-     *
-     * 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.
+     * binds during initialization. The Proxy supports `key in proxy` queries, getter access,
+     * spreads, and more.
      *
+     * @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}
      */
-    createBindsProxy(bindFunc: string): string;
+    createBindsProxy(keyArrayName: string, keySetName: string, bindFunc: string): string;
     /**
-     * Return a map of key names to bound message getter functions. If `proxyBinds` is
+     * 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.
      *

package/types/types.d.ts

@@ -54,22 +54,21 @@ export interface MessageDefinitionsTransformerOptions {
    */
   exportMode?: 'esm' | 'commonjs' | 'transpiledEsModule';
   /**
-   * 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.
+   * 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.
    *
-   * 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'
+   * @default false
    */
-  bindMode?: 'proxy' | 'literal';
+  preGenerateBinds?: boolean | 'proxy';
 }
 
 /**

package/types.d.ts

@@ -54,22 +54,21 @@ export interface MessageDefinitionsTransformerOptions {
    */
   exportMode?: 'esm' | 'commonjs' | 'transpiledEsModule';
   /**
-   * 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.
+   * 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.
    *
-   * 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'
+   * @default false
    */
-  bindMode?: 'proxy' | 'literal';
+  preGenerateBinds?: boolean | 'proxy';
 }
 
 /**