@discord/intl 0.2.0 → 0.2.1-canary.1ed7c43

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,129 @@
-import { FormatJsNode, FormatJsNodeType } from './keyless-json';
+import { FormatJsNode, FormatJsNodeType, FormatJsTag } from './keyless-json';
 
 export class InternalIntlMessage {
   locale: string;
-  message?: string;
   ast: FormatJsNode[];
 
+  constructor(messageOrAst: FormatJsNode[], locale: string) {
+    this.locale = locale;
+    this.ast = messageOrAst;
+  }
+
   /**
-   * 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`).
+   * Return a stringified serialization of this message's AST, with no
+   * formatting or values applied.
    */
-  get plainAst(): FormatJsNode[] {
-    return (this._plainAst = this._removeRichTags(this.ast));
+  reserialize(): string {
+    const value = '';
+    serializeFormatJsAst(this.ast, { value });
+    return value;
   }
-  _plainAst: FormatJsNode[];
-
-  constructor(messageOrAst: string | FormatJsNode[], locale: string) {
-    this.locale = locale;
+}
 
-    if (typeof messageOrAst === 'string') {
-      this.message = messageOrAst;
-    } else {
-      this.ast = messageOrAst;
+// Accepting an object as the `result` parameter lets the same string get passed around and
+// appended, rather than creating a bunch of intermediate strings.
+function serializeFormatJsAst(ast: FormatJsNode[], result: { value: string }) {
+  for (const node of ast) {
+    switch (node.type) {
+      case FormatJsNodeType.Literal:
+        result.value += node.value;
+        return;
+      case FormatJsNodeType.Argument:
+        // Empties are an artifact of our parsing strategy, not necessary here.
+        if (result.value === '$_') return;
+        result.value += '{' + node.value + '}';
+        return;
+      case FormatJsNodeType.Date:
+        result.value += '{' + node.value + ', date';
+        if (node.style != null) {
+          result.value += ', ' + node.style;
+        }
+        result.value += '}';
+        return;
+      case FormatJsNodeType.Time:
+        result.value += '{' + node.value + ', time';
+        if (node.style != null) {
+          result.value += ', ' + node.style;
+        }
+        result.value += '}';
+        return;
+      case FormatJsNodeType.Number:
+        result.value += '{' + node.value + ', number';
+        if (node.style != null) {
+          result.value += ', ' + node.style;
+        }
+        result.value += '}';
+        return;
+      case FormatJsNodeType.Plural: {
+        const pluralType = node.pluralType == 'ordinal' ? 'selectordinal' : 'plural';
+        result.value += '{' + node.value + ', ' + pluralType + ', ';
+        if (node.offset) {
+          result.value += 'offset:' + node.offset;
+        }
+        for (const [name, arm] of Object.entries(node.options)) {
+          result.value += ' ' + name + ' {';
+          serializeFormatJsAst(arm.value, result);
+          result.value += '}';
+        }
+        return;
+      }
+      case FormatJsNodeType.Pound:
+        result.value += '#';
+        return;
+      case FormatJsNodeType.Select: {
+        result.value += '{' + node.value + ', select, ';
+        for (const [name, arm] of Object.entries(node.options)) {
+          result.value += ' ' + name + ' {';
+          serializeFormatJsAst(arm.value, result);
+          result.value += '}';
+        }
+        return;
+      }
+      case FormatJsNodeType.Tag:
+        serializeFormatJsTag(node, result);
+        return;
     }
   }
+}
 
-  /**
-   * 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);
+function serializeFormatJsTag(node: FormatJsTag, result: { value: string }) {
+  switch (node.value) {
+    case '$b':
+      result.value += '**';
+      serializeFormatJsAst(node.children, result);
+      result.value += '**';
+      return;
+    case '$i':
+      result.value += '*';
+      serializeFormatJsAst(node.children, result);
+      result.value += '*';
+      return;
+    case '$code':
+      result.value += '`';
+      serializeFormatJsAst(node.children, result);
+      result.value += '`';
+      return;
+    case '$p':
+      serializeFormatJsAst(node.children, result);
+      result.value += '\n\n';
+      return;
+    case '$link':
+      // The target is the first child of the link. We don't have to care if it's a placeholder
+      // or not, because the serialization will automatically remove the extra empty.
+      const [target, ...children] = node.children;
+      result.value += '[';
+      serializeFormatJsAst(children, result);
+      result.value += '](';
+      if (target != null) {
+        serializeFormatJsAst([target], result);
       }
-    }
-    return result;
+      result.value += ')';
+      return;
+    default:
+      // Any other tag name is a hook, which just adds the `$[` on a link tag.
+      result.value += '$[';
+      serializeFormatJsAst(node.children, result);
+      result.value += '](' + node.value + ')';
+      return;
   }
 }

package/src/types.d.ts

@@ -197,9 +197,9 @@ export interface FunctionTypeMap {
   handler: any;
 }
 
-export interface FunctionTypes<Result, HandlerType = (content: Result[]) => Result | Result[]> {
-  link: undefined | ((content: Result[]) => Result | Result[]);
-  hook: undefined | ((content: Result[]) => Result | Result[]);
+export interface FunctionTypes<Result, HandlerType = () => void> {
+  link: undefined | ((content: Result[], key: string) => Result | Result[]);
+  hook: undefined | ((content: Result[], key: string) => Result | Result[]);
   handler: undefined | HandlerType;
 }
 
@@ -276,6 +276,7 @@ export interface RichTextFormattingMap<T = any> {
   $p: T;
   $link: T;
   $code: T;
+  $del: T;
 }
 
 export type RichTextTagNames = keyof RichTextFormattingMap;