@discord/intl 0.1.3-rc.0 → 0.2.0

package/dist/message.d.ts

@@ -1,41 +1,20 @@
-import { Formats, Formatters, MessageFormatPart } from 'intl-messageformat';
-import type { MessageFormatElement } from '@formatjs/icu-messageformat-parser';
+import { FormatJsNode } from './keyless-json';
 export declare class InternalIntlMessage {
     locale: string;
     message?: string;
-    ast: MessageFormatElement[];
+    ast: FormatJsNode[];
     /**
      * 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);
-    /**
-     * 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>>;
-    /**
-     * 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;
+    get plainAst(): FormatJsNode[];
+    _plainAst: FormatJsNode[];
+    constructor(messageOrAst: string | FormatJsNode[], locale: string);
     /**
      * 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[];
+    private _removeRichTags;
 }

package/dist/message.js

@@ -37,106 +37,57 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InternalIntlMessage = void 0;
-var icu_messageformat_parser_1 = require("@formatjs/icu-messageformat-parser");
-var intl_messageformat_1 = require("intl-messageformat");
+var keyless_json_1 = require("./keyless-json");
 var InternalIntlMessage = /** @class */ (function () {
     function InternalIntlMessage(messageOrAst, locale) {
         this.locale = locale;
         if (typeof messageOrAst === 'string') {
             this.message = messageOrAst;
-            this.ast = (0, icu_messageformat_parser_1.parse)(messageOrAst);
         }
         else {
             this.ast = messageOrAst;
         }
-        this.plainAst = undefined;
     }
+    Object.defineProperty(InternalIntlMessage.prototype, "plainAst", {
+        /**
+         * 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`).
+         */
+        get: function () {
+            return (this._plainAst = this._removeRichTags(this.ast));
+        },
+        enumerable: false,
+        configurable: true
+    });
     /**
-     * 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.
-     */
-    InternalIntlMessage.prototype.formatToParts = function (formatters, formats, values) {
-        return (0, intl_messageformat_1.formatToParts)(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.
+     * 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.
      */
-    InternalIntlMessage.prototype.formatToPlainString = function (formatters, formats, values) {
-        var e_1, _a, _b, e_2, _c;
-        // Lazily create the reduced AST if it hasn't already been done.
-        if (this.plainAst == null) {
-            this.plainAst = [];
-            try {
-                for (var _d = __values(this.ast), _e = _d.next(); !_e.done; _e = _d.next()) {
-                    var part = _e.value;
-                    (_b = this.plainAst).push.apply(_b, __spreadArray([], __read(this._removeRichTags(part)), false));
+    InternalIntlMessage.prototype._removeRichTags = function (nodes) {
+        var e_1, _a;
+        var result = new Array(nodes.length);
+        try {
+            for (var nodes_1 = __values(nodes), nodes_1_1 = nodes_1.next(); !nodes_1_1.done; nodes_1_1 = nodes_1.next()) {
+                var node = nodes_1_1.value;
+                if (node.type === keyless_json_1.FormatJsNodeType.Tag) {
+                    result.push.apply(result, __spreadArray([], __read(this._removeRichTags(node.children)), false));
                 }
-            }
-            catch (e_1_1) { e_1 = { error: e_1_1 }; }
-            finally {
-                try {
-                    if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+                else {
+                    result.push(node);
                 }
-                finally { if (e_1) throw e_1.error; }
-            }
-        }
-        var parts = (0, intl_messageformat_1.formatToParts)(this.plainAst, this.locale, formatters, formats, values);
-        var result = '';
-        try {
-            for (var parts_1 = __values(parts), parts_1_1 = parts_1.next(); !parts_1_1.done; parts_1_1 = parts_1.next()) {
-                var part = parts_1_1.value;
-                result += String(part.value);
             }
         }
-        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
         finally {
             try {
-                if (parts_1_1 && !parts_1_1.done && (_c = parts_1.return)) _c.call(parts_1);
+                if (nodes_1_1 && !nodes_1_1.done && (_a = nodes_1.return)) _a.call(nodes_1);
             }
-            finally { if (e_2) throw e_2.error; }
+            finally { if (e_1) throw e_1.error; }
         }
         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.
-     */
-    InternalIntlMessage.prototype._removeRichTags = function (element) {
-        var e_3, _a;
-        if (element.type === icu_messageformat_parser_1.TYPE.tag) {
-            var childContent = [];
-            try {
-                for (var _b = __values(element.children), _c = _b.next(); !_c.done; _c = _b.next()) {
-                    var child = _c.value;
-                    childContent.push.apply(childContent, __spreadArray([], __read(this._removeRichTags(child)), false));
-                }
-            }
-            catch (e_3_1) { e_3 = { error: e_3_1 }; }
-            finally {
-                try {
-                    if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
-                }
-                finally { if (e_3) throw e_3.error; }
-            }
-            return childContent;
-        }
-        else {
-            return [element];
-        }
-    };
     return InternalIntlMessage;
 }());
 exports.InternalIntlMessage = InternalIntlMessage;

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { InternalIntlMessage } from './message';
 import type { IntlMessageGetterAdditions } from './message-loader';
+import { FormatBuilderConstructor } from './format';
 
 /**
  * Use this function to define messages as part of the `@discord/intl`
@@ -11,14 +12,6 @@ import type { IntlMessageGetterAdditions } from './message-loader';
  */
 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>;
-
 /**
  * Placeholder type representing that this property is a Hook to be rendered
  * while formatting.
@@ -46,19 +39,8 @@ export type IntlTime = string | number | Date | null | undefined;
  * 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>;
+export type PlainIntlMessage = string;
+export type AnyIntlMessage = PlainIntlMessage | InternalIntlMessage;
 
 export interface IntlMessageGetter extends IntlMessageGetterAdditions {
   (locale: string): InternalIntlMessage | PlainIntlMessage;
@@ -85,8 +67,8 @@ export interface TypedIntlMessageGetter<FormatValues extends object | undefined>
   // from the declared type. The latter of these is definitely semantically
   // correct, but the former is more just an annoying part of the type system
   // because of this returned type being nested within this interface and the
-  // strict subtying that TypeScript uses.
-  (locale: string): InternalIntlMessage | PlainIntlMessage;
+  // strict subtyping that TypeScript uses.
+  (locale: string): InternalIntlMessage;
 
   /**
    * A phantom type (not part of the actual typing of the object) that ensures
@@ -183,7 +165,7 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
  * checked against the provided message types, and error messages will be
  * accurate as a result.
  */
-type FormatValuesFor<T> =
+export 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
@@ -209,12 +191,18 @@ type FormatValuesFor<T> =
  * the caller to inject React elements within a string, while an AST formatter
  * might require a specific object shape, or allow any plain object.
  */
-interface FunctionTypeMap {
+export interface FunctionTypeMap {
   link: any;
   hook: any;
   handler: any;
 }
 
+export interface FunctionTypes<Result, HandlerType = (content: Result[]) => Result | Result[]> {
+  link: undefined | ((content: Result[]) => Result | Result[]);
+  hook: undefined | ((content: Result[]) => Result | Result[]);
+  handler: undefined | HandlerType;
+}
+
 type ReplaceKeepingNullability<T, P> = P | Exclude<T, NonNullable<T>>;
 
 /**
@@ -226,6 +214,8 @@ type ReplaceKeepingNullability<T, P> = P | Exclude<T, NonNullable<T>>;
 type MapFunctionTypes<T, FunctionTypes extends FunctionTypeMap> = {
   [K in keyof T]: ReplaceKeepingNullability<
     T[K],
+    // TODO: replace these types with string literal types in the generated
+    // file, turning this whole chain into `FunctionTypes[T[K]] ?? T[K]`.
     NonNullable<T[K]> extends LinkFunction
       ? FunctionTypes['link']
       : NonNullable<T[K]> extends HookFunction
@@ -251,7 +241,7 @@ type CheckStrictAny<Check, Yes, No> = (Check extends never ? true : false) exten
  * // Result is `{name: string}`
  * ```
  */
-type IntlMessageGetterInnerType<T extends IntlMessageGetter> =
+export type IntlMessageGetterInnerType<T extends IntlMessageGetter> =
   T extends TypedIntlMessageGetter<infer U> ? U : never;
 
 /**
@@ -260,13 +250,12 @@ type IntlMessageGetterInnerType<T extends IntlMessageGetter> =
  * types from `FunctionTypes`. The result is the set of required values
  * necessary to format the message of type `T` with the calling formatter.
  */
-type RequiredFormatValues<
+export type RequiredFormatValues<
   Values extends IntlMessageGetter,
-  DefaultElements,
   FunctionTypes extends FunctionTypeMap,
 > =
   IntlMessageGetterInnerType<Values> extends undefined
-    ? never
+    ? {}
     : CheckStrictAny<
         IntlMessageGetterInnerType<Values>,
         // If `T` is explicitly `any`, then individual properties can't be typed and
@@ -277,23 +266,30 @@ type RequiredFormatValues<
         // value and turn every property into the mapped `LinkFunction` type, which
         // is almost always going to be wrong.
         any,
-        MapFunctionTypes<
-          Omit<FormatValuesFor<IntlMessageGetterInnerType<Values>>, keyof DefaultElements>,
-          FunctionTypes
-        >
+        MapFunctionTypes<FormatValuesFor<IntlMessageGetterInnerType<Values>>, FunctionTypes>
       >;
 
-export interface IntlOptionalRichTextKeys {
-  $_: any;
-  $b: any;
-  $i: any;
-  $p: any;
-  $link: any;
-  $code: any;
+export interface RichTextFormattingMap<T = any> {
+  $_: T;
+  $b: T;
+  $i: T;
+  $p: T;
+  $link: T;
+  $code: T;
 }
 
-export type IntlFormatFunctionValuesArg<T extends IntlMessageGetter> = RequiredFormatValues<
-  T,
-  IntlOptionalRichTextKeys,
-  FunctionTypeMap
->;
+export type RichTextTagNames = keyof RichTextFormattingMap;
+
+export interface FormatterImplementation<
+  FunctionTypes extends FunctionTypeMap,
+  Result,
+  BuilderResult = Result,
+> {
+  format: (
+    message: AnyIntlMessage,
+    values: object,
+    builder?: FormatBuilderConstructor<BuilderResult>,
+  ) => Result;
+  builder: FormatBuilderConstructor<BuilderResult extends (infer T)[] ? T : BuilderResult>;
+  __$functionTypes?: FunctionTypes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl",
-  "version": "0.1.3-rc.0",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "Client runtime for managing messages and translations in a React project.",
   "main": "./dist/index.js",
@@ -15,7 +15,6 @@
     "src"
   ],
   "dependencies": {
-    "@formatjs/icu-messageformat-parser": "^2.7.6",
     "@formatjs/intl": "^2.10.1",
     "intl-messageformat": "^10.5.11"
   },

package/src/format.ts

@@ -0,0 +1,224 @@
+/**
+ * The core formatter, responsible for applying values to placeholders in
+ * messages and creating a static CST from the result. This method does _not_
+ * replace any of the rich-text formatting values (e.g., `$b` or `$link`) and
+ * leaves those to final formatters to apply as appropriate for the context
+ * of where the message is being rendered (e.g., React versus a plain string).
+ *
+ * The majority of this method is lifted from FormatJS' own `formatToParts`
+ * implementation, but is abstracted here to provide a few benefits:
+ * - working with the keyless AST format rather than having to transpose to the
+ *   exact object format that FormatJS expects.
+ * - understanding the difference between rich text formatting values and
+ *   user-provided values.
+ * - provide extra options related to the above for more control over how
+ *   formatting operates, while abstracting out some of the common values.
+ * - adding extra context for hook and link functions to provide a `key`
+ *   parameter, important to have React treat the resulting elements nicely.
+ */
+
+import { FormatJsNode, FormatJsNodeType } from './keyless-json';
+import { Formats, Formatters, MissingValueError } from 'intl-messageformat';
+import { RichTextTagNames } from './types';
+
+/**
+ * Returns true if the tag name should be considered a rich text tag that
+ * applies formatting to a message, rather than being a user-supplied value.
+ */
+function isRichTextTag(name: string) {
+  return name[0] === '$';
+}
+
+export abstract class FormatBuilder<Result> {
+  abstract pushRichTextTag(tag: RichTextTagNames, children: Result[]): void;
+  abstract pushLiteralText(text: string): void;
+  abstract pushObject(value: object): void;
+  abstract finish(): Result[];
+}
+
+export type FormatBuilderConstructor<Result> = new () => FormatBuilder<Result>;
+
+export function bindFormatValuesWithBuilder<T, Builder extends FormatBuilder<T>>(
+  builder: Builder,
+  nodes: FormatJsNode[],
+  locales: string | string[],
+  formatters: Formatters,
+  formats: Formats,
+  values: Record<string, string | object> = {},
+  currentPluralValue?: number,
+  originalMessage?: string,
+) {
+  // Hot path for static messages that are just parsed as a single string element.
+  if (nodes.length === 1 && nodes[0].type === FormatJsNodeType.Literal) {
+    builder.pushLiteralText(nodes[0].value);
+    return;
+  }
+
+  for (const node of nodes) {
+    switch (node.type) {
+      case FormatJsNodeType.Literal:
+        builder.pushLiteralText(node.value);
+        continue;
+
+      case FormatJsNodeType.Pound:
+        // Replace `#` in plural rules with the actual numeric value. Only
+        // numeric values are replaced, otherwise the value is completed ignored?
+        // Behavior copied from FormatJS directly.
+        if (typeof currentPluralValue === 'number') {
+          const value = formatters.getNumberFormat(locales).format(currentPluralValue);
+          builder.pushLiteralText(value);
+        }
+        continue;
+    }
+
+    const { value: variableName } = node;
+    // Enforce that all required values are provided by the caller, even if the
+    // actual value is falsy/undefined.
+    if (!(variableName in values) && !isRichTextTag(variableName)) {
+      throw new MissingValueError(variableName, originalMessage);
+    }
+
+    const value = values[variableName];
+
+    switch (node.type) {
+      case FormatJsNodeType.Argument:
+        // Empty values don't need to be added at all, they are purely for AST representation.
+        if (variableName == '$_') break;
+
+        if (typeof value === 'object') {
+          builder.pushObject(value);
+        } else {
+          // Taken from FormatJS: non-objects (strings, numbers, and falsy
+          // values) all get cast to strings immediately as literal nodes.
+          builder.pushLiteralText(String(value));
+        }
+        break;
+      case FormatJsNodeType.Date: {
+        // Distinct from FormatJS: We don't currently parse the skeleton ahead of time in the AST,
+        // so this manages parsing the skeleton as well before passing it onto the date formatter.
+        if (typeof node.style !== 'string') {
+          throw '@discord/intl does not currently support non-string format skeletons';
+        }
+        const style = node.style in formats.date ? formats.date[node.style] : undefined; // TODO: parseSkeleton();
+        // @ts-expect-error Cast string values to dates properly.
+        builder.pushLiteralText(formatters.getDateTimeFormat(locales, style).format(value));
+        break;
+      }
+      case FormatJsNodeType.Time: {
+        // Distinct from FormatJS: We don't currently parse the skeleton ahead of time in the AST,
+        // so this manages parsing the skeleton as well before passing it onto the date formatter.
+        if (typeof node.style !== 'string') {
+          throw '@discord/intl does not currently support non-string format skeletons';
+        }
+        const style = node.style in formats.time ? formats.time[node.style] : undefined; // TODO: parseSkeleton();
+        builder.pushLiteralText(
+          // @ts-expect-error Cast string values to dates properly.
+          formatters.getDateTimeFormat(locales, style).format(value),
+        );
+        break;
+      }
+      case FormatJsNodeType.Number: {
+        // Distinct from FormatJS: We don't currently parse the skeleton ahead of time in the AST,
+        // so this manages parsing the skeleton as well before passing it onto the date formatter.
+        if (typeof node.style !== 'string') {
+          throw '@discord/intl does not currently support non-string format skeletons';
+        }
+        const style = node.style in formats.number ? formats.number[node.style] : undefined; // TODO: parseSkeleton();
+
+        // @ts-expect-error Support `scale` style property.
+        const scaledValue = value as number;
+        // const scaledValue = (value as number) * (style?.scale ?? 1);
+        builder.pushLiteralText(formatters.getNumberFormat(locales, style).format(scaledValue));
+        break;
+      }
+
+      case FormatJsNodeType.Tag: {
+        const { children } = node;
+        const appliedChildren = bindFormatValues(
+          builder.constructor as FormatBuilderConstructor<T>,
+          children,
+          locales,
+          formatters,
+          formats,
+          values,
+          currentPluralValue,
+        );
+        if (isRichTextTag(variableName)) {
+          builder.pushRichTextTag(variableName as RichTextTagNames, appliedChildren);
+        } else {
+          if (typeof value !== 'function') {
+            throw `expected a function type for a Tag formatting value, ${variableName}. got ${typeof value}: ${value}`;
+          }
+          let chunks = value(appliedChildren);
+          chunks = Array.isArray(chunks) ? chunks : [chunks];
+          for (const chunk of chunks) {
+            if (typeof chunk === 'string') {
+              builder.pushLiteralText(chunk);
+            } else {
+              builder.pushObject(chunk);
+            }
+          }
+        }
+        break;
+      }
+
+      case FormatJsNodeType.Select: {
+        const option = node.value in node.options ? node.options[node.value] : node.options.other;
+        if (option == null) {
+          throw `${node.value} is not a known option for select value ${variableName}. Valid options are ${Object.keys(node.options).join(', ')}`;
+        }
+        bindFormatValuesWithBuilder(builder, option.value, locales, formatters, formats, values);
+        break;
+      }
+
+      case FormatJsNodeType.Plural: {
+        const option = (() => {
+          const exactSelector = `=${value}`;
+          if (exactSelector in node.options) return node.options[exactSelector];
+          const rule = formatters
+            .getPluralRules(locales, { type: node.pluralType })
+            // @ts-expect-error Assert this `as number` properly.
+            .select((value as number) - (node.offset ?? 0));
+          return node.options[rule] ?? node.options.other;
+        })();
+
+        if (option == null) {
+          throw `${node.value} is not a known option for plural value ${variableName}. Valid options are ${Object.keys(node.options).join(', ')}`;
+        }
+        bindFormatValuesWithBuilder(
+          builder,
+          option.value,
+          locales,
+          formatters,
+          formats,
+          values,
+          // @ts-expect-error assert this `as number` properly.
+          (value as number) - (node.offset ?? 0),
+        );
+        break;
+      }
+    }
+  }
+}
+
+export function bindFormatValues<Result>(
+  Builder: FormatBuilderConstructor<Result>,
+  nodes: FormatJsNode[],
+  locales: string | string[],
+  formatters: Formatters,
+  formats: Formats,
+  values: Record<string, string | object> = {},
+  currentPluralValue?: number,
+): Result[] {
+  const builder = new Builder();
+  bindFormatValuesWithBuilder(
+    builder,
+    nodes,
+    locales,
+    formatters,
+    formats,
+    values,
+    currentPluralValue,
+  );
+  return builder.finish();
+}