@discord/intl 0.0.1

package/src/keyless-json.ts

@@ -0,0 +1,154 @@
+export enum FormatJsNodeType {
+  Literal = 0,
+  Argument,
+  Number,
+  Date,
+  Time,
+  Select,
+  Plural,
+  Pound,
+  Tag,
+}
+
+export interface FormatJsLiteral {
+  type: FormatJsNodeType.Literal;
+  value: string;
+}
+
+export interface FormatJsArgument {
+  type: FormatJsNodeType.Argument;
+  value: string;
+}
+
+export interface FormatJsNumber {
+  type: FormatJsNodeType.Number;
+  value: string;
+  style?: string;
+}
+
+export interface FormatJsDate {
+  type: FormatJsNodeType.Date;
+  value: string;
+  style?: string;
+}
+
+export interface FormatJsTime {
+  type: FormatJsNodeType.Time;
+  value: string;
+  style?: string;
+}
+
+export type FormatJsPluralType = 'cardinal' | 'ordinal';
+
+export interface FormatJsPlural {
+  type: FormatJsNodeType.Plural;
+  value: string;
+  options: Record<string, { value: FormatJsNode[] }>;
+  offset: number;
+  pluralType: FormatJsPluralType;
+}
+
+export interface FormatJsPound {
+  type: FormatJsNodeType.Pound;
+}
+
+export interface FormatJsTag {
+  type: FormatJsNodeType.Tag;
+  value: string;
+  children: FormatJsNode[];
+}
+
+export type FormatJsNode =
+  | FormatJsLiteral
+  | FormatJsArgument
+  | FormatJsNumber
+  | FormatJsDate
+  | FormatJsTime
+  | FormatJsPlural
+  | FormatJsPound
+  | FormatJsTag;
+
+// Using a static object here ensures there's only one allocation for it, which
+// will likely appear in many, many messages. Freezing ensures that the shared
+// object can't be accidentally modified if a consumer tries to transform the
+// AST.
+export const FORMAT_JS_POUND: FormatJsPound = Object.freeze({ type: 7 });
+
+function hydrateArray(elements: Array<Array<any>>) {
+  for (let i = 0; i < elements.length; i++) {
+    elements[i] = hydrateFormatJsAst(elements[i]);
+  }
+}
+
+function hydratePlural(keyless: Array<any>): FormatJsNode {
+  const [type, value, options, offset, pluralType] = keyless;
+  // This tries to be efficient about updating the value for each option
+  // with a parsed version, reusing the same receiving object, and even
+  // the inner key within it, just replacing the end value with the
+  // parsed version.
+  // This saves multiple allocations compared to building a new object
+  // from scratch, either for the whole options object or for each value.
+  for (const key in options) {
+    hydrateArray(options[key].value);
+  }
+  // `pluralType` is technically only valid on `Plural` nodes, even
+  // though the structure is identical to `Select`.
+  if (type === FormatJsNodeType.Plural) {
+    return { type, value, options, offset, pluralType };
+  } else {
+    return { type, value, options, offset };
+  }
+}
+
+function hydrateSingle(keyless: Array<any>): FormatJsNode {
+  const [type] = keyless;
+  switch (type) {
+    case FormatJsNodeType.Literal:
+    case FormatJsNodeType.Argument:
+      return { type, value: keyless[1] };
+    case FormatJsNodeType.Number:
+    case FormatJsNodeType.Date:
+    case FormatJsNodeType.Time:
+      return { type, value: keyless[1], style: keyless[2] };
+    case FormatJsNodeType.Select:
+    case FormatJsNodeType.Plural:
+      return hydratePlural(keyless);
+    case FormatJsNodeType.Pound:
+      return FORMAT_JS_POUND;
+    case FormatJsNodeType.Tag: {
+      const [type, value, children] = keyless;
+      hydrateArray(children);
+      return { type, value, children: children };
+    }
+    default:
+      throw new Error(`FormatJS keyless JSON encountered an unknown type: ${type}`);
+  }
+}
+
+/**
+ * Hydrate the given keyless JSON into a FormatJS-compatible AST structure.
+ * The given object is reused as much as possible, meaning it cannot be safely
+ * used again after hydrating.
+ */
+export function hydrateFormatJsAst(keyless: Array<Array<any>>): FormatJsNode[];
+export function hydrateFormatJsAst(keyless: Array<any>): FormatJsNode | FormatJsNode[] {
+  // If the first element of the array is itself an array, then we have a list
+  // of elements to parse rather than a single object.
+  if (Array.isArray(keyless[0])) {
+    hydrateArray(keyless);
+    return keyless;
+  } else if (keyless.length === 0) {
+    // Some entries can be empty arrays, like an empty set of children, and those can
+    // be preserved.
+    return keyless;
+  }
+
+  return hydrateSingle(keyless);
+}
+
+export function hydrateMessages(messages: Record<string, any>) {
+  for (const key in messages) {
+    messages[key] = hydrateFormatJsAst(messages[key]);
+  }
+  return messages;
+}

