hanzio 2.2.0 → 3.1.0

package/src/i18n/i18next.ts

@@ -0,0 +1,89 @@
+// i18next bindings for apps (React Native, React) that keep `{name}`
+// placeholders. Types only from `i18next`: you pass your own instance, already
+// `.use(initReactI18next)` where you need React.
+
+import type { i18n as I18next, InitOptions, ResourceLanguage } from 'i18next'
+import { type AsyncStorageLike, createAsyncStorageItem } from '../storage'
+import type { LocaleRegistry } from '.'
+
+/**
+ * Starts `i18n` in the persisted locale, then the first supported device
+ * locale, then `locales.defaultLocale` (also the fallback). Interpolation uses
+ * `{name}` (not `{{name}}`) and does not escape, matching the catalog check
+ * and `hanzio/i18n`.
+ *
+ * ```ts
+ * export const appI18n = initI18next(i18n.use(initReactI18next), {
+ * 	locales: uiLocales,
+ * 	resources: { en: { translation: en }, da: { translation: da } },
+ * 	deviceLocales: () => getLocales().flatMap((l) => [l.languageTag, l.languageCode]),
+ * 	storageKey: 'app.ui-locale',
+ * 	storage: AsyncStorage
+ * })
+ * ```
+ */
+export function initI18next<L extends string>(
+	i18n: I18next,
+	options: Omit<InitOptions, 'lng' | 'resources'> & {
+		locales: LocaleRegistry<L>
+		resources: Record<L, ResourceLanguage>
+		/** Device languages in preference order, e.g. from `expo-localization`. */
+		deviceLocales?: () => readonly (string | null | undefined)[]
+		/** Remembers the chosen locale (a raw string). Needs `storage`. */
+		storageKey?: string
+		storage?: AsyncStorageLike
+	}
+) {
+	const { locales, deviceLocales, storageKey, storage, ...initOptions } =
+		options
+	const persisted =
+		storageKey && storage
+			? createAsyncStorageItem<string | null>({
+					key: storageKey,
+					fallback: null,
+					storage,
+					serialize: (value) => value ?? '',
+					deserialize: (raw) => raw
+				})
+			: undefined
+
+	const ready = (async () => {
+		const locale = locales.resolve(
+			await persisted?.get(),
+			...(deviceLocales?.() ?? [])
+		)
+		await i18n.init({
+			fallbackLng: locales.defaultLocale,
+			returnNull: false,
+			...initOptions,
+			interpolation: {
+				escapeValue: false,
+				prefix: '{',
+				suffix: '}',
+				...initOptions.interpolation
+			},
+			lng: locale
+		})
+	})()
+
+	async function setLocale(locale: L) {
+		if (i18n.language !== locale) await i18n.changeLanguage(locale)
+		await persisted?.set(locale)
+	}
+
+	return {
+		/** Resolves once `i18n.init` finishes. Await it before the first render. */
+		ready,
+		setLocale,
+		/** The active locale, or the default before `ready`. */
+		locale: () => locales.match(i18n.language) ?? locales.defaultLocale,
+		/**
+		 * Follows a server-side preference (the signed-in user's locale). An
+		 * unsupported or missing tag changes nothing.
+		 */
+		async syncLocale(tag: string | null | undefined) {
+			const locale = locales.match(tag)
+			if (locale) await setLocale(locale)
+		}
+	}
+}

package/src/i18n/index.ts

@@ -123,3 +123,37 @@ export function createTranslator<const T extends Messages>(messages: T) {
 			...(args as [Record<string, PlaceholderValue>?])
 		)
 }
