@ultraq/icu-message-formatter 0.13.0 → 0.14.0

package/source/IcuMessageFormatter.js

@@ -1,20 +0,0 @@
-/* 
- * 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.
- */
-
-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/source/MessageFormatter.js

@@ -1,138 +0,0 @@
-/* 
- * 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.
- */
-
-import {findClosingBracket, splitFormattedArgument} from './utilities.js';
-
-import {flatten} from '@ultraq/array-utils';
-import {memoize} from '@ultraq/function-utils';
-
-/**
- * @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, 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 = memoize((message, values = {}) => {
-
-		return flatten(this.process(message, values)).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];
-					if (body === null || body === undefined) {
-						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];
-	}
-}

package/source/MessageFormatter.test.js

@@ -1,153 +0,0 @@
-/* 
- * 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.
- */
-
-/* eslint-env jest */
-import MessageFormatter from './MessageFormatter';
-import pluralTypeHandler from './pluralTypeHandler';
-import selectTypeHandler from './selectTypeHandler';
-
-/**
- * Tests for the ICU message formatter.
- */
-describe('MessageFormatter', function() {
-
-	describe('#format', function() {
-
-		test('Basic string replacement', function() {
-			let formatter = new MessageFormatter('en-NZ');
-			let message = formatter.format('Hey {name}, that\'s gonna cost you!', {
-				name: 'Emanuel'
-			});
-			expect(message).toBe('Hey Emanuel, that\'s gonna cost you!');
-		});
-
-		test('Options finding when containing nested types', function() {
-			let locale = 'en-NZ';
-			let selectSpy = jest.fn(selectTypeHandler);
-			let formatter = new MessageFormatter(locale, {
-				select: selectSpy
-			});
-
-			let values = {
-				at: 'asap'
-			};
-			let message = formatter.format(
-				'Hit me up {at, select, date {at {specificDate, date}} asap {as soon as possible}}',
-				values
-			);
-
-			expect(selectSpy).toHaveBeenCalledWith(
-				values.at,
-				'date {at {specificDate, date}} asap {as soon as possible}',
-				locale,
-				values,
-				expect.any(Function)
-			);
-			expect(message).toBe('Hit me up as soon as possible');
-		});
-
-		test('Replaces multiple instances of the same parameter', function() {
-			let formatter = new MessageFormatter('en-NZ');
-			let message = formatter.format('Hello {name} {name}!', {
-				name: 'Emanuel'
-			});
-			expect(message).toBe('Hello Emanuel Emanuel!');
-		});
-
-		test('Returns empty strings for null/undefined message values', function() {
-			let formatter = new MessageFormatter('en-NZ');
-			[null, undefined].forEach(value => {
-				let message = formatter.format(value);
-				expect(message).toBe('');
-			});
-		});
-
-		test('Lets falsey values in parameters through', function() {
-			let formatter = new MessageFormatter('en-NZ');
-			[0, false].forEach(value => {
-				let message = formatter.format(`{param}`, {
-					param: value
-				});
-				expect(message).toBe(value.toString());
-			});
-		});
-
-		test('Plural inside select', function() {
-			let formatter = new MessageFormatter('en-NZ', {
-				plural: pluralTypeHandler,
-				select: selectTypeHandler
-			});
-			let message = `{gender_of_host, select,
-				female {{num_guests, plural,
-					=0    {{host} does not give a party.}
-					=1    {{host} invites {guest} to her party.}
-					=2    {{host} invites {guest} and one other person to her party.}
-					other {{host} invites {guest} and # other people to her party.}
-				}}
-				male {{num_guests, plural,
-					=0    {{host} does not give a party.}
-					=1    {{host} invites {guest} to his party.}
-					=2    {{host} invites {guest} and one other person to his party.}
-					other {{host} invites {guest} and # other people to his party.}
-				}}
-				other {{num_guests, plural,
-					=0    {{host} does not give a party.}
-					=1    {{host} invites {guest} to their party.}
-					=2    {{host} invites {guest} and one other person to their party.}
-					other {{host} invites {guest} and # other people to their party.}
-				}}
-			}`;
-
-			expect(formatter.format(message, {'gender_of_host': 'male', host: 'John', 'num_guests': 115, guest: 'you'})).toBe('John invites you and 115 other people to his party.');
-			expect(formatter.format(message, {'gender_of_host': 'female', host: 'John', 'num_guests': 1, guest: 'you'})).toBe('John invites you to her party.');
-			expect(formatter.format(message, {'gender_of_host': 'other', host: 'John', 'num_guests': 2, guest: 'you'})).toBe('John invites you and one other person to their party.');
-			expect(formatter.format(message, {'gender_of_host': 'other', host: 'John', 'num_guests': 12345, guest: 'you'})).toBe('John invites you and 12345 other people to their party.');
-		});
-
-		test('Select inside plural', function() {
-			let formatter = new MessageFormatter('en-NZ', {
-				plural: pluralTypeHandler,
-				select: selectTypeHandler
-			});
-
-			let message = `{num_guests, plural,
-				=0    {{host} does not give a party.}
-				=1    {{gender_of_host, select,
-					female {{host} invites {guest} to her party.}
-					male   {{host} invites {guest} to his party.}
-					other  {{host} invites {guest} to their party.}
-				}}
-				=2    {{gender_of_host, select,
-					female {{host} invites {guest} and one other person to her party.}
-					male   {{host} invites {guest} and one other person to his party.}
-					other  {{host} invites {guest} and one other person to their party.}
-				}}
-				other {{gender_of_host, select,
-					female {{host} invites {guest} and # other people to her party.}
-					male   {{host} invites {guest} and # other people to his party.}
-					other  {{host} invites {guest} and # other people to their party.}
-				}}
-			}`;
-
-			expect(formatter.format(message, {'gender_of_host': 'female', host: 'John', 'num_guests': 1, guest: 'you'})).toBe('John invites you to her party.');
-			expect(formatter.format(message, {'gender_of_host': 'other', host: 'John', 'num_guests': 2, guest: 'you'})).toBe('John invites you and one other person to their party.');
-
-			// number sign only works in the immediately corresponding layer! Can't use a nested one.
-			expect(formatter.format(message, {'gender_of_host': 'male', host: 'John', 'num_guests': 115, guest: 'you'})).toBe('John invites you and # other people to his party.');
-			expect(formatter.format(message, {'gender_of_host': 'other', host: 'John', 'num_guests': 12345, guest: 'you'})).toBe('John invites you and # other people to their party.');
-		});
-	});
-});