package/src/message-loader.ts

@@ -0,0 +1,156 @@
+import { InternalIntlMessage } from './message';
+
+import type { MessageFormatElement } from '@formatjs/icu-messageformat-parser';
+
+type AnyRawMessage = string | MessageFormatElement[];
+type MessagesData = Record<string, AnyRawMessage>;
+export interface IntlMessageGetterAdditions {
+  isLocaleLoaded(locale: LocaleId): boolean;
+  onChange(callback: () => void): () => void;
+}
+
+export interface IntlMessageGetter extends IntlMessageGetterAdditions {
+  (locale: LocaleId): InternalIntlMessage;
+}
+
+type LocaleId = string;
+
+export type LocaleImportMap = Record<LocaleId, () => Promise<{ default: MessagesData }>>;
+
+export class MessageLoader {
+  messageKeys: string[];
+  /** Map of locale to string key to message content. */
+  messages: Record<LocaleId, MessagesData>;
+  localeImportMap: LocaleImportMap;
+  supportedLocales: LocaleId[];
+
+  /**
+   * Promise representing the current locale being loaded. If this is non-null,
+   * then a request has already been made to load the locale and it is waiting
+   * to resolve.
+   */
+  _localeLoadingPromises: Record<LocaleId, Promise<{ default: MessagesData }> | undefined>;
+
+  /**
+   * Map of pre-parsed messages, keyed by the message key and locale
+   */
+  _parseCache: Map<string, InternalIntlMessage>;
+
+  /**
+   * List of subscribers listening for changes to the current locale and
+   * when it has loaded.
+   */
+  _subscribers: Set<() => void>;
+
+  fallbackMessage: InternalIntlMessage;
+
+  constructor(messageKeys: string[], localeImportMap: LocaleImportMap) {
+    this.messageKeys = messageKeys;
+    this.messages = {};
+    this.localeImportMap = localeImportMap;
+    this.supportedLocales = Object.keys(localeImportMap);
+
+    this._localeLoadingPromises = {};
+    this._parseCache = new Map();
+    this._subscribers = new Set();
+
+    this.fallbackMessage = new InternalIntlMessage('THIS MESSAGE FAILED TO LOAD', 'en-US');
+  }
+
+  get(key: string, locale: LocaleId): InternalIntlMessage {
+    const cacheKey = key + '@' + locale;
+    const cachedValue = this._parseCache.get(cacheKey);
+    if (cachedValue != null) return cachedValue;
+
+    if (this.messages[locale] == null) {
+      // Ensure the locale is loaded, if it is supported
+      if (this.supportedLocales.includes(locale)) {
+        this._loadLocale(locale);
+      }
+
+      // Otherwise, fallback to just the key value in the meantime.
+      return this.fallbackMessage;
+    }
+
+    // Then try to return the loaded message
+    if (key in this.messages[locale]) {
+      const content = this.messages[locale][key];
+      const message = new InternalIntlMessage(content, locale);
+      this._parseCache.set(cacheKey, message);
+      return message;
+    }
+
+    // And finally throw if there's no match whatsoever
+    throw new Error(
+      `Requested message ${key} does not have a value in the requested locale nor the default locale`,
+    );
+  }
+
+  /**
+   * 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.
+   */
+  getBinds(): Record<string, IntlMessageGetter> {
+    const onChange = this.onChange.bind(this);
+    return this.messageKeys.reduce(
+      (acc, key) => {
+        const bound = this.get.bind(this, key) as IntlMessageGetter;
+        bound.onChange = onChange;
+        acc[key] = bound;
+        return acc;
+      },
+      {} as Record<string, IntlMessageGetter>,
+    );
+  }
+
+  async _loadLocale(locale: LocaleId) {
+    // Don't re-load a locale that's already in progress.
+    if (this._localeLoadingPromises[locale] != null) {
+      return;
+    }
+
+    // Safety check in case the locale map doesn't include a require for the
+    // requested locale. Shouldn't happen, but throwing here is much more
+    // contextual than whatever error would result otherwise.
+    if (this.localeImportMap[locale] == null) {
+      throw new Error(
+        `Requested to load locale ${locale}, which should be supported, but no source for translation data was provided.`,
+      );
+    }
+
+    // If the locale is already set in `messages`, then it doesn't need to be loaded again.
+    if (this.messages[locale] != null) return;
+
+    const loadStart = performance.now();
+    const loadingPromise = this.localeImportMap[locale]();
+    this._localeLoadingPromises[locale] = loadingPromise;
+    this.messages[locale] = (await loadingPromise).default;
+    delete this._localeLoadingPromises[locale];
+    const loadEnd = performance.now();
+    console.warn(
+      `[INTL] Took ${loadEnd - loadStart}ms to load ${locale} with ${Object.keys(this.messages[locale]).length} keys`,
+    );
+    this.emitChange();
+  }
+
+  /**
+   * Inform subscribers that the loader state has changed and they should
+   * potentially update to get new values for messages.
+   */
+  emitChange() {
+    for (const callback of this._subscribers.values()) {
+      callback();
+    }
+  }
+
+  /**
+   * Subscribe to events about when a locale has loaded.
+   */
+  onChange(callback: () => void): () => void {
+    this._subscribers.add(callback);
+
+    return () => this._subscribers.delete(callback);
+  }
+}

