@discord/intl 0.0.6-rc.1 → 0.0.7

package/dist/intl-manager.d.ts

@@ -1,6 +1,6 @@
 import { IntlShape } from '@formatjs/intl';
-import { LocaleImportMap, LocaleId, MessageLoader } from './message-loader';
-import type { TypedIntlMessageGetter, FormatValuesFor, RichTextElementMap } from './types';
+import { LocaleId, LocaleImportMap, MessageLoader } from './message-loader';
+import type { FormatValuesFor, RichTextElementMap, TypedIntlMessageGetter } from './types';
 /**
  * Fallback locale used for all internationalization when an operation in the
  * requested locale is not possible.
@@ -44,12 +44,31 @@ export declare class IntlManager<DefaultElements extends RichTextElementMap, Def
      */
     formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(message: T): Array<string | any>;
     formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(message: T, values: Omit<FormatValuesFor<T>, DefaultValues>): Array<string | any>;
+    /**
+     * 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;
     /**
      * 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<object | undefined>>(message: T): string;
     formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(message: T, values: Omit<FormatValuesFor<T>, DefaultValues>): string;
+    /**
+     * 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<object | undefined>>(message: T): string;
+    formatToMarkdownString<T extends TypedIntlMessageGetter<object | undefined>>(message: T, values: Omit<FormatValuesFor<T>, DefaultValues>): string;
 }
 /**
  * Create a new MessageLoader, which handles lazily loading messages for

package/dist/intl-manager.js

@@ -115,6 +115,19 @@ var IntlManager = /** @class */ (function () {
         }
         return result;
     };
+    /**
+     * 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.
+     */
+    IntlManager.prototype.string = function (message) {
+        // TODO(faulty): Optimize this so that plain strings are hotpathed even faster.
+        return this.formatToPlainString(message);
+    };
     IntlManager.prototype.formatToPlainString = function (message, values) {
         if (typeof message === 'string')
             return message;
@@ -125,6 +138,17 @@ var IntlManager = /** @class */ (function () {
         // will be removed from the string anyway.
         return resolvedMessage.formatToPlainString(this.intl.formatters, this.intl.formats, values);
     };
+    IntlManager.prototype.formatToMarkdownString = function (message, values) {
+        // TODO(faulty): Implement the markdown syntax conversion here.
+        if (typeof message === 'string')
+            return message;
+        var 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, this.intl.formats, values);
+    };
     return IntlManager;
 }());
 exports.IntlManager = IntlManager;

package/dist/message-loader.d.ts

