@intlayer/config 9.0.0-canary.10 → 9.0.0-canary.12

package/dist/types/callers/index.d.ts

@@ -0,0 +1,49 @@
+import { CallerDescriptor, CallerResultShape, CallerValueSource } from "./types.js";
+import { BASE_CALLERS } from "./base.js";
+import { I18NEXT_CALLERS } from "./compat/i18next.js";
+import { LINGUI_CALLERS } from "./compat/lingui.js";
+import { NEXT_INTL_CALLERS } from "./compat/nextIntl.js";
+import { REACT_I18NEXT_CALLERS } from "./compat/reactI18next.js";
+import { REACT_INTL_CALLERS } from "./compat/reactIntl.js";
+import { USE_INTL_CALLERS } from "./compat/useIntl.js";
+import { VUE_I18N_CALLERS } from "./compat/vueI18n.js";
+import { SwcExtraCallerConfig, getRewritableCallers, toSwcExtraCallers } from "./transform.js";
+
+//#region src/callers/index.d.ts
+/**
+ * Compat-adapter callers, grouped in one list. Each compat package's bundler
+ * plugin injects its own slice (e.g. `REACT_I18NEXT_CALLERS`) into the build
+ * pipeline; this aggregate exists for consumers that need every syntax at
+ * once, such as the LSP.
+ */
+declare const COMPAT_CALLERS: CallerDescriptor[];
+/** Base + compat callers — the full registry the matchers run against. */
+declare const ALL_CALLERS: CallerDescriptor[];
+/**
+ * Descriptors indexed by caller name. A name can map to several descriptors
+ * (e.g. `Trans` exists in both react-i18next and lingui with different
+ * attributes); matchers try them in registry order.
+ */
+declare const CALLERS_BY_NAME: Map<string, CallerDescriptor[]>;
+/**
+ * Caller names whose dictionary key can appear as a positional string literal
+ * argument (`caller('key', …)` / `caller(locale, 'key', …)`). Used to build
+ * text-search regexes over project source files (find-references) and the
+ * completion trigger pattern. Callers whose key never appears positionally
+ * (fixed namespace, options object, JSX-only) are excluded on purpose.
+ */
+declare const getPositionalKeyCallerNames: () => string[];
+/**
+ * Returns `true` when the descriptor may participate in matching for a file
+ * importing from `importSources`. Descriptors flagged `requiresImport` only
+ * activate when the file imports from one of their declared modules;
+ * everything else is always active (results are still validated against the
+ * project's dictionaries downstream).
+ *
+ * @param descriptor - The caller descriptor to gate.
+ * @param fileImportSources - Module specifiers imported by the analysed file.
+ */
+declare const isCallerActive: (descriptor: CallerDescriptor, fileImportSources: ReadonlySet<string>) => boolean;
+//#endregion
+export { ALL_CALLERS, BASE_CALLERS, CALLERS_BY_NAME, COMPAT_CALLERS, type CallerDescriptor, type CallerResultShape, type CallerValueSource, I18NEXT_CALLERS, LINGUI_CALLERS, NEXT_INTL_CALLERS, REACT_I18NEXT_CALLERS, REACT_INTL_CALLERS, type SwcExtraCallerConfig, USE_INTL_CALLERS, VUE_I18N_CALLERS, getPositionalKeyCallerNames, getRewritableCallers, isCallerActive, toSwcExtraCallers };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/callers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/callers/index.ts"],"mappings":";;;;;;;;;;;;;AAmCA;;;;;cAAa,cAAA,EAAgB,gBAAA;;cAWhB,WAAA,EAAa,gBAAA;;;AAU1B;;;cAAa,eAAA,EAAiB,GAAA,SAAY,gBAAA;;AAuB1C;;;;;AAwBA;cAxBa,2BAAA;;;;;;;;;;;cAwBA,cAAA,GACX,UAAA,EAAY,gBAAA,EACZ,iBAAA,EAAmB,WAAA"}

package/dist/types/callers/transform.d.ts

