@ultraq/icu-message-formatter 0.12.0-beta.0 → 0.13.0

package/source/utilities.js

@@ -15,18 +15,25 @@
  */
 
 /**
- * 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.
+ * @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).
+ * 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 {Object} The `cases` key points to a map of all cases.
- *                  The `arguments` key points to a list of prepended arguments.
+ * @param {string} string
+ * @return {ParseCasesResult}
  */
 export function parseCases(string) {
 	const isWhitespace = ch => /\s/.test(ch);
@@ -100,10 +107,11 @@ export function parseCases(string) {
  * 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.
+ * @param {string} string
+ * @param {number} fromIndex
+ * @return {number}
+ *   The index of the matching closing bracket, or -1 if no closing bracket
+ *   could be found.
  */
 export function findClosingBracket(string, fromIndex) {
 	let depth = 0;
@@ -126,8 +134,8 @@ export function findClosingBracket(string, fromIndex) {
  * 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 {Array}
+ * @param {string} block
+ * @return {string[]}
  *   An array with `key`, `type`, and `format` items in that order, if present
  *   in the formatted argument block.
  */
@@ -140,11 +148,11 @@ export function splitFormattedArgument(block) {
  * remainder of the string to be grouped together in a final entry.
  * 
  * @private
- * @param {String} string
- * @param {String} separator
- * @param {Number} limit
- * @param {Array} [accumulator=[]]
- * @return {Array}
+ * @param {string} string
+ * @param {string} separator
+ * @param {number} limit
+ * @param {string[]} accumulator
+ * @return {string[]}
  */
 function split(string, separator, limit, accumulator = []) {
 	if (!string) {

package/source/utilities.test.js

@@ -15,7 +15,7 @@
  */
 
 /* eslint-env jest */
-import { parseCases } from './utilities';
+import {parseCases} from './utilities';
 
 /**
  * Tests for the `parseCases` util.
@@ -45,13 +45,13 @@ describe('parseCases', function() {
 		test('multiple cases', function() {
 			let result = parseCases('key1 {case1} key2 {case2} key3 {case3}');
 			expect(result.args).toStrictEqual([]);
-			expect(result.cases).toStrictEqual({ key1: 'case1', key2: 'case2', key3: 'case3' });
+			expect(result.cases).toStrictEqual({key1: 'case1', key2: 'case2', key3: 'case3'});
 		});
 
 		test('multiple cases with symbols', function() {
 			let result = parseCases('=key1 {case1} &key2 {case2} key3 {case3}');
 			expect(result.args).toStrictEqual([]);
-			expect(result.cases).toStrictEqual({ '=key1': 'case1', '&key2': 'case2', key3: 'case3' });
+			expect(result.cases).toStrictEqual({'=key1': 'case1', '&key2': 'case2', key3: 'case3'});
 		});
 
 		test('multiple cases with inconsistent whitespace', function() {
@@ -61,13 +61,13 @@ describe('parseCases', function() {
     key2 {case2}
                                 key3 {case3}`);
 			expect(result.args).toStrictEqual([]);
-			expect(result.cases).toStrictEqual({ key1: 'case1', key2: 'case2', key3: 'case3' });
+			expect(result.cases).toStrictEqual({key1: 'case1', key2: 'case2', key3: 'case3'});
 		});
 
 		test('multiple cases with minimal whitespace', function() {
 			let result = parseCases(`key1{case1}key2{case2}key3{case3}`);
 			expect(result.args).toStrictEqual([]);
-			expect(result.cases).toStrictEqual({ key1: 'case1', key2: 'case2', key3: 'case3' });
+			expect(result.cases).toStrictEqual({key1: 'case1', key2: 'case2', key3: 'case3'});
 		});
 
 		test('multiple cases with complex bodies', function() {
@@ -77,7 +77,7 @@ describe('parseCases', function() {
     key2 {=key1 {case1} &key2 {case2} key3 {case3}}
                                 key3 {}`);
 			expect(result.args).toStrictEqual([]);
-			expect(result.cases).toStrictEqual({ key1: '{}{}{}{{{{}}}}', key2: '=key1 {case1} &key2 {case2} key3 {case3}', key3: '' });
+			expect(result.cases).toStrictEqual({key1: '{}{}{}{{{{}}}}', key2: '=key1 {case1} &key2 {case2} key3 {case3}', key3: ''});
 		});
 	});
 

package/types/IcuMessageFormatter.d.ts

@@ -0,0 +1,4 @@
+export { default as MessageFormatter } from "./MessageFormatter.js";
+export { default as pluralTypeHandler } from "./pluralTypeHandler.js";
+export { default as selectTypeHandler } from "./selectTypeHandler.js";
+export { findClosingBracket, parseCases, splitFormattedArgument } from "./utilities.js";

package/types/MessageFormatter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @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
+ */
+export default 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: string, typeHandlers?: Record<string, TypeHandler>);
+    locale: string;
+    typeHandlers: Record<string, TypeHandler>;
+    /**
+     * Formats an ICU message syntax string using `values` for placeholder data
+     * and any currently-registered type handlers.
+     *
+     * @type {(message: string, values?: FormatValues) => string}
+     */
+    format: (message: string, values?: FormatValues) => string;
+    /**
+     * 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: string, values?: FormatValues): any[];
+}
+export type FormatValues = Record<string, any>;
+export type ProcessFunction = (message: string, values?: FormatValues) => any[];
+export type TypeHandler = (value: any, matches: string, locale: string, values: FormatValues, process: ProcessFunction) => any | any[];

package/types/pluralTypeHandler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 {Record<string,any>} values
+ * @param {(message: string, values?: Record<string,any>) => any[]} process
+ * @return {any | any[]}
+ */
+export default function pluralTypeHandler(value: string, matches: string, locale: string, values: Record<string, any>, process: (message: string, values?: Record<string, any>) => any[]): any | any[];

package/types/selectTypeHandler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 {Record<string,any>} values
+ * @param {(message: string, values?: Record<string,any>) => any[]} process
+ * @return {any | any[]}
+ */
+export default function selectTypeHandler(value: string, matches: string, locale: string, values: Record<string, any>, process: (message: string, values?: Record<string, any>) => any[]): any | any[];

package/types/typedefs.d.ts

@@ -0,0 +1,3 @@
+type FormatValues = Record<string, any>;
+type ProcessFunction = (message: string, values?: FormatValues) => any[];
+type TypeHandler = (value: any, matches: string, locale: string, values: FormatValues, process: ProcessFunction) => any | any[];

package/types/utilities.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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}
+ */
+export function parseCases(string: string): ParseCasesResult;
+/**
+ * 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.
+ */
+export function findClosingBracket(string: string, fromIndex: number): number;
+/**
+ * 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.
+ */
+export function splitFormattedArgument(block: string): string[];
+export type ParseCasesResult = {
+    /**
+     *   A list of prepended arguments.
+     */
+    args: string[];
+    /**
+     *   A map of all cases.
+     */
+    cases: Record<string, string>;
+};