+
+/** Generated key → placeholder-name map: `{ 'greeting': 'name', 'common.save': never }`. */
+export type TranslationParamsMap = Record<string, string>
+
+/**
+ * Strict `t` over a generated key → placeholder-name map (see `hanzio-i18n
+ * generate`). Keys without placeholders take no params; keys with placeholders
+ * require every named value.
+ */
+export type TypedTranslate<Params extends TranslationParamsMap> = <
+	Key extends keyof Params & string
+>(
+	...args: [Params[Key]] extends [never]
+		? [key: Key]
+		: [key: Key, params: Record<Params[Key], PlaceholderValue>]
+) => string
+
+/** Explicit escape hatch for data-driven keys validated outside TypeScript. */
+export type DynamicTranslate = (
+	key: string,
+	params?: Record<string, PlaceholderValue>
+) => string
+
+/**
+ * Narrows a framework's string-wide `t` (vue-i18n, i18next) to the generated
+ * map. Types only; returns `t` unchanged.
+ */
+export function typedTranslate<Params extends TranslationParamsMap>(
+	t: (...args: never[]) => unknown
+): TypedTranslate<Params> {
+	return t as unknown as TypedTranslate<Params>
+}
+
+export * from './locales'

package/src/i18n/locales.ts

@@ -0,0 +1,135 @@
+export type LocaleRegistry<L extends string> = {
+	/** Locale ids in declaration order. They name the catalog files. */
+	readonly locales: readonly L[]
+	readonly defaultLocale: L
+	tag(locale: L): string
+	name(locale: L): string
+	/**
+	 * A supported locale for a BCP-47-ish tag (`'da'`, `'da-DK'`, `'en_US'`), or
+	 * `null`. Matches the id, then the tag, then the language subtag, then the
+	 * aliases.
+	 */
+	match(tag: string | null | undefined): L | null
+	/** The first candidate that matches, else `defaultLocale`. */
+	resolve(...candidates: readonly (string | null | undefined)[]): L
+}
+
+/** The locale union of a registry: `LocaleOf<typeof locales>`. */
+export type LocaleOf<R> = R extends LocaleRegistry<infer L> ? L : never
+
+const normalizeTag = (tag: string) =>
+	tag.trim().replaceAll('_', '-').toLowerCase()
+
+/**
+ * The app's shipped UI locales, shared by every runtime and the catalog check.
+ *
+ * ```ts
+ * export const uiLocales = defineLocales({
+ * 	locales: {
+ * 		en: { tag: 'en-US', name: 'English' },
+ * 		nb: { tag: 'nb-NO', name: 'Norsk bokmål' }
+ * 	},
+ * 	defaultLocale: 'en',
+ * 	aliases: { no: 'nb' }
+ * })
+ * uiLocales.match('no-NO') // 'nb'
+ * ```
+ */
+export function defineLocales<
+	const T extends Record<
+		string,
+		{
+			/** BCP-47 tag for `Intl` and `<html lang>`, e.g. `'da-DK'`. */
+			tag: string
+			/** The language naming itself, for locale pickers: `'Dansk'`. */
+			name: string
+		}
+	>
+>(options: {
+	locales: T
+	defaultLocale: keyof T & string
+	/** Extra tags or language subtags that mean a locale: `{ no: 'nb' }`. */
+	aliases?: Record<string, keyof T & string>
+}): LocaleRegistry<keyof T & string> {
+	type L = keyof T & string
+	const { locales: info, defaultLocale, aliases = {} } = options
+	const locales = Object.keys(info) as L[]
+	const lookup = new Map<string, L>()
+	for (const locale of locales) lookup.set(normalizeTag(locale), locale)
+	for (const locale of locales) {
+		const tag = normalizeTag(info[locale]!.tag)
+		if (!lookup.has(tag)) lookup.set(tag, locale)
+	}
+	const aliasLookup = new Map<string, L>()
+	for (const [alias, locale] of Object.entries(aliases)) {
+		if (!Object.hasOwn(info, locale)) {
+			throw new Error(`Alias "${alias}" points at unknown locale "${locale}"`)
+		}
+		aliasLookup.set(normalizeTag(alias), locale)
+	}
+	if (!Object.hasOwn(info, defaultLocale)) {
+		throw new Error(`Default locale "${defaultLocale}" is not in locales`)
+	}
+
+	const match = (tag: string | null | undefined): L | null => {
+		if (!tag) return null
+		const full = normalizeTag(tag)
+		const language = full.split('-')[0] ?? ''
+		return (
+			lookup.get(full) ??
+			aliasLookup.get(full) ??
+			lookup.get(language) ??
+			aliasLookup.get(language) ??
+			null
+		)
+	}
+
+	return {
+		locales,
+		defaultLocale,
+		tag: (locale) => info[locale]!.tag,
+		name: (locale) => info[locale]!.name,
+		match,
+		resolve: (...candidates) => {
+			for (const candidate of candidates) {
+				const locale = match(candidate)
+				if (locale) return locale
+			}
+			return defaultLocale
+		}
+	}
+}
+
+/**
+ * A locale picker that switches immediately and rolls back when `persist`
+ * (for example saving the user's language on the server) rejects.
+ *
+ * ```ts
+ * const selectLocale = createLocaleSelector({
+ * 	getLocale: () => locale.value,
+ * 	setLocale,
+ * 	persist: (locale) => api.user.updateLocale({ locale }),
+ * 	onError: () => toast.error(t('settings.language.error'))
+ * })
+ * ```
+ */
+export function createLocaleSelector<L extends string>(options: {
+	getLocale: () => L
+	setLocale: (locale: L) => unknown
+	persist?: (locale: L) => Promise<unknown>
+	onError?: (error: unknown) => void
+}) {
+	const { getLocale, setLocale, persist, onError } = options
+	return async (next: L) => {
+		const previous = getLocale()
+		if (previous === next) return
+		await setLocale(next)
+		if (!persist) return
+		try {
+			await persist(next)
+		} catch (error) {
+			await setLocale(previous)
+			onError?.(error)
+		}
+	}
+}