@@ -0,0 +1,57 @@
+import { CallerDescriptor } from "./types.js";
+
+//#region src/callers/transform.d.ts
+/**
+ * Wire format of an extra caller forwarded to the `@intlayer/swc` plugin.
+ *
+ * Field names mirror the serde attributes of `ExtraCallerConfig` in
+ * `packages/@intlayer/swc/src/lib.rs` — both sides must stay in sync.
+ */
+type SwcExtraCallerConfig = {
+  /** The function name the user calls, e.g. `"useTranslation"`. */callerName: string; /** Module specifiers exporting the function (original + `@intlayer/*`). */
+  importSources: string[];
+  /**
+   * Zero-based index of the positional argument holding the namespace string.
+   * Omitted for fixed/option namespace callers.
+   */
+  namespaceArgIndex?: number;
+  /**
+   * Compile-time constant namespace — the dictionary ident is inserted as a
+   * new first argument (lingui's `useLingui()`).
+   */
+  fixedNamespace?: string;
+  /**
+   * Namespace read from a property of an options-object argument — the
+   * dictionary ident is inserted as a new first argument and the property is
+   * rewritten to the key-prefix remainder (vue-i18n's `useI18n({ namespace })`).
+   */
+  namespaceOption?: {
+    argumentIndex: number;
+    property: string;
+  }; /** Replacement function name for static import mode, e.g. `"useDictionary"`. */
+  staticReplacement: string; /** Replacement function name for dynamic/fetch mode, e.g. `"useDictionaryDynamic"`. */
+  dynamicReplacement: string;
+};
+/**
+ * Returns the callers of a registry slice that the optimize pass can rewrite
+ * at build time: plain imported functions carrying both replacement names.
+ *
+ * Method-matched callers (`i18n.getFixedT`) and JSX components are excluded —
+ * their call sites cannot be re-pointed through an import specifier rename.
+ */
+declare const getRewritableCallers: (descriptors: CallerDescriptor[]) => CallerDescriptor[];
+/**
+ * Serialises the rewritable callers of a registry slice into the
+ * `@intlayer/swc` plugin wire format (`extraCallers` option).
+ *
+ * Callers whose namespace can only be derived per-message id
+ * (`path-first-segment`) are skipped: the transform cannot bind a single
+ * dictionary to the call site.
+ *
+ * @param descriptors - Registry slice, e.g. `REACT_I18NEXT_CALLERS`.
+ * @returns Configs ready to pass as `swcExtraCallers` / `extraCallers`.
+ */
+declare const toSwcExtraCallers: (descriptors: CallerDescriptor[]) => SwcExtraCallerConfig[];
+//#endregion
+export { SwcExtraCallerConfig, getRewritableCallers, toSwcExtraCallers };
+//# sourceMappingURL=transform.d.ts.map

package/dist/types/callers/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","names":[],"sources":["../../../src/callers/transform.ts"],"mappings":";;;;;AAQA;;;;KAAY,oBAAA;EAIV,iEAFA,UAAA,UAYA;EAVA,aAAA;EAgBoB;;;;EAXpB,iBAAA;EAekB;AAUpB;;;EApBE,cAAA;EAqBa;;;;;EAfb,eAAA;IAAoB,aAAA;IAAuB,QAAA;EAAA,GA8C9B;EA5Cb,iBAAA,UA6CC;EA3CD,kBAAA;AAAA;;;;;;;;cAUW,oBAAA,GACX,WAAA,EAAa,gBAAA,OACZ,gBAAA;;;;;;;;;;;;cA6BU,iBAAA,GACX,WAAA,EAAa,gBAAA,OACZ,oBAAA"}

package/dist/types/callers/types.d.ts

