@chipmobilesdk/rn-i18n 0.1.2 → 0.2.0

package/src/config/validateConfig.ts

@@ -1,174 +1,161 @@
-import type { I18nConfig, LocaleConfig } from './types';
-import { I18nConfigError } from './types';
-
-/**
- * Validates an I18nConfig before any localized content is served (FR-003,
- * FR-046). Collects every violation and throws a single I18nConfigError so
- * apps see the complete picture instead of fixing issues one at a time.
- */
-export function validateConfig(
-	config: I18nConfig,
-	knownUnits: ReadonlySet<string>,
-): void {
-	const issues: string[] = [];
-	const locales = Array.isArray(config.locales) ? config.locales : [];
-
-	if (locales.length === 0) {
-		issues.push('At least one supported locale must be declared.');
-	}
-
-	const codes = new Set<string>();
-	for (const locale of locales) {
-		if (codes.has(locale.code)) {
-			issues.push(`Duplicate locale code "${locale.code}".`);
-		}
-		codes.add(locale.code);
-	}
-
-	for (const locale of locales) {
-		validateLocale(locale, codes, knownUnits, issues);
-	}
-
-	detectFallbackCycles(locales, codes, issues);
-
-	if (locales.length > 0 && !codes.has(config.primaryLocale)) {
-		issues.push(
-			`Primary locale "${config.primaryLocale}" is not a supported locale.`,
-		);
-	}
-
-	for (const code of codes) {
-		const resource = config.resources?.[code];
-		if (resource === undefined || resource === null) {
-			issues.push(`Locale "${code}" has no translation resource.`);
-		}
-	}
-
-	if (config.persistLocale !== false && !config.storage) {
-		issues.push(
-			'Locale persistence is enabled but no storage adapter was injected. ' +
-				'Provide `storage` or set `persistLocale: false`.',
-		);
-	}
-
-	const runtimeKeys = new Set<string>();
-	for (const entry of config.runtimeEntries ?? []) {
-		if (!entry.key) {
-			issues.push('Runtime-only entries must declare a non-empty key.');
-			continue;
-		}
-		if (runtimeKeys.has(entry.key)) {
-			issues.push(`Duplicate runtime-only entry "${entry.key}".`);
-		}
-		runtimeKeys.add(entry.key);
-		if (typeof entry.defaultText !== 'string') {
-			issues.push(
-				`Runtime-only entry "${entry.key}" must declare default text.`,
-			);
-		}
-	}
-
-	if (issues.length > 0) {
-		throw new I18nConfigError(issues);
-	}
-}
-
-function validateLocale(
-	locale: LocaleConfig,
-	codes: ReadonlySet<string>,
-	knownUnits: ReadonlySet<string>,
-	issues: string[],
-): void {
-	const code = locale.code;
-	if (!code) {
-		issues.push('Every locale must declare a non-empty code.');
-		return;
-	}
-	if (!locale.displayName) {
-		issues.push(`Locale "${code}" must declare a display name.`);
-	}
-	if (locale.direction !== 'ltr' && locale.direction !== 'rtl') {
-		issues.push(`Locale "${code}" must declare direction "ltr" or "rtl".`);
-	}
-	if (!locale.defaultCurrency) {
-		issues.push(`Locale "${code}" must declare a default currency.`);
-	}
-	if (!knownUnits.has(locale.defaultUnit)) {
-		issues.push(
-			`Locale "${code}" declares unknown default unit "${locale.defaultUnit}".`,
-		);
-	}
-	if (typeof locale.defaultDateFormat !== 'object' || !locale.defaultDateFormat) {
-		issues.push(`Locale "${code}" must declare a default date format.`);
-	}
-	if (
-		typeof locale.defaultNumberFormat !== 'object' ||
-		!locale.defaultNumberFormat
-	) {
-		issues.push(`Locale "${code}" must declare a default number format.`);
-	}
-	if (!Array.isArray(locale.fallbackChain)) {
-		issues.push(`Locale "${code}" must declare a fallback chain array.`);
-		return;
-	}
-	const seen = new Set<string>();
-	for (const entry of locale.fallbackChain) {
-		if (entry === code) {
-			issues.push(`Locale "${code}" must not include itself in its fallback chain.`);
-		}
-		if (seen.has(entry)) {
-			issues.push(
-				`Locale "${code}" lists duplicate fallback-chain entry "${entry}".`,
-			);
-		}
-		seen.add(entry);
-		if (!codes.has(entry)) {
-			issues.push(
-				`Locale "${code}" references unsupported fallback locale "${entry}".`,
-			);
-		}
-	}
-}
-
-function detectFallbackCycles(
-	locales: readonly LocaleConfig[],
-	codes: ReadonlySet<string>,
-	issues: string[],
-): void {
-	const chains = new Map(
-		locales.map(locale => [
-			locale.code,
-			(locale.fallbackChain ?? []).filter(entry => codes.has(entry)),
-		]),
-	);
-	const states = new Map<string, 'visiting' | 'done'>();
-
-	const visit = (code: string, path: string[]): boolean => {
-		const state = states.get(code);
-		if (state === 'done') {
-			return false;
-		}
-		if (state === 'visiting') {
-			issues.push(
-				`Fallback cycle detected: ${[...path, code].join(' -> ')}.`,
-			);
-			return true;
-		}
-		states.set(code, 'visiting');
-		for (const next of chains.get(code) ?? []) {
-			if (visit(next, [...path, code])) {
-				states.set(code, 'done');
-				return true;
-			}
-		}
-		states.set(code, 'done');
-		return false;
-	};
-
-	for (const locale of locales) {
-		if (visit(locale.code, [])) {
-			// Report the first cycle only; one clear cycle message is actionable.
-			return;
-		}
-	}
-}
+import type { I18nConfig, LocaleConfig } from './types';
+import { I18nConfigError } from './types';
+
+/**
+ * Validates an I18nConfig before any localized content is served (FR-003,
+ * FR-046). Collects every violation and throws a single I18nConfigError so
+ * apps see the complete picture instead of fixing issues one at a time.
+ */
+export function validateConfig(config: I18nConfig, knownUnits: ReadonlySet<string>): void {
+	const issues: string[] = [];
+	const locales = Array.isArray(config.locales) ? config.locales : [];
+
+	if (locales.length === 0) {
+		issues.push('At least one supported locale must be declared.');
+	}
+
+	const codes = new Set<string>();
+	for (const locale of locales) {
+		if (codes.has(locale.code)) {
+			issues.push(`Duplicate locale code "${locale.code}".`);
+		}
+		codes.add(locale.code);
+	}
+
+	for (const locale of locales) {
+		validateLocale(locale, codes, knownUnits, issues);
+	}
+
+	detectFallbackCycles(locales, codes, issues);
+
+	if (locales.length > 0 && !codes.has(config.primaryLocale)) {
+		issues.push(`Primary locale "${config.primaryLocale}" is not a supported locale.`);
+	}
+
+	for (const code of codes) {
+		const resource = config.resources?.[code];
+		if (resource === undefined || resource === null) {
+			issues.push(`Locale "${code}" has no translation resource.`);
+		}
+	}
+
+	if (config.persistLocale !== false && !config.storage) {
+		issues.push(
+			'Locale persistence is enabled but no storage adapter was injected. ' +
+				'Provide `storage` or set `persistLocale: false`.',
+		);
+	}
+
+	const runtimeKeys = new Set<string>();
+	for (const entry of config.runtimeEntries ?? []) {
+		if (!entry.key) {
+			issues.push('Runtime-only entries must declare a non-empty key.');
+			continue;
+		}
+		if (runtimeKeys.has(entry.key)) {
+			issues.push(`Duplicate runtime-only entry "${entry.key}".`);
+		}
+		runtimeKeys.add(entry.key);
+		if (typeof entry.defaultText !== 'string') {
+			issues.push(`Runtime-only entry "${entry.key}" must declare default text.`);
+		}
+	}
+
+	if (issues.length > 0) {
+		throw new I18nConfigError(issues);
+	}
+}
+
+function validateLocale(
+	locale: LocaleConfig,
+	codes: ReadonlySet<string>,
+	knownUnits: ReadonlySet<string>,
+	issues: string[],
+): void {
+	const code = locale.code;
+	if (!code) {
+		issues.push('Every locale must declare a non-empty code.');
+		return;
+	}
+	if (!locale.displayName) {
+		issues.push(`Locale "${code}" must declare a display name.`);
+	}
+	if (locale.direction !== 'ltr' && locale.direction !== 'rtl') {
+		issues.push(`Locale "${code}" must declare direction "ltr" or "rtl".`);
+	}
+	if (!locale.defaultCurrency) {
+		issues.push(`Locale "${code}" must declare a default currency.`);
+	} else if (!/^[A-Z]{3}$/.test(locale.defaultCurrency)) {
+		// An ISO 4217 code; anything else would fail every currency format (I18N-08).
+		issues.push(
+			`Locale "${code}" default currency "${locale.defaultCurrency}" is not a three-letter ISO 4217 code.`,
+		);
+	}
+	if (!knownUnits.has(locale.defaultUnit)) {
+		issues.push(`Locale "${code}" declares unknown default unit "${locale.defaultUnit}".`);
+	}
+	if (typeof locale.defaultDateFormat !== 'object' || !locale.defaultDateFormat) {
+		issues.push(`Locale "${code}" must declare a default date format.`);
+	}
+	if (typeof locale.defaultNumberFormat !== 'object' || !locale.defaultNumberFormat) {
+		issues.push(`Locale "${code}" must declare a default number format.`);
+	}
+	if (!Array.isArray(locale.fallbackChain)) {
+		issues.push(`Locale "${code}" must declare a fallback chain array.`);
+		return;
+	}
+	const seen = new Set<string>();
+	for (const entry of locale.fallbackChain) {
+		if (entry === code) {
+			issues.push(`Locale "${code}" must not include itself in its fallback chain.`);
+		}
+		if (seen.has(entry)) {
+			issues.push(`Locale "${code}" lists duplicate fallback-chain entry "${entry}".`);
+		}
+		seen.add(entry);
+		if (!codes.has(entry)) {
+			issues.push(`Locale "${code}" references unsupported fallback locale "${entry}".`);
+		}
+	}
+}
+
+function detectFallbackCycles(
+	locales: readonly LocaleConfig[],
+	codes: ReadonlySet<string>,
+	issues: string[],
+): void {
+	const chains = new Map(
+		locales.map(locale => [
+			locale.code,
+			(locale.fallbackChain ?? []).filter(entry => codes.has(entry)),
+		]),
+	);
+	const states = new Map<string, 'visiting' | 'done'>();
+
+	const visit = (code: string, path: string[]): boolean => {
+		const state = states.get(code);
+		if (state === 'done') {
+			return false;
+		}
+		if (state === 'visiting') {
+			issues.push(`Fallback cycle detected: ${[...path, code].join(' -> ')}.`);
+			return true;
+		}
+		states.set(code, 'visiting');
+		for (const next of chains.get(code) ?? []) {
+			if (visit(next, [...path, code])) {
+				states.set(code, 'done');
+				return true;
+			}
+		}
+		states.set(code, 'done');
+		return false;
+	};
+
+	for (const locale of locales) {
+		if (visit(locale.code, [])) {
+			// Report the first cycle only; one clear cycle message is actionable.
+			return;
+		}
+	}
+}