package/src/i18n/vite.ts

@@ -0,0 +1,40 @@
+import type { Plugin } from 'vite'
+
+const INTLIFY_VIRTUAL_PREFIX = 'virtual:intlify-i18n-'
+
+/**
+ * Dev-server plugin: reload the page with fresh catalogs when a
+ * `locales/*.json` file changes.
+ *
+ * `@intlify/unplugin-vue-i18n` serves each catalog as a `virtual:intlify-i18n-N`
+ * module that the module graph cannot tie back to its JSON file, and its own
+ * hot update only invalidates its bundle module, so an edited key kept serving
+ * the old catalog until the dev server restarted. This invalidates every
+ * catalog module and reloads: `createI18n` reads messages once at startup, so a
+ * hot swap would not reach the running instance anyway.
+ */
+export function localeCatalogReloadPlugin(
+	options: {
+		/** Which changed files are catalogs. Default: `.json` in a `locales` folder. */
+		match?: RegExp
+	} = {}
+): Plugin {
+	const match = options.match ?? /[/\\]locales[/\\][^/\\]+\.json$/
+	return {
+		name: 'hanzio-locale-catalog-reload',
+		apply: 'serve',
+		hotUpdate({ file }) {
+			if (this.environment.name !== 'client') return
+			if (!match.test(file)) return
+
+			const graph = this.environment.moduleGraph
+			for (const [id, module] of graph.idToModuleMap) {
+				if (id.startsWith(INTLIFY_VIRTUAL_PREFIX))
+					graph.invalidateModule(module)
+			}
+
+			this.environment.hot.send({ type: 'full-reload' })
+			return []
+		}
+	}
+}

package/src/i18n/vue.ts

