intor 2.5.0 → 2.6.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Ivan Liao
+Copyright (c) 2025 Yiming Liao
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -16,7 +16,7 @@ The i18n library for modern JavaScript
 
 <div align="center">
 
-#### [![Documentation ↗](https://img.shields.io/badge/%20Documentation%20%F0%9F%93%9A%20-3e668c?style=for-the-badge)](https://intor-doc.pages.dev/en-US/frameworks)
+#### [![Documentation ↗](https://img.shields.io/badge/%20Documentation%20%F0%9F%93%9A%20-3e668c?style=for-the-badge)](https://intor.dev)
 
 </div>
 

package/dist/core/export/index.js

@@ -1,3 +1,4 @@
+export { LOCALE_PLACEHOLDER } from '../src/core/constants/locale-placeholder.js';
 export { INTOR_ERROR_CODE, IntorError } from '../src/core/error/intor-error.js';
 export { matchLocale } from '../src/core/locale/match-locale.js';
 import 'logry';

package/dist/core/src/client/shared/helpers/get-client-locale.js

@@ -5,27 +5,12 @@ import 'intor-translator';
 import { detectBrowserLocale } from '../utils/locale/detect-browser-locale.js';
 import { getLocaleFromCookie } from '../utils/locale/get-locale-from-cookie.js';
 
-/**
- * Resolve the active locale in a browser-only environment.
- *
- * This helper is intended for pure client-side setups where
- * no server-side locale resolution is involved.
- *
- * Resolution order:
- * 1. Locale from cookie
- * 2. Locale from browser preference
- * 3. Fallback to `defaultLocale`
- *
- * @public
- */
 function getClientLocale(config) {
-    const { defaultLocale, supportedLocales, cookie } = config;
-    // Locale from browser cookie
-    const cookieLocale = getLocaleFromCookie(cookie.name);
-    // Locale from browser preference
-    const browserLocale = detectBrowserLocale();
-    const localeCandidate = cookieLocale || browserLocale;
-    return matchLocale(localeCandidate, supportedLocales) || defaultLocale;
+  const { defaultLocale, supportedLocales, cookie } = config;
+  const cookieLocale = getLocaleFromCookie(cookie.name);
+  const browserLocale = detectBrowserLocale();
+  const localeCandidate = cookieLocale || browserLocale;
+  return matchLocale(localeCandidate, supportedLocales) || defaultLocale;
 }
 
 export { getClientLocale };

package/dist/core/src/client/shared/utils/locale/detect-browser-locale.js

@@ -1,12 +1,6 @@
-/**
- * Detect the preferred locale from the browser.
- *
- * This function relies on `navigator.languages` and `navigator.language`.
- */
 function detectBrowserLocale() {
-    if (typeof navigator === "undefined")
-        return undefined;
-    return navigator.languages?.[0] || navigator.language || undefined;
+  if (typeof navigator === "undefined") return void 0;
+  return navigator.languages?.[0] || navigator.language || void 0;
 }
 
 export { detectBrowserLocale };

package/dist/core/src/client/shared/utils/locale/get-locale-from-cookie.js

@@ -1,16 +1,9 @@
-/**
- * Gets the locale value from the browser cookie.
- *
- * This function relies on `document.cookie`.
- */
 function getLocaleFromCookie(cookieName) {
-    if (typeof document === "undefined")
-        return undefined;
-    const cookies = document.cookie.split(";").map((c) => c.trim());
-    const entry = cookies.find((c) => c.startsWith(`${cookieName}=`));
-    if (!entry)
-        return undefined;
-    return decodeURIComponent(entry.slice(cookieName.length + 1));
+  if (typeof document === "undefined") return void 0;
+  const cookies = document.cookie.split(";").map((c) => c.trim());
+  const entry = cookies.find((c) => c.startsWith(`${cookieName}=`));
+  if (!entry) return void 0;
+  return decodeURIComponent(entry.slice(cookieName.length + 1));
 }
 
 export { getLocaleFromCookie };

package/dist/core/src/config/constants/cookie.js