@@ -0,0 +1,152 @@
+//#region src/callers/types.d.ts
+/**
+ * Shared caller-descriptor model.
+ *
+ * A "caller" is any function or JSX component through which application code
+ * reads intlayer content: the base getters (`useIntlayer`, `getIntlayer`) and
+ * every compat-adapter entry point (`useTranslation`, `useTranslations`,
+ * `formatMessage`, lingui's `t`/`_`, …).
+ *
+ * This registry is the single source of truth consumed by:
+ * - `@intlayer/babel` — field-usage analysis (purge/minify) and the optimize
+ *   pass that rewrites caller invocations to `useDictionary(...)` /
+ *   `useDictionaryDynamic(...)` with pre-imported dictionaries.
+ * - `@intlayer/swc` — the same optimize pass for Next.js builds; descriptors
+ *   are serialised to the plugin's wire format via `toSwcExtraCallers`.
+ * - `@intlayer/lsp` and the VS Code extension — AST/regex matchers powering
+ *   go-to-definition, references and completion.
+ * - Each compat package's bundler plugin — injects its library's descriptors
+ *   into the pipelines above, so no compat-specific name is hard-coded in the
+ *   core packages.
+ */
+/**
+ * Where a value (namespace/dictionary key, or key prefix) is read from a call
+ * expression.
+ */
+type CallerValueSource = /** Positional argument holding a string literal, e.g. `useTranslations('ns')`. */{
+  from: 'argument';
+  index: number;
+} /** Property of an options-object argument, e.g. `useI18n({ namespace: 'ns' })`. */ | {
+  from: 'option';
+  argumentIndex: number;
+  property: string;
+}
+/**
+ * Compile-time constant — every call site reads the same dictionary.
+ * Used by single-catalog libraries such as lingui (`messages`).
+ */
+| {
+  from: 'fixed';
+  value: string;
+}
+/**
+ * The first dot-segment of the message id passed to the call itself.
+ * Used by react-intl where `formatMessage({ id: 'home.title' })` encodes
+ * both the dictionary key (`home`) and the field path (`title`).
+ */
+| {
+  from: 'path-first-segment';
+};
+/**
+ * How translated content is obtained from the caller's result.
+ *
+ * - `'content'`        — returns the dictionary content object; fields are
+ *                        read through member access or destructuring
+ *                        (`useIntlayer`, `getIntlayer`).
+ * - `'return-value'`   — returns the translation function directly:
+ *                        `const t = useTranslations('ns'); t('key')`.
+ * - `'destructured-t'` — returns an object holding `t`:
+ *                        `const { t } = useTranslation('ns'); t('key')`.
+ * - `'self'`           — the caller IS the translation call; the message id is
+ *                        one of its own arguments (`formatMessage`, `i18n._`).
+ * - `'all'`            — field-level analysis is impossible; the whole
+ *                        dictionary is marked as used (Angular templates,
+ *                        lingui hashed ids).
+ */
+type CallerResultShape = 'content' | 'return-value' | 'destructured-t' | 'self' | 'all';
+/**
+ * Full description of a single caller.
+ */
+type CallerDescriptor = {
+  /** Function or JSX component name, e.g. `'useTranslation'`, `'FormattedMessage'`. */callerName: string; /** Library identifier grouping related callers, e.g. `'react-i18next'`. */
+  library: string;
+  /**
+   * Module specifiers the caller may be imported from. Includes both the
+   * original library names and the `@intlayer/*` adapter equivalents, because
+   * bundler aliasing keeps user imports on the original names.
+   */
+  importSources: string[];
+  /**
+   * When `true`, the caller only participates in matching when the analysed
+   * file imports from one of `importSources`. Used for generic names such as
+   * lingui's `t` / `_` that would otherwise produce false positives.
+   */
+  requiresImport?: boolean;
+  /**
+   * When `true`, the caller is also matched as a method on any object
+   * (`i18n.getFixedT(...)`, `intl.formatMessage(...)`) in addition to the
+   * bare-identifier form.
+   */
+  matchAsMethod?: boolean; /** When `true`, also match the tagged-template form, e.g. lingui's ``t`…` ``. */
+  matchAsTaggedTemplate?: boolean;
+  /**
+   * When set, the caller is also matched as a JSX element whose attribute of
+   * this name holds the message id, e.g. `<FormattedMessage id="home.title" />`
+   * or `<Trans i18nKey="richText" />`.
+   */
+  jsxIdAttribute?: string;
+  /**
+   * Optional JSX attribute carrying the namespace (dictionary key), e.g.
+   * react-i18next's `<Trans ns="home" i18nKey="title" />`.
+   */
+  jsxNamespaceAttribute?: string;
+  /**
+   * Where the dictionary key is read from, tried in declaration order.
+   * The first source that yields a static string wins.
+   */
+  namespaceSources: CallerValueSource[];
+  /**
+   * Optional key prefix prepended to every message path resolved through the
+   * returned translation function, e.g. `getFixedT(lng, ns, keyPrefix)` or
+   * `useTranslation(ns, { keyPrefix })`.
+   */
+  keyPrefixSources?: CallerValueSource[];
+  /**
+   * When `true`, a dotted namespace is split at the first `.`: the first
+   * segment is the dictionary key and the rest becomes a key prefix.
+   * next-intl semantics: `useTranslations('about.counter')` reads the
+   * `about` dictionary with every `t()` path prefixed by `counter`.
+   */
+  nestedNamespace?: boolean;
+  /**
+   * When `true`, the caller may be invoked without any namespace
+   * (`useTranslations()` root scope) — the dictionary key is then the first
+   * dot-segment of each message id passed to the returned `t()`.
+   */
+  allowRootScope?: boolean; /** How translated content is obtained from the caller's result. */
+  translationFunction: CallerResultShape;
+  /**
+   * When `true`, the message id is a *flat* dictionary field that itself may
+   * contain dots (lingui catalogs). When unset, dotted ids map onto nested
+   * dictionary objects and are split into a field path.
+   */
+  flatKey?: boolean;
+  /**
+   * Name of the dictionary-accepting replacement used by the optimize pass in
+   * static import mode, e.g. `'useDictionary'`. The replacement must be
+   * exported from every module in `importSources` (the compat package exports
+   * it; original-library specifiers are bundler-aliased to the compat package).
+   *
+   * Only callers with both replacements set — and matched as plain imported
+   * functions (not `matchAsMethod` / JSX) — are rewritten at build time.
+   */
+  staticReplacement?: string;
+  /**
+   * Name of the dictionary-accepting replacement used by the optimize pass in
+   * dynamic/fetch import mode, e.g. `'useDictionaryDynamic'`.
+   */
+  dynamicReplacement?: string;
+};
+//#endregion
+export { CallerDescriptor, CallerResultShape, CallerValueSource };
+//# sourceMappingURL=types.d.ts.map