package/src/message.ts

@@ -0,0 +1,110 @@
+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';
+
+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[];
+
+  constructor(messageOrAst: string | MessageFormatElement[], locale: string) {
+    this.locale = locale;
+
+    if (typeof messageOrAst === 'string') {
+      // TODO: This part should pre-parse our Markdown shorthand, too, so that
+      // the AST that comes out of this is a standardized format, and we don't
+      // have to do any special handling after calling `format`. That also
+      // removes the need for handling "unsafe" values, since they'll be
+      // parsed before values get interpolated. We can actually do that in the
+      // loader, too, and avoid any runtime cost for it.
+
+      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];
+    }
+  }
+}

package/src/react.ts

@@ -0,0 +1,59 @@
+import * as React from 'react';
+
+import { IntlManager } from './intl-manager';
+
+import type { FormatValuesFor, RichTextElementMap, TypedIntlMessageGetter } from './types';
+
+export class IntlManagerReact<
+  DefaultElements extends RichTextElementMap,
+  DefaultValues extends keyof DefaultElements,
+> extends IntlManager<DefaultElements, DefaultValues> {
+  /**
+   * A reactive component form of `intl.format` that automatically updates when
+   * the application's locale changes and when new data is loaded for the
+   * subject message.
+   */
+  IntlMessage = <T extends TypedIntlMessageGetter<object | undefined>>(props: {
+    message: T;
+    values?: Omit<FormatValuesFor<T>, DefaultValues>;
+  }) => {
+    const { message, values } = props;
+    // Use the locale from this point in the application, which may be
+    // different from the global locale.
+    const locale = React.useSyncExternalStore(this.onLocaleChange, () => this.currentLocale);
+    // Source the actual message to render for that locale from its loader.
+    // TODO(faulty): This can and should be replaced by a
+    // `use(messagesLoadedPromise)` once `use` is shipped to stable.
+    React.useSyncExternalStore(message.onChange, () => message(locale));
+    // The return the formatted version of that string.
+    if (typeof message === 'string') return message;
+
+    return React.createElement(
+      React.Fragment,
+      undefined,
+      this.formatToParts(message, values as Omit<FormatValuesFor<T>, DefaultValues> | never),
+    );
+  };
+
+  /**
+   * Format the given message as a React component, allowing it to listen for
+   * and respond to updates about the current locale and other relevant
+   * information.
+   */
+  format<T extends TypedIntlMessageGetter<object | undefined>>(message: T): JSX.Element;
+  format<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+    values: Omit<FormatValuesFor<T>, DefaultValues>,
+  ): JSX.Element;
+  format(message: any): JSX.Element;
+  format<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+    values?: Omit<FormatValuesFor<T>, DefaultValues>,
+  ) {
+    // A string literal means there's no locale dependency, so it can just be
+    // formatted directly without any subscription.
+    if (typeof message === 'string') return this.formatToParts(message);
+
+    return React.createElement(this.IntlMessage, { message, values });
+  }
+}

package/src/types.d.ts

