@discord/intl 0.1.2 → 0.2.0-canary.641ab2f

package/src/intl-manager.ts

@@ -1,30 +1,16 @@
 import { createIntl, IntlShape } from '@formatjs/intl';
-import {
-  Formats,
-  Formatters,
-  IntlMessageFormat,
-  PART_TYPE as FormatPartType,
-} from 'intl-messageformat';
+import { Formats, Formatters, IntlMessageFormat } from 'intl-messageformat';
 
 import { LocaleId, LocaleImportMap, MessageLoader } from './message-loader';
 
 import type {
-  FunctionTypeMap,
+  FormatterImplementation,
   IntlMessageGetter,
   RequiredFormatValues,
-  RichTextElementMap,
   TypedIntlMessageGetter,
 } from './types';
-
-/**
- * Types for formatting functions when calling `formatToParts`, ensuring the
- * functions yield value AST nodes.
- */
-type AstFunctionTypes = {
-  link: undefined | object | ((children: object) => Array<string | any>);
-  hook: undefined | object | ((children: object) => Array<string | any>);
-  handler: undefined | object | ((children: object) => Array<string | any>);
-};
+import { InternalIntlMessage } from './message';
+import { bindFormatValues, FormatBuilderConstructor } from './format';
 
 /**
  * Fallback locale used for all internationalization when an operation in the
@@ -32,26 +18,35 @@ type AstFunctionTypes = {
  */
 export const DEFAULT_LOCALE: string = 'en-US';
 