@@ -53,7 +53,7 @@ export declare class MessageLoader {
      *
      * @private
      */
-    _debugKeyMap: Record<string, string>;
+    _debugKeyMap?: Record<string, string>;
     /**
      * Map of locale names to source file names, used to provide context for where messages are
      * imported from during development.
@@ -62,7 +62,7 @@ export declare class MessageLoader {
      *
      * @private
      */
-    _localeFileMap: Record<string, string>;
+    _localeFileMap?: Record<string, string>;
     constructor(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId);
     /**
      * Provide additional debug information to use during development, providing additional context

package/dist/react.d.ts

@@ -10,7 +10,7 @@ export declare class IntlManagerReact<DefaultElements extends RichTextElementMap
     IntlMessage: <T extends TypedIntlMessageGetter<object | undefined>>(props: {
         message: T;
         values?: Omit<FormatValuesFor<T>, DefaultValues> | never;
-    }) => React.FunctionComponentElement<{
+    }) => string | React.FunctionComponentElement<{
         children?: React.ReactNode | undefined;
     }>;
     /**

package/dist/react.js

@@ -57,15 +57,18 @@ var IntlManagerReact = /** @class */ (function (_super) {
             // Use the locale from this point in the application, which may be
             // different from the global locale.
             var locale = React.useSyncExternalStore(_this.onLocaleChange, function () { return _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.
+            // Source the actual message to render for that locale from its loader.
             React.useSyncExternalStore(message.onChange, function () { return message(locale); });
             // If there are no object parts in the message, it has no formatting and can just be returned as
             // a plain string.
-            return typeof message === 'string'
-                ? message
-                : React.createElement(React.Fragment, undefined, _this.formatToParts(message, values));
+            if (typeof message === 'string')
+                return message;
+            var parts = _this.formatToParts(message, values);
+            if (parts.length === 1 && typeof parts[0] === 'string')
+                return parts[0];
+            return React.createElement(React.Fragment, undefined, _this.formatToParts(message, values));
         };
         return _this;
     }

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+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 undefined ? PlainIntlMessage : TypedIntlMessage<FormatValues>;
+
+/**
+ * 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 interface TypedIntlMessageGetter<FormatValues extends object | undefined>
+  extends 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 defined in any of the messages.
+ *
+ * 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` condition 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
+      >;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl",
-  "version": "0.0.6-rc.1",
+  "version": "0.0.7",
   "license": "MIT",
   "description": "Client runtime for managing messages and translations in a React project.",
   "main": "./dist/index.js",
@@ -38,6 +38,7 @@
     }
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "build:release": "tsc && cp ./src/*.d.ts dist/"
   }
 }

package/src/intl-manager.ts

@@ -1,14 +1,14 @@
-import { IntlShape, createIntl } from '@formatjs/intl';
+import { createIntl, IntlShape } from '@formatjs/intl';
 import {
-  PART_TYPE as FormatPartType,
   Formats,
   Formatters,
   IntlMessageFormat,
+  PART_TYPE as FormatPartType,
 } from 'intl-messageformat';
 
-import { LocaleImportMap, LocaleId, MessageLoader } from './message-loader';
+import { LocaleId, LocaleImportMap, MessageLoader } from './message-loader';
 
-import type { TypedIntlMessageGetter, FormatValuesFor, RichTextElementMap } from './types';
+import type { FormatValuesFor, RichTextElementMap, TypedIntlMessageGetter } from './types';
 
 /**
  * Fallback locale used for all internationalization when an operation in the
@@ -129,6 +129,20 @@ export class IntlManager<
     return result;
   }
 
+  /**
+   * 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.
@@ -154,6 +168,36 @@ export class IntlManager<
       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<object | undefined>>(message: T): string;
+  formatToMarkdownString<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+    values: Omit<FormatValuesFor<T>, DefaultValues>,
+  ): string;
+  formatToMarkdownString<T extends TypedIntlMessageGetter<object | undefined>>(
+    message: T,
+    values?: Omit<FormatValuesFor<T>, DefaultValues>,
+  ) {
+    // 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,
+    );
+  }
 }
 
 /**

package/src/message-loader.ts

@@ -64,7 +64,7 @@ export class MessageLoader {
    *
    * @private
    */
-  _debugKeyMap: Record<string, string>;
+  _debugKeyMap?: Record<string, string>;
   /**
    * Map of locale names to source file names, used to provide context for where messages are
    * imported from during development.
@@ -73,7 +73,7 @@ export class MessageLoader {
    *
    * @private
    */
-  _localeFileMap: Record<string, string>;
+  _localeFileMap?: Record<string, string>;
 
   constructor(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId) {
     this.messageKeys = messageKeys;

package/src/react.ts

@@ -21,19 +21,21 @@ export class IntlManagerReact<
     // 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.
+    // Source the actual message to render for that locale from its loader.
     React.useSyncExternalStore(message.onChange, () => message(locale));
     // If there are no object parts in the message, it has no formatting and can just be returned as
     // a plain string.
-    return typeof message === 'string'
-      ? message
-      : React.createElement(
-          React.Fragment,
-          undefined,
-          this.formatToParts(message, values as Omit<FormatValuesFor<T>, DefaultValues>),
-        );
+    if (typeof message === 'string') return message;
+
+    const parts = this.formatToParts(message, values as Omit<FormatValuesFor<T>, DefaultValues>);
+    if (parts.length === 1 && typeof parts[0] === 'string') return parts[0];
+    return React.createElement(
+      React.Fragment,
+      undefined,
+      this.formatToParts(message, values as Omit<FormatValuesFor<T>, DefaultValues>),
+    );
   };
 
   /**

package/src/types.d.ts

@@ -36,7 +36,7 @@ type TypedIntlMessage<FormatValues extends object> = InternalIntlMessage & {
 };
 
 type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
-  FormatValues extends object ? TypedIntlMessage<FormatValues> : PlainIntlMessage;
+  FormatValues extends undefined ? PlainIntlMessage : TypedIntlMessage<FormatValues>;
 
 /**
  * Getter function that retrieves a message that best matches the requested
@@ -45,10 +45,10 @@ type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
  * 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>;
-  };
+export interface TypedIntlMessageGetter<FormatValues extends object | undefined>
+  extends IntlMessageGetterAdditions {
+  (locale: string): AnyIntlMessage<FormatValues>;
+}
 
 /**
  * Common utility type for converting a union type to an intersection of all