@intlayer/config 9.0.0-canary.11 → 9.0.0-canary.14

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

@@ -278,8 +278,8 @@ declare const buildSchema: z.ZodObject<{
   }>>;
   traversePattern: z.ZodOptional<z.ZodArray<z.ZodString>>;
   outputFormat: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-    esm: "esm";
     cjs: "cjs";
+    esm: "esm";
   }>>>;
   cache: z.ZodOptional<z.ZodBoolean>;
   require: z.ZodOptional<z.ZodUnknown>;
@@ -476,8 +476,8 @@ declare const intlayerConfigSchema: z.ZodObject<{
     }>>;
     traversePattern: z.ZodOptional<z.ZodArray<z.ZodString>>;
     outputFormat: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-      esm: "esm";
       cjs: "cjs";
+      esm: "esm";
     }>>>;
     cache: z.ZodOptional<z.ZodBoolean>;
     require: z.ZodOptional<z.ZodUnknown>;

package/dist/types/loadEnvFile.d.ts

@@ -4,7 +4,7 @@ type LoadEnvFileOptions = {
   envFile?: string;
 };
 declare const getEnvFilePath: (env?: string, envFile?: string) => string | undefined;
-declare const loadEnvFile: (options?: Partial<LoadEnvFileOptions>) => {};
+declare const loadEnvFile: (options?: Partial<LoadEnvFileOptions>) => Record<string, string>;
 //#endregion
 export { LoadEnvFileOptions, getEnvFilePath, loadEnvFile };
 //# sourceMappingURL=loadEnvFile.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"loadEnvFile.d.ts","names":[],"sources":["../../src/loadEnvFile.ts"],"mappings":";KAKY,kBAAA;EACV,GAAA;EACA,OAAA;AAAA;AAAA,cAGW,cAAA,GACX,GAAA,WACA,OAAA;AAAA,cASW,WAAA,GAAe,OAAA,GAAU,OAAA,CAAQ,kBAAA"}
+{"version":3,"file":"loadEnvFile.d.ts","names":[],"sources":["../../src/loadEnvFile.ts"],"mappings":";KAKY,kBAAA;EACV,GAAA;EACA,OAAA;AAAA;AAAA,cAGW,cAAA,GACX,GAAA,WACA,OAAA;AAAA,cAuCW,WAAA,GACX,OAAA,GAAU,OAAA,CAAQ,kBAAA,MACjB,MAAA"}

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

@@ -1,6 +1,6 @@
 import { SandBoxContextOptions, getSandBoxContext, parseFileContent } from "./parseFileContent.js";
-import { TranspileOptions, transpileTSToCJS, transpileTSToCJSSync } from "./transpileTSToCJS.js";
+import { TranspileOptions, clearTranspileCache, transpileTSToCJS, transpileTSToCJSSync } from "./transpileTSToCJS.js";
 import { LoadExternalFileOptions, loadExternalFile, loadExternalFileSync } from "./loadExternalFile.js";
 import { ESBuildPlugin, bundleFile, bundleFileSync, getLoader } from "./bundleFile.js";
 import { bundleJSFile } from "./bundleJSFile.js";
-export { ESBuildPlugin, LoadExternalFileOptions, SandBoxContextOptions, TranspileOptions, bundleFile, bundleFileSync, bundleJSFile, getLoader, getSandBoxContext, loadExternalFile, loadExternalFileSync, parseFileContent, transpileTSToCJS, transpileTSToCJSSync };
+export { ESBuildPlugin, LoadExternalFileOptions, SandBoxContextOptions, TranspileOptions, bundleFile, bundleFileSync, bundleJSFile, clearTranspileCache, getLoader, getSandBoxContext, loadExternalFile, loadExternalFileSync, parseFileContent, transpileTSToCJS, transpileTSToCJSSync };

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

@@ -1 +1 @@
-{"version":3,"file":"loadExternalFile.d.ts","names":[],"sources":["../../../src/loadExternalFile/loadExternalFile.ts"],"mappings":";;;;;KAmBY,uBAAA;EACV,aAAA,GAAgB,cAAA;EAChB,YAAA,GAAe,gBAAA;EACf,QAAA;;;;;;;;EAQA,cAAA,GAAiB,MAAA;AAAA,IACf,qBAAA;;;;;;cAOS,oBAAA,GACX,QAAA,UACA,OAAA,GAAU,uBAAA;;;AAFZ;;;cAyFa,gBAAA,GACX,QAAA,UACA,OAAA,GAAU,uBAAA,KACT,OAAA"}
+{"version":3,"file":"loadExternalFile.d.ts","names":[],"sources":["../../../src/loadExternalFile/loadExternalFile.ts"],"mappings":";;;;;KAmBY,uBAAA;EACV,aAAA,GAAgB,cAAA;EAChB,YAAA,GAAe,gBAAA;EACf,QAAA;;;;;;;;EAQA,cAAA,GAAiB,MAAA;AAAA,IACf,qBAAA;;;;;;cAOS,oBAAA,GACX,QAAA,UACA,OAAA,GAAU,uBAAA;;;AAFZ;;;cAiGa,gBAAA,GACX,QAAA,UACA,OAAA,GAAU,uBAAA,KACT,OAAA"}

