@burojs/i18n-core 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,21 +1,22 @@
-import { FallbackLng } from 'i18next';
-
+import { FallbackLng } from "i18next";
+//#region src/types/adapter.d.ts
 interface I18nAdapter {
-    t: (key: string, params?: Record<string, unknown>) => string;
-    changeLocale: (locale: string) => Promise<void>;
-    loadNamespace: (namespace: string, locale: string) => Promise<void>;
-    getCurrentLocale: () => string;
-    hasKey: (key: string) => boolean;
-    /**
-     * Subscribe to active-locale changes (fired by {@link I18nAdapter.changeLocale}).
-     * Returns an unsubscribe fn. Optional — adapters that cannot notify omit it,
-     * and the React layer then degrades to a non-reactive locale read. This is
-     * what powers the live language switch (no page reload): `useLocale()` wires
-     * it into `useSyncExternalStore`.
-     */
-    onLocaleChange?: (cb: () => void) => () => void;
+  t: (key: string, params?: Record<string, unknown>) => string;
+  changeLocale: (locale: string) => Promise<void>;
+  loadNamespace: (namespace: string, locale: string) => Promise<void>;
+  getCurrentLocale: () => string;
+  hasKey: (key: string) => boolean;
+  /**
+   * Subscribe to active-locale changes (fired by {@link I18nAdapter.changeLocale}).
+   * Returns an unsubscribe fn. Optional — adapters that cannot notify omit it,
+   * and the React layer then degrades to a non-reactive locale read. This is
+   * what powers the live language switch (no page reload): `useLocale()` wires
+   * it into `useSyncExternalStore`.
+   */
+  onLocaleChange?: (cb: () => void) => () => void;
 }
-
+//#endregion
+//#region src/types/bundle.d.ts
 /**
  * Recursive translation bundle: keys map to a string, a nested bundle, or an
  * ARRAY of either.
@@ -30,17 +31,18 @@ interface I18nAdapter {
  * the package that owns the type.
  */
 type TranslationBundle = {
-    [key: string]: string | TranslationBundle | readonly (string | TranslationBundle)[];
+  [key: string]: string | TranslationBundle | readonly (string | TranslationBundle)[];
 };
 /**
  * Per-resource bundle: optional async loader returning default-export bundle.
  */
 type ResourceBundle = (() => Promise<{
-    default: TranslationBundle;
+  default: TranslationBundle;
 }>) | Record<string, () => Promise<{
-    default: TranslationBundle;
+  default: TranslationBundle;
 }>>;
-
+//#endregion
+//#region src/types/i18n-keys.d.ts
 /**
  * Open interface for opt-in codegen-typed i18n keys.
  *
@@ -50,14 +52,13 @@ type ResourceBundle = (() => Promise<{
  *     }
  *   }
  */
-interface I18nKeys {
-}
+interface I18nKeys {}
 /**
  * Open interface for keys requiring interpolation parameters.
  */
-interface I18nKeysWithParams {
-}
-
+interface I18nKeysWithParams {}
+//#endregion
+//#region src/lookup.d.ts
 /**
  * Build candidate keys for fallback lookup.
  *
@@ -71,22 +72,23 @@ interface I18nKeysWithParams {
  * `common.`), return it as-is without further scoping.
  */
 declare function resolveKey(key: string, resource?: string): string[];
-
+//#endregion
+//#region src/i18next-adapter.d.ts
 interface I18nextAdapterConfig {
-    defaultLocale: string;
-    locales: string[];
-    resources?: Record<string, Record<string, TranslationBundle>>;
-    /**
-     * A single fallback locale (`'en'`) applies uniformly to every locale. A
-     * `fr → en` fallback for one locale but not another needs i18next's own
-     * per-locale chain shape instead — `{ fr: ['en'], default: ['en'] }` — so
-     * this accepts i18next's full `FallbackLng` type rather than just `string`.
-     * The chain is entirely CONFIG: nothing in this adapter special-cases any
-     * particular locale code, here or anywhere else.
-     */
-    fallbackLocale?: FallbackLng;
-    keySeparator?: string | false;
-    nsSeparator?: string | false;
+  defaultLocale: string;
+  locales: string[];
+  resources?: Record<string, Record<string, TranslationBundle>>;
+  /**
+   * A single fallback locale (`'en'`) applies uniformly to every locale. A
+   * `fr → en` fallback for one locale but not another needs i18next's own
+   * per-locale chain shape instead — `{ fr: ['en'], default: ['en'] }` — so
+   * this accepts i18next's full `FallbackLng` type rather than just `string`.
+   * The chain is entirely CONFIG: nothing in this adapter special-cases any
+   * particular locale code, here or anywhere else.
+   */
+  fallbackLocale?: FallbackLng;
+  keySeparator?: string | false;
+  nsSeparator?: string | false;
 }
 /**
  * Default I18nAdapter implementation backed by i18next.
@@ -94,47 +96,49 @@ interface I18nextAdapterConfig {
  * (e.g. 'common', 'resources').
  */
 declare function createI18nextAdapter(config: I18nextAdapterConfig): Promise<I18nAdapter>;
