@discord/intl 0.0.5 → 0.0.6-rc.0

package/dist/intl-manager.d.ts

@@ -1,5 +1,5 @@
 import { IntlShape } from '@formatjs/intl';
-import { LocaleImportMap, MessageLoader } from './message-loader';
+import { LocaleImportMap, LocaleId, MessageLoader } from './message-loader';
 import type { TypedIntlMessageGetter, FormatValuesFor, RichTextElementMap } from './types';
 /**
  * Fallback locale used for all internationalization when an operation in the
@@ -56,4 +56,4 @@ export declare class IntlManager<DefaultElements extends RichTextElementMap, Def
  * different locales and sanity checks as needed to provide accessors for each
  * message defined in `messageKeys`.
  */
-export declare function createLoader(messageKeys: string[], localeImportMap: LocaleImportMap): MessageLoader;
+export declare function createLoader(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId): MessageLoader;

package/dist/intl-manager.js

@@ -133,6 +133,6 @@ exports.IntlManager = IntlManager;
  * different locales and sanity checks as needed to provide accessors for each
  * message defined in `messageKeys`.
  */
-function createLoader(messageKeys, localeImportMap) {
-    return new message_loader_1.MessageLoader(messageKeys, localeImportMap);
+function createLoader(messageKeys, localeImportMap, defaultLocale) {
+    return new message_loader_1.MessageLoader(messageKeys, localeImportMap, defaultLocale);
 }

package/dist/message-loader.d.ts

@@ -8,7 +8,7 @@ export interface IntlMessageGetterAdditions {
 export interface IntlMessageGetter extends IntlMessageGetterAdditions {
     (locale: LocaleId): InternalIntlMessage;
 }
-type LocaleId = string;
+export type LocaleId = string;
 export type LocaleImportMap = Record<LocaleId, () => Promise<{
     default: MessagesData;
 }>>;
@@ -18,6 +18,12 @@ export declare class MessageLoader {
     messages: Record<LocaleId, MessagesData>;
     localeImportMap: LocaleImportMap;
     supportedLocales: LocaleId[];
+    /**
+     * Fallback locale where messages will try to be looked up if they don't exist in the requested
+     * locale in a given call. This locale will also be immediately loaded when this loader is
+     * constructed to ensure the contents are available as soon as possible.
+     */
+    defaultLocale: LocaleId;
     /**
      * Promise representing the current locale being loaded. If this is non-null,
      * then a request has already been made to load the locale and it is waiting
@@ -35,9 +41,48 @@ export declare class MessageLoader {
      * when it has loaded.
      */
     _subscribers: Set<() => void>;
+    /**
+     * Message to show as a fallback when the requested message is unavailable.
+     */
     fallbackMessage: InternalIntlMessage;
-    constructor(messageKeys: string[], localeImportMap: LocaleImportMap);
+    /**
+     * Map from hashed message keys to their original values, to provide context in error messages
+     * that would otherwise be obfuscated.
+     *
+     * Consumers should only provide this value in developer or debug environments.
+     *
+     * @private
+     */
+    _debugKeyMap: Record<string, string>;
+    /**
+     * Map of locale names to source file names, used to provide context for where messages are
+     * imported from during development.
+     *
+     * Consumers should only provide this value in developer or debug environments.
+     *
+     * @private
+     */
+    _localeFileMap: Record<string, string>;
+    constructor(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId);
+    /**
+     * Provide additional debug information to use during development, providing additional context
+     * for console error messages.
+     *
+     * @param {Record<string, string>} keyMap
+     * @param {Record<string, string>} localeFileMap
+     */
+    withDebugValues(keyMap: Record<string, string>, localeFileMap: Record<string, string>): void;
     get(key: string, locale: LocaleId): InternalIntlMessage;
+    /**
+     * Return the value of the message with the given `key` in the given `locale`. If the message has
+     * no value in that locale, this function returns `undefined`.
+     *
+     * This function will first check the cache to see if it has already been loaded, and will later
+     * set the cache after parsing if not. If the requested locale has not yet been loaded, this
+     * function will trigger a load for that locale, but will not wait for it to resolve before
+     * 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

package/dist/message-loader.js

@@ -46,42 +46,127 @@ var __values = (this && this.__values) || function(o) {
     };
     throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
 };
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessageLoader = void 0;
 var message_1 = require("./message");
 var MessageLoader = /** @class */ (function () {
-    function MessageLoader(messageKeys, localeImportMap) {
+    function MessageLoader(messageKeys, localeImportMap, defaultLocale) {
+        var e_1, _a;
+        var _this = this;
         this.messageKeys = messageKeys;
         this.messages = {};
         this.localeImportMap = localeImportMap;
         this.supportedLocales = Object.keys(localeImportMap);
+        this.defaultLocale = defaultLocale;
         this._localeLoadingPromises = {};
         this._parseCache = new Map();
         this._subscribers = new Set();
+        this._loadLocale(this.defaultLocale);
         this.fallbackMessage = new message_1.InternalIntlMessage('THIS MESSAGE FAILED TO LOAD', 'en-US');
+        // In cases where hot module replacement is available, set up cache clearing whenever the
+        // targets change so that values are always replaced.
+        // @ts-expect-error `hot` not defined in types.
+        if (module.hot) {
+            var _loop_1 = function (locale, file) {
+                // @ts-expect-error `hot` not defined in types.
+                module.hot.accept(file, function () {
+                    _this._parseCache.clear();
+                    _this._loadLocale(locale);
+                });
+            };
+            try {
+                for (var _b = __values(Object.entries(localeImportMap)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                    var _d = __read(_c.value, 2), locale = _d[0], file = _d[1];
+                    _loop_1(locale, file);
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
     }
+    /**
+     * Provide additional debug information to use during development, providing additional context
+     * for console error messages.
+     *
+     * @param {Record<string, string>} keyMap
+     * @param {Record<string, string>} localeFileMap
+     */
+    MessageLoader.prototype.withDebugValues = function (keyMap, localeFileMap) {
+        this._debugKeyMap = keyMap;
+        this._localeFileMap = localeFileMap;
+    };
     MessageLoader.prototype.get = function (key, locale) {
+        var _a;
+        var value = (_a = this.getMessageValue(key, locale)) !== null && _a !== void 0 ? _a : this.getMessageValue(key, this.defaultLocale);
+        if (value != null) {
+            return value;
+        }
+        // If the message couldn't be found in either the requested nor the default locale, then
+        // nothing can be done.
+        var errorKey = this._debugKeyMap != null ? "\"".concat(this._debugKeyMap[key], "\" (").concat(key, ")") : undefined;
+        var requestedLocale = this._localeFileMap != null ? "".concat(locale, " (").concat(this._localeFileMap[locale], ")") : locale;
+        var defaultLocale = this._localeFileMap != null
+            ? "".concat(this.defaultLocale, " (").concat(this._localeFileMap[this.defaultLocale], ")")
+            : this.defaultLocale;
+        console.warn("Requested message ".concat(errorKey, " does not have a value in the requested locale ").concat(requestedLocale, " nor the default locale ").concat(defaultLocale));
+        return this.fallbackMessage;
+    };
+    /**
+     * Return the value of the message with the given `key` in the given `locale`. If the message has
+     * no value in that locale, this function returns `undefined`.
+     *
+     * This function will first check the cache to see if it has already been loaded, and will later
+     * set the cache after parsing if not. If the requested locale has not yet been loaded, this
+     * function will trigger a load for that locale, but will not wait for it to resolve before
+     * returning.
+     */
+    MessageLoader.prototype.getMessageValue = function (key, locale) {
         var cacheKey = key + '@' + locale;
         var cachedValue = this._parseCache.get(cacheKey);
         if (cachedValue != null)
             return cachedValue;
+        // Return early if this locale is still in the process of being loaded.
+        if (this._localeLoadingPromises[locale] != null) {
+            return undefined;
+        }
+        // If not, check whether it's been loaded and trigger a load if not.
         if (this.messages[locale] == null) {
             // Ensure the locale is loaded, if it is supported
             if (this.supportedLocales.includes(locale)) {
                 this._loadLocale(locale);
             }
-            // Otherwise, fallback to just the key value in the meantime.
-            return this.fallbackMessage;
+            return undefined;
         }
-        // Then try to return the loaded message
+        // Then try to return the loaded message.
         if (key in this.messages[locale]) {
             var content = this.messages[locale][key];
             var message = new message_1.InternalIntlMessage(content, locale);
             this._parseCache.set(cacheKey, message);
             return message;
         }
-        // And finally throw if there's no match whatsoever
-        throw new Error("Requested message ".concat(key, " does not have a value in the requested locale nor the default locale"));
+        // Otherwise just assume it doesn't exist.
+        return undefined;
     };
     /**
      * Returns a record mapping the keys this object manages to bound functions
@@ -92,7 +177,7 @@ var MessageLoader = /** @class */ (function () {
     MessageLoader.prototype.getBinds = function () {
         var _this = this;
         var onChange = this.onChange.bind(this);
-        return this.messageKeys.reduce(function (acc, key) {
+        return Object.keys(this.messageKeys).reduce(function (acc, key) {
             var bound = _this.get.bind(_this, key);
             bound.onChange = onChange;
             acc[key] = bound;
@@ -101,7 +186,7 @@ var MessageLoader = /** @class */ (function () {
     };
     MessageLoader.prototype._loadLocale = function (locale) {
         return __awaiter(this, void 0, void 0, function () {
-            var loadStart, loadingPromise, _a, _b, loadEnd;
+            var loadingPromise, _a, _b;
             return __generator(this, function (_c) {
                 switch (_c.label) {
                     case 0:
@@ -118,7 +203,6 @@ var MessageLoader = /** @class */ (function () {
                         // If the locale is already set in `messages`, then it doesn't need to be loaded again.
                         if (this.messages[locale] != null)
                             return [2 /*return*/];
-                        loadStart = performance.now();
                         loadingPromise = this.localeImportMap[locale]();
                         this._localeLoadingPromises[locale] = loadingPromise;
                         _a = this.messages;
@@ -127,7 +211,6 @@ var MessageLoader = /** @class */ (function () {
                     case 1:
                         _a[_b] = (_c.sent()).default;
                         delete this._localeLoadingPromises[locale];
-                        loadEnd = performance.now();
                         this.emitChange();
                         return [2 /*return*/];
                 }
@@ -139,19 +222,19 @@ var MessageLoader = /** @class */ (function () {
      * potentially update to get new values for messages.
      */
     MessageLoader.prototype.emitChange = function () {
-        var e_1, _a;
+        var e_2, _a;
         try {
             for (var _b = __values(this._subscribers.values()), _c = _b.next(); !_c.done; _c = _b.next()) {
                 var callback = _c.value;
                 callback();
             }
         }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
         finally {
             try {
                 if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_1) throw e_1.error; }
+            finally { if (e_2) throw e_2.error; }
         }
     };
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl",
-  "version": "0.0.5",
+  "version": "0.0.6-rc.0",
   "license": "MIT",
   "description": "Client runtime for managing messages and translations in a React project.",
   "main": "./dist/index.js",

package/src/intl-manager.ts

@@ -6,7 +6,7 @@ import {
   IntlMessageFormat,
 } from 'intl-messageformat';
 
-import { LocaleImportMap, MessageLoader } from './message-loader';
+import { LocaleImportMap, LocaleId, MessageLoader } from './message-loader';
 
 import type { TypedIntlMessageGetter, FormatValuesFor, RichTextElementMap } from './types';
 
@@ -161,6 +161,10 @@ export class IntlManager<
  * different locales and sanity checks as needed to provide accessors for each
  * message defined in `messageKeys`.
  */
-export function createLoader(messageKeys: string[], localeImportMap: LocaleImportMap) {
-  return new MessageLoader(messageKeys, localeImportMap);
+export function createLoader(
+  messageKeys: string[],
+  localeImportMap: LocaleImportMap,
+  defaultLocale: LocaleId,
+) {
+  return new MessageLoader(messageKeys, localeImportMap, defaultLocale);
 }

package/src/message-loader.ts

@@ -12,7 +12,7 @@ export interface IntlMessageGetter extends IntlMessageGetterAdditions {
   (locale: LocaleId): InternalIntlMessage;
 }
 
-type LocaleId = string;
+export type LocaleId = string;
 
 export type LocaleImportMap = Record<LocaleId, () => Promise<{ default: MessagesData }>>;
 
@@ -22,6 +22,12 @@ export class MessageLoader {
   messages: Record<LocaleId, MessagesData>;
   localeImportMap: LocaleImportMap;
   supportedLocales: LocaleId[];
+  /**
+   * Fallback locale where messages will try to be looked up if they don't exist in the requested
+   * locale in a given call. This locale will also be immediately loaded when this loader is
+   * constructed to ensure the contents are available as soon as possible.
+   */
+  defaultLocale: LocaleId;
 
   /**
    * Promise representing the current locale being loaded. If this is non-null,
@@ -41,37 +47,126 @@ export class MessageLoader {
    */
   _subscribers: Set<() => void>;
 
+  /**
+   * Message to show as a fallback when the requested message is unavailable.
+   */
   fallbackMessage: InternalIntlMessage;
 
-  constructor(messageKeys: string[], localeImportMap: LocaleImportMap) {
+  ///
+  // Debug mode values
+  ///
+
+  /**
+   * Map from hashed message keys to their original values, to provide context in error messages
+   * that would otherwise be obfuscated.
+   *
+   * Consumers should only provide this value in developer or debug environments.
+   *
+   * @private
+   */
+  _debugKeyMap: Record<string, string>;
+  /**
+   * Map of locale names to source file names, used to provide context for where messages are
+   * imported from during development.
+   *
+   * Consumers should only provide this value in developer or debug environments.
+   *
+   * @private
+   */
+  _localeFileMap: Record<string, string>;
+
+  constructor(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId) {
     this.messageKeys = messageKeys;
     this.messages = {};
     this.localeImportMap = localeImportMap;
     this.supportedLocales = Object.keys(localeImportMap);
+    this.defaultLocale = defaultLocale;
 
     this._localeLoadingPromises = {};
     this._parseCache = new Map();
     this._subscribers = new Set();
 
+    this._loadLocale(this.defaultLocale);
     this.fallbackMessage = new InternalIntlMessage('THIS MESSAGE FAILED TO LOAD', 'en-US');
+
+    // In cases where hot module replacement is available, set up cache clearing whenever the
+    // targets change so that values are always replaced.
+    // @ts-expect-error `hot` not defined in types.
+    if (module.hot) {
+      for (const [locale, file] of Object.entries(localeImportMap)) {
+        // @ts-expect-error `hot` not defined in types.
+        module.hot.accept(file, () => {
+          this._parseCache.clear();
+          this._loadLocale(locale);
+        });
+      }
+    }
+  }
+
+  /**
+   * Provide additional debug information to use during development, providing additional context
+   * for console error messages.
+   *
+   * @param {Record<string, string>} keyMap
+   * @param {Record<string, string>} localeFileMap
+   */
+  withDebugValues(keyMap: Record<string, string>, localeFileMap: Record<string, string>) {
+    this._debugKeyMap = keyMap;
+    this._localeFileMap = localeFileMap;
   }
 
   get(key: string, locale: LocaleId): InternalIntlMessage {
+    const value =
+      this.getMessageValue(key, locale) ?? this.getMessageValue(key, this.defaultLocale);
+    if (value != null) {
+      return value;
+    }
+
+    // If the message couldn't be found in either the requested nor the default locale, then
+    // nothing can be done.
+    const errorKey = this._debugKeyMap != null ? `"${this._debugKeyMap[key]}" (${key})` : undefined;
+    const requestedLocale =
+      this._localeFileMap != null ? `${locale} (${this._localeFileMap[locale]})` : locale;
+    const defaultLocale =
+      this._localeFileMap != null
+        ? `${this.defaultLocale} (${this._localeFileMap[this.defaultLocale]})`
+        : this.defaultLocale;
+    console.warn(
+      `Requested message ${errorKey} does not have a value in the requested locale ${requestedLocale} nor the default locale ${defaultLocale}`,
+    );
+    return this.fallbackMessage;
+  }
+
+  /**
+   * Return the value of the message with the given `key` in the given `locale`. If the message has
+   * no value in that locale, this function returns `undefined`.
+   *
+   * This function will first check the cache to see if it has already been loaded, and will later
+   * set the cache after parsing if not. If the requested locale has not yet been loaded, this
+   * function will trigger a load for that locale, but will not wait for it to resolve before
+   * returning.
+   */
+  getMessageValue(key: string, locale: LocaleId): InternalIntlMessage | undefined {
     const cacheKey = key + '@' + locale;
     const cachedValue = this._parseCache.get(cacheKey);
     if (cachedValue != null) return cachedValue;
 
+    // Return early if this locale is still in the process of being loaded.
+    if (this._localeLoadingPromises[locale] != null) {
+      return undefined;
+    }
+
+    // If not, check whether it's been loaded and trigger a load if not.
     if (this.messages[locale] == null) {
       // Ensure the locale is loaded, if it is supported
       if (this.supportedLocales.includes(locale)) {
         this._loadLocale(locale);
       }
 
-      // Otherwise, fallback to just the key value in the meantime.
-      return this.fallbackMessage;
+      return undefined;
     }
 
-    // Then try to return the loaded message
+    // 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);
@@ -79,10 +174,8 @@ export class MessageLoader {
       return message;
     }
 
-    // And finally throw if there's no match whatsoever
-    throw new Error(
-      `Requested message ${key} does not have a value in the requested locale nor the default locale`,
-    );
+    // Otherwise just assume it doesn't exist.
+    return undefined;
   }
 
   /**
@@ -93,7 +186,7 @@ export class MessageLoader {
    */
   getBinds(): Record<string, IntlMessageGetter> {
     const onChange = this.onChange.bind(this);
-    return this.messageKeys.reduce(
+    return Object.keys(this.messageKeys).reduce(
       (acc, key) => {
         const bound = this.get.bind(this, key) as IntlMessageGetter;
         bound.onChange = onChange;
@@ -122,12 +215,10 @@ export class MessageLoader {
     // If the locale is already set in `messages`, then it doesn't need to be loaded again.
     if (this.messages[locale] != null) return;
 
-    const loadStart = performance.now();
     const loadingPromise = this.localeImportMap[locale]();
     this._localeLoadingPromises[locale] = loadingPromise;
     this.messages[locale] = (await loadingPromise).default;
     delete this._localeLoadingPromises[locale];
-    const loadEnd = performance.now();
     this.emitChange();
   }