package/src/format/currency.ts

@@ -1,27 +1,34 @@
-import type { InvalidFormatPolicy } from '../config/types';
-import { applyInvalidFormatPolicy } from './invalid';
-
-/**
- * Locale-aware currency formatting. The locale's configured default currency
- * applies unless the caller passes an explicit currency override (FR-021).
- */
-export function formatCurrencyValue(
-	value: number,
-	localeCode: string,
-	defaultCurrency: string,
-	currencyOverride: string | undefined,
-	options: Intl.NumberFormatOptions | undefined,
-	invalidFormat: InvalidFormatPolicy,
-): string {
-	if (typeof value !== 'number' || !Number.isFinite(value)) {
-		return applyInvalidFormatPolicy(
-			invalidFormat,
-			`Cannot format invalid currency value "${String(value)}" for locale "${localeCode}".`,
-		);
-	}
-	return new Intl.NumberFormat(localeCode, {
-		...options,
-		style: 'currency',
-		currency: currencyOverride ?? defaultCurrency,
-	}).format(value);
-}
+import { getNumberFormat } from '@chipmobilesdk/rn-core';
+import type { InvalidFormatPolicy } from '../config/types';
+import { applyInvalidFormatPolicy } from './invalid';
+
+/**
+ * Locale-aware currency formatting. The locale's configured default currency
+ * applies unless the caller passes an explicit currency override (FR-021).
+ */
+export function formatCurrencyValue(
+	value: number,
+	localeCode: string,
+	defaultCurrency: string,
+	currencyOverride: string | undefined,
+	options: Intl.NumberFormatOptions | undefined,
+	invalidFormat: InvalidFormatPolicy,
+): string {
+	if (typeof value !== 'number' || !Number.isFinite(value)) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			`Cannot format invalid currency value "${String(value)}" for locale "${localeCode}".`,
+		);
+	}
+	const currency = currencyOverride ?? defaultCurrency;
+	// rn-core's cached formatter (I18N-03). An unknown currency code (`usd1`) used
+	// to throw out of render; it is a format problem now (I18N-08).
+	try {
+		return getNumberFormat(localeCode, { ...options, style: 'currency', currency }).format(value);
+	} catch (error) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			`Cannot format currency "${currency}" for locale "${localeCode}": ${String(error)}`,
+		);
+	}
+}

