@discord/intl 0.2.0 → 0.2.1-canary.dff7875

package/dist/formatters/ast.js

@@ -65,14 +65,6 @@ var RichTextNodeType;
      */
     RichTextNodeType["Object"] = "object";
 })(RichTextNodeType || (exports.RichTextNodeType = RichTextNodeType = {}));
-var RICH_TEXT_TAG_TYPES = {
-    $_: RichTextNodeType.Text,
-    $b: RichTextNodeType.Strong,
-    $i: RichTextNodeType.Emphasis,
-    $code: RichTextNodeType.Code,
-    $link: RichTextNodeType.Link,
-    $p: RichTextNodeType.Paragraph,
-};
 var AST_RICH_TEXT_ELEMENTS = {
     $_: function () { return ({ type: RichTextNodeType.Text, content: '' }); },
     $b: function (content) { return ({ type: RichTextNodeType.Strong, content: content }); },
@@ -100,7 +92,7 @@ var AstBuilder = /** @class */ (function (_super) {
         if (!(tag in AST_RICH_TEXT_ELEMENTS)) {
             throw "".concat(tag, " is not a known rich text formatting tag");
         }
-        var result = AST_RICH_TEXT_ELEMENTS[tag](children);
+        var result = AST_RICH_TEXT_ELEMENTS[tag](children, 0);
         if (Array.isArray(result)) {
             (_a = this.result).push.apply(_a, __spreadArray([], __read(result), false));
         }

package/dist/formatters/markdown.js

@@ -62,7 +62,7 @@ var MarkdownBuilder = /** @class */ (function (_super) {
         return _this;
     }
     MarkdownBuilder.prototype.pushRichTextTag = function (tag, children) {
-        this.result += MARKDOWN_RICH_TEXT_ELEMENTS[tag](children);
+        this.result += MARKDOWN_RICH_TEXT_ELEMENTS[tag](children, 0);
     };
     return MarkdownBuilder;
 }(string_1.StringBuilder));

package/dist/formatters/react.d.ts

@@ -18,7 +18,10 @@ export type ReactFunctionTypes = FunctionTypes<React.ReactNode, ReactClickHandle
     onContextMenu: ReactClickHandler;
 }>;
 export declare const DEFAULT_REACT_RICH_TEXT_ELEMENTS: RichTextFormattingMap<ReactFunctionTypes['hook']>;
-export declare function formatReact(this: IntlManager, message: AnyIntlMessage, values: object, Builder: FormatBuilderConstructor<React.ReactElement>): React.ReactElement;
+export type ReactIntlMessage = React.ReactElement<{}, typeof React.Fragment & {
+    __brand: 'discord-intl';
+}>;
+export declare function formatReact(this: IntlManager, message: AnyIntlMessage, values: object, Builder: FormatBuilderConstructor<React.ReactElement>): ReactIntlMessage;
 /**
  * Create a new React formatter with the given rich text elements replacing the defaults. Use this
  * function to inject custom components for things like links and paragraphs, which may be best

package/dist/formatters/react.js

@@ -48,15 +48,15 @@ var format_1 = require("../format");
 var h = React.createElement;
 exports.DEFAULT_REACT_RICH_TEXT_ELEMENTS = {
     $_: function () { return ''; },
-    $b: function (content) { return h('strong', undefined, content); },
-    $code: function (content) { return h('code', undefined, content); },
-    $i: function (content) { return h('em', undefined, content); },
+    $b: function (content, key) { return h('strong', { key: key }, content); },
+    $code: function (content, key) { return h('code', { key: key }, content); },
+    $i: function (content, key) { return h('em', { key: key }, content); },
     // $link will always be [href, <empty>, ...content]
-    $link: function (_a) {
+    $link: function (_a, key) {
         var _b = __read(_a), href = _b[0], content = _b.slice(1);
-        return h('a', { href: href }, content);
+        return h('a', { href: href, key: key }, content);
     },
-    $p: function (content) { return h('p', undefined, content); },
+    $p: function (content, key) { return h('p', { key: key }, content); },
 };
 /**
  * Creates a new `FormatBuilder` class that constructs a React element tree
@@ -70,11 +70,12 @@ function createReactBuilder(richTextElements) {
         __extends(class_1, _super);
         function class_1() {
             var _this = _super.apply(this, __spreadArray([], __read(arguments), false)) || this;
+            _this._nodeKey = 0;
             _this.result = [];
             return _this;
         }
         class_1.prototype.pushRichTextTag = function (tag, children) {
-            this.result.push(richTextElements[tag](children));
+            this.result.push(richTextElements[tag](children, this._nodeKey++));
         };
         class_1.prototype.pushLiteralText = function (text) {
             this.result.push(text);

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import * as React from 'react';
 import { RichTextNode } from './formatters';
-export { IntlManager, createLoader, DEFAULT_LOCALE, type FormatFunction } from './intl-manager';
 export * from './formatters';
+export { IntlManager, DEFAULT_LOCALE, type FormatFunction } from './intl-manager';
+export { createLoader, loadAllMessagesInLocale, waitForAllDefaultIntlMessagesLoaded, MessageLoader, } from './message-loader';
 export type * from './types.d.ts';
 /**
  * A type representing any message that has been formatted using one of the

package/dist/index.js

@@ -14,9 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_LOCALE = exports.createLoader = exports.IntlManager = void 0;
+exports.MessageLoader = exports.waitForAllDefaultIntlMessagesLoaded = exports.loadAllMessagesInLocale = exports.createLoader = exports.DEFAULT_LOCALE = exports.IntlManager = void 0;
+__exportStar(require("./formatters"), exports);
 var intl_manager_1 = require("./intl-manager");
 Object.defineProperty(exports, "IntlManager", { enumerable: true, get: function () { return intl_manager_1.IntlManager; } });
-Object.defineProperty(exports, "createLoader", { enumerable: true, get: function () { return intl_manager_1.createLoader; } });
 Object.defineProperty(exports, "DEFAULT_LOCALE", { enumerable: true, get: function () { return intl_manager_1.DEFAULT_LOCALE; } });
-__exportStar(require("./formatters"), exports);
+var message_loader_1 = require("./message-loader");
+Object.defineProperty(exports, "createLoader", { enumerable: true, get: function () { return message_loader_1.createLoader; } });
+Object.defineProperty(exports, "loadAllMessagesInLocale", { enumerable: true, get: function () { return message_loader_1.loadAllMessagesInLocale; } });
+Object.defineProperty(exports, "waitForAllDefaultIntlMessagesLoaded", { enumerable: true, get: function () { return message_loader_1.waitForAllDefaultIntlMessagesLoaded; } });
+Object.defineProperty(exports, "MessageLoader", { enumerable: true, get: function () { return message_loader_1.MessageLoader; } });

package/dist/intl-manager.d.ts

@@ -1,5 +1,4 @@
 import { IntlShape } from '@formatjs/intl';
-import { LocaleId, LocaleImportMap, MessageLoader } from './message-loader';
 import type { FormatterImplementation, IntlMessageGetter, RequiredFormatValues, TypedIntlMessageGetter } from './types';
 import { InternalIntlMessage } from './message';
 import { FormatBuilderConstructor } from './format';
@@ -48,10 +47,4 @@ export declare class IntlManager {
     string<T extends TypedIntlMessageGetter<undefined>>(message: T): string;
     bindFormatValues<T>(Builder: FormatBuilderConstructor<T>, message: InternalIntlMessage, values: Record<string, any>): T[];
 }
-/**
- * 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(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId): MessageLoader;
 export {};

package/dist/intl-manager.js

@@ -28,10 +28,8 @@ var __read = (this && this.__read) || function (o, n) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IntlManager = exports.DEFAULT_LOCALE = void 0;
-exports.createLoader = createLoader;
 var intl_1 = require("@formatjs/intl");
 var intl_messageformat_1 = require("intl-messageformat");
-var message_loader_1 = require("./message-loader");
 var format_1 = require("./format");
 /**
  * Fallback locale used for all internationalization when an operation in the
@@ -122,8 +120,11 @@ var IntlManager = /** @class */ (function () {
      * immediately return the plain string value of the message in the current locale.
      */
     IntlManager.prototype.string = function (message) {
-        // TODO: Figure out how to make this typing exact.
-        return message(this.currentLocale).message;
+        // @ts-expect-error Figure out how to make this typing exact. This
+        // currently relies on the generic typing being sound enough to know that
+        // the message can only contain a single static text node and no
+        // placeholders or rich text.
+        return message(this.currentLocale).ast[0].value;
     };
     IntlManager.prototype.bindFormatValues = function (Builder, message, values) {
         return (0, format_1.bindFormatValues)(Builder, message.ast, [this.currentLocale, this.defaultLocale], this.intl.formatters, this.intl.formats, values);
@@ -131,11 +132,3 @@ var IntlManager = /** @class */ (function () {
     return IntlManager;
 }());
 exports.IntlManager = IntlManager;
-/**
- * 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(messageKeys, localeImportMap, defaultLocale) {
-    return new message_loader_1.MessageLoader(messageKeys, localeImportMap, defaultLocale);
-}

package/dist/message-loader.d.ts

@@ -28,9 +28,17 @@ export declare class MessageLoader {
      * then a request has already been made to load the locale and it is waiting
      * to resolve.
      */
-    _localeLoadingPromises: Record<LocaleId, Promise<{
-        default: MessagesData;
-    }> | undefined>;
+    _localeLoadingPromises: Record<LocaleId, {
+        /**`true` if this locale has been loaded at least once. */
+        initialized: boolean;
+        /**
+         * If the locale is currently being loaded, this Promise will exist and
+         * represent that loading status. Otherwise, this value is undefined.
+         */
+        current?: Promise<{
+            default: MessagesData;
+        }> | undefined;
+    }>;
     /**
      * Map of pre-parsed messages, keyed by the message key and locale
      */
@@ -99,5 +107,36 @@ export declare class MessageLoader {
      * Subscribe to events about when a locale has loaded.
      */
     onChange(callback: () => void): () => void;
+    isLocaleLoaded(locale: LocaleId, requireCurrent?: boolean): boolean;
+    waitForLocaleLoaded(locale: LocaleId, requireCurrent?: boolean): Promise<void>;
+    /**
+     * Returns true if this loader's default locale has finished loading. When
+     * true, all messages managed by this loader are guaranteed to have _a_
+     * render-able value, even if one does not exist in the current locale.
+     */
+    waitForDefaultLocale(requireCurrent?: boolean): Promise<void>;
 }
+/**
+ * Kick off a load request for the given locale across all currently-registered
+ * message loaders, returning a Promise that resolves when all loaders have
+ * finished loading that locale.
+ */
+export declare function loadAllMessagesInLocale(locale: LocaleId): Promise<void>;
+/**
+ * Returns a new Promise that resolves after all currently-registered message
+ * loaders have finished successfully loading their default locale content.
+ * Once this Promise has resolved, all messages that currently exist in the
+ * application (i.e., within all modules that have been imported or required in
+ * the current session) can be guaranteed to have _a_ render-able value.
+ *
+ * This function can be called at any point in an applications life cycle and
+ * will always ensure that _all_ loaders that currently exist are initialized.
+ */
+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 defined in `messageKeys`.
+ */
+export declare function createLoader(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId): MessageLoader;
 export {};

package/dist/message-loader.js

@@ -64,6 +64,9 @@ var __read = (this && this.__read) || function (o, n) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessageLoader = void 0;
+exports.loadAllMessagesInLocale = loadAllMessagesInLocale;
+exports.waitForAllDefaultIntlMessagesLoaded = waitForAllDefaultIntlMessagesLoaded;
+exports.createLoader = createLoader;
 var message_1 = require("./message");
 var MessageLoader = /** @class */ (function () {
     function MessageLoader(messageKeys, localeImportMap, defaultLocale) {
@@ -78,17 +81,24 @@ var MessageLoader = /** @class */ (function () {
         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');
+        this.fallbackMessage = new message_1.InternalIntlMessage([], this.defaultLocale);
         // 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);
-                });
+                module.hot.accept(file, function () { return __awaiter(_this, void 0, void 0, function () {
+                    return __generator(this, function (_a) {
+                        switch (_a.label) {
+                            case 0: return [4 /*yield*/, this._loadLocale(locale)];
+                            case 1:
+                                _a.sent();
+                                this._parseCache.clear();
+                                return [2 /*return*/];
+                        }
+                    });
+                }); });
             };
             try {
                 for (var _b = __values(Object.entries(localeImportMap)), _c = _b.next(); !_c.done; _c = _b.next()) {
@@ -119,9 +129,8 @@ var MessageLoader = /** @class */ (function () {
     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) {
+        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;
@@ -146,13 +155,11 @@ var MessageLoader = /** @class */ (function () {
         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.
+        // Check whether the locale exists in memory. If not, start a request to
+        // load the locale if one has not already started. It's impossible for
+        // the request to finish within the same tick, so return undefined in any
+        // case then.
         if (this.messages[locale] == null) {
-            // Ensure the locale is loaded, if it is supported
             if (this.supportedLocales.includes(locale)) {
                 this._loadLocale(locale);
             }
@@ -186,12 +193,13 @@ var MessageLoader = /** @class */ (function () {
     };
     MessageLoader.prototype._loadLocale = function (locale) {
         return __awaiter(this, void 0, void 0, function () {
-            var loadingPromise, _a, _b;
-            return __generator(this, function (_c) {
-                switch (_c.label) {
+            var current, _a, _b;
+            var _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
                     case 0:
                         // Don't re-load a locale that's already in progress.
-                        if (this._localeLoadingPromises[locale] != null) {
+                        if (((_c = this._localeLoadingPromises[locale]) === null || _c === void 0 ? void 0 : _c.current) != null) {
                             return [2 /*return*/];
                         }
                         // Safety check in case the locale map doesn't include a require for the
@@ -203,14 +211,14 @@ 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*/];
-                        loadingPromise = this.localeImportMap[locale]();
-                        this._localeLoadingPromises[locale] = loadingPromise;
+                        current = this.localeImportMap[locale]();
+                        this._localeLoadingPromises[locale] = { initialized: false, current: current };
                         _a = this.messages;
                         _b = locale;
-                        return [4 /*yield*/, loadingPromise];
+                        return [4 /*yield*/, current];
                     case 1:
-                        _a[_b] = (_c.sent()).default;
-                        delete this._localeLoadingPromises[locale];
+                        _a[_b] = (_d.sent()).default;
+                        this._localeLoadingPromises[locale] = { initialized: true, current: undefined };
                         this.emitChange();
                         return [2 /*return*/];
                 }
@@ -245,6 +253,111 @@ var MessageLoader = /** @class */ (function () {
         this._subscribers.add(callback);
         return function () { return _this._subscribers.delete(callback); };
     };
+    MessageLoader.prototype.isLocaleLoaded = function (locale, requireCurrent) {
+        if (requireCurrent === void 0) { requireCurrent = false; }
+        var ref = this._localeLoadingPromises[locale];
+        // Ensure the locale at least exists and is initialized.
+        if (ref == null || ref.initialized == false)
+            return false;
+        // `current` will be deleted once the locale has loaded, so if it is null,
+        // then the locale data is current.
+        if (requireCurrent)
+            return ref.current == null;
+        // Otherwise, initialization is enough.
+        return true;
+    };
+    MessageLoader.prototype.waitForLocaleLoaded = function (locale_1) {
+        return __awaiter(this, arguments, void 0, function (locale, requireCurrent) {
+            var ref;
+            if (requireCurrent === void 0) { requireCurrent = false; }
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        ref = this._localeLoadingPromises[locale];
+                        // If the locale hasn't been loaded at all, kick off the load and return
+                        // that Promise directly.
+                        if (ref == null)
+                            return [2 /*return*/, this._loadLocale(locale)];
+                        // If initialization is enough for this request, just resolve immediately.
+                        if (ref.initialized && !requireCurrent)
+                            return [2 /*return*/];
+                        // Otherwise, check the `current` loading state on the object, and if that
+                        // doesn't exist, then the locale data is already finished loading, and the
+                        // containing Promise will just resolve with `undefined`.
+                        return [4 /*yield*/, ref.current];
+                    case 1:
+                        // Otherwise, check the `current` loading state on the object, and if that
+                        // doesn't exist, then the locale data is already finished loading, and the
+                        // containing Promise will just resolve with `undefined`.
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Returns true if this loader's default locale has finished loading. When
+     * true, all messages managed by this loader are guaranteed to have _a_
+     * render-able value, even if one does not exist in the current locale.
+     */
+    MessageLoader.prototype.waitForDefaultLocale = function () {
+        return __awaiter(this, arguments, void 0, function (requireCurrent) {
+            if (requireCurrent === void 0) { requireCurrent = false; }
+            return __generator(this, function (_a) {
+                return [2 /*return*/, this.waitForLocaleLoaded(this.defaultLocale, requireCurrent)];
+            });
+        });
+    };
     return MessageLoader;
 }());
 exports.MessageLoader = MessageLoader;
+var LOADER_REGISTRY = [];
+/**
+ * Kick off a load request for the given locale across all currently-registered
+ * message loaders, returning a Promise that resolves when all loaders have
+ * finished loading that locale.
+ */
+function loadAllMessagesInLocale(locale) {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, Promise.all(LOADER_REGISTRY.map(function (loader) { return loader._loadLocale(locale); }))];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Returns a new Promise that resolves after all currently-registered message
+ * loaders have finished successfully loading their default locale content.
+ * Once this Promise has resolved, all messages that currently exist in the
+ * application (i.e., within all modules that have been imported or required in
+ * the current session) can be guaranteed to have _a_ render-able value.
+ *
+ * This function can be called at any point in an applications life cycle and
+ * will always ensure that _all_ loaders that currently exist are initialized.
+ */
+function waitForAllDefaultIntlMessagesLoaded() {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, Promise.all(LOADER_REGISTRY.map(function (loader) { return loader.waitForDefaultLocale(); }))];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * 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(messageKeys, localeImportMap, defaultLocale) {
+    var loader = new MessageLoader(messageKeys, localeImportMap, defaultLocale);
+    LOADER_REGISTRY.push(loader);
+    return loader;
+}

package/dist/message.d.ts

@@ -1,20 +1,6 @@
 import { FormatJsNode } from './keyless-json';
 export declare class InternalIntlMessage {
     locale: string;
-    message?: string;
     ast: FormatJsNode[];
-    /**
-     * A stripped-down representation of the message with no rich formatting
-     * elements preserved. This will be lazily created the first time it is
-     * requested (e.g., by calling `formatToPlainString`).
-     */
-    get plainAst(): FormatJsNode[];
-    _plainAst: FormatJsNode[];
-    constructor(messageOrAst: string | FormatJsNode[], locale: string);
-    /**
-     * Returns the same element with any formatting tags removed. If the element
-     * itself is a tag, the children will be hoisted and returned, otherwise the
-     * element is returned as an array of itself.
-     */
-    private _removeRichTags;
+    constructor(messageOrAst: FormatJsNode[], locale: string);
 }

package/dist/message.js

@@ -1,93 +1,11 @@
 "use strict";
-var __values = (this && this.__values) || function(o) {
-    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
-    if (m) return m.call(o);
-    if (o && typeof o.length === "number") return {
-        next: function () {
-            if (o && i >= o.length) o = void 0;
-            return { value: o && o[i++], done: !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;
-};
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InternalIntlMessage = void 0;
-var keyless_json_1 = require("./keyless-json");
 var InternalIntlMessage = /** @class */ (function () {
     function InternalIntlMessage(messageOrAst, locale) {
         this.locale = locale;
-        if (typeof messageOrAst === 'string') {
-            this.message = messageOrAst;
-        }
-        else {
-            this.ast = messageOrAst;
-        }
+        this.ast = messageOrAst;
     }
-    Object.defineProperty(InternalIntlMessage.prototype, "plainAst", {
-        /**
-         * A stripped-down representation of the message with no rich formatting
-         * elements preserved. This will be lazily created the first time it is
-         * requested (e.g., by calling `formatToPlainString`).
-         */
-        get: function () {
-            return (this._plainAst = this._removeRichTags(this.ast));
-        },
-        enumerable: false,
-        configurable: true
-    });
-    /**
-     * Returns the same element with any formatting tags removed. If the element
-     * itself is a tag, the children will be hoisted and returned, otherwise the
-     * element is returned as an array of itself.
-     */
-    InternalIntlMessage.prototype._removeRichTags = function (nodes) {
-        var e_1, _a;
-        var result = new Array(nodes.length);
-        try {
-            for (var nodes_1 = __values(nodes), nodes_1_1 = nodes_1.next(); !nodes_1_1.done; nodes_1_1 = nodes_1.next()) {
-                var node = nodes_1_1.value;
-                if (node.type === keyless_json_1.FormatJsNodeType.Tag) {
-                    result.push.apply(result, __spreadArray([], __read(this._removeRichTags(node.children)), false));
-                }
-                else {
-                    result.push(node);
-                }
-            }
-        }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
-        finally {
-            try {
-                if (nodes_1_1 && !nodes_1_1.done && (_a = nodes_1.return)) _a.call(nodes_1);
-            }
-            finally { if (e_1) throw e_1.error; }
-        }
-        return result;
-    };
     return InternalIntlMessage;
 }());
 exports.InternalIntlMessage = InternalIntlMessage;

package/dist/types.d.ts

@@ -198,8 +198,8 @@ export interface FunctionTypeMap {
 }
 
 export interface FunctionTypes<Result, HandlerType = (content: Result[]) => Result | Result[]> {
-  link: undefined | ((content: Result[]) => Result | Result[]);
-  hook: undefined | ((content: Result[]) => Result | Result[]);
+  link: undefined | ((content: Result[], key: number) => Result | Result[]);
+  hook: undefined | ((content: Result[], key: number) => Result | Result[]);
   handler: undefined | HandlerType;
 }
 

package/package.json

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

package/src/formatters/ast.ts

@@ -36,15 +36,6 @@ export enum RichTextNodeType {
   Object = 'object',
 }
 
-const RICH_TEXT_TAG_TYPES: Record<RichTextTagNames, RichTextNodeType> = {
-  $_: RichTextNodeType.Text,
-  $b: RichTextNodeType.Strong,
-  $i: RichTextNodeType.Emphasis,
-  $code: RichTextNodeType.Code,
-  $link: RichTextNodeType.Link,
-  $p: RichTextNodeType.Paragraph,
-};
-
 interface RichTextNodeBase<ContentType> {
   type: RichTextNodeType;
   content: ContentType;
@@ -101,7 +92,7 @@ class AstBuilder extends FormatBuilder<RichTextNode> {
     if (!(tag in AST_RICH_TEXT_ELEMENTS)) {
       throw `${tag} is not a known rich text formatting tag`;
     }
-    const result = AST_RICH_TEXT_ELEMENTS[tag](children);
+    const result = AST_RICH_TEXT_ELEMENTS[tag](children, 0);
     if (Array.isArray(result)) {
       this.result.push(...result);
     } else {

package/src/formatters/markdown.ts

@@ -31,7 +31,7 @@ class MarkdownBuilder extends StringBuilder {
   result: string = '';
 
   pushRichTextTag(tag: RichTextTagNames, children: string[]) {
-    this.result += MARKDOWN_RICH_TEXT_ELEMENTS[tag](children);
+    this.result += MARKDOWN_RICH_TEXT_ELEMENTS[tag](children, 0);
   }
 }
 

package/src/formatters/react.ts

@@ -28,12 +28,12 @@ export type ReactFunctionTypes = FunctionTypes<
 const h = React.createElement;
 export const DEFAULT_REACT_RICH_TEXT_ELEMENTS: RichTextFormattingMap<ReactFunctionTypes['hook']> = {
   $_: () => '',
-  $b: (content) => h('strong', undefined, content),
-  $code: (content) => h('code', undefined, content),
-  $i: (content) => h('em', undefined, content),
+  $b: (content, key) => h('strong', { key }, content),
+  $code: (content, key) => h('code', { key }, content),
+  $i: (content, key) => h('em', { key }, content),
   // $link will always be [href, <empty>, ...content]
-  $link: ([href, ...content]) => h('a', { href }, content),
-  $p: (content) => h('p', undefined, content),
+  $link: ([href, ...content], key) => h('a', { href, key }, content),
+  $p: (content, key) => h('p', { key }, content),
 };
 
 /**
@@ -47,10 +47,11 @@ function createReactBuilder(richTextElements: RichTextFormattingMap<ReactFunctio
   new (): FormatBuilder<React.ReactNode>;
 } {
   return class extends FormatBuilder<React.ReactNode> {
+    _nodeKey: number = 0;
     result: React.ReactNode[] = [];
 
     pushRichTextTag(tag: RichTextTagNames, children: React.ReactNode[]) {
-      this.result.push(richTextElements[tag](children));
+      this.result.push(richTextElements[tag](children, this._nodeKey++));
     }
 
     pushLiteralText(text: string) {
@@ -69,18 +70,23 @@ function createReactBuilder(richTextElements: RichTextFormattingMap<ReactFunctio
   };
 }
 
+export type ReactIntlMessage = React.ReactElement<
+  {},
+  typeof React.Fragment & { __brand: 'discord-intl' }
+>;
+
 export function formatReact(
   this: IntlManager,
   message: AnyIntlMessage,
   values: object,
   Builder: FormatBuilderConstructor<React.ReactElement>,
-): React.ReactElement {
+): ReactIntlMessage {
   if (typeof message === 'string') {
-    return React.createElement(React.Fragment, undefined, message);
+    return React.createElement(React.Fragment, undefined, message) as ReactIntlMessage;
   }
 
   const parts = this.bindFormatValues(Builder, message, values);
-  return React.createElement(React.Fragment, undefined, parts);
+  return React.createElement(React.Fragment, undefined, parts) as ReactIntlMessage;
 }
 
 /**

package/src/index.ts

@@ -1,9 +1,14 @@
 import * as React from 'react';
 import { RichTextNode } from './formatters';
 
-export { IntlManager, createLoader, DEFAULT_LOCALE, type FormatFunction } from './intl-manager';
 export * from './formatters';
-
+export { IntlManager, DEFAULT_LOCALE, type FormatFunction } from './intl-manager';
+export {
+  createLoader,
+  loadAllMessagesInLocale,
+  waitForAllDefaultIntlMessagesLoaded,
+  MessageLoader,
+} from './message-loader';
 export type * from './types.d.ts';
 
 /**
@@ -21,6 +26,7 @@ export type * from './types.d.ts';
  * intl message, even if the actual value comes from elsewhere (like a
  * user-generated string).
  */
+// TODO: Replace this with ReactIntlMessage from `formatters/react`.
 export type ReactIntlMessage = string | React.ReactElement;
 
 /**

package/src/intl-manager.ts

@@ -116,8 +116,11 @@ export class IntlManager {
    * immediately return the plain string value of the message in the current locale.
    */
   string<T extends TypedIntlMessageGetter<undefined>>(message: T): string {
-    // TODO: Figure out how to make this typing exact.
-    return message(this.currentLocale).message;
+    // @ts-expect-error Figure out how to make this typing exact. This
+    // currently relies on the generic typing being sound enough to know that
+    // the message can only contain a single static text node and no
+    // placeholders or rich text.
+    return message(this.currentLocale).ast[0].value;
   }
 
   bindFormatValues<T>(
@@ -135,16 +138,3 @@ export class IntlManager {
     );
   }
 }
-
-/**
- * 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(
-  messageKeys: string[],
-  localeImportMap: LocaleImportMap,
-  defaultLocale: LocaleId,
-) {
-  return new MessageLoader(messageKeys, localeImportMap, defaultLocale);
-}

package/src/message-loader.ts

@@ -32,7 +32,18 @@ export class MessageLoader {
    * then a request has already been made to load the locale and it is waiting
    * to resolve.
    */
-  _localeLoadingPromises: Record<LocaleId, Promise<{ default: MessagesData }> | undefined>;
+  _localeLoadingPromises: Record<
+    LocaleId,
+    {
+      /**`true` if this locale has been loaded at least once. */
+      initialized: boolean;
+      /**
+       * If the locale is currently being loaded, this Promise will exist and
+       * represent that loading status. Otherwise, this value is undefined.
+       */
+      current?: Promise<{ default: MessagesData }> | undefined;
+    }
+  >;
 
   /**
    * Map of pre-parsed messages, keyed by the message key and locale
@@ -85,7 +96,7 @@ export class MessageLoader {
     this._subscribers = new Set();
 
     this._loadLocale(this.defaultLocale);
-    this.fallbackMessage = new InternalIntlMessage('THIS MESSAGE FAILED TO LOAD', 'en-US');
+    this.fallbackMessage = new InternalIntlMessage([], this.defaultLocale);
 
     // In cases where hot module replacement is available, set up cache clearing whenever the
     // targets change so that values are always replaced.
@@ -93,9 +104,9 @@ export class MessageLoader {
     if (module.hot) {
       for (const [locale, file] of Object.entries(localeImportMap)) {
         // @ts-expect-error `hot` not defined in types.
-        module.hot.accept(file, () => {
+        module.hot.accept(file, async () => {
+          await this._loadLocale(locale);
           this._parseCache.clear();
-          this._loadLocale(locale);
         });
       }
     }
@@ -116,9 +127,7 @@ export class MessageLoader {
   get(key: string, locale: LocaleId): InternalIntlMessage {
     const value =
       this.getMessageValue(key, locale) ?? this.getMessageValue(key, this.defaultLocale);
-    if (value != null) {
-      return value;
-    }
+    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.
@@ -149,18 +158,14 @@ export class MessageLoader {
     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.
+    // Check whether the locale exists in memory. If not, start a request to
+    // load the locale if one has not already started. It's impossible for
+    // the request to finish within the same tick, so return undefined in any
+    // case then.
     if (this.messages[locale] == null) {
-      // Ensure the locale is loaded, if it is supported
       if (this.supportedLocales.includes(locale)) {
         this._loadLocale(locale);
       }
-
       return undefined;
     }
 
@@ -197,7 +202,7 @@ export class MessageLoader {
 
   async _loadLocale(locale: LocaleId) {
     // Don't re-load a locale that's already in progress.
-    if (this._localeLoadingPromises[locale] != null) {
+    if (this._localeLoadingPromises[locale]?.current != null) {
       return;
     }
 
@@ -213,10 +218,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 loadingPromise = this.localeImportMap[locale]();
-    this._localeLoadingPromises[locale] = loadingPromise;
-    this.messages[locale] = (await loadingPromise).default;
-    delete this._localeLoadingPromises[locale];
+    const current = this.localeImportMap[locale]();
+    this._localeLoadingPromises[locale] = { initialized: false, current };
+    this.messages[locale] = (await current).default;
+    this._localeLoadingPromises[locale] = { initialized: true, current: undefined };
     this.emitChange();
   }
 
@@ -238,4 +243,77 @@ export class MessageLoader {
 
     return () => this._subscribers.delete(callback);
   }
+
+  isLocaleLoaded(locale: LocaleId, requireCurrent: boolean = false): boolean {
+    const ref = this._localeLoadingPromises[locale];
+    // Ensure the locale at least exists and is initialized.
+    if (ref == null || ref.initialized == false) return false;
+    // `current` will be deleted once the locale has loaded, so if it is null,
+    // then the locale data is current.
+    if (requireCurrent) return ref.current == null;
+    // Otherwise, initialization is enough.
+    return true;
+  }
+
+  async waitForLocaleLoaded(locale: LocaleId, requireCurrent = false): Promise<void> {
+    const ref = this._localeLoadingPromises[locale];
+    // If the locale hasn't been loaded at all, kick off the load and return
+    // that Promise directly.
+    if (ref == null) return this._loadLocale(locale);
+    // If initialization is enough for this request, just resolve immediately.
+    if (ref.initialized && !requireCurrent) return;
+    // Otherwise, check the `current` loading state on the object, and if that
+    // doesn't exist, then the locale data is already finished loading, and the
+    // containing Promise will just resolve with `undefined`.
+    await ref.current;
+  }
+
+  /**
+   * Returns true if this loader's default locale has finished loading. When
+   * true, all messages managed by this loader are guaranteed to have _a_
+   * render-able value, even if one does not exist in the current locale.
+   */
+  async waitForDefaultLocale(requireCurrent = false): Promise<void> {
+    return this.waitForLocaleLoaded(this.defaultLocale, requireCurrent);
+  }
+}
+
+const LOADER_REGISTRY: MessageLoader[] = [];
+
+/**
+ * Kick off a load request for the given locale across all currently-registered
+ * message loaders, returning a Promise that resolves when all loaders have
+ * finished loading that locale.
+ */
+export async function loadAllMessagesInLocale(locale: LocaleId): Promise<void> {
+  await Promise.all(LOADER_REGISTRY.map((loader) => loader._loadLocale(locale)));
+}
+
+/**
+ * Returns a new Promise that resolves after all currently-registered message
+ * loaders have finished successfully loading their default locale content.
+ * Once this Promise has resolved, all messages that currently exist in the
+ * application (i.e., within all modules that have been imported or required in
+ * the current session) can be guaranteed to have _a_ render-able value.
+ *
+ * This function can be called at any point in an applications life cycle and
+ * will always ensure that _all_ loaders that currently exist are initialized.
+ */
+export async function waitForAllDefaultIntlMessagesLoaded(): Promise<void> {
+  await Promise.all(LOADER_REGISTRY.map((loader) => loader.waitForDefaultLocale()));
+}
+
+/**
+ * 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(
+  messageKeys: string[],
+  localeImportMap: LocaleImportMap,
+  defaultLocale: LocaleId,
+) {
+  const loader = new MessageLoader(messageKeys, localeImportMap, defaultLocale);
+  LOADER_REGISTRY.push(loader);
+  return loader;
 }

package/src/message.ts

@@ -1,44 +1,11 @@
-import { FormatJsNode, FormatJsNodeType } from './keyless-json';
+import { FormatJsNode } from './keyless-json';
 
 export class InternalIntlMessage {
   locale: string;
-  message?: string;
   ast: FormatJsNode[];
 
-  /**
-   * A stripped-down representation of the message with no rich formatting
-   * elements preserved. This will be lazily created the first time it is
-   * requested (e.g., by calling `formatToPlainString`).
-   */
-  get plainAst(): FormatJsNode[] {
-    return (this._plainAst = this._removeRichTags(this.ast));
-  }
-  _plainAst: FormatJsNode[];
-
-  constructor(messageOrAst: string | FormatJsNode[], locale: string) {
+  constructor(messageOrAst: FormatJsNode[], locale: string) {
     this.locale = locale;
-
-    if (typeof messageOrAst === 'string') {
-      this.message = messageOrAst;
-    } else {
-      this.ast = messageOrAst;
-    }
-  }
-
-  /**
-   * Returns the same element with any formatting tags removed. If the element
-   * itself is a tag, the children will be hoisted and returned, otherwise the
-   * element is returned as an array of itself.
-   */
-  private _removeRichTags(nodes: FormatJsNode[]): FormatJsNode[] {
-    const result = new Array(nodes.length);
-    for (const node of nodes) {
-      if (node.type === FormatJsNodeType.Tag) {
-        result.push(...this._removeRichTags(node.children));
-      } else {
-        result.push(node);
-      }
-    }
-    return result;
+    this.ast = messageOrAst;
   }
 }

package/src/types.d.ts

@@ -198,8 +198,8 @@ export interface FunctionTypeMap {
 }
 
 export interface FunctionTypes<Result, HandlerType = (content: Result[]) => Result | Result[]> {
-  link: undefined | ((content: Result[]) => Result | Result[]);
-  hook: undefined | ((content: Result[]) => Result | Result[]);
+  link: undefined | ((content: Result[], key: number) => Result | Result[]);
+  hook: undefined | ((content: Result[], key: number) => Result | Result[]);
   handler: undefined | HandlerType;
 }