@ultraq/icu-message-formatter 0.15.0-beta.1 → 0.15.0

package/dist/icu-message-formatter.cjs

@@ -1,239 +1,482 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const functionUtils = require("@ultraq/function-utils");
-function parseCases(string = "") {
-  const isWhitespace = (ch) => /\s/.test(ch);
-  const args = [];
-  const cases = {};
-  let currTermStart = 0;
-  let latestTerm = null;
-  let inTerm = false;
-  let i = 0;
-  while (i < string.length) {
-    if (inTerm && (isWhitespace(string[i]) || string[i] === "{")) {
-      inTerm = false;
-      latestTerm = string.slice(currTermStart, i);
-      if (string[i] === "{") {
-        i--;
-      }
-    } else if (!inTerm && !isWhitespace(string[i])) {
-      const caseBody = string[i] === "{";
-      if (latestTerm && caseBody) {
-        const branchEndIndex = findClosingBracket(string, i);
-        if (branchEndIndex === -1) {
-          throw new Error(`Unbalanced curly braces in string: "${string}"`);
-        }
-        cases[latestTerm] = string.slice(i + 1, branchEndIndex);
-        i = branchEndIndex;
-        latestTerm = null;
-      } else {
-        if (latestTerm) {
-          args.push(latestTerm);
-          latestTerm = null;
-        }
-        inTerm = true;
-        currTermStart = i;
-      }
-    }
-    i++;
-  }
-  if (inTerm) {
-    latestTerm = string.slice(currTermStart);
-  }
-  if (latestTerm) {
-    args.push(latestTerm);
-  }
-  return {
-    args,
-    cases
-  };
+'use strict';
+
+var functionUtils = require('@ultraq/function-utils');
+
+/*
+ * Copyright 2019, Emanuel Rabina (http://www.ultraq.net.nz/)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @typedef ParseCasesResult
+ * @property {string[]} args
+ *   A list of prepended arguments.
+ * @property {Record<string,string>} cases
+ *   A map of all cases.
+ */
+
+/**
+ * Most branch-based type handlers are based around "cases".  For example,
+ * `select` and `plural` compare compare a value to "case keys" to choose a
+ * subtranslation.
+ *
+ * This util splits "matches" portions provided to the aforementioned handlers
+ * into case strings, and extracts any prepended arguments (for example,
+ * `plural` supports an `offset:n` argument used for populating the magic `#`
+ * variable).
+ *
+ * @param {string} string
+ * @return {ParseCasesResult}
+ */
+function parseCases(string = '') {
+	const isWhitespace = ch => /\s/.test(ch);
+
+	const args = [];
+	const cases = {};
+
+	let currTermStart = 0;
+	let latestTerm = null;
+	let inTerm = false;
+
+	let i = 0;
+	while (i < string.length) {
+		// Term ended
+		if (inTerm && (isWhitespace(string[i]) || string[i] === '{')) {
+			inTerm = false;
+			latestTerm = string.slice(currTermStart, i);
+
+			// We want to process the opening char again so the case will be properly registered.
+			if (string[i] === '{') {
+				i--;
+			}
+		}
+
+		// New term
+		else if (!inTerm && !isWhitespace(string[i])) {
+			const caseBody = string[i] === '{';
+
+			// If there's a previous term, we can either handle a whole
+			// case, or add that as an argument.
+			if (latestTerm && caseBody) {
+				const branchEndIndex = findClosingBracket(string, i);
+
+				if (branchEndIndex === -1) {
+					throw new Error(`Unbalanced curly braces in string: "${string}"`);
+				}
+
+				cases[latestTerm] = string.slice(i + 1, branchEndIndex);  // Don't include the braces
+
+				i = branchEndIndex; // Will be moved up where needed at end of loop.
+				latestTerm = null;
+			}
+			else {
+				if (latestTerm) {
+					args.push(latestTerm);
+					latestTerm = null;
+				}
+
+				inTerm = true;
+				currTermStart = i;
+			}
+		}
+		i++;
+	}
+
+	if (inTerm) {
+		latestTerm = string.slice(currTermStart);
+	}
+
+	if (latestTerm) {
+		args.push(latestTerm);
+	}
+
+	return {
+		args,
+		cases
+	};
 }
+
+/**
+ * Finds the index of the matching closing curly bracket, including through
+ * strings that could have nested brackets.
+ *
+ * @param {string} string
+ * @param {number} fromIndex
+ * @return {number}
+ *   The index of the matching closing bracket, or -1 if no closing bracket
+ *   could be found.
+ */
 function findClosingBracket(string, fromIndex) {
-  let depth = 0;
-  for (let i = fromIndex + 1; i < string.length; i++) {
-    let char = string.charAt(i);
-    if (char === "}") {
-      if (depth === 0) {
-        return i;
-      }
-      depth--;
-    } else if (char === "{") {
-      depth++;
-    }
-  }
-  return -1;
+	let depth = 0;
+	for (let i = fromIndex + 1; i < string.length; i++) {
+		let char = string.charAt(i);
+		if (char === '}') {
+			if (depth === 0) {
+				return i;
+			}
+			depth--;
+		}
+		else if (char === '{') {
+			depth++;
+		}
+	}
+	return -1;
 }
+
+/**
+ * Split a `{key, type, format}` block into those 3 parts, taking into account
+ * nested message syntax that can exist in the `format` part.
+ *
+ * @param {string} block
+ * @return {string[]}
+ *   An array with `key`, `type`, and `format` items in that order, if present
+ *   in the formatted argument block.
+ */
 function splitFormattedArgument(block) {
-  return split(block.slice(1, -1), ",", 3);
+	return split(block.slice(1, -1), ',', 3);
 }
+
+/**
+ * Like `String.prototype.split()` but where the limit parameter causes the
+ * remainder of the string to be grouped together in a final entry.
+ *
+ * @private
+ * @param {string} string
+ * @param {string} separator
+ * @param {number} limit
+ * @param {string[]} accumulator
+ * @return {string[]}
+ */
 function split(string, separator, limit, accumulator = []) {
-  if (!string) {
-    return accumulator;
-  }
-  if (limit === 1) {
-    accumulator.push(string);
-    return accumulator;
-  }
-  let indexOfDelimiter = string.indexOf(separator);
-  if (indexOfDelimiter === -1) {
-    accumulator.push(string);
-    return accumulator;
-  }
-  let head = string.substring(0, indexOfDelimiter).trim();
-  let tail = string.substring(indexOfDelimiter + separator.length + 1).trim();
-  accumulator.push(head);
-  return split(tail, separator, limit - 1, accumulator);
+	if (!string) {
+		return accumulator;
+	}
+	if (limit === 1) {
+		accumulator.push(string);
+		return accumulator;
+	}
+	let indexOfDelimiter = string.indexOf(separator);
+	if (indexOfDelimiter === -1) {
+		accumulator.push(string);
+		return accumulator;
+	}
+	let head = string.substring(0, indexOfDelimiter).trim();
+	let tail = string.substring(indexOfDelimiter + separator.length + 1).trim();
+	accumulator.push(head);
+	return split(tail, separator, limit - 1, accumulator);
 }
+
+/*
+ * Copyright 2019, Emanuel Rabina (http://www.ultraq.net.nz/)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+/**
+ * @typedef {Record<string,any>} FormatValues
+ */
+
+/**
+ * @callback ProcessFunction
+ * @param {string} message
+ * @param {FormatValues} [values={}]
+ * @return {any[]}
+ */
+
+/**
+ * @callback TypeHandler
+ * @param {any} value
+ *   The object which matched the key of the block being processed.
+ * @param {string} matches
+ *   Any format options associated with the block being processed.
+ * @param {string} locale
+ *   The locale to use for formatting.
+ * @param {FormatValues} values
+ *   The object of placeholder data given to the original `format`/`process`
+ *   call.
+ * @param {ProcessFunction} process
+ *   The `process` function itself so that sub-messages can be processed by type
+ *   handlers.
+ * @return {any | any[]}
+ */
+
+/**
+ * The main class for formatting messages.
+ *
+ * @author Emanuel Rabina
+ */
 class MessageFormatter {
-  /**
-   * Creates a new formatter that can work using any of the custom type handlers
-   * you register.
-   *
-   * @param {string} locale
-   * @param {Record<string,TypeHandler>} [typeHandlers]
-   *   Optional object where the keys are the names of the types to register,
-   *   their values being the functions that will return a nicely formatted
-   *   string for the data and locale they are given.
-   */
-  constructor(locale, typeHandlers = {}) {
-    /**
-     * Formats an ICU message syntax string using `values` for placeholder data
-     * and any currently-registered type handlers.
-     *
-     * @type {(message: string, values?: FormatValues) => string}
-     */
-    __publicField(this, "format", functionUtils.memoize((message, values = {}) => {
-      return this.process(message, values).flat(Infinity).join("");
-    }));
-    this.locale = locale;
-    this.typeHandlers = typeHandlers;
-  }
-  /**
-   * Process an ICU message syntax string using `values` for placeholder data
-   * and any currently-registered type handlers.  The result of this method is
-   * an array of the component parts after they have been processed in turn by
-   * their own type handlers.  This raw output is useful for other renderers,
-   * eg: React where components can be used instead of being forced to return
-   * raw strings.
-   *
-   * This method is used by {@link MessageFormatter#format} where it acts as a
-   * string renderer.
-   *
-   * @param {string} message
-   * @param {FormatValues} [values]
-   * @return {any[]}
-   */
-  process(message, values = {}) {
-    if (!message) {
-      return [];
-    }
-    let blockStartIndex = message.indexOf("{");
-    if (blockStartIndex !== -1) {
-      let blockEndIndex = findClosingBracket(message, blockStartIndex);
-      if (blockEndIndex !== -1) {
-        let block = message.substring(blockStartIndex, blockEndIndex + 1);
-        if (block) {
-          let result = [];
-          let head = message.substring(0, blockStartIndex);
-          if (head) {
-            result.push(head);
-          }
-          let [key, type, format] = splitFormattedArgument(block);
-          let body = values[key];
-          if (body === null || body === void 0) {
-            body = "";
-          }
-          let typeHandler = type && this.typeHandlers[type];
-          result.push(typeHandler ? typeHandler(body, format, this.locale, values, this.process.bind(this)) : body);
-          let tail = message.substring(blockEndIndex + 1);
-          if (tail) {
-            result.push(this.process(tail, values));
-          }
-          return result;
-        }
-      } else {
-        throw new Error(`Unbalanced curly braces in string: "${message}"`);
-      }
-    }
-    return [message];
-  }
+
+	/**
+	 * Creates a new formatter that can work using any of the custom type handlers
+	 * you register.
+	 *
+	 * @param {string} locale
+	 * @param {Record<string,TypeHandler>} [typeHandlers]
+	 *   Optional object where the keys are the names of the types to register,
+	 *   their values being the functions that will return a nicely formatted
+	 *   string for the data and locale they are given.
+	 */
+	constructor(locale, typeHandlers = {}) {
+
+		this.locale = locale;
+		this.typeHandlers = typeHandlers;
+	}
+
+	/**
+	 * Formats an ICU message syntax string using `values` for placeholder data
+	 * and any currently-registered type handlers.
+	 *
+	 * @type {(message: string, values?: FormatValues) => string}
+	 */
+	format = functionUtils.memoize((message, values = {}) => {
+
+		return this.process(message, values).flat(Infinity).join('');
+	});
+
+	/**
+	 * Process an ICU message syntax string using `values` for placeholder data
+	 * and any currently-registered type handlers.  The result of this method is
+	 * an array of the component parts after they have been processed in turn by
+	 * their own type handlers.  This raw output is useful for other renderers,
+	 * eg: React where components can be used instead of being forced to return
+	 * raw strings.
+	 *
+	 * This method is used by {@link MessageFormatter#format} where it acts as a
+	 * string renderer.
+	 *
+	 * @param {string} message
+	 * @param {FormatValues} [values]
+	 * @return {any[]}
+	 */
+	process(message, values = {}) {
+
+		if (!message) {
+			return [];
+		}
+
+		let blockStartIndex = message.indexOf('{');
+		if (blockStartIndex !== -1) {
+			let blockEndIndex = findClosingBracket(message, blockStartIndex);
+			if (blockEndIndex !== -1) {
+				let block = message.substring(blockStartIndex, blockEndIndex + 1);
+				if (block) {
+					let result = [];
+					let head = message.substring(0, blockStartIndex);
+					if (head) {
+						result.push(head);
+					}
+					let [key, type, format] = splitFormattedArgument(block);
+					let body = values[key];
+					let typeHandler = type && this.typeHandlers[type];
+					result.push(typeHandler ?
+						typeHandler(body, format, this.locale, values, this.process.bind(this)) :
+						body);
+					let tail = message.substring(blockEndIndex + 1);
+					if (tail) {
+						result.push(this.process(tail, values));
+					}
+					return result;
+				}
+			}
+			else {
+				throw new Error(`Unbalanced curly braces in string: "${message}"`);
+			}
+		}
+		return [message];
+	}
 }
+
+/*
+ * Copyright 2019, Emanuel Rabina (http://www.ultraq.net.nz/)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
 let pluralFormatter;
+
 let keyCounter = 0;
-const ONE = "one";
-const OTHER$1 = "other";
+
+// All the special keywords that can be used in `plural` blocks for the various branches
+const ONE   = 'one';
+const OTHER$1 = 'other';
+
+/**
+ * @private
+ * @param {string} caseBody
+ * @param {number} value
+ * @return {{caseBody: string, numberValues: object}}
+ */
 function replaceNumberSign(caseBody, value) {
-  let i = 0;
-  let output = "";
-  let numBraces = 0;
-  const numberValues = {};
-  while (i < caseBody.length) {
-    if (caseBody[i] === "#" && !numBraces) {
-      let keyParam = `__hashToken${keyCounter++}`;
-      output += `{${keyParam}, number}`;
-      numberValues[keyParam] = value;
-    } else {
-      output += caseBody[i];
-    }
-    if (caseBody[i] === "{") {
-      numBraces++;
-    } else if (caseBody[i] === "}") {
-      numBraces--;
-    }
-    i++;
-  }
-  return {
-    caseBody: output,
-    numberValues
-  };
+	let i = 0;
+	let output = '';
+	let numBraces = 0;
+	const numberValues = {};
+
+	while (i < caseBody.length) {
+		if (caseBody[i] === '#' && !numBraces) {
+			let keyParam = `__hashToken${keyCounter++}`;
+			output += `{${keyParam}, number}`;
+			numberValues[keyParam] = value;
+		}
+		else {
+			output += caseBody[i];
+		}
+
+		if (caseBody[i] === '{') {
+			numBraces++;
+		}
+		else if (caseBody[i] === '}') {
+			numBraces--;
+		}
+
+		i++;
+	}
+
+	return {
+		caseBody: output,
+		numberValues
+	};
 }
+
+/**
+ * Handler for `plural` statements within ICU message syntax strings.  Returns
+ * a formatted string for the branch that closely matches the current value.
+ *
+ * See https://formatjs.io/docs/core-concepts/icu-syntax#plural-format for more
+ * details on how the `plural` statement works.
+ *
+ * @param {string} value
+ * @param {string} matches
+ * @param {string} locale
+ * @param {import('./MessageFormatter.js').FormatValues} values
+ * @param {import('./MessageFormatter.js').ProcessFunction} process
+ * @return {any | any[]}
+ */
 function pluralTypeHandler(value, matches, locale, values, process) {
-  const { args, cases } = parseCases(matches);
-  let intValue = parseInt(value);
-  args.forEach((arg) => {
-    if (arg.startsWith("offset:")) {
-      intValue -= parseInt(arg.slice("offset:".length));
-    }
-  });
-  const keywordPossibilities = [];
-  if ("PluralRules" in Intl) {
-    if (pluralFormatter === void 0 || pluralFormatter.resolvedOptions().locale !== locale) {
-      pluralFormatter = new Intl.PluralRules(locale);
-    }
-    const pluralKeyword = pluralFormatter.select(intValue);
-    if (pluralKeyword !== OTHER$1) {
-      keywordPossibilities.push(pluralKeyword);
-    }
-  }
-  if (intValue === 1) {
-    keywordPossibilities.push(ONE);
-  }
-  keywordPossibilities.push(`=${intValue}`, OTHER$1);
-  for (let i = 0; i < keywordPossibilities.length; i++) {
-    const keyword = keywordPossibilities[i];
-    if (keyword in cases) {
-      const { caseBody, numberValues } = replaceNumberSign(cases[keyword], intValue);
-      return process(caseBody, {
-        ...values,
-        ...numberValues
-      });
-    }
-  }
-  return value;
+	const {args, cases} = parseCases(matches);
+
+	let intValue = parseInt(value);
+
+	args.forEach((arg) => {
+		if (arg.startsWith('offset:')) {
+			intValue -= parseInt(arg.slice('offset:'.length));
+		}
+	});
+
+	const keywordPossibilities = [];
+
+	if ('PluralRules' in Intl) {
+		// Effectively memoize because instantiation of `Int.*` objects is expensive.
+		if (pluralFormatter === undefined || pluralFormatter.resolvedOptions().locale !== locale) {
+			pluralFormatter = new Intl.PluralRules(locale);
+		}
+
+		const pluralKeyword = pluralFormatter.select(intValue);
+
+		// Other is always added last with least priority, so we don't want to add it here.
+		if (pluralKeyword !== OTHER$1) {
+			keywordPossibilities.push(pluralKeyword);
+		}
+	}
+	if (intValue === 1) {
+		keywordPossibilities.push(ONE);
+	}
+	keywordPossibilities.push(`=${intValue}`, OTHER$1);
+
+	for (let i = 0; i < keywordPossibilities.length; i++) {
+		const keyword = keywordPossibilities[i];
+		if (keyword in cases) {
+			const {caseBody, numberValues} = replaceNumberSign(cases[keyword], intValue);
+			return process(caseBody, {
+				...values,
+				...numberValues
+			});
+		}
+	}
+
+	return value;
 }
-const OTHER = "other";
+
+/*
+ * Copyright 2019, Emanuel Rabina (http://www.ultraq.net.nz/)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+const OTHER = 'other';
+
+/**
+ * Handler for `select` statements within ICU message syntax strings.  Returns
+ * a formatted string for the branch that closely matches the current value.
+ *
+ * See https://formatjs.io/docs/core-concepts/icu-syntax#select-format for more
+ * details on how the `select` statement works.
+ *
+ * @param {string} value
+ * @param {string} matches
+ * @param {string} locale
+ * @param {import('./MessageFormatter.js').FormatValues} values
+ * @param {import('./MessageFormatter.js').ProcessFunction} process
+ * @return {any | any[]}
+ */
 function selectTypeHandler(value, matches, locale, values, process) {
-  const { cases } = parseCases(matches);
-  if (value in cases) {
-    return process(cases[value], values);
-  } else if (OTHER in cases) {
-    return process(cases[OTHER], values);
-  }
-  return value;
+	const {cases} = parseCases(matches);
+
+	if (value in cases) {
+		return process(cases[value], values);
+	}
+	else if (OTHER in cases) {
+		return process(cases[OTHER], values);
+	}
+
+	return value;
 }
+
 exports.MessageFormatter = MessageFormatter;
 exports.findClosingBracket = findClosingBracket;
 exports.parseCases = parseCases;