package/src/format/date.ts

@@ -1,26 +1,32 @@
-import type { InvalidFormatPolicy } from '../config/types';
-import { applyInvalidFormatPolicy } from './invalid';
-
-/**
- * Locale-aware date formatting through the Hermes built-in
- * Intl.DateTimeFormat. The locale's configured default date format applies
- * unless the caller passes explicit overrides (FR-020). Options are limited
- * to component options supported by Hermes on both platforms.
- */
-export function formatDateValue(
-	value: Date | number,
-	localeCode: string,
-	defaults: Intl.DateTimeFormatOptions,
-	override: Intl.DateTimeFormatOptions | undefined,
-	invalidFormat: InvalidFormatPolicy,
-): string {
-	const date = value instanceof Date ? value : new Date(value);
-	if (Number.isNaN(date.getTime())) {
-		return applyInvalidFormatPolicy(
-			invalidFormat,
-			`Cannot format invalid date value "${String(value)}" for locale "${localeCode}".`,
-		);
-	}
-	const options = override ?? defaults;
-	return new Intl.DateTimeFormat(localeCode, options).format(date);
-}
+import { getDateTimeFormat } from '@chipmobilesdk/rn-core';
+import type { InvalidFormatPolicy } from '../config/types';
+import { applyInvalidFormatPolicy } from './invalid';
+
+/**
+ * Locale-aware date formatting through the Hermes built-in
+ * Intl.DateTimeFormat. The locale's configured default date format applies
+ * unless the caller passes explicit overrides (FR-020). Options are limited
+ * to component options supported by Hermes on both platforms.
+ */
+export function formatDateValue(
+	value: Date | number,
+	localeCode: string,
+	defaults: Intl.DateTimeFormatOptions,
+	override: Intl.DateTimeFormatOptions | undefined,
+	invalidFormat: InvalidFormatPolicy,
+): string {
+	const date = value instanceof Date ? value : new Date(value);
+	if (Number.isNaN(date.getTime())) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			`Cannot format invalid date value "${String(value)}" for locale "${localeCode}".`,
+		);
+	}
+	const options = override ?? defaults;
+	// rn-core's cached formatter (I18N-03); a bad option is a format problem (I18N-08).
+	try {
+		return getDateTimeFormat(localeCode, options).format(date);
+	} catch (error) {
+		return applyInvalidFormatPolicy(invalidFormat, `Cannot format a date: ${String(error)}`);
+	}
+}