-
+//#endregion
+//#region src/i18n.d.ts
 interface I18nFacade {
-    t: (key: string, options?: {
-        resource?: string;
-        params?: Record<string, unknown>;
-    }) => string;
-    /**
-     * True when a translation for `key` EXISTS (through the same candidate chain
-     * as {@link I18nFacade.t}). Distinct from `t`, which returns the raw key on a
-     * miss — the content model probes presence with `has` to tell "no bundle
-     * entry" (render nothing) from "bundle entry === key text".
-     */
-    has: (key: string, options?: {
-        resource?: string;
-    }) => boolean;
-    changeLocale: (locale: string) => Promise<void>;
-    getCurrentLocale: () => string;
-    /**
-     * Subscribe to active-locale changes. Returns an unsubscribe fn. When the
-     * adapter can't notify, this is a no-op subscription (returns an unsubscribe
-     * that does nothing) — the live language switch then falls back to a static
-     * read. Consumed by `useLocale()` via `useSyncExternalStore`.
-     */
-    onLocaleChange: (cb: () => void) => () => void;
-    loadNamespace: (namespace: string, locale: string) => Promise<void>;
-    adapter: I18nAdapter;
+  t: (key: string, options?: {
+    resource?: string;
+    params?: Record<string, unknown>;
+  }) => string;
+  /**
+   * True when a translation for `key` EXISTS (through the same candidate chain
+   * as {@link I18nFacade.t}). Distinct from `t`, which returns the raw key on a
+   * miss — the content model probes presence with `has` to tell "no bundle
+   * entry" (render nothing) from "bundle entry === key text".
+   */
+  has: (key: string, options?: {
+    resource?: string;
+  }) => boolean;
+  changeLocale: (locale: string) => Promise<void>;
+  getCurrentLocale: () => string;
+  /**
+   * Subscribe to active-locale changes. Returns an unsubscribe fn. When the
+   * adapter can't notify, this is a no-op subscription (returns an unsubscribe
+   * that does nothing) — the live language switch then falls back to a static
+   * read. Consumed by `useLocale()` via `useSyncExternalStore`.
+   */
+  onLocaleChange: (cb: () => void) => () => void;
+  loadNamespace: (namespace: string, locale: string) => Promise<void>;
+  adapter: I18nAdapter;
 }
 interface CreateI18nConfig {
-    adapter: I18nAdapter;
-    warnOnMissing?: boolean;
+  adapter: I18nAdapter;
+  warnOnMissing?: boolean;
 }
 declare function createI18n(config: CreateI18nConfig): I18nFacade;
-
+//#endregion
+//#region src/resource-context.d.ts
 interface ResourceI18n {
-    t: (key: string, options?: {
-        resource?: string;
-        params?: Record<string, unknown>;
-    }) => string;
-    changeLocale: (locale: string) => Promise<void>;
-    getCurrentLocale: () => string;
-    resource: string;
+  t: (key: string, options?: {
+    resource?: string;
+    params?: Record<string, unknown>;
+  }) => string;
+  changeLocale: (locale: string) => Promise<void>;
+  getCurrentLocale: () => string;
+  resource: string;
 }
 /**
  * Wraps an I18nFacade with a default resource scope.
@@ -142,7 +146,8 @@ interface ResourceI18n {
  * Pass an explicit `resource` option to override the default scope.
  */
 declare function createResourceI18n(i18n: I18nFacade, resource: string): ResourceI18n;