package/dist/types/callers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/callers/types.ts"],"mappings":";;AAyBA;;;;;;;;;;;;;;AAiCA;;;;;AAUA;;;;AAAA,KA3CY,iBAAA;EAEN,IAAA;EAAkB,KAAA;AAAA;EAElB,IAAA;EAAgB,aAAA;EAAuB,QAAA;AAAA;;;;;;EAKvC,IAAA;EAAe,KAAA;AAAA;;;;;;;EAMf,IAAA;AAAA;;;;;;;;;;;;;;;;;KAkBM,iBAAA;;;;KAUA,gBAAA;uFAEV,UAAA;EAEA,OAAA;;;;;;EAMA,aAAA;;;;;;EAMA,cAAA;;;;;;EAMA,aAAA;EAEA,qBAAA;;;;;;EAMA,cAAA;;;;;EAKA,qBAAA;;;;;EAKA,gBAAA,EAAkB,iBAAA;;;;;;EAMlB,gBAAA,GAAmB,iBAAA;;;;;;;EAOnB,eAAA;;;;;;EAMA,cAAA;EAEA,mBAAA,EAAqB,iBAAA;;;;;;EAMrB,OAAA;;;;;;;;;;EAUA,iBAAA;;;;;EAKA,kBAAA;AAAA"}

package/dist/types/configFile/configurationSchema.d.ts

@@ -20,9 +20,9 @@ declare const cookiesAttributesSchema: z.ZodObject<{
   secure: z.ZodOptional<z.ZodBoolean>;
   httpOnly: z.ZodOptional<z.ZodBoolean>;
   sameSite: z.ZodOptional<z.ZodEnum<{
+    none: "none";
     strict: "strict";
     lax: "lax";
-    none: "none";
   }>>;
   expires: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Date, Date>, z.ZodNumber, z.ZodString]>>;
   maxAge: z.ZodOptional<z.ZodNumber>;
