@discord/intl 0.18.0 → 0.19.1-canary.f6592a8

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { runtimeHashMessageKey } from './hash';
 export { IntlManager, DEFAULT_LOCALE, type FormatFunction } from './intl-manager';
 export { createLoader, loadAllMessagesInLocale, waitForAllDefaultIntlMessagesLoaded, MessageLoader, } from './message-loader';
 export type * from './types.d.ts';
+export { chainMessagesObjects, makeMessagesProxy } from './runtime-utils';
 /**
  * The return value of `formatToParts` from `@discord/intl`, this type
  * represents any AST structure for a message rendered using this system.

package/dist/index.js

@@ -14,7 +14,7 @@ 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.MessageLoader = exports.waitForAllDefaultIntlMessagesLoaded = exports.loadAllMessagesInLocale = exports.createLoader = exports.DEFAULT_LOCALE = exports.IntlManager = exports.runtimeHashMessageKey = exports.bindFormatValues = exports.FormatBuilder = exports.dataFormatterCache = exports.makeDataFormatters = void 0;
+exports.makeMessagesProxy = exports.chainMessagesObjects = exports.MessageLoader = exports.waitForAllDefaultIntlMessagesLoaded = exports.loadAllMessagesInLocale = exports.createLoader = exports.DEFAULT_LOCALE = exports.IntlManager = exports.runtimeHashMessageKey = exports.bindFormatValues = exports.FormatBuilder = exports.dataFormatterCache = exports.makeDataFormatters = void 0;
 var data_formatters_1 = require("./data-formatters");
 Object.defineProperty(exports, "makeDataFormatters", { enumerable: true, get: function () { return data_formatters_1.makeDataFormatters; } });
 var cache_1 = require("./data-formatters/cache");
@@ -33,3 +33,6 @@ Object.defineProperty(exports, "createLoader", { enumerable: true, get: function
 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; } });
+var runtime_utils_1 = require("./runtime-utils");
+Object.defineProperty(exports, "chainMessagesObjects", { enumerable: true, get: function () { return runtime_utils_1.chainMessagesObjects; } });
+Object.defineProperty(exports, "makeMessagesProxy", { enumerable: true, get: function () { return runtime_utils_1.makeMessagesProxy; } });

package/dist/message-loader.d.ts

@@ -52,9 +52,28 @@ export declare class MessageLoader {
      */
     _subscribers: Set<() => void>;
     /**
-     * Message to show as a fallback when the requested message is unavailable.
+     * If a message is not present in this loader, try looking it up in this
+     * loader instead before resorting to a default placeholder message.
+     *
+     * The order of lookups will be:
+     * - this loader, requested locale
+     * - this loader, default locale
+     * - fallback loader, requested locale
+     * - fallback loader, default locale
+     * - fallback message
+     */
+    fallbackLoader?: MessageLoader;
+    /**
+     * Message to show as a fallback when the requested message is unavailable
+     * from both this loader and the fallback loader.
      */
     fallbackMessage: InternalIntlMessage;
+    /**
+     * When `fallbackLoader` is set, this value will be set on the fallback
+     * loader to reference this loader. Setting this ensures that loaders won't
+     * ever form an infinite circular chain.
+     */
+    _parentLoader?: MessageLoader;
     /**
      * Map from hashed message keys to their original values, to provide context in error messages
      * that would otherwise be obfuscated.
@@ -73,7 +92,7 @@ export declare class MessageLoader {
      * @private
      */
     _localeFileMap?: Record<string, string>;
-    constructor(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId);
+    constructor(localeImportMap: LocaleImportMap, defaultLocale: LocaleId);
     /**
      * Provide additional debug information to use during development, providing additional context
      * for console error messages.
@@ -82,6 +101,23 @@ export declare class MessageLoader {
      * @param {Record<string, string>} localeFileMap
      */
     withDebugValues(keyMap: Record<string, string>, localeFileMap: Record<string, string>): void;
+    /**
+     * Configure a fallback loader to search for any message requests that are not resolved by this
+     * loader directly. For example, if a request for a message "abcdef" in locale `pt-BR` is not
+     * found in this loader's managed content, the request gets forwarded on to this fallback instead.
+     *
+     * The lookup first exhausts this loader entirely before checking the fallback, in the order:
+     * - This loader's requested locale.
+     * - This loader's default locale.
+     * - Fallback loader's requested locale.
+     * - Fallback loader's default locale.
+     * - Fallback loader's final fallback value.
+     * - This loader's final fallback value.
+     *
+     * Note that the final fallback value (the `fallbackMessage` property on this class) will first
+     * be retrieved from the fallback loader rather than this instance.
+     */
+    fallbackWith(fallback: MessageLoader): 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
@@ -93,20 +129,6 @@ 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
@@ -145,9 +167,12 @@ 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 defined in `messageKeys`.
+ * 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).
  */