-
+//#endregion
+//#region src/locale-registry.d.ts
 /**
  * One package/app/domain module's offering for one locale.
  *
@@ -155,52 +160,52 @@ declare function createResourceI18n(i18n: I18nFacade, resource: string): Resourc
  * twenty-first `case`.
  */
 interface LocaleContribution {
-    /** Locale code this contribution provides strings for (e.g. 'en', 'es', 'fr'). */
-    locale: string;
-    /**
-     * i18next namespace the bundle merges into. Defaults to `'common'` — the
-     * same default namespace `createI18nextAdapter` uses.
-     */
-    namespace?: string;
-    /**
-     * Declared merge priority. On a key collision within the same
-     * (locale, namespace), the contribution with the HIGHER priority wins —
-     * not whichever happened to register last. Ties fall back to registration
-     * order (last registered wins), which is why two genuinely competing
-     * sources must declare distinct priorities rather than relying on the tie
-     * break.
-     */
-    priority: number;
-    /**
-     * Where this contribution came from — a package name, `'app'`, an enum
-     * module name. Diagnostic only (surfaced by {@link LocaleRegistry.contributions}
-     * for debugging a collision); never branched on.
-     */
-    source: string;
-    bundle: TranslationBundle;
+  /** Locale code this contribution provides strings for (e.g. 'en', 'es', 'fr'). */
+  locale: string;
+  /**
+   * i18next namespace the bundle merges into. Defaults to `'common'` — the
+   * same default namespace `createI18nextAdapter` uses.
+   */
+  namespace?: string;
+  /**
+   * Declared merge priority. On a key collision within the same
+   * (locale, namespace), the contribution with the HIGHER priority wins —
+   * not whichever happened to register last. Ties fall back to registration
+   * order (last registered wins), which is why two genuinely competing
+   * sources must declare distinct priorities rather than relying on the tie
+   * break.
+   */
+  priority: number;
+  /**
+   * Where this contribution came from — a package name, `'app'`, an enum
+   * module name. Diagnostic only (surfaced by {@link LocaleRegistry.contributions}
+   * for debugging a collision); never branched on.
+   */
+  source: string;
+  bundle: TranslationBundle;
 }
 interface LocaleRegistry {
-    /** Add one contribution. Order of registration does not matter for the merge result — only `priority` does (see {@link LocaleContribution.priority}). */
-    register(contribution: LocaleContribution): void;
-    /**
-     * Every locale code that has at least one contribution, sorted. Derived
-     * purely from what was registered — nothing enumerates or counts locales
-     * anywhere else in this module.
-     */
-    locales(): string[];
-    /** Every namespace that has at least one contribution, sorted. */
-    namespaces(): string[];
-    /** All registered contributions, in registration order. For diagnostics/tests. */
-    contributions(): readonly LocaleContribution[];
-    /**
-     * Assemble `{ [locale]: { [namespace]: TranslationBundle } }`, ready to
-     * pass straight as `createI18nextAdapter`'s `resources` config. Within one
-     * (locale, namespace) group, contributions are deep-merged in ascending
-     * priority order, so a higher-priority contribution's leaves win over a
-     * lower-priority one's on any overlapping key while leaving the rest of
-     * the lower-priority bundle intact.
-     */
-    buildResources(): Record<string, Record<string, TranslationBundle>>;
+  /** Add one contribution. Order of registration does not matter for the merge result — only `priority` does (see {@link LocaleContribution.priority}). */
+  register(contribution: LocaleContribution): void;
+  /**
+   * Every locale code that has at least one contribution, sorted. Derived
+   * purely from what was registered — nothing enumerates or counts locales
+   * anywhere else in this module.
+   */
+  locales(): string[];
+  /** Every namespace that has at least one contribution, sorted. */
+  namespaces(): string[];
+  /** All registered contributions, in registration order. For diagnostics/tests. */
+  contributions(): readonly LocaleContribution[];
+  /**
+   * Assemble `{ [locale]: { [namespace]: TranslationBundle } }`, ready to
+   * pass straight as `createI18nextAdapter`'s `resources` config. Within one
+   * (locale, namespace) group, contributions are deep-merged in ascending
+   * priority order, so a higher-priority contribution's leaves win over a
+   * lower-priority one's on any overlapping key while leaving the rest of
+   * the lower-priority bundle intact.
+   */
+  buildResources(): Record<string, Record<string, TranslationBundle>>;
 }
 declare function createLocaleRegistry(): LocaleRegistry;
 /**
@@ -214,24 +219,24 @@ declare function createLocaleRegistry(): LocaleRegistry;
  * whatever their bundler offers) and hands the plain object here.
  */
 type LocaleGlobModule = TranslationBundle | {
-    default: TranslationBundle;
+  default: TranslationBundle;
 };
 interface LocaleContributionsFromGlobOptions {
-    /** {@link LocaleContribution.source} for every contribution produced. */
-    source: string;
-    /** {@link LocaleContribution.priority} for every contribution produced. */
-    priority: number;
-    /** {@link LocaleContribution.namespace}. Defaults to `'common'`. */
-    namespace?: string;
-    /**
-     * Extracts the locale code from a glob path. Default matches a bare
-     * `<locale>.ts`/`<locale>.tsx`/`<locale>.js` filename (`'./locales/en.ts'`
-     * → `'en'`, `'./locales/fr-CA.ts'` → `'fr-CA'`) — no restriction to a
-     * known set of codes; whatever the filename says IS the locale code. Paths
-     * that don't match are skipped rather than guessed at (same discipline as
-     * `docsFromGlob`).
-     */
-    localeOf?: (path: string) => string | undefined;
+  /** {@link LocaleContribution.source} for every contribution produced. */
+  source: string;
+  /** {@link LocaleContribution.priority} for every contribution produced. */
+  priority: number;
+  /** {@link LocaleContribution.namespace}. Defaults to `'common'`. */
+  namespace?: string;
+  /**
+   * Extracts the locale code from a glob path. Default matches a bare
+   * `<locale>.ts`/`<locale>.tsx`/`<locale>.js` filename (`'./locales/en.ts'`
+   * → `'en'`, `'./locales/fr-CA.ts'` → `'fr-CA'`) — no restriction to a
+   * known set of codes; whatever the filename says IS the locale code. Paths
+   * that don't match are skipped rather than guessed at (same discipline as
+   * `docsFromGlob`).
+   */
+  localeOf?: (path: string) => string | undefined;
 }
 /**
  * Normalize a bundler glob of per-locale files into {@link LocaleContribution}s.
@@ -241,9 +246,10 @@ interface LocaleContributionsFromGlobOptions {
  * mechanism for adding a language.
  */
 declare function localeContributionsFromGlob(glob: Record<string, LocaleGlobModule>, options: LocaleContributionsFromGlobOptions): LocaleContribution[];