@@ -0,0 +1,158 @@
+import type { InternalIntlMessage } from './message';
+import type { IntlMessageGetterAdditions } from './message-loader';
+/**
+ * Use this function to define messages as part of the `@discord/intl`
+ * system, with type checking support.
+ *
+ * This function does not actually exist, and gets compiled out as part
+ * of the bundling process both on web and mobile. See the
+ * `@discord/intl/README.md` for more information.
+ */
+export declare function defineMessages(messages: object): object;
+
+/**
+ * A map of tag names to render functions to apply when the tags are
+ * encountered while formatting a message. Each `IntlManager` can be
+ * constructed with a different map of these elements, for example to allow
+ * one manager to render React output while another renders accessibility text.
+ */
+export type RichTextElementMap = Record<string, (chunks: any[]) => any>;
+
+/**
+ * Messages with no rich formatting and no value interpolations are just plain
+ * strings, and are able to skip multiple formatting steps to work more
+ * efficiently. This type represents those messages distinctly.
+ */
+type PlainIntlMessage = string;
+/**
+ * A richly-formatted message that injects dynamic values while formatting,
+ * with the types of those values defined by the `FormatValues` object. All
+ * messages of this type must have at least one value in the object, otherwise
+ * the message should be typed as a `PlainIntlMessage`.
+ */
+type TypedIntlMessage<FormatValues extends object> = InternalIntlMessage & {
+  values: FormatValues;
+};
+
+type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
+  FormatValues extends object ? TypedIntlMessage<FormatValues> : PlainIntlMessage;
+
+/**
+ * Getter function that retrieves a message that best matches the requested
+ * locale. `FormatValues` represents either an object containing all of the
+ * value types that are required to format the message, or `undefined` to
+ * represent that there are no values required and the message is a plain
+ * string.
+ */
+export type TypedIntlMessageGetter<FormatValues extends object | undefined> =
+  IntlMessageGetterAdditions & {
+    (locale: string): AnyIntlMessage<FormatValues>;
+  };
+
+/**
+ * Common utility type for converting a union type to an intersection of all
+ * the types in that union.
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Given a message getter of type `T` (which may be a union of multiple message
+ * types), return a combined type representing the intersection of all values
+ * needed to satisfy the mix of values.
+ *
+ * For example, given a variable representing one of two message getters, where
+ * one requires a single value to be formatted, but the other requires an
+ * additional value on top of that one:
+ *
+ * ```typescript
+ * // message1: "Hello {username}"
+ * // message2: "Hello {username}, it's {currentDate, date}"
+ * const message = someCondition ? message1 || message2;
+ * ```
+ *
+ * Attempting to format this message would require that both `username` _and_
+ * `currentDate` are supplied, so that all possible cases are covered, which is
+ * what this type resolves:
+ *
+ * ```typescript
+ * type ResolvedValuesTypes = FormatValuesFor<typeof message>;
+ * // => {username: string, currentDate: Date}
+ * ```
+ *
+ * This values type can then be used to enforce that all values are passed to
+ * functions that format the message, like `i18n.format`:
+ *
+ * ```typescript
+ * declare function format<T>(message: T, values: FormatValuesFor<T>): string;
+ * ```
+ *
+ * ## Mixed message types
+ *
+ * If T is a union of message types including both rich messages requiring
+ * values _and_ plain string messages with no values, this type will still
+ * properly resolve all of the required values, assuming that the getters for
+ * the plain messages use the convention of passing `undefined` as the generic
+ * argument, representing "no values should be passed for this message".
+ *
+ *
+ * ## Why this type?
+ *
+ * All "messages" are really defined as functions that return a specific
+ * value of the message for a requested locale, `(locale: string) => Message`.
+ * This is named `TypedIntlMessageGetter<T>`, where `T` is the definition of
+ * the values required to format the message.
+ *
+ * This type requires being passed the entire getter function rather than the
+ * returned message types, as narrowing to the returned type prevents
+ * TypeScript from distributing the union properly. This surfaces as error
+ * messages showing up on the _message_ type rather than the _value_ type when
+ * they don't match, which doesn't give the user any helpful information about
+ * what's wrong. This method ensures the value type is always the one being
+ * checked against the provided message types, and error messages will be
+ * accurate as a result.
+ */
+type FormatValuesFor<T> =
+  // `[]` syntax forces TypeScript to not distribute the possible union of
+  // types, meaning this represents "_all_ values of T are an extension of
+  // the parent type", which in this case represents messages with no
+  // format values. If that condition is matched, then `FormatValues` _cannot_
+  // be supplied, represented by the `never`. This prevents accidentally
+  // passing an object, even an empty one, for those strings, and allows the
+  // formatter to optimize a little more on each call.
+  [T] extends [TypedIntlMessageGetter<undefined>]
+    ? never
+    : // The `never` conditino needs to be repeated here, but this time _without_
+      // the `[]` syntax, so that only the union elements with actual values are
+      // included in the union. Without this, the `infer U` on the latter side
+      // fails to resolve and the type just becomes `never`.
+      UnionToIntersection<
+        T extends TypedIntlMessageGetter<undefined>
+          ? never
+          : T extends TypedIntlMessageGetter<infer U>
+            ? U
+            : never
+      >;
+
+/**
+ * A generic definition of a `format*` function that accepts any message
+ * argument as the first parameter, and the required values object for that
+ * message as the second parameter. The second parameter
+ *
+ * An optional third parameter for additional options can be specified as the
+ * second generic type parameter.
+ */
+export interface IntlFormatFn<
+  T extends object | undefined,
+  DefaultValues extends string | number | symbol,
+  OptionsType,
+  ResultType,
+> {
+  (message: TypedIntlMessageGetter<T>, options?: OptionsType): ResultType;
+  (
+    message: TypedIntlMessageGetter<T>,
+    values: Omit<FormatValuesFor<T>, DefaultValues>,
+    options?: OptionsType,
+  ): ResultType;
+}