-export declare function createLoader(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId): MessageLoader;
+export declare function createLoader(localeImportMap: LocaleImportMap, defaultLocale: LocaleId): MessageLoader;
 export {};

package/dist/message-loader.js

@@ -15,8 +15,7 @@ exports.waitForAllDefaultIntlMessagesLoaded = waitForAllDefaultIntlMessagesLoade
 exports.createLoader = createLoader;
 const message_1 = require("./message");
 class MessageLoader {
-    constructor(messageKeys, localeImportMap, defaultLocale) {
-        this.messageKeys = messageKeys;
+    constructor(localeImportMap, defaultLocale) {
         this.messages = {};
         this.localeImportMap = localeImportMap;
         this.supportedLocales = Object.keys(localeImportMap);
@@ -51,7 +50,35 @@ class MessageLoader {
         this._debugKeyMap = keyMap;
         this._localeFileMap = localeFileMap;
     }
+    /**
+     * Configure a fallback loader to search for any message requests that are not resolved by this
+     * loader directly. For example, if a request for a message "abcdef" in locale `pt-BR` is not
+     * found in this loader's managed content, the request gets forwarded on to this fallback instead.
+     *
+     * The lookup first exhausts this loader entirely before checking the fallback, in the order:
+     * - This loader's requested locale.
+     * - This loader's default locale.
+     * - Fallback loader's requested locale.
+     * - Fallback loader's default locale.
+     * - Fallback loader's final fallback value.
+     * - This loader's final fallback value.
+     *
+     * Note that the final fallback value (the `fallbackMessage` property on this class) will first
+     * be retrieved from the fallback loader rather than this instance.
+     */
+    fallbackWith(fallback) {
+        let parent = this;
+        while (parent != null) {
+            parent = parent._parentLoader;
+            if (parent === this) {
+                throw new Error('Setting `fallbackWith` on MessageLoader created a circular chain that would never resolve');
+            }
+        }
+        this.fallbackLoader = fallback;
+        fallback._parentLoader = this;
+    }
     get(key, locale) {
+        var _a;
         const expectedValue = this.getMessageValue(key, locale);
         if (expectedValue != null)
             return expectedValue;
@@ -61,9 +88,13 @@ class MessageLoader {
         if (this.isLocaleLoading(locale) && !this.isLocaleLoaded(this.defaultLocale)) {
             return this.fallbackMessage;
         }
-        const fallbackValue = this.getMessageValue(key, this.defaultLocale);
-        if (fallbackValue != null)
-            return fallbackValue;
+        const defaultLocaleValue = this.getMessageValue(key, this.defaultLocale);
+        if (defaultLocaleValue != null)
+            return defaultLocaleValue;
+        const fallbackLoaderValue = (_a = this.fallbackLoader) === null || _a === void 0 ? void 0 : _a.get(key, locale);
+        if (fallbackLoaderValue != null) {
+            return fallbackLoaderValue;
+        }
         // 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;
@@ -99,9 +130,16 @@ class MessageLoader {
             }
             return undefined;
         }
-        // Then try to return the loaded message.
-        if (key in this.messages[locale]) {
-            const content = this.messages[locale][key];
+        // 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) {
             const message = new message_1.InternalIntlMessage(content, locale);
             ((_b = (_c = this._parseCache)[locale]) !== null && _b !== void 0 ? _b : (_c[locale] = {}))[key] = message;
             return message;
@@ -109,26 +147,6 @@ 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;
@@ -248,12 +266,15 @@ 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 defined in `messageKeys`.
+ * 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).
  */
-function createLoader(messageKeys, localeImportMap, defaultLocale) {
-    const loader = new MessageLoader(messageKeys, localeImportMap, defaultLocale);
+function createLoader(localeImportMap, defaultLocale) {
+    const loader = new MessageLoader(localeImportMap, defaultLocale);
     LOADER_REGISTRY.push(loader);
     return loader;
 }

package/dist/runtime-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Utility functions and classes used at runtime by the compiled output of bundlers using the intl
+ * packages like `intl-loader-core`'s `MessageDefinitionsTransformer`.
+ */
+import { MessageLoader } from './message-loader';
+import { IntlMessageGetter } from './types';
+interface MessageBindsProxy {
+    $$baseObject: Record<string, IntlMessageGetter>;
+    $$loader: MessageLoader;
+}
+/** Type created by the message transformer when `bindMode` is set to `literal`. */
+export type MessagesLiteral<T extends string> = Record<T, IntlMessageGetter>;
+export type AnyIntlMessagesObject<T extends string> = MessageBindsProxy | MessagesLiteral<T>;
+/**
+ * Return a new value that represents two message objects combined into one, regardless of their
+ * kind (either proxies or object literals). The returned value will be able to access any message
+ * contained in either of the two objects. This method generally assumes there is no overlap in
+ * keys between the two message objects, and the order of resolution is undefined (varies based on
+ * the types of the objects).
+ *
+ * Note that if both objects are proxies, the base loaders _are mutated in place_ to be chained
+ * together. Any other usages of the first object will also automatically fall back to the second.
+ */
+export declare function chainMessagesObjects<const First extends MessagesLiteral<string>, const Second extends MessagesLiteral<string>>(first: First, second: Second): First & Second;
+export declare function makeMessagesProxy(loader: MessageLoader): Record<string, IntlMessageGetter>;
+export {};

package/dist/runtime-utils.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chainMessagesObjects = chainMessagesObjects;
+exports.makeMessagesProxy = makeMessagesProxy;
+function isMessagesProxy(object) {
+    return object[Symbol.toStringTag] === 'IntlMessagesProxy';
+}
+/**
+ * Return a new value that represents two message objects combined into one, regardless of their
+ * kind (either proxies or object literals). The returned value will be able to access any message
+ * contained in either of the two objects. This method generally assumes there is no overlap in
+ * keys between the two message objects, and the order of resolution is undefined (varies based on
+ * the types of the objects).
+ *
+ * Note that if both objects are proxies, the base loaders _are mutated in place_ to be chained
+ * together. Any other usages of the first object will also automatically fall back to the second.
+ */
+function chainMessagesObjects(first, second) {
+    const firstIsProxy = isMessagesProxy(first);
+    const secondIsProxy = isMessagesProxy(second);
+    // This explicit any is a little strange, but when the objects are proxies, they don't have any
+    // actual type information, so trying to return them as a combination of `First` and `Second`
+    // causes TypeScript to error saying there are possibly different instantiations. Casting to `any`
+    // first makes it not care.
+    let result = first;
+    if (firstIsProxy && secondIsProxy) {
+        // If both are proxies, no change is actually required, and the first proxy can just have its
+        // loader set to fall back to the second.
+        first.$$loader.fallbackWith(second.$$loader);
+        result = first;
+    }
+    else if (!firstIsProxy && !secondIsProxy) {
+        // If both objects are plain literals, they can just be spread together to get the result.
+        result = Object.assign(Object.assign({}, second), first);
+    }
+    else if (firstIsProxy && !secondIsProxy) {
+        // If the first is a proxy and the second is an object, the second can be spread onto the first
+        // to "pre-fill" values on it. In reality these cases should never be hit.
+        result = Object.assign(first.$$baseObject, second);
+    }
+    else if (secondIsProxy && !firstIsProxy) {
+        // And the same is true in reverse.
+        result = Object.assign(second.$$baseObject, first);
+    }
+    return result;
+}
+function makeMessagesProxy(loader) {
+    function makeBind(prop) {
+        return (locale) => loader.get(prop, locale);
+    }
+    const baseObject = {};
+    const proxy = new Proxy(baseObject, {
+        ownKeys(self) {
+            return Reflect.ownKeys(self);
+        },
+        getOwnPropertyDescriptor(self, prop) {
+            return {
+                value: (self[prop] || (self[prop] = makeBind(prop))),
+                configurable: true,
+                enumerable: true,
+                writable: false,
+            };
+        },
+        get(self, prop) {
+            if (prop === '$$typeof') {
+                return 'object';
+            }
+            if (prop === Symbol.toStringTag) {
+                return 'IntlMessagesProxy';
+            }
+            self[prop] || (self[prop] = makeBind(prop));
+            return self[prop];
+        },
+    });
+    // Define the base object and loader on the proxy directly, but make them non-enumerable so that
+    // they don't show up when using `Object.keys` or other accessors.
+    Object.defineProperty(proxy, '$$baseObject', {
+        value: baseObject,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    Object.defineProperty(proxy, '$$loader', {
+        value: loader,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return proxy;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl",
-  "version": "0.18.0",
+  "version": "0.19.1-canary.f6592a8",
   "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.19.1-canary.f6592a8"
   },
   "devDependencies": {
     "@formatjs/intl-durationformat": "^0.7.3",

package/src/index.ts

@@ -12,6 +12,8 @@ export {
 } from './message-loader';
 export type * from './types.d.ts';
 
+export { chainMessagesObjects, makeMessagesProxy } from './runtime-utils';
+
 /**
  * The return value of `formatToParts` from `@discord/intl`, this type
  * represents any AST structure for a message rendered using this system.

package/src/message-loader.ts

@@ -58,10 +58,30 @@ export class MessageLoader {
   _subscribers: Set<() => void>;
 
   /**
-   * Message to show as a fallback when the requested message is unavailable.
+   * If a message is not present in this loader, try looking it up in this
+   * loader instead before resorting to a default placeholder message.
+   *
+   * The order of lookups will be:
+   * - this loader, requested locale
+   * - this loader, default locale
+   * - fallback loader, requested locale
+   * - fallback loader, default locale
+   * - fallback message
+   */
+  fallbackLoader?: MessageLoader;
+  /**
+   * Message to show as a fallback when the requested message is unavailable
+   * from both this loader and the fallback loader.
    */
   fallbackMessage: InternalIntlMessage;
 
+  /**
+   * When `fallbackLoader` is set, this value will be set on the fallback
+   * loader to reference this loader. Setting this ensures that loaders won't
+   * ever form an infinite circular chain.
+   */
+  _parentLoader?: MessageLoader;
+
   ///
   // Debug mode values
   ///
@@ -85,8 +105,7 @@ export class MessageLoader {
    */
   _localeFileMap?: Record<string, string>;
 
-  constructor(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId) {
-    this.messageKeys = messageKeys;
+  constructor(localeImportMap: LocaleImportMap, defaultLocale: LocaleId) {
     this.messages = {};
     this.localeImportMap = localeImportMap;
     this.supportedLocales = Object.keys(localeImportMap);
@@ -126,6 +145,36 @@ export class MessageLoader {
     this._localeFileMap = localeFileMap;
   }
 
+  /**
+   * Configure a fallback loader to search for any message requests that are not resolved by this
+   * loader directly. For example, if a request for a message "abcdef" in locale `pt-BR` is not
+   * found in this loader's managed content, the request gets forwarded on to this fallback instead.
+   *
+   * The lookup first exhausts this loader entirely before checking the fallback, in the order:
+   * - This loader's requested locale.
+   * - This loader's default locale.
+   * - Fallback loader's requested locale.
+   * - Fallback loader's default locale.
+   * - Fallback loader's final fallback value.
+   * - This loader's final fallback value.
+   *
+   * Note that the final fallback value (the `fallbackMessage` property on this class) will first
+   * be retrieved from the fallback loader rather than this instance.
+   */
+  fallbackWith(fallback: MessageLoader) {
+    let parent: MessageLoader = this;
+    while (parent != null) {
+      parent = parent._parentLoader;
+      if (parent === this) {
+        throw new Error(
+          'Setting `fallbackWith` on MessageLoader created a circular chain that would never resolve',
+        );
+      }
+    }
+    this.fallbackLoader = fallback;
+    fallback._parentLoader = this;
+  }
+
   get(key: string, locale: LocaleId): InternalIntlMessage {
     const expectedValue = this.getMessageValue(key, locale);
     if (expectedValue != null) return expectedValue;
@@ -136,8 +185,13 @@ export class MessageLoader {
       return this.fallbackMessage;
     }
 
-    const fallbackValue = this.getMessageValue(key, this.defaultLocale);
-    if (fallbackValue != null) return fallbackValue;
+    const defaultLocaleValue = this.getMessageValue(key, this.defaultLocale);
+    if (defaultLocaleValue != null) return defaultLocaleValue;
+
+    const fallbackLoaderValue = this.fallbackLoader?.get(key, locale);
+    if (fallbackLoaderValue != null) {
+      return fallbackLoaderValue;
+    }
 
     // If the message couldn't be found in either the requested nor the default locale, then
     // nothing can be done.
@@ -178,9 +232,16 @@ export class MessageLoader {
       return undefined;
     }
 
-    // Then try to return the loaded message.
-    if (key in this.messages[locale]) {
-      const content = this.messages[locale][key];
+    // 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) {
       const message = new InternalIntlMessage(content, locale);
       (this._parseCache[locale] ??= {})[key] = message;
       return message;
@@ -190,28 +251,6 @@ 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;
@@ -328,16 +367,15 @@ 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 defined in `messageKeys`.
+ * 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).
  */
-export function createLoader(
-  messageKeys: string[],
-  localeImportMap: LocaleImportMap,
-  defaultLocale: LocaleId,
-) {
-  const loader = new MessageLoader(messageKeys, localeImportMap, defaultLocale);
+export function createLoader(localeImportMap: LocaleImportMap, defaultLocale: LocaleId) {
+  const loader = new MessageLoader(localeImportMap, defaultLocale);
   LOADER_REGISTRY.push(loader);
   return loader;
 }

package/src/runtime-utils.ts

@@ -0,0 +1,110 @@
+/**
+ * Utility functions and classes used at runtime by the compiled output of bundlers using the intl
+ * packages like `intl-loader-core`'s `MessageDefinitionsTransformer`.
+ */
+import { MessageLoader } from './message-loader';
+import { IntlMessageGetter } from './types';
+
+interface MessageBindsProxy {
+  $$baseObject: Record<string, IntlMessageGetter>;
+  $$loader: MessageLoader;
+}
+
+/** Type created by the message transformer when `bindMode` is set to `literal`. */
+export type MessagesLiteral<T extends string> = Record<T, IntlMessageGetter>;
+export type AnyIntlMessagesObject<T extends string> = MessageBindsProxy | MessagesLiteral<T>;
+
+function isMessagesProxy(object: AnyIntlMessagesObject<any>): object is MessageBindsProxy {
+  return object[Symbol.toStringTag] === 'IntlMessagesProxy';
+}
+
+/**
+ * Return a new value that represents two message objects combined into one, regardless of their
+ * kind (either proxies or object literals). The returned value will be able to access any message
+ * contained in either of the two objects. This method generally assumes there is no overlap in
+ * keys between the two message objects, and the order of resolution is undefined (varies based on
+ * the types of the objects).
+ *
+ * Note that if both objects are proxies, the base loaders _are mutated in place_ to be chained
+ * together. Any other usages of the first object will also automatically fall back to the second.
+ */
+export function chainMessagesObjects<
+  const First extends MessagesLiteral<string>,
+  const Second extends MessagesLiteral<string>,
+>(first: First, second: Second): First & Second {
+  const firstIsProxy = isMessagesProxy(first);
+  const secondIsProxy = isMessagesProxy(second);
+
+  // This explicit any is a little strange, but when the objects are proxies, they don't have any
+  // actual type information, so trying to return them as a combination of `First` and `Second`
+  // causes TypeScript to error saying there are possibly different instantiations. Casting to `any`
+  // first makes it not care.
+  let result: any = first;
+
+  if (firstIsProxy && secondIsProxy) {
+    // If both are proxies, no change is actually required, and the first proxy can just have its
+    // loader set to fall back to the second.
+    first.$$loader.fallbackWith(second.$$loader);
+    result = first;
+  } else if (!firstIsProxy && !secondIsProxy) {
+    // If both objects are plain literals, they can just be spread together to get the result.
+    result = { ...second, ...first };
+  } else if (firstIsProxy && !secondIsProxy) {
+    // If the first is a proxy and the second is an object, the second can be spread onto the first
+    // to "pre-fill" values on it. In reality these cases should never be hit.
+    result = Object.assign(first.$$baseObject, second);
+  } else if (secondIsProxy && !firstIsProxy) {
+    // And the same is true in reverse.
+    result = Object.assign(second.$$baseObject, first);
+  }
+
+  return result as First & Second;
+}
+
+export function makeMessagesProxy(loader: MessageLoader): Record<string, IntlMessageGetter> {
+  function makeBind(prop: string) {
+    return (locale: string) => loader.get(prop, locale);
+  }
+
+  const baseObject = {};
+  const proxy = new Proxy(baseObject, {
+    ownKeys(self) {
+      return Reflect.ownKeys(self);
+    },
+    getOwnPropertyDescriptor(self, prop) {
+      return {
+        value: (self[prop] ||= makeBind(prop as string)),
+        configurable: true,
+        enumerable: true,
+        writable: false,
+      };
+    },
+    get(self, prop) {
+      if (prop === '$$typeof') {
+        return 'object';
+      }
+      if (prop === Symbol.toStringTag) {
+        return 'IntlMessagesProxy';
+      }
+
+      self[prop] ||= makeBind(prop as string);
+      return self[prop];
+    },
+  });
+
+  // Define the base object and loader on the proxy directly, but make them non-enumerable so that
+  // they don't show up when using `Object.keys` or other accessors.
+  Object.defineProperty(proxy, '$$baseObject', {
+    value: baseObject,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  Object.defineProperty(proxy, '$$loader', {
+    value: loader,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return proxy;
+}