package/source/pluralTypeHandler.js

@@ -1,122 +0,0 @@
-/* 
- * 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.
- */
-
-import {parseCases} from './utilities.js';
-
-let pluralFormatter;
-
-let keyCounter = 0;
-
-// All the special keywords that can be used in `plural` blocks for the various branches
-const ONE   = 'one';
-const OTHER = '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
-	};
-}
-
-/**
- * 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, 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) {
-		// 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) {
-			keywordPossibilities.push(pluralKeyword);
-		}
-	}
-	if (intValue === 1) {
-		keywordPossibilities.push(ONE);
-	}
-	keywordPossibilities.push(`=${intValue}`, OTHER);
-
-	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;
-}

package/source/pluralTypeHandler.test.js

@@ -1,188 +0,0 @@
-/* 
- * 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.
- */
-
-/* eslint-env jest */
-import MessageFormatter from './MessageFormatter.js';
-import pluralTypeHandler from './pluralTypeHandler.js';
-
-/**
- * Tests for the `plural` handler.
- */
-describe('pluralTypeHandler', function() {
-
-	describe('Branch selection', function() {
-		const formatter = new MessageFormatter('en-NZ', {
-			plural: pluralTypeHandler
-		});
-		const message = `Stop thinking about {value, plural,
-			one {that donut}
-			=2 {that delicious duo of donuts}
-			=3 {that triumphant trio of donuts}
-			other {those donuts}
-		}`;
-
-		test('=n', function() {
-			let result = formatter.format(message, {value: 2});
-			expect(result).toBe('Stop thinking about that delicious duo of donuts');
-
-			result = formatter.format(message, {value: 3});
-			expect(result).toBe('Stop thinking about that triumphant trio of donuts');
-		});
-
-		test('other', function() {
-			let result = formatter.format(message, {value: 1000});
-			expect(result).toBe('Stop thinking about those donuts');
-		});
-
-		test('other fallback', function() {
-			let result = formatter.format(message);
-			expect(result).toBe('Stop thinking about those donuts');
-		});
-	});
-
-	describe('Fallback of emitting the value', function() {
-		const formatter = new MessageFormatter('en-NZ', {
-			plural: pluralTypeHandler
-		});
-
-		test('No matching branch', function() {
-			let message = 'I have {cows, plural, one {a cow} two {some cows}}';
-			let result = formatter.format(message, {cows: 7});
-			expect(result).toBe('I have 7');
-		});
-
-		test('Keyword without branch', function() {
-			let message = 'I have {cows, plural, other}';
-			let result = formatter.format(message, {cows: 7});
-			expect(result).toBe('I have 7');
-		});
-	});
-
-	describe('Special # token', function() {
-		let message = '{days, plural, one {# day} other {# days}}...';
-
-		test('Emit value without a registered number handler', function() {
-			let formatter = new MessageFormatter('en-NZ', {
-				plural: pluralTypeHandler
-			});
-			let result = formatter.format(message, {days: 7});
-			expect(result).toBe('7 days...');
-		});
-
-		test('Use the registered number handler', function() {
-			let numberTypeHandler = jest.fn((value, options, values, locale) => new Intl.NumberFormat(locale).format(value));
-			let formatter = new MessageFormatter('en-NZ', {
-				number: numberTypeHandler,
-				plural: pluralTypeHandler
-			});
-			let result = formatter.format(message, {days: 1000});
-			expect(result).toBe('1,000 days...');
-		});
-
-		test('Number signs for nested plurals doesnt apply top level count to inner sign', function() {
-			let formatter = new MessageFormatter('en-NZ', {
-				plural: pluralTypeHandler
-			});
-			let result = formatter.format(`{id, plural,
-				other {ID: # {count, plural,
-						other {Count: #}
-					}}
-			}`, {id: 5, count: 11});
-			expect(result).toBe('ID: 5 Count: 11');
-		});
-	});
-
-	describe('Supports offset argument', function() {
-		const formatter = new MessageFormatter('en-NZ', {
-			plural: pluralTypeHandler
-		});
-
-		test('If unspecified, offset is null', function() {
-			let message = '{days, plural, one {one day} =2 {two days} other {# days}}...';
-
-			let result = formatter.format(message, {days: 5});
-			expect(result).toBe('5 days...');
-		});
-
-		test('Specified offset will be applied via =X branch', function() {
-			let message = '{days, plural, offset:3 one {one day} =2 {two days} other {# days}}...';
-
-			let result = formatter.format(message, {days: 5});
-			expect(result).toBe('two days...');
-		});
-
-		test('Specified offset will be applied via number sign', function() {
-			let message = '{days, plural, offset:1 one {one day} =2 {two days} other {# days}}...';
-
-			let result = formatter.format(message, {days: 5});
-			expect(result).toBe('4 days...');
-		});
-
-		test('Specified offset will be applied via `one` keyword', function() {
-			let message = '{days, plural, offset:4 one {one day} =2 {two days} other {# days}}...';
-
-			let result = formatter.format(message, {days: 5});
-			expect(result).toBe('one day...');
-		});
-	});
-
-
-	describe('Intl PluralRules', function() {
-		const formatterAr = new MessageFormatter('ar', {
-			plural: pluralTypeHandler
-		});
-
-		const messageAr = `{value, plural,
-			zero {ZERO}
-			one {ONE}
-			two {TWO}
-			few {FEW}
-			other {OTHER}
-		}`;
-
-		test('zero', function() {
-			let result = formatterAr.format(messageAr, {value: 0});
-			expect(result).toBe('ZERO');
-		});
-
-		test('one', function() {
-			let result = formatterAr.format(messageAr, {value: 1});
-			expect(result).toBe('ONE');
-		});
-
-		test('two', function() {
-			let result = formatterAr.format(messageAr, {value: 2});
-			expect(result).toBe('TWO');
-		});
-
-		test('few', function() {
-			let result = formatterAr.format(messageAr, {value: 3});
-			expect(result).toBe('FEW');
-		});
-
-		test('other', function() {
-			let result = formatterAr.format(messageAr, {value: 17});
-			expect(result).toBe('OTHER');
-		});
-	});
-
-	describe('Empty matches', function() {
-		test('No matching branch', function() {
-			let result = pluralTypeHandler('some value');
-			expect(result).toBe('some value');
-		});
-	});
-});

package/source/selectTypeHandler.js

@@ -1,46 +0,0 @@
-/* 
- * 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.
- */
-
-import {parseCases} from './utilities.js';
-
-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 {Record<string,any>} values
- * @param {(message: string, values?: Record<string,any>) => any[]} process
- * @return {any | any[]}
- */
-export default 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;
-}