@@ -1,13 +1,13 @@
-// Default cookie options
 const DEFAULT_COOKIE_OPTIONS = {
-    persist: true,
-    name: "intor.locale",
-    domain: undefined,
-    path: "/",
-    maxAge: 60 * 60 * 24 * 365, // 365 days
-    httpOnly: false,
-    secure: process.env["NODE_ENV"] !== "development",
-    sameSite: "lax",
+  persist: true,
+  name: "intor.locale",
+  domain: void 0,
+  path: "/",
+  maxAge: 60 * 60 * 24 * 365,
+  // 365 days
+  httpOnly: false,
+  secure: process.env["NODE_ENV"] !== "development",
+  sameSite: "lax"
 };
 
 export { DEFAULT_COOKIE_OPTIONS };

package/dist/core/src/config/constants/routing.js

@@ -1,18 +1,17 @@
-// Default routing options
 const DEFAULT_ROUTING_OPTIONS = {
-    basePath: "/",
-    localePrefix: "none",
-    inbound: {
-        localeSources: ["path", "query", "cookie", "detected"],
-        queryKey: "locale",
-        firstVisit: { localeSource: "browser", persist: true, redirect: true },
-    },
-    outbound: {
-        localeCarrier: "path",
-        queryKey: "locale",
-        host: { map: {} },
-        forceFullReload: false,
-    },
+  basePath: "/",
+  localePrefix: "none",
+  inbound: {
+    localeSources: ["path", "query", "cookie", "detected"],
+    queryKey: "locale",
+    firstVisit: { localeSource: "browser", persist: true, redirect: true }
+  },
+  outbound: {
+    localeCarrier: "path",
+    queryKey: "locale",
+    host: { map: {} },
+    forceFullReload: false
+  }
 };
 
 export { DEFAULT_ROUTING_OPTIONS };

package/dist/core/src/config/define-intor-config.js

@@ -5,51 +5,35 @@ import { validateDefaultLocale } from './validators/validate-default-locale.js';
 import { validateId } from './validators/validate-id.js';
 import { validateSupportedLocales } from './validators/validate-supported-locales.js';
 
-/**
- * Defines the canonical Intor configuration.
- *
- * This is the primary entry point for creating a validated,
- * runtime-ready Intor configuration.
- *
- * It transforms a user-provided raw config into a normalized form by:
- * - enforcing required invariants
- * - resolving derived options
- * - applying stable defaults
- *
- * This function is pure and side-effect free.
- *
- * @public
- */
 const defineIntorConfig = (config) => {
-    // -----------------------------------------------------------------------------
-    // Validators
-    // -----------------------------------------------------------------------------
-    const id = validateId(config.id ?? "default");
-    const supportedLocales = validateSupportedLocales(id, config.supportedLocales);
-    const supportedSet = new Set(supportedLocales);
-    const defaultLocale = validateDefaultLocale(id, config.defaultLocale, supportedSet);
-    // -----------------------------------------------------------------------------
-    // Resolvers
-    // -----------------------------------------------------------------------------
-    const fallbackLocales = resolveFallbackLocales(config, id, supportedSet);
-    const cookie = resolveCookieOptions(config.cookie);
-    const routing = resolveRoutingOptions(config.routing);
-    return {
-        id,
-        ...(config.messages !== undefined ? { messages: config.messages } : {}),
-        ...(config.loader !== undefined ? { loader: config.loader } : {}),
-        defaultLocale,
-        supportedLocales,
-        fallbackLocales,
-        ...(config.translator !== undefined
-            ? { translator: config.translator }
-            : {}),
-        cookie,
-        routing,
-        logger: { id, ...config.logger },
-        ...(config.client !== undefined ? { client: config.client } : {}),
-        ...(config.server !== undefined ? { server: config.server } : {}),
-    };
+  const id = validateId(config.id ?? "default");
+  const supportedLocales = validateSupportedLocales(
+    id,
+    config.supportedLocales
+  );
+  const supportedSet = new Set(supportedLocales);
+  const defaultLocale = validateDefaultLocale(
+    id,
+    config.defaultLocale,
+    supportedSet
+  );
+  const fallbackLocales = resolveFallbackLocales(config, id, supportedSet);
+  const cookie = resolveCookieOptions(config.cookie);
+  const routing = resolveRoutingOptions(config.routing);
+  return {
+    id,
+    ...config.messages !== void 0 ? { messages: config.messages } : {},
+    ...config.loader !== void 0 ? { loader: config.loader } : {},
+    defaultLocale,
+    supportedLocales,
+    fallbackLocales,
+    ...config.translator !== void 0 ? { translator: config.translator } : {},
+    cookie,
+    routing,
+    logger: { id, ...config.logger },
+    ...config.client !== void 0 ? { client: config.client } : {},
+    ...config.server !== void 0 ? { server: config.server } : {}
+  };
 };
 
 export { defineIntorConfig };

