@bquery/bquery 1.6.0 → 1.7.0

package/src/i18n/i18n.ts

@@ -0,0 +1,200 @@
+/**
+ * Core i18n factory function.
+ * @module bquery/i18n
+ */
+
+import { computed, signal } from '../reactive/index';
+import { isPrototypePollutionKey } from '../core/utils/object';
+import { formatDate, formatNumber } from './formatting';
+import { deepMerge, translate } from './translate';
+import type {
+  DateFormatOptions,
+  I18nConfig,
+  I18nInstance,
+  LocaleLoader,
+  LocaleMessages,
+  Messages,
+  NumberFormatOptions,
+  TranslateParams,
+} from './types';
+
+/**
+ * Creates a reactive internationalization instance.
+ *
+ * The returned object provides:
+ * - `$locale` — a reactive signal for the current locale
+ * - `t()` — translation with interpolation and pluralization
+ * - `tc()` — reactive translation that auto-updates on locale change
+ * - `loadLocale()` — register lazy-loaded locale files
+ * - `n()` — locale-aware number formatting
+ * - `d()` — locale-aware date formatting
+ *
+ * @param config - Initial configuration
+ * @returns An i18n instance
+ *
+ * @example
+ * ```ts
+ * import { createI18n } from '@bquery/bquery/i18n';
+ *
+ * const i18n = createI18n({
+ *   locale: 'en',
+ *   fallbackLocale: 'en',
+ *   messages: {
+ *     en: {
+ *       greeting: 'Hello, {name}!',
+ *       items: '{count} item | {count} items',
+ *     },
+ *     de: {
+ *       greeting: 'Hallo, {name}!',
+ *       items: '{count} Gegenstand | {count} Gegenstände',
+ *     },
+ *   },
+ * });
+ *
+ * i18n.t('greeting', { name: 'Ada' }); // 'Hello, Ada!'
+ * i18n.t('items', { count: 3 });       // '3 items'
+ *
+ * // Switch locale reactively
+ * i18n.$locale.value = 'de';
+ * i18n.t('greeting', { name: 'Ada' }); // 'Hallo, Ada!'
+ * ```
+ */
+export const createI18n = (config: I18nConfig): I18nInstance => {
+  const { locale: initialLocale, messages: initialMessages, fallbackLocale } = config;
+
+  const sanitizeLocaleMessages = (localeMessages: LocaleMessages): LocaleMessages =>
+    deepMerge(Object.create(null) as LocaleMessages, localeMessages);
+
+  // Deep-clone initial messages to prevent external mutation
+  const messages = Object.create(null) as Messages;
+  for (const [loc, msgs] of Object.entries(initialMessages)) {
+    if (isPrototypePollutionKey(loc)) {
+      continue;
+    }
+    messages[loc] = sanitizeLocaleMessages(msgs);
+  }
+
+  // Reactive locale signal
+  const $locale = signal(initialLocale);
+
+  // Lazy-loader registry
+  const loaders = new Map<string, LocaleLoader>();
+
+  // Track which loaders have been invoked to avoid duplicate loads
+  const loadedLocales = new Set<string>(Object.keys(messages));
+
+  /**
+   * Get messages for a locale, or undefined if not loaded.
+   */
+  const getMessages = (loc: string): LocaleMessages | undefined => {
+    if (isPrototypePollutionKey(loc)) {
+      return undefined;
+    }
+    return messages[loc];
+  };
+
+  /**
+   * Register a lazy-loader for a locale.
+   */
+  const loadLocale = (loc: string, loader: LocaleLoader): void => {
+    if (isPrototypePollutionKey(loc)) {
+      return;
+    }
+    loaders.set(loc, loader);
+  };
+
+  /**
+   * Ensure a locale's messages are loaded.
+   */
+  const ensureLocale = async (loc: string): Promise<void> => {
+    if (isPrototypePollutionKey(loc)) return;
+    if (loadedLocales.has(loc)) return;
+
+    const loader = loaders.get(loc);
+    if (!loader) {
+      throw new Error(`bQuery i18n: No messages or loader registered for locale "${loc}".`);
+    }
+
+    const loaded = await loader();
+    // Handle both default exports and direct objects
+    const msgs = (loaded as { default?: LocaleMessages }).default ?? (loaded as LocaleMessages);
+    messages[loc] = sanitizeLocaleMessages(msgs);
+    loadedLocales.add(loc);
+  };
+
+  /**
+   * Translate a key path.
+   */
+  const t = (key: string, params: TranslateParams = {}): string => {
+    const currentLocale = $locale.value;
+    const currentMessages = messages[currentLocale];
+    const fallbackMessages = fallbackLocale ? messages[fallbackLocale] : undefined;
+
+    return translate(currentMessages, key, params, fallbackMessages);
+  };
+
+  /**
+   * Reactive translation — returns a computed signal.
+   */
+  const tc = (key: string, params: TranslateParams = {}) => {
+    return computed(() => {
+      // Reading $locale.value creates a reactive dependency
+      const currentLocale = $locale.value;
+      const currentMessages = messages[currentLocale];
+      const fallbackMessages = fallbackLocale ? messages[fallbackLocale] : undefined;
+
+      return translate(currentMessages, key, params, fallbackMessages);
+    });
+  };
+
+  /**
+   * Format a number with the current (or overridden) locale.
+   */
+  const n = (value: number, options?: NumberFormatOptions): string => {
+    const loc = options?.locale ?? $locale.value;
+    return formatNumber(value, loc, options);
+  };
+
+  /**
+   * Format a date with the current (or overridden) locale.
+   */
+  const d = (value: Date | number, options?: DateFormatOptions): string => {
+    const loc = options?.locale ?? $locale.value;
+    return formatDate(value, loc, options);
+  };
+
+  /**
+   * Merge additional messages into a locale.
+   */
+  const mergeMessages = (loc: string, newMessages: LocaleMessages): void => {
+    if (isPrototypePollutionKey(loc)) {
+      return;
+    }
+    if (!messages[loc]) {
+      messages[loc] = Object.create(null) as LocaleMessages;
+      loadedLocales.add(loc);
+    }
+    messages[loc] = deepMerge(messages[loc], sanitizeLocaleMessages(newMessages));
+  };
+
+  /**
+   * List all available locales (loaded + registered loaders).
+   */
+  const availableLocales = (): string[] => {
+    const locales = new Set<string>([...loadedLocales, ...loaders.keys()]);
+    return Array.from(locales).sort();
+  };
+
+  return {
+    $locale,
+    t,
+    tc,
+    loadLocale,
+    ensureLocale,
+    n,
+    d,
+    getMessages,
+    mergeMessages,
+    availableLocales,
+  };
+};