@@ -48,9 +48,9 @@ declare const storageSchema: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodEnum
   secure: z.ZodOptional<z.ZodBoolean>;
   httpOnly: z.ZodOptional<z.ZodBoolean>;
   sameSite: z.ZodOptional<z.ZodEnum<{
+    none: "none";
     strict: "strict";
     lax: "lax";
-    none: "none";
   }>>;
   expires: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Date, Date>, z.ZodNumber, z.ZodString]>>;
   maxAge: z.ZodOptional<z.ZodNumber>;
@@ -74,9 +74,9 @@ declare const storageSchema: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodEnum
   secure: z.ZodOptional<z.ZodBoolean>;
   httpOnly: z.ZodOptional<z.ZodBoolean>;
   sameSite: z.ZodOptional<z.ZodEnum<{
+    none: "none";
     strict: "strict";
     lax: "lax";
-    none: "none";
   }>>;
   expires: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Date, Date>, z.ZodNumber, z.ZodString]>>;
   maxAge: z.ZodOptional<z.ZodNumber>;
@@ -159,9 +159,9 @@ declare const routingSchema: z.ZodObject<{
     secure: z.ZodOptional<z.ZodBoolean>;
     httpOnly: z.ZodOptional<z.ZodBoolean>;
     sameSite: z.ZodOptional<z.ZodEnum<{
+      none: "none";
       strict: "strict";
       lax: "lax";
-      none: "none";
     }>>;
     expires: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Date, Date>, z.ZodNumber, z.ZodString]>>;
     maxAge: z.ZodOptional<z.ZodNumber>;
@@ -185,9 +185,9 @@ declare const routingSchema: z.ZodObject<{
     secure: z.ZodOptional<z.ZodBoolean>;
     httpOnly: z.ZodOptional<z.ZodBoolean>;
     sameSite: z.ZodOptional<z.ZodEnum<{
+      none: "none";
       strict: "strict";
       lax: "lax";
-      none: "none";
     }>>;
     expires: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Date, Date>, z.ZodNumber, z.ZodString]>>;
     maxAge: z.ZodOptional<z.ZodNumber>;
@@ -357,9 +357,9 @@ declare const intlayerConfigSchema: z.ZodObject<{
       secure: z.ZodOptional<z.ZodBoolean>;
       httpOnly: z.ZodOptional<z.ZodBoolean>;
       sameSite: z.ZodOptional<z.ZodEnum<{
+        none: "none";
         strict: "strict";
         lax: "lax";
-        none: "none";
       }>>;
       expires: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Date, Date>, z.ZodNumber, z.ZodString]>>;
       maxAge: z.ZodOptional<z.ZodNumber>;
@@ -383,9 +383,9 @@ declare const intlayerConfigSchema: z.ZodObject<{
       secure: z.ZodOptional<z.ZodBoolean>;
       httpOnly: z.ZodOptional<z.ZodBoolean>;
       sameSite: z.ZodOptional<z.ZodEnum<{
+        none: "none";
         strict: "strict";
         lax: "lax";
-        none: "none";
       }>>;
       expires: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Date, Date>, z.ZodNumber, z.ZodString]>>;
       maxAge: z.ZodOptional<z.ZodNumber>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/config",
-  "version": "9.0.0-canary.10",
+  "version": "9.0.0-canary.12",
   "private": false,
   "description": "Retrieve Intlayer configurations and manage environment variables for both server-side and client-side environments.",
   "keywords": [
@@ -53,6 +53,11 @@
       "require": "./dist/cjs/built.cjs",
       "import": "./dist/esm/built.mjs"
     },
+    "./callers": {
+      "types": "./dist/types/callers/index.d.ts",
+      "import": "./dist/esm/callers/index.mjs",
+      "require": "./dist/cjs/callers/index.cjs"
+    },
     "./utils": {
       "types": "./dist/types/utils/index.d.ts",
       "require": "./dist/cjs/utils/index.cjs",
@@ -160,7 +165,7 @@
     "typecheck": "tsc --noEmit --project tsconfig.types.json"
   },
   "dependencies": {
-    "@intlayer/types": "9.0.0-canary.10",
+    "@intlayer/types": "9.0.0-canary.12",
     "defu": "6.1.7",
     "dotenv": "17.4.2",
     "esbuild": "0.28.1",