package/src/format/invalid.ts

@@ -1,16 +1,22 @@
-import type { InvalidFormatPolicy } from '../config/types';
-
-/**
- * Applies the configured invalid-format behavior: return the placeholder, or
- * throw a clear formatting error in `error` mode (FR-037, FR-045).
- */
-export function applyInvalidFormatPolicy(
-	policy: InvalidFormatPolicy,
-	message: string,
-): string {
-	console.warn(`[rn-i18n] ${message}`);
-	if (policy.mode === 'error') {
-		throw new RangeError(`[rn-i18n] ${message}`);
-	}
-	return policy.text;
-}
+import { defaultReporter, type I18nDiagnosticHandler } from '../config/diagnostics';
+import type { InvalidFormatPolicy } from '../config/types';
+
+/** The policy as an i18n instance resolves it: with the instance's reporter. */
+export type ResolvedInvalidFormatPolicy = InvalidFormatPolicy & {
+	readonly report?: I18nDiagnosticHandler | undefined;
+};
+
+/**
+ * Applies the configured invalid-format behavior: return the placeholder, or
+ * throw a clear formatting error in `error` mode (FR-037, FR-045).
+ */
+export function applyInvalidFormatPolicy(
+	policy: ResolvedInvalidFormatPolicy,
+	message: string,
+): string {
+	(policy.report ?? defaultReporter)({ code: 'invalid_format', message });
+	if (policy.mode === 'error') {
+		throw new RangeError(`[rn-i18n] ${message}`);
+	}
+	return policy.text;
+}