package/src/i18n/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Internationalization (i18n) module for bQuery.js.
+ *
+ * Provides a reactive, TypeScript-first internationalization API
+ * with interpolation, pluralization, lazy-loading, and locale-aware
+ * formatting — all backed by bQuery's signal-based reactivity system.
+ *
+ * @module bquery/i18n
+ *
+ * @example
+ * ```ts
+ * import { createI18n } from '@bquery/bquery/i18n';
+ *
+ * const i18n = createI18n({
+ *   locale: 'en',
+ *   fallbackLocale: 'en',
+ *   messages: {
+ *     en: {
+ *       greeting: 'Hello, {name}!',
+ *       items: '{count} item | {count} items',
+ *       nested: { deep: { key: 'Found it!' } },
+ *     },
+ *     de: {
+ *       greeting: 'Hallo, {name}!',
+ *       items: '{count} Gegenstand | {count} Gegenstände',
+ *     },
+ *   },
+ * });
+ *
+ * // Basic translation
+ * i18n.t('greeting', { name: 'Ada' }); // 'Hello, Ada!'
+ *
+ * // Pluralization
+ * i18n.t('items', { count: 1 }); // '1 item'
+ * i18n.t('items', { count: 5 }); // '5 items'
+ *
+ * // Reactive translation (auto-updates on locale change)
+ * const label = i18n.tc('greeting', { name: 'Ada' });
+ * console.log(label.value); // 'Hello, Ada!'
+ *
+ * i18n.$locale.value = 'de';
+ * console.log(label.value); // 'Hallo, Ada!'
+ *
+ * // Number & date formatting
+ * i18n.n(1234.56);                              // '1,234.56' (en)
+ * i18n.d(new Date(), { dateStyle: 'long' });     // 'March 26, 2026'
+ *
+ * // Lazy-load a locale
+ * i18n.loadLocale('fr', () => import('./locales/fr.json'));
+ * await i18n.ensureLocale('fr');
+ * i18n.$locale.value = 'fr';
+ * ```
+ */
+
+export { createI18n } from './i18n';
+export { formatDate, formatNumber } from './formatting';
+
+export type {
+  DateFormatOptions,
+  I18nConfig,
+  I18nInstance,
+  LocaleLoader,
+  LocaleMessages,
+  Messages,
+  NumberFormatOptions,
+  TranslateParams,
+} from './types';