-export class IntlManager<
-  DefaultElements extends RichTextElementMap,
-  FunctionTypes extends FunctionTypeMap,
-> {
+type FormatterReturnType<F extends FormatterImplementation<any, any>> =
+  F extends FormatterImplementation<any, infer Return> ? Return : never;
+
+type FormatterFunctionTypes<F extends FormatterImplementation<any, any>> =
+  F extends FormatterImplementation<infer Functions, any> ? Functions : never;
+
+export type FormatFunction<F extends FormatterImplementation<any, any>> = <
+  T extends IntlMessageGetter,
+>(
+  this: IntlManager,
+  message: T,
+  values: RequiredFormatValues<T, FormatterFunctionTypes<F>>,
+) => FormatterReturnType<F>;
+
+type ThisWithFormatters<
+  This,
+  T extends Record<string, FormatterImplementation<any, any>>,
+> = This & {
+  [K in keyof T]: FormatFunction<T[K]>;
+};
+
+export class IntlManager {
   defaultLocale: string;
   currentLocale: string;
   intl: IntlShape;
 
-  /**
-   * When formatting tag elements like `<b>value</b>`, these functions will
-   * automatically be used by all messages, unless they are explicitly removed
-   * for a specific call, either by overriding the value or by calling a
-   * dedicated method like `formatToPlainString` which will remove all
-   * rich elements from the string and return only the plain text result.
-   */
-  defaultRichTextElements: DefaultElements;
-
   _localeSubscriptions: Set<(locale: string) => void>;
 
-  constructor(defaultLocale: string = DEFAULT_LOCALE, defaultRichTextElements: DefaultElements) {
+  constructor(defaultLocale: string = DEFAULT_LOCALE) {
     this.defaultLocale = defaultLocale;
     this.currentLocale = defaultLocale;
     this.intl = createIntl({
@@ -60,10 +55,38 @@ export class IntlManager<
       locale: defaultLocale,
     });
 
-    this.defaultRichTextElements = defaultRichTextElements;
     this._localeSubscriptions = new Set();
   }
 
+  /**
+   * Add a set of formatter implementations to this manager, making each available as a direct
+   * property
+   */
+  withFormatters<const T extends Record<string, FormatterImplementation<any, any>>>(
+    formatters: T,
+  ): ThisWithFormatters<this, T> {
+    for (const [name, formatter] of Object.entries(formatters)) {
+      this[name] = this.makeFormatFunction(formatter);
+    }
+
+    return this as ThisWithFormatters<this, T>;
+  }
+
+  /**
+   * Return a new function bound to this manager that uses the given `FormatterImplementation` to
+   * format a message after it has been resolved for the current locale and potentially processed in
+   * other ways by the manager.
+   */
+  makeFormatFunction<F extends FormatterImplementation<any, any>>({
+    format,
+    builder,
+  }: F): FormatFunction<FormatterReturnType<F>> {
+    const formatter = format.bind(this);
+    return (message, values) => {
+      return formatter(message(this.currentLocale), values, builder);
+    };
+  }
+
   /**
    * Set the locale for this package to use. This is a global change, and all
    * methods on this object will use this locale for formatting.
@@ -89,140 +112,29 @@ export class IntlManager<
   };
 
   /**
-   * Format the given message in the current locale with the provided values.
-   * The returned values is _always_ an Array of parts, even if the message is
-   * a simple string value.
-   *
-   * This function is the basis of how messages are normally formatted, and can
-   * be used anywhere. However, it is not reactive and only functions on the
-   * data that is currently loaded and known. For a reactive function that
-   * automatically updates when the locale changes or when new data is loaded,
-   * use `format`, which will wrap the formatting in a React component that
-   * subscribes to the current locale and state of loaded messages.
+   * For static messages with no rich text and no dynamic placeholders, use this method to
+   * immediately return the plain string value of the message in the current locale.
    */
-  formatToParts<T extends TypedIntlMessageGetter<undefined>>(message: T): Array<string | any>;
-  formatToParts<T extends IntlMessageGetter>(
-    message: T,
-    values: RequiredFormatValues<T, DefaultElements, AstFunctionTypes>,
-  ): Array<string | any>;
-  formatToParts<T extends IntlMessageGetter>(
-    message: T,
-    values?: RequiredFormatValues<T, DefaultElements, AstFunctionTypes>,
-  ): Array<string | any> {
-    if (typeof message === 'string') return [message];
-    const resolvedMessage = typeof message === 'function' ? message(this.currentLocale) : message;
-    if (typeof resolvedMessage === 'string') return [resolvedMessage];
-
-    const resolvedValues =
-      values != null
-        ? { ...this.defaultRichTextElements, ...values }
-        : this.defaultRichTextElements;
-    const parts = resolvedMessage.formatToParts(
-      this.intl.formatters as Formatters,
-      this.intl.formats as Formats,
-      resolvedValues,
-    );
-
-    const result = [];
-    let inLiteral = false;
-    for (const part of parts) {
-      // This condition merges consecutive literal elements (static strings)
-      // into single parts to reduce the number of nodes in the result. This
-      // condition will never be true on the first loop, ensuring that the
-      // array must at least have one entry before it attempts to concatenate
-      // onto that value again.
-      if (inLiteral && (inLiteral = part.type === FormatPartType.literal)) {
-        result[result.length - 1] += part.value;
-        continue;
-      }
-
-      inLiteral = part.type === FormatPartType.literal;
-      result.push(part.value);
-    }
-
-    return result;
+  string<T extends TypedIntlMessageGetter<undefined>>(message: T): string {
+    // @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;
   }
 
-  /**
-   * For messages with no formatting values (i.e., plain strings, they can skip
-   * a majority of the processing work and just resolve the message itself for
-   * the current locale, then return the plain string directly.
-   *
-   * This is separate from `formatToPlainString`, which still allows for
-   * formatting variables and other elements but reduces the output to only
-   * include textual elements in a plain string.
-   */
-  string(message: TypedIntlMessageGetter<undefined>): string {
-    // TODO(faulty): Optimize this so that plain strings are hotpathed even faster.
-    return this.formatToPlainString(message);
-  }
-
-  /**
-   * Format the given message with the provided values, removing any styling
-   * and non-textual content from the message, returning a plain string.
-   */
-  formatToPlainString<T extends TypedIntlMessageGetter<undefined>>(message: T): string;
-  formatToPlainString<T extends IntlMessageGetter>(
-    message: T,
-    values: RequiredFormatValues<T, DefaultElements, FunctionTypes>,
-  ): string;
-  formatToPlainString<T extends IntlMessageGetter>(
-    message: T,
-    values?: RequiredFormatValues<T, DefaultElements, FunctionTypes>,
-  ): string {
-    if (typeof message === 'string') return message;
-    const resolvedMessage = message(this.currentLocale);
-    if (typeof resolvedMessage === 'string') return resolvedMessage;
-
-    // No need to pass in `defaultRichTextElements`, since the stylistic tags
-    // will be removed from the string anyway.
-    return resolvedMessage.formatToPlainString(
+  bindFormatValues<T>(
+    Builder: FormatBuilderConstructor<T>,
+    message: InternalIntlMessage,
+    values: Record<string, any>,
+  ): T[] {
+    return bindFormatValues(
+      Builder,
+      message.ast,
+      [this.currentLocale, this.defaultLocale],
       this.intl.formatters as Formatters,
       this.intl.formats as Formats,
       values,
     );
   }
-
-  /**
-   * Similar to `formatToPlainString`, format the given message with the provided
-   * values, but convert all rich text formatting back to Markdown syntax rather
-   * than rendering the actual rich content. The result is a plain string that
-   * can be sent through a separate Markdown renderer to get an equivalent
-   * result to formatting this message directly.
-   */
-  formatToMarkdownString<T extends TypedIntlMessageGetter<undefined>>(message: T): string;
-  formatToMarkdownString<T extends IntlMessageGetter>(
-    message: T,
-    values: RequiredFormatValues<T, DefaultElements, FunctionTypes>,
-  ): string;
-  formatToMarkdownString<T extends IntlMessageGetter>(
-    message: T,
-    values?: RequiredFormatValues<T, DefaultElements, FunctionTypes>,
-  ): string {
-    // TODO(faulty): Implement the markdown syntax conversion here.
-    if (typeof message === 'string') return message;
-    const resolvedMessage = message(this.currentLocale);
-    if (typeof resolvedMessage === 'string') return resolvedMessage;
-
-    // No need to pass in `defaultRichTextElements`, since the stylistic tags
-    // will be removed from the string anyway.
-    return resolvedMessage.formatToPlainString(
-      this.intl.formatters as Formatters,
-      this.intl.formats as Formats,
-      values,
-    );
-  }
-}
-
-/**
- * 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/keyless-json.ts

@@ -38,6 +38,12 @@ export interface FormatJsTime {
   style?: string;
 }
 
+export interface FormatJsSelect {
+  type: FormatJsNodeType.Select;
+  value: string;
+  options: Record<string, { value: FormatJsNode[] }>;
+}
+
 export type FormatJsPluralType = 'cardinal' | 'ordinal';
 
 export interface FormatJsPlural {
@@ -64,6 +70,7 @@ export type FormatJsNode =
   | FormatJsNumber
   | FormatJsDate
   | FormatJsTime
+  | FormatJsSelect
   | FormatJsPlural
   | FormatJsPound
   | FormatJsTag;

package/src/message-loader.ts

@@ -1,9 +1,7 @@
+import { FormatJsNode } from './keyless-json';
 import { InternalIntlMessage } from './message';
 
-import type { MessageFormatElement } from '@formatjs/icu-messageformat-parser';
-
-type AnyRawMessage = string | MessageFormatElement[];
-type MessagesData = Record<string, AnyRawMessage>;
+type MessagesData = Record<string, FormatJsNode[]>;
 export interface IntlMessageGetterAdditions {
   onChange(callback: () => void): () => void;
 }
@@ -34,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
@@ -87,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.
@@ -95,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);
         });
       }
     }
@@ -118,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.
@@ -151,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;
     }
 
@@ -199,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;
     }
 
@@ -215,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();
   }
 
@@ -240,4 +243,68 @@ 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[] = [];
+
+/**
+ * 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,103 +1,11 @@
-import {
-  TYPE as FormatElementType,
-  parse as parseMessageFormat,
-} from '@formatjs/icu-messageformat-parser';
-import {
-  Formats,
-  Formatters,
-  MessageFormatPart,
-  formatToParts as libFormatToParts,
-} from 'intl-messageformat';
-
-import type { MessageFormatElement } from '@formatjs/icu-messageformat-parser';
+import { FormatJsNode } from './keyless-json';
 
 export class InternalIntlMessage {
   locale: string;
-  message?: string;
-  ast: MessageFormatElement[];
-  /**
-   * 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`).
-   */
-  plainAst?: MessageFormatElement[];
+  ast: FormatJsNode[];
 
-  constructor(messageOrAst: string | MessageFormatElement[], locale: string) {
+  constructor(messageOrAst: FormatJsNode[], locale: string) {
     this.locale = locale;
-
-    if (typeof messageOrAst === 'string') {
-      this.message = messageOrAst;
-      this.ast = parseMessageFormat(messageOrAst);
-    } else {
-      this.ast = messageOrAst;
-    }
-
-    this.plainAst = undefined;
-  }
-
-  /**
-   * Format this message with the given locale into an AST of chunks that can
-   * then be used or rendered into strings, React elements, or anything else as
-   * needed.
-   */
-  formatToParts<T>(
-    formatters: Formatters,
-    formats: Formats,
-    values?: Record<string, any>,
-  ): Array<MessageFormatPart<T>> {
-    return libFormatToParts(this.ast, this.locale, formatters, formats, values);
-  }
-
-  /**
-   * Formats this message just like `formatToParts`, but strips all stylistic
-   * elements and tags and returns a plain string with only the literal text of
-   * the message remaining.
-   *
-   * This method works by quickly scanning the string and removing any tag
-   * elements, formatting, then concatenating the pieces into a single result.
-   *
-   * Note that this function does _not_ handle serializing values other than
-   * plain/primitive values into strings. All values are simply converted using
-   * the `String()` constructor. So, for example, passing a function as a value
-   * will directly serialize the function definition into a string, rather than
-   * calling the function or evaluating the result.
-   */
-  formatToPlainString(
-    formatters: Formatters,
-    formats: Formats,
-    values?: Record<string, any>,
-  ): string {
-    // Lazily create the reduced AST if it hasn't already been done.
-    if (this.plainAst == null) {
-      this.plainAst = [];
-      for (const part of this.ast) {
-        this.plainAst.push(...this._removeRichTags(part));
-      }
-    }
-
-    const parts = libFormatToParts(this.plainAst, this.locale, formatters, formats, values);
-    let result = '';
-    for (const part of parts) {
-      result += String(part.value);
-    }
-
-    return result;
-  }
-
-  /**
-   * 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.
-   */
-  _removeRichTags(element: MessageFormatElement): MessageFormatElement[] {
-    if (element.type === FormatElementType.tag) {
-      const childContent = [];
-      for (const child of element.children) {
-        childContent.push(...this._removeRichTags(child));
-      }
-      return childContent;
-    } else {
-      return [element];
-    }
+    this.ast = messageOrAst;
   }
 }