@@ -0,0 +1,82 @@
+// vue-i18n bindings: a locale-registry-aware `createI18n` with a typed
+// composer. Needs `vue-i18n` (and so `vue`).
+
+import type { WritableComputedRef } from 'vue'
+import { createI18n, type I18nOptions, useI18n } from 'vue-i18n'
+import { createStorageItem, type SyncStorageLike } from '../storage'
+import {
+	type LocaleRegistry,
+	type Messages,
+	type TranslationParamsMap,
+	typedTranslate
+} from '.'
+
+type BrowserGlobals = {
+	navigator?: { language?: string }
+	document?: { documentElement: { lang: string } }
+}
+
+const browser = globalThis as BrowserGlobals
+
+/**
+ * `createI18n` in composition mode, starting in the persisted locale, then the
+ * browser language, then `locales.defaultLocale` (also the fallback locale).
+ * `setLocale` is the one write path: it switches vue-i18n, persists the choice
+ * and keeps `<html lang>` accurate. `useI18n<Params>()` is vue-i18n's composer
+ * with the locale and `t` narrowed to the registry and a generated key map;
+ * make it the one place the app calls vue-i18n's `useI18n`.
+ */
+export function createVueI18n<L extends string>(
+	options: Omit<I18nOptions, 'legacy' | 'locale' | 'messages'> & {
+		locales: LocaleRegistry<L>
+		/** One catalog per locale; a missing locale is a type error. */
+		messages: Record<L, Messages>
+		/**
+		 * Remembers the chosen locale (a raw string) so screens before sign-in
+		 * come up in the right language. Omit to persist nothing.
+		 */
+		storageKey?: string
+		/** Defaults to `localStorage`, falling back to memory. */
+		storage?: SyncStorageLike
+	}
+) {
+	const { locales, storageKey, storage, ...i18nOptions } = options
+	const persisted = storageKey
+		? createStorageItem<string | null>({
+				key: storageKey,
+				fallback: null,
+				storage,
+				serialize: (value) => value ?? '',
+				deserialize: (raw) => raw
+			})
+		: undefined
+	const initial = locales.resolve(persisted?.get(), browser.navigator?.language)
+	const i18n = createI18n({
+		fallbackLocale: locales.defaultLocale,
+		...i18nOptions,
+		legacy: false,
+		locale: initial
+	})
+
+	const apply = (locale: L) => {
+		;(i18n.global.locale as WritableComputedRef<string>).value = locale
+		if (browser.document) browser.document.documentElement.lang = locale
+	}
+	apply(initial)
+
+	return {
+		i18n,
+		setLocale(locale: L) {
+			apply(locale)
+			persisted?.set(locale)
+		},
+		useI18n<Params extends TranslationParamsMap>() {
+			const composer = useI18n()
+			return {
+				...composer,
+				locale: composer.locale as WritableComputedRef<L>,
+				t: typedTranslate<Params>(composer.t)
+			}
+		}
+	}
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 // Dependency-free helpers only. Modules that need zod, network access or a
 // specific runtime live on subpath exports (hanzio/zod, hanzio/api-wrapper,
 // hanzio/jwt, hanzio/sitemap, hanzio/p-queue, hanzio/cool-console-log,
-// hanzio/secrets).
+// hanzio/secrets, hanzio/redis, hanzio/http, hanzio/testing).
 export * from './typedswitch'
 export * from './array'
 export * from './string'

package/src/iso/README.md

@@ -0,0 +1,44 @@
+# hanzio/iso
+
+ISO codes as literal unions, with English names. Static data with no
+dependencies, so it works where `Intl.DisplayNames` does not (Hermes). For
+names in other languages, use `Intl.DisplayNames`.
+
+```ts
+import {
+	countryCodes,
+	countryFlag,
+	countryNames,
+	currencyNames,
+	languageNames,
+	matchLanguageCode,
+	type CountryCode
+} from 'hanzio/iso'
+
+countryNames.DK // 'Denmark'
+countryFlag('DK') // '🇩🇰'
+currencyNames.EUR // 'Euro'
+languageNames.nb // 'Norwegian Bokmål'
+matchLanguageCode('da_DK') // 'da'
+
+const options = countryCodes.map((code) => ({
+	value: code,
+	label: `${countryFlag(code)} ${countryNames[code]}`
+}))
+```
+
+| Data | Codes | Type and guard |
+| --- | --- | --- |
+| `countryNames` | All 249 ISO 3166-1 alpha-2 codes | `CountryCode`, `isCountryCode` |
+| `currencyNames` | ISO 4217 codes in circulation (no historic codes, funds or metals) | `CurrencyCode`, `isCurrencyCode` |
+| `languageNames` | All 183 ISO 639-1 codes, lowercase | `LanguageCode`, `isLanguageCode` |
+
+`countryCodes`, `currencyCodes` and `languageCodes` list the keys.
+`matchLanguageCode(tag)` returns the language subtag of a BCP-47-ish tag when
+it is an ISO 639-1 code; map languages your app treats as one (`'nn'` to
+`'nb'`, say) yourself.
+
+`languageFromE164PhoneNumber(number)` guesses a conversation language from a
+phone number's calling code (`'+4520304050'` → `'da'`). It covers the Nordics,
+the UK, Ireland, North America and the larger Western European countries, and
+returns `null` for anything else.