package/src/i18n/translate.ts

@@ -0,0 +1,182 @@
+/**
+ * Translation resolution helpers.
+ * @module bquery/i18n
+ * @internal
+ */
+
+import { isPlainObject, isPrototypePollutionKey, merge } from '../core/utils/object';
+import type { LocaleMessages, TranslateParams } from './types';
+
+/**
+ * Resolves a dot-delimited key path against a messages object.
+ *
+ * @param messages - The locale messages
+ * @param key - Dot-delimited key (e.g. 'user.welcome')
+ * @returns The resolved string, or `undefined` if not found
+ *
+ * @internal
+ */
+export const resolveKey = (messages: LocaleMessages, key: string): string | undefined => {
+  const parts = key.split('.');
+  let current: LocaleMessages | string = messages;
+
+  for (const part of parts) {
+    if (typeof current === 'string') return undefined;
+    if (current[part] === undefined) return undefined;
+    current = current[part];
+  }
+
+  return typeof current === 'string' ? current : undefined;
+};
+
+/**
+ * Interpolates `{param}` placeholders in a string.
+ *
+ * @param template - The template string with `{key}` placeholders
+ * @param params - Key-value pairs for replacement
+ * @returns The interpolated string
+ *
+ * @example
+ * ```ts
+ * interpolate('Hello, {name}!', { name: 'Ada' });
+ * // → 'Hello, Ada!'
+ * ```
+ *
+ * @internal
+ */
+export const interpolate = (template: string, params: TranslateParams): string => {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) => {
+    if (key in params) {
+      return String(params[key]);
+    }
+    return match; // Leave unmatched placeholders as-is
+  });
+};
+
+/**
+ * Selects the correct plural form from a pipe-delimited string.
+ *
+ * Supports two formats:
+ * - **Two forms:** `"singular | plural"` — singular when count === 1
+ * - **Three forms:** `"zero | one | many"` — zero when count === 0,
+ *   one when count === 1, many otherwise
+ *
+ * The `count` parameter must be present in `params` for pluralization.
+ * If no `count` param exists or the string has no pipes, the string is
+ * returned as-is.
+ *
+ * @param template - Pipe-delimited plural forms
+ * @param params - Must include a `count` key for plural selection
+ * @returns The selected form
+ *
+ * @example
+ * ```ts
+ * pluralize('{count} item | {count} items', { count: 1 });
+ * // → '{count} item'
+ *
+ * pluralize('no items | {count} item | {count} items', { count: 0 });
+ * // → 'no items'
+ * ```
+ *
+ * @internal
+ */
+export const pluralize = (template: string, params: TranslateParams): string => {
+  if (!template.includes('|')) return template;
+  if (!('count' in params)) return template;
+
+  const count = Number(params.count);
+  const forms = template.split('|').map((s) => s.trim());
+
+  if (forms.length === 3) {
+    // zero | one | many
+    if (count === 0) return forms[0];
+    if (count === 1) return forms[1];
+    return forms[2];
+  }
+
+  if (forms.length === 2) {
+    // singular | plural
+    return count === 1 ? forms[0] : forms[1];
+  }
+
+  // More than 3 forms: use last form for "many"
+  if (count === 0 && forms.length > 0) return forms[0];
+  if (count === 1 && forms.length > 1) return forms[1];
+  return forms[forms.length - 1];
+};
+
+/**
+ * Full translation pipeline: resolve → pluralize → interpolate.
+ *
+ * @param messages - Locale messages
+ * @param key - Dot-delimited key path
+ * @param params - Interpolation + pluralization params
+ * @param fallbackMessages - Optional fallback locale messages
+ * @returns The translated string, or the key if not found
+ *
+ * @internal
+ */
+export const translate = (
+  messages: LocaleMessages | undefined,
+  key: string,
+  params: TranslateParams,
+  fallbackMessages?: LocaleMessages
+): string => {
+  let template: string | undefined;
+
+  // Try current locale
+  if (messages) {
+    template = resolveKey(messages, key);
+  }
+
+  // Fallback locale
+  if (template === undefined && fallbackMessages) {
+    template = resolveKey(fallbackMessages, key);
+  }
+
+  // Key not found — return key as-is
+  if (template === undefined) {
+    return key;
+  }
+
+  // Pluralize first, then interpolate
+  const pluralized = pluralize(template, params);
+  return interpolate(pluralized, params);
+};
+
+/**
+ * Deep merges source into target and returns a sanitized, prototype-safe copy.
+ *
+ * @param target - Target messages object
+ * @param source - Source messages to merge
+ * @returns A new merged, sanitized messages object
+ *
+ * @internal
+ */
+export const deepMerge = (target: LocaleMessages, source: LocaleMessages): LocaleMessages => {
+  const merged = merge(
+    target as Record<string, unknown>,
+    source as Record<string, unknown>
+  ) as LocaleMessages;
+
+  const cloneSafeMessages = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+      return value.map((entry) => cloneSafeMessages(entry));
+    }
+
+    if (!isPlainObject(value)) {
+      return value;
+    }
+
+    const safeObject = Object.create(null) as Record<string, unknown>;
+    for (const [key, entry] of Object.entries(value)) {
+      if (isPrototypePollutionKey(key)) {
+        continue;
+      }
+      safeObject[key] = cloneSafeMessages(entry);
+    }
+    return safeObject;
+  };
+
+  return cloneSafeMessages(merged) as LocaleMessages;
+};