package/dist/core/src/config/resolvers/resolve-cookie-options.js

@@ -1,10 +1,10 @@
 import { DEFAULT_COOKIE_OPTIONS } from '../constants/cookie.js';
 
 const resolveCookieOptions = (cookie = {}) => {
-    return {
-        ...DEFAULT_COOKIE_OPTIONS,
-        ...cookie,
-    };
+  return {
+    ...DEFAULT_COOKIE_OPTIONS,
+    ...cookie
+  };
 };
 
 export { resolveCookieOptions };

package/dist/core/src/config/resolvers/resolve-fallback-locales.js

@@ -2,59 +2,42 @@ import { getLogger } from '../../core/logger/get-logger.js';
 import 'p-limit';
 import 'intor-translator';
 
-/**
- * Resolves fallbackLocales into a runtime-safe mapping.
- *
- * Invalid entries are ignored and reported via warnings.
- */
 const resolveFallbackLocales = (config, id, supportedSet) => {
-    const { defaultLocale, fallbackLocales } = config;
-    // Fast exit: no fallback configuration provided
-    if (!fallbackLocales || typeof fallbackLocales !== "object") {
-        return {};
+  const { defaultLocale, fallbackLocales } = config;
+  if (!fallbackLocales || typeof fallbackLocales !== "object") {
+    return {};
+  }
+  const logger = getLogger({ ...config.logger, id }).child({
+    scope: "resolve-fallback-locales"
+  });
+  const resolvedMap = {};
+  const invalidMap = /* @__PURE__ */ new Map();
+  for (const [locale, fallbacks] of Object.entries(fallbackLocales)) {
+    if (!supportedSet.has(locale) && locale !== defaultLocale) {
+      logger.warn(
+        `Fallback locale "${locale}" is not listed in supportedLocales.`
+      );
+      continue;
     }
-    const logger = getLogger({ ...config.logger, id }).child({
-        scope: "resolve-fallback-locales",
-    });
-    const resolvedMap = {};
-    const invalidMap = new Map();
-    // ---------------------------------------------------------------------------
-    // Normalize each fallback rule
-    // ---------------------------------------------------------------------------
-    for (const [locale, fallbacks] of Object.entries(fallbackLocales)) {
-        // Guard: fallback rules for unreachable locales are ignored.
-        if (!supportedSet.has(locale) && locale !== defaultLocale) {
-            logger.warn(`Fallback locale "${locale}" is not listed in supportedLocales.`);
-            continue;
-        }
-        const fallbackArray = Array.isArray(fallbacks) ? fallbacks : [];
-        const validFallbacks = [];
-        const invalidFallbacks = [];
-        for (const fallback of fallbackArray) {
-            // A fallback target is considered valid if:
-            // - It exists in `supportedLocales`
-            // - It is the literal value "default"
-            if (fallback === "default" || supportedSet.has(fallback)) {
-                validFallbacks.push(fallback);
-            }
-            else {
-                invalidFallbacks.push(fallback);
-            }
-        }
-        if (invalidFallbacks.length > 0)
-            invalidMap.set(locale, invalidFallbacks);
-        if (validFallbacks.length > 0)
-            resolvedMap[locale] = validFallbacks;
-    }
-    // ---------------------------------------------------------------------------
-    // Diagnostics: report ignored fallback entries
-    // ---------------------------------------------------------------------------
-    for (const [locale, invalids] of invalidMap.entries()) {
-        logger.warn(`Invalid fallback locales for "${locale}".`, {
-            invalids: invalids.join(", "),
-        });
+    const fallbackArray = Array.isArray(fallbacks) ? fallbacks : [];
+    const validFallbacks = [];
+    const invalidFallbacks = [];
+    for (const fallback of fallbackArray) {
+      if (fallback === "default" || supportedSet.has(fallback)) {
+        validFallbacks.push(fallback);
+      } else {
+        invalidFallbacks.push(fallback);
+      }
     }
-    return resolvedMap;
+    if (invalidFallbacks.length > 0) invalidMap.set(locale, invalidFallbacks);
+    if (validFallbacks.length > 0) resolvedMap[locale] = validFallbacks;
+  }
+  for (const [locale, invalids] of invalidMap.entries()) {
+    logger.warn(`Invalid fallback locales for "${locale}".`, {
+      invalids: invalids.join(", ")
+    });
+  }
+  return resolvedMap;
 };
 
 export { resolveFallbackLocales };

package/dist/core/src/config/resolvers/resolve-routing-options.js

@@ -6,76 +6,47 @@ import 'intor-translator';
 import { DEFAULT_ROUTING_OPTIONS } from '../constants/routing.js';
 import '../constants/cookie.js';
 
-/**
- * Resolves routing configuration into a fully normalized form.
- *
- * - Flat shortcuts are projected into structured options.
- * - Structured options override projected values.
- * - Defaults are applied last.
- */
 function resolveRoutingOptions(raw) {
-    if (!raw) {
-        return enforceRoutingInvariants(DEFAULT_ROUTING_OPTIONS);
-    }
-    const projectedFromFlat = projectFlatToStructured(raw);
-    const structuredOverrides = stripFlatShortcuts(raw);
-    const defined = deepMerge(projectedFromFlat, structuredOverrides);
-    const merged = deepMerge(DEFAULT_ROUTING_OPTIONS, defined);
-    return enforceRoutingInvariants(merged);
+  if (!raw) {
+    return enforceRoutingInvariants(DEFAULT_ROUTING_OPTIONS);
+  }
+  const projectedFromFlat = projectFlatToStructured(raw);
+  const structuredOverrides = stripFlatShortcuts(raw);
+  const defined = deepMerge(projectedFromFlat, structuredOverrides);
+  const merged = deepMerge(DEFAULT_ROUTING_OPTIONS, defined);
+  return enforceRoutingInvariants(merged);
 }
-/**
- * Enforces runtime invariants for routing configuration.
- *
- * Invariants:
- * - basePath is normalized
- * - basePath always starts with "/"
- * - root basePath is represented as "/"
- */
 function enforceRoutingInvariants(routing) {
-    const normalizedBase = routing.basePath && routing.basePath !== "/"
-        ? normalizePathname(routing.basePath)
-        : "/";
-    return { ...routing, basePath: normalizedBase };
+  const normalizedBase = routing.basePath && routing.basePath !== "/" ? normalizePathname(routing.basePath) : "/";
+  return { ...routing, basePath: normalizedBase };
 }
-/** Assigns a value to the target only if it is explicitly defined. */
 function assignIfDefined(target, key, value) {
-    if (value !== undefined)
-        target[key] = value;
+  if (value !== void 0) target[key] = value;
 }
-/** Projects flat routing shortcuts into structured options. */
 function projectFlatToStructured(flat) {
-    const structured = {};
-    assignIfDefined(structured, "basePath", flat.basePath);
-    assignIfDefined(structured, "localePrefix", flat.localePrefix);
-    // inbound
-    const inbound = {};
-    assignIfDefined(inbound, "localeSources", flat.localeSources);
-    assignIfDefined(inbound, "queryKey", flat.queryKey);
-    assignIfDefined(inbound, "firstVisit", flat.firstVisit);
-    if (Object.keys(inbound).length > 0)
-        structured.inbound = inbound;
-    // outbound
-    const outbound = {};
-    assignIfDefined(outbound, "localeCarrier", flat.localeCarrier);
-    assignIfDefined(outbound, "queryKey", flat.queryKey);
-    assignIfDefined(outbound, "host", flat.host);
-    assignIfDefined(outbound, "forceFullReload", flat.forceFullReload);
-    if (Object.keys(outbound).length > 0)
-        structured.outbound = outbound;
-    return structured;
+  const structured = {};
+  assignIfDefined(structured, "basePath", flat.basePath);
+  assignIfDefined(structured, "localePrefix", flat.localePrefix);
+  const inbound = {};
+  assignIfDefined(inbound, "localeSources", flat.localeSources);
+  assignIfDefined(inbound, "queryKey", flat.queryKey);
+  assignIfDefined(inbound, "firstVisit", flat.firstVisit);
+  if (Object.keys(inbound).length > 0) structured.inbound = inbound;
+  const outbound = {};
+  assignIfDefined(outbound, "localeCarrier", flat.localeCarrier);
+  assignIfDefined(outbound, "queryKey", flat.queryKey);
+  assignIfDefined(outbound, "host", flat.host);
+  assignIfDefined(outbound, "forceFullReload", flat.forceFullReload);
+  if (Object.keys(outbound).length > 0) structured.outbound = outbound;
+  return structured;
 }
-/** Removes flat shortcuts, preserving structured overrides only. */
 function stripFlatShortcuts(raw) {
-    const structured = {};
-    if ("basePath" in raw)
-        structured.basePath = raw.basePath;
-    if ("localePrefix" in raw)
-        structured.localePrefix = raw.localePrefix;
-    if ("inbound" in raw)
-        structured.inbound = raw.inbound;
-    if ("outbound" in raw)
-        structured.outbound = raw.outbound;
-    return structured;
+  const structured = {};
+  if ("basePath" in raw) structured.basePath = raw.basePath;
+  if ("localePrefix" in raw) structured.localePrefix = raw.localePrefix;
+  if ("inbound" in raw) structured.inbound = raw.inbound;
+  if ("outbound" in raw) structured.outbound = raw.outbound;
+  return structured;
 }
 
 export { resolveRoutingOptions };

package/dist/core/src/config/validators/validate-default-locale.js

@@ -3,20 +3,15 @@ import 'logry';
 import 'p-limit';
 import 'intor-translator';
 
-/**
- * Validates that the configured defaultLocale is supported.
- *
- * Fails fast if `defaultLocale` is not included in `supportedLocales`.
- */
 const validateDefaultLocale = (id, defaultLocale, supportedSet) => {
-    if (!supportedSet.has(defaultLocale)) {
-        throw new IntorError({
-            id,
-            code: INTOR_ERROR_CODE.CONFIG_UNSUPPORTED_DEFAULT_LOCALE,
-            message: `"defaultLocale" must be included in "supportedLocales".`,
-        });
-    }
-    return defaultLocale;
+  if (!supportedSet.has(defaultLocale)) {
+    throw new IntorError({
+      id,
+      code: INTOR_ERROR_CODE.CONFIG_UNSUPPORTED_DEFAULT_LOCALE,
+      message: `"defaultLocale" must be included in "supportedLocales".`
+    });
+  }
+  return defaultLocale;
 };
 
 export { validateDefaultLocale };

package/dist/core/src/config/validators/validate-id.js

@@ -3,20 +3,15 @@ import 'logry';
 import 'p-limit';
 import 'intor-translator';
 
-/**
- * Validates that the given id is a non-empty string.
- *
- * Fails fast if the id is empty or whitespace-only.
- */
 const validateId = (id) => {
-    if (id.trim() === "") {
-        throw new IntorError({
-            id,
-            code: INTOR_ERROR_CODE.CONFIG_INVALID_ID,
-            message: `"id" must be a non-empty string.`,
-        });
-    }
-    return id;
+  if (id.trim() === "") {
+    throw new IntorError({
+      id,
+      code: INTOR_ERROR_CODE.CONFIG_INVALID_ID,
+      message: `"id" must be a non-empty string.`
+    });
+  }
+  return id;
 };
 
 export { validateId };

package/dist/core/src/config/validators/validate-supported-locales.js

@@ -3,20 +3,15 @@ import 'logry';
 import 'p-limit';
 import 'intor-translator';
 
-/**
- * Validates that supportedLocales is provided and non-empty.
- *
- * Fails fast when missing.
- */
 const validateSupportedLocales = (id, supportedLocales) => {
-    if (!supportedLocales || supportedLocales.length === 0) {
-        throw new IntorError({
-            id,
-            code: INTOR_ERROR_CODE.CONFIG_MISSING_SUPPORTED_LOCALES,
-            message: `"supportedLocales" must be specified.`,
-        });
-    }
-    return supportedLocales;
+  if (!supportedLocales || supportedLocales.length === 0) {
+    throw new IntorError({
+      id,
+      code: INTOR_ERROR_CODE.CONFIG_MISSING_SUPPORTED_LOCALES,
+      message: `"supportedLocales" must be specified.`
+    });
+  }
+  return supportedLocales;
 };
 
 export { validateSupportedLocales };

package/dist/core/src/core/constants/locale-placeholder.js

@@ -1,4 +1,3 @@
-// Default locale placeholder
 const LOCALE_PLACEHOLDER = "{locale}";
 
 export { LOCALE_PLACEHOLDER };

package/dist/core/src/core/error/intor-error.js

@@ -1,35 +1,20 @@
-/**
- * Framework-level error used by Intor.
- *
- * Extends the native Error with optional structured metadata.
- *
- * @public
- */
 class IntorError extends Error {
-    code;
-    id;
-    constructor({ message, code, id }) {
-        const fullMessage = id ? `[${id}] ${message}` : message;
-        super(fullMessage);
-        this.name = "IntorError";
-        if (id)
-            this.id = id;
-        if (code)
-            this.code = code;
-        Object.setPrototypeOf(this, new.target.prototype); // Fix prototype
-        if (Error.captureStackTrace)
-            Error.captureStackTrace(this, IntorError);
-    }
+  code;
+  id;
+  constructor({ message, code, id }) {
+    const fullMessage = id ? `[${id}] ${message}` : message;
+    super(fullMessage);
+    this.name = "IntorError";
+    if (id) this.id = id;
+    if (code) this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) Error.captureStackTrace(this, IntorError);
+  }
 }
-/**
- * Built-in error codes used by Intor.
- *
- * @public
- */
 const INTOR_ERROR_CODE = {
-    CONFIG_INVALID_ID: "INTOR_CONFIG_INVALID_ID",
-    CONFIG_MISSING_SUPPORTED_LOCALES: "INTOR_CONFIG_MISSING_SUPPORTED_LOCALES",
-    CONFIG_UNSUPPORTED_DEFAULT_LOCALE: "INTOR_CONFIG_UNSUPPORTED_DEFAULT_LOCALE",
+  CONFIG_INVALID_ID: "INTOR_CONFIG_INVALID_ID",
+  CONFIG_MISSING_SUPPORTED_LOCALES: "INTOR_CONFIG_MISSING_SUPPORTED_LOCALES",
+  CONFIG_UNSUPPORTED_DEFAULT_LOCALE: "INTOR_CONFIG_UNSUPPORTED_DEFAULT_LOCALE"
 };
 
 export { INTOR_ERROR_CODE, IntorError };

package/dist/core/src/core/locale/canonicalize-locale.js

@@ -1,23 +1,12 @@
-/**
- * Canonicalizes a BCP 47 locale string.
- *
- * - Uses `Intl.getCanonicalLocales` when available.
- * - Returns the original input if `Intl` is unavailable.
- * - Returns `undefined` for invalid locale input.
- *
- * This function performs normalization only.
- * It does not perform matching or fallback.
- */
 function canonicalizeLocale(input) {
-    try {
-        if (typeof Intl === "undefined" || !Intl.getCanonicalLocales) {
-            return input;
-        }
-        return Intl.getCanonicalLocales(input)[0];
-    }
-    catch {
-        return;
+  try {
+    if (typeof Intl === "undefined" || !Intl.getCanonicalLocales) {
+      return input;
     }
+    return Intl.getCanonicalLocales(input)[0];
+  } catch {
+    return;
+  }
 }
 
 export { canonicalizeLocale };