@discord/intl 0.19.1 → 0.19.2

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.
@@ -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

package/dist/message-loader.js

@@ -50,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;
@@ -60,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;

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.19.1",
+  "version": "0.19.2",
   "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.19.1"
+    "@discord/intl-ast": "0.19.2"
   },
   "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
   ///
@@ -125,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;
@@ -135,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.

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;
+}