package/src/i18n/types.ts

@@ -0,0 +1,171 @@
+/**
+ * Type definitions for the i18n module.
+ * @module bquery/i18n
+ */
+
+import type { ReadonlySignal, Signal } from '../reactive/index';
+
+/**
+ * A nested record of translation messages.
+ * Values can be strings or nested objects for namespacing.
+ *
+ * @example
+ * ```ts
+ * const messages: LocaleMessages = {
+ *   greeting: 'Hello',
+ *   user: {
+ *     name: 'Name',
+ *     welcome: 'Welcome, {name}!',
+ *   },
+ *   items: '{count} item | {count} items',
+ * };
+ * ```
+ */
+export type LocaleMessages = {
+  [key: string]: string | LocaleMessages;
+};
+
+/**
+ * Record of locale codes to their messages.
+ */
+export type Messages = {
+  [locale: string]: LocaleMessages;
+};
+
+/**
+ * Interpolation parameters for translation strings.
+ * Values are converted to strings during interpolation.
+ */
+export type TranslateParams = Record<string, string | number>;
+
+/**
+ * Configuration for creating an i18n instance.
+ */
+export type I18nConfig = {
+  /** The initial locale code (e.g. 'en', 'de', 'fr') */
+  locale: string;
+  /** Pre-loaded message dictionaries keyed by locale */
+  messages: Messages;
+  /** Fallback locale when a key is missing in the current locale */
+  fallbackLocale?: string;
+};
+
+/**
+ * A lazy-loader function that returns a promise resolving to locale messages.
+ */
+export type LocaleLoader = () => Promise<LocaleMessages | { default: LocaleMessages }>;
+
+/**
+ * Options for number formatting via `Intl.NumberFormat`.
+ */
+export type NumberFormatOptions = Intl.NumberFormatOptions & {
+  /** Override the locale for this specific formatting call */
+  locale?: string;
+};
+
+/**
+ * Options for date formatting via `Intl.DateTimeFormat`.
+ */
+export type DateFormatOptions = Intl.DateTimeFormatOptions & {
+  /** Override the locale for this specific formatting call */
+  locale?: string;
+};
+
+/**
+ * The public i18n instance returned by `createI18n()`.
+ */
+export type I18nInstance = {
+  /**
+   * Reactive signal holding the current locale code.
+   * Setting `.value` switches the locale and reactively updates
+   * all computed translations.
+   */
+  $locale: Signal<string>;
+
+  /**
+   * Translate a key path with optional interpolation and pluralization.
+   *
+   * @param key - Dot-delimited key path (e.g. 'user.welcome')
+   * @param params - Interpolation values (e.g. `{ name: 'Ada' }`)
+   * @returns The translated string, or the key itself if not found
+   *
+   * @example
+   * ```ts
+   * i18n.t('greeting');           // 'Hello'
+   * i18n.t('user.welcome', { name: 'Ada' }); // 'Welcome, Ada!'
+   * i18n.t('items', { count: 3 }); // '3 items'
+   * ```
+   */
+  t: (key: string, params?: TranslateParams) => string;
+
+  /**
+   * Reactive translation — returns a ReadonlySignal that updates
+   * when the locale changes.
+   *
+   * @param key - Dot-delimited key path
+   * @param params - Interpolation values
+   * @returns A reactive signal containing the translated string
+   */
+  tc: (key: string, params?: TranslateParams) => ReadonlySignal<string>;
+
+  /**
+   * Register a lazy-loader for a locale's messages.
+   * The loader is invoked when the locale is first needed.
+   *
+   * @param locale - Locale code
+   * @param loader - Async function returning messages
+   *
+   * @example
+   * ```ts
+   * i18n.loadLocale('de', () => import('./locales/de.json'));
+   * ```
+   */
+  loadLocale: (locale: string, loader: LocaleLoader) => void;
+
+  /**
+   * Ensure a locale's messages are loaded (triggers lazy-loader if registered).
+   *
+   * @param locale - Locale code to load
+   * @returns A promise that resolves when the locale is ready
+   */
+  ensureLocale: (locale: string) => Promise<void>;
+
+  /**
+   * Format a number according to the current locale using `Intl.NumberFormat`.
+   *
+   * @param value - Number to format
+   * @param options - Intl.NumberFormat options
+   * @returns The formatted number string
+   */
+  n: (value: number, options?: NumberFormatOptions) => string;
+
+  /**
+   * Format a date according to the current locale using `Intl.DateTimeFormat`.
+   *
+   * @param value - Date to format
+   * @param options - Intl.DateTimeFormat options
+   * @returns The formatted date string
+   */
+  d: (value: Date | number, options?: DateFormatOptions) => string;
+
+  /**
+   * Get all currently loaded messages for a locale.
+   *
+   * @param locale - Locale code
+   * @returns The messages object, or undefined if not loaded
+   */
+  getMessages: (locale: string) => LocaleMessages | undefined;
+
+  /**
+   * Merge additional messages into an existing locale.
+   *
+   * @param locale - Locale code
+   * @param messages - Messages to merge (deep merge)
+   */
+  mergeMessages: (locale: string, messages: LocaleMessages) => void;
+
+  /**
+   * List all available locale codes (loaded or registered for lazy-loading).
+   */
+  availableLocales: () => string[];
+};