package/dist/types/loadExternalFile/parseFileContent.d.ts

@@ -22,6 +22,15 @@ type SandBoxContextOptions = {
    */
   aliases?: Record<string, string>;
 };
+/**
+ * Builds the global context handed to `runInNewContext`.
+ *
+ * SECURITY NOTE: this sandbox exists for global-scope hygiene (fresh
+ * module/exports, controlled env), NOT for containment. It exposes the real
+ * project `require`, a copy of `process`, and `fetch` — code executed here has
+ * full host privileges. Only ever run trusted, build-time project files
+ * (same trust model as `vite.config.ts`).
+ */
 declare const getSandBoxContext: (options?: SandBoxContextOptions) => Context;
 declare const parseFileContent: <T>(fileContentString: string, options?: SandBoxContextOptions) => T | undefined;
 //#endregion

package/dist/types/loadExternalFile/parseFileContent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseFileContent.d.ts","names":[],"sources":["../../../src/loadExternalFile/parseFileContent.ts"],"mappings":";;;;KAKY,qBAAA;EACV,aAAA,GAAgB,kBAAA;EAChB,cAAA,GAAiB,MAAA,CAAO,OAAA;EACxB,iBAAA,GAAoB,MAAA;;;;;;;;EAQpB,KAAA,GAAQ,MAAA;EAVR;;;;;;EAiBA,OAAA,GAAU,MAAA;AAAA;AAAA,cA6BC,iBAAA,GAAqB,OAAA,GAAU,qBAAA,KAAwB,OAAA;AAAA,cAgGvD,gBAAA,MACX,iBAAA,UACA,OAAA,GAAU,qBAAA,KACT,CAAA"}
+{"version":3,"file":"parseFileContent.d.ts","names":[],"sources":["../../../src/loadExternalFile/parseFileContent.ts"],"mappings":";;;;KAKY,qBAAA;EACV,aAAA,GAAgB,kBAAA;EAChB,cAAA,GAAiB,MAAA,CAAO,OAAA;EACxB,iBAAA,GAAoB,MAAA;;;;;;;;EAQpB,KAAA,GAAQ,MAAA;EAVR;;;;;;EAiBA,OAAA,GAAU,MAAA;AAAA;;;;;;AA2FZ;;;;cAAa,iBAAA,GAAqB,OAAA,GAAU,qBAAA,KAAwB,OAAA;AAAA,cAuEvD,gBAAA,MACX,iBAAA,UACA,OAAA,GAAU,qBAAA,KACT,CAAA"}

package/dist/types/loadExternalFile/transpileTSToCJS.d.ts

@@ -12,8 +12,10 @@ type TranspileOptions = BuildOptions & {
    */
   esbuildInstance?: typeof _$esbuild;
 };
+/** Clears the in-memory transpilation cache (mainly for tests). */
+declare const clearTranspileCache: () => void;
 declare const transpileTSToCJSSync: (code: string, filePath: string, options?: TranspileOptions) => string | undefined;
 declare const transpileTSToCJS: (code: string, filePath: string, options?: TranspileOptions) => Promise<string | undefined>;
 //#endregion
-export { TranspileOptions, transpileTSToCJS, transpileTSToCJSSync };
+export { TranspileOptions, clearTranspileCache, transpileTSToCJS, transpileTSToCJSSync };
 //# sourceMappingURL=transpileTSToCJS.d.ts.map

package/dist/types/loadExternalFile/transpileTSToCJS.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transpileTSToCJS.d.ts","names":[],"sources":["../../../src/loadExternalFile/transpileTSToCJS.ts"],"mappings":";;;;KAaY,gBAAA,GAAmB,YAAA;;;AAA/B;;;;;EAQE,eAAA,UARyC,SAAA;AAAA;AAAA,cA8C9B,oBAAA,GACX,IAAA,UACA,QAAA,UACA,OAAA,GAAU,gBAAA;AAAA,cAmEC,gBAAA,GACX,IAAA,UACA,QAAA,UACA,OAAA,GAAU,gBAAA,KACT,OAAA"}
+{"version":3,"file":"transpileTSToCJS.d.ts","names":[],"sources":["../../../src/loadExternalFile/transpileTSToCJS.ts"],"mappings":";;;;KAeY,gBAAA,GAAmB,YAAA;;;AAA/B;;;;;EAQE,eAAA,UARyC,SAAA;AAAA;;cAoL9B,mBAAA;AAAA,cAKA,oBAAA,GACX,IAAA,UACA,QAAA,UACA,OAAA,GAAU,gBAAA;AAAA,cAsFC,gBAAA,GACX,IAAA,UACA,QAAA,UACA,OAAA,GAAU,gBAAA,KACT,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/config",
-  "version": "9.0.0-canary.11",
+  "version": "9.0.0-canary.14",
   "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.11",
+    "@intlayer/types": "9.0.0-canary.14",
     "defu": "6.1.7",
     "dotenv": "17.4.2",
     "esbuild": "0.28.1",