package/src/format/number.ts

@@ -1,25 +1,30 @@
-import type { InvalidFormatPolicy } from '../config/types';
-import { applyInvalidFormatPolicy } from './invalid';
-
-/**
- * Locale-aware number formatting through the Hermes built-in
- * Intl.NumberFormat. The locale default options apply unless the caller
- * passes explicit overrides (FR-019).
- */
-export function formatNumberValue(
-	value: number,
-	localeCode: string,
-	defaults: Intl.NumberFormatOptions,
-	override: Intl.NumberFormatOptions | undefined,
-	invalidFormat: InvalidFormatPolicy,
-): string {
-	if (typeof value !== 'number' || !Number.isFinite(value)) {
-		return applyInvalidFormatPolicy(
-			invalidFormat,
-			`Cannot format invalid number value "${String(value)}" for locale "${localeCode}".`,
-		);
-	}
-	return new Intl.NumberFormat(localeCode, { ...defaults, ...override }).format(
-		value,
-	);
-}
+import { getNumberFormat } from '@chipmobilesdk/rn-core';
+import type { InvalidFormatPolicy } from '../config/types';
+import { applyInvalidFormatPolicy } from './invalid';
+
+/**
+ * Locale-aware number formatting through the Hermes built-in
+ * Intl.NumberFormat. The locale default options apply unless the caller
+ * passes explicit overrides (FR-019).
+ */
+export function formatNumberValue(
+	value: number,
+	localeCode: string,
+	defaults: Intl.NumberFormatOptions,
+	override: Intl.NumberFormatOptions | undefined,
+	invalidFormat: InvalidFormatPolicy,
+): string {
+	if (typeof value !== 'number' || !Number.isFinite(value)) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			`Cannot format invalid number value "${String(value)}" for locale "${localeCode}".`,
+		);
+	}
+	// rn-core's cached formatter (I18N-03); a bad option is a format problem, not a
+	// crash in render (I18N-08).
+	try {
+		return getNumberFormat(localeCode, { ...defaults, ...override }).format(value);
+	} catch (error) {
+		return applyInvalidFormatPolicy(invalidFormat, `Cannot format a number: ${String(error)}`);
+	}
+}