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

package/dist/message-loader.d.ts

@@ -73,7 +73,7 @@ export declare class MessageLoader {
      * @private
      */
     _localeFileMap?: Record<string, string>;
-    constructor(localeImportMap: LocaleImportMap, defaultLocale: LocaleId);
+    constructor(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId);
     /**
      * Provide additional debug information to use during development, providing additional context
      * for console error messages.
@@ -93,6 +93,20 @@ export declare class MessageLoader {
      * returning.
      */
     getMessageValue(key: string, locale: LocaleId): InternalIntlMessage | undefined;
+    /**
+     * Returns a record mapping the keys this object manages to bound functions
+     * for `get` with the that key as the first argument, allowing consumers to
+     * just call the function with a locale to retrieve the translated message
+     * for that key.
+     *
+     * This method is provided as a way to generate binds _at runtime_, but for
+     * very-large messages files (e.g., thousands of messages), this can be a
+     * non-negligible cost. Where feasible, consider generating these binds
+     * at build/bundle time, especially in cases where they can be substantially
+     * minified (i.e., Hermes bytecode). This is provided automatically as an
+     * option when using one of `@discord/intl`'s transformers.
+     */
+    getBinds(): Record<string, IntlMessageGetter>;
     _loadLocale(locale: LocaleId): Promise<void>;
     /**
      * Inform subscribers that the loader state has changed and they should
@@ -131,12 +145,9 @@ export declare function loadAllMessagesInLocale(locale: LocaleId): Promise<void>
  */
 export declare function waitForAllDefaultIntlMessagesLoaded(): Promise<void>;
 /**
- * Create a new MessageLoader, which handles lazily loading messages for different locales and
- * sanity checks as needed to provide accessors for each message contained by the import map.
- *
- * Notably, this does _not_ verify whether the locale objects managed by this loader actually
- * contain a given key. It is the responsibility of the caller to verify this (easily enforced with
- * typescript, eslint rules, and others).
+ * Create a new MessageLoader, which handles lazily loading messages for
+ * different locales and sanity checks as needed to provide accessors for each
+ * message defined in `messageKeys`.
  */
-export declare function createLoader(localeImportMap: LocaleImportMap, defaultLocale: LocaleId): MessageLoader;
+export declare function createLoader(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId): MessageLoader;
 export {};

package/dist/message-loader.js

@@ -15,7 +15,8 @@ exports.waitForAllDefaultIntlMessagesLoaded = waitForAllDefaultIntlMessagesLoade
 exports.createLoader = createLoader;
 const message_1 = require("./message");
 class MessageLoader {
-    constructor(localeImportMap, defaultLocale) {
+    constructor(messageKeys, localeImportMap, defaultLocale) {
+        this.messageKeys = messageKeys;
         this.messages = {};
         this.localeImportMap = localeImportMap;
         this.supportedLocales = Object.keys(localeImportMap);
@@ -98,16 +99,9 @@ class MessageLoader {
             }
             return undefined;
         }
-        // Then try to return the loaded message. Previously, this used a `key in ...` check to quickly
-        // verify whether the locale object contains the requested message, but in the case where the
-        // target is a Proxy or uses some other internalized method for providing gettable values, `in`
-        // queries aren't guaranteed to work. Instead, since this is realistically amortized to just be
-        // a property access on every call, we can just the returned value as the determining factor. If
-        // the locale object returns `undefined`, then it "does not contain" the message, whether it's
-        // still loading or otherwise. Future calls will then be able to pick up any changed value,
-        // since it won't be cached in the `_parseCache`.
-        const content = this.messages[locale][key];
-        if (content != null) {
+        // Then try to return the loaded message.
+        if (key in this.messages[locale]) {
+            const content = this.messages[locale][key];
             const message = new message_1.InternalIntlMessage(content, locale);
             ((_b = (_c = this._parseCache)[locale]) !== null && _b !== void 0 ? _b : (_c[locale] = {}))[key] = message;
             return message;
@@ -115,6 +109,26 @@ class MessageLoader {
         // Otherwise just assume it doesn't exist.
         return undefined;
     }
+    /**
+     * Returns a record mapping the keys this object manages to bound functions
+     * for `get` with the that key as the first argument, allowing consumers to
+     * just call the function with a locale to retrieve the translated message
+     * for that key.
+     *
+     * This method is provided as a way to generate binds _at runtime_, but for
+     * very-large messages files (e.g., thousands of messages), this can be a
+     * non-negligible cost. Where feasible, consider generating these binds
+     * at build/bundle time, especially in cases where they can be substantially
+     * minified (i.e., Hermes bytecode). This is provided automatically as an
+     * option when using one of `@discord/intl`'s transformers.
+     */
+    getBinds() {
+        const result = {};
+        for (const key of this.messageKeys) {
+            result[key] = this.get.bind(this, key);
+        }
+        return result;
+    }
     _loadLocale(locale) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d;
@@ -234,15 +248,12 @@ function waitForAllDefaultIntlMessagesLoaded() {
     });
 }
 /**
- * Create a new MessageLoader, which handles lazily loading messages for different locales and
- * sanity checks as needed to provide accessors for each message contained by the import map.
- *
- * Notably, this does _not_ verify whether the locale objects managed by this loader actually
- * contain a given key. It is the responsibility of the caller to verify this (easily enforced with
- * typescript, eslint rules, and others).
+ * Create a new MessageLoader, which handles lazily loading messages for
+ * different locales and sanity checks as needed to provide accessors for each
+ * message defined in `messageKeys`.
  */
-function createLoader(localeImportMap, defaultLocale) {
-    const loader = new MessageLoader(localeImportMap, defaultLocale);
+function createLoader(messageKeys, localeImportMap, defaultLocale) {
+    const loader = new MessageLoader(messageKeys, localeImportMap, defaultLocale);
     LOADER_REGISTRY.push(loader);
     return loader;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl",
-  "version": "0.18.0-canary.fa54f84",
+  "version": "0.18.0-rc.0",
   "license": "MIT",
   "description": "Client runtime for managing messages and translations in a React project.",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
     "@formatjs/intl": "^2.10.1",
     "@intrnl/xxhash64": "^0.1.2",
     "intl-messageformat": "^10.5.11",
-    "@discord/intl-ast": "0.18.0"
+    "@discord/intl-ast": "0.18.0-rc.0"
   },
   "devDependencies": {
     "@formatjs/intl-durationformat": "^0.7.3",

package/src/message-loader.ts

@@ -85,7 +85,8 @@ export class MessageLoader {
    */
   _localeFileMap?: Record<string, string>;
 
-  constructor(localeImportMap: LocaleImportMap, defaultLocale: LocaleId) {
+  constructor(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId) {
+    this.messageKeys = messageKeys;
     this.messages = {};
     this.localeImportMap = localeImportMap;
     this.supportedLocales = Object.keys(localeImportMap);
@@ -177,16 +178,9 @@ export class MessageLoader {
       return undefined;
     }
 
-    // Then try to return the loaded message. Previously, this used a `key in ...` check to quickly
-    // verify whether the locale object contains the requested message, but in the case where the
-    // target is a Proxy or uses some other internalized method for providing gettable values, `in`
-    // queries aren't guaranteed to work. Instead, since this is realistically amortized to just be
-    // a property access on every call, we can just the returned value as the determining factor. If
-    // the locale object returns `undefined`, then it "does not contain" the message, whether it's
-    // still loading or otherwise. Future calls will then be able to pick up any changed value,
-    // since it won't be cached in the `_parseCache`.
-    const content = this.messages[locale][key];
-    if (content != null) {
+    // Then try to return the loaded message.
+    if (key in this.messages[locale]) {
+      const content = this.messages[locale][key];
       const message = new InternalIntlMessage(content, locale);
       (this._parseCache[locale] ??= {})[key] = message;
       return message;
@@ -196,6 +190,28 @@ export class MessageLoader {
     return undefined;
   }
 
+  /**
+   * Returns a record mapping the keys this object manages to bound functions
+   * for `get` with the that key as the first argument, allowing consumers to
+   * just call the function with a locale to retrieve the translated message
+   * for that key.
+   *
+   * This method is provided as a way to generate binds _at runtime_, but for
+   * very-large messages files (e.g., thousands of messages), this can be a
+   * non-negligible cost. Where feasible, consider generating these binds
+   * at build/bundle time, especially in cases where they can be substantially
+   * minified (i.e., Hermes bytecode). This is provided automatically as an
+   * option when using one of `@discord/intl`'s transformers.
+   */
+  getBinds(): Record<string, IntlMessageGetter> {
+    const result: Record<string, IntlMessageGetter> = {};
+    for (const key of this.messageKeys) {
+      result[key] = this.get.bind(this, key);
+    }
+
+    return result;
+  }
+
   async _loadLocale(locale: LocaleId) {
     // If the locale is already set in `messages`, then it doesn't need to be loaded again.
     if (this.messages[locale] != null) return;
@@ -312,15 +328,16 @@ export async function waitForAllDefaultIntlMessagesLoaded(): Promise<void> {
 }
 
 /**
- * Create a new MessageLoader, which handles lazily loading messages for different locales and
- * sanity checks as needed to provide accessors for each message contained by the import map.
- *
- * Notably, this does _not_ verify whether the locale objects managed by this loader actually
- * contain a given key. It is the responsibility of the caller to verify this (easily enforced with
- * typescript, eslint rules, and others).
+ * Create a new MessageLoader, which handles lazily loading messages for
+ * different locales and sanity checks as needed to provide accessors for each
+ * message defined in `messageKeys`.
  */
-export function createLoader(localeImportMap: LocaleImportMap, defaultLocale: LocaleId) {
-  const loader = new MessageLoader(localeImportMap, defaultLocale);
+export function createLoader(
+  messageKeys: string[],
+  localeImportMap: LocaleImportMap,
+  defaultLocale: LocaleId,
+) {
+  const loader = new MessageLoader(messageKeys, localeImportMap, defaultLocale);
   LOADER_REGISTRY.push(loader);
   return loader;
 }