-
+//#endregion
+//#region src/create-i18n-from-registry.d.ts
 type CreateI18nFromRegistryConfig = Pick<I18nextAdapterConfig, 'defaultLocale' | 'fallbackLocale' | 'keySeparator' | 'nsSeparator'> & {
-    warnOnMissing?: boolean;
+  warnOnMissing?: boolean;
 };
 /**
  * Wires a {@link LocaleRegistry} straight into `createI18nextAdapter` +
@@ -254,8 +260,10 @@ type CreateI18nFromRegistryConfig = Pick<I18nextAdapterConfig, 'defaultLocale' |
  * just calls this.
  */
 declare function createI18nFromRegistry(registry: LocaleRegistry, config: CreateI18nFromRegistryConfig): Promise<I18nFacade>;
-
+//#endregion
+//#region src/index.d.ts
 declare const PACKAGE_NAME: "@burojs/i18n-core";
 declare const PACKAGE_VERSION: "0.0.0";
-
+//#endregion
 export { type CreateI18nConfig, type CreateI18nFromRegistryConfig, type I18nAdapter, type I18nFacade, type I18nKeys, type I18nKeysWithParams, type I18nextAdapterConfig, type LocaleContribution, type LocaleContributionsFromGlobOptions, type LocaleGlobModule, type LocaleRegistry, PACKAGE_NAME, PACKAGE_VERSION, type ResourceBundle, type ResourceI18n, type TranslationBundle, createI18n, createI18nFromRegistry, createI18nextAdapter, createLocaleRegistry, createResourceI18n, localeContributionsFromGlob, resolveKey };
+//# sourceMappingURL=index.d.ts.map