feat: unproxy locale access

Author: ST-DDT

docs/.vitepress/components/api-docs/refreshable-code.vue

@@ -25,10 +25,13 @@ function initRefresh(): Element[] {
   let lineIndex = 0;
   const result: Element[] = [];
   while (lineIndex < domLines.length) {
-    // Skip empty and preparatory lines (no '^faker.' invocation)
+    // Skip empty and preparatory lines (no recorded invocation)
+    // Keep in sync with ref scripts/shared/refreshable-code.ts
     if (
       domLines[lineIndex]?.children.length === 0 ||
-      !/^\w*faker\w*\./i.test(domLines[lineIndex]?.textContent ?? '')
+      !/^\w*faker\w*\.|^\w+\((faker\.)?fakerCore/i.test(
+        domLines[lineIndex]?.textContent ?? ''
+      )
     ) {
       lineIndex++;
       continue;

scripts/apidocs/output/page.ts

@@ -23,18 +23,27 @@ editLink: false
  * @param pages The pages to write.
  */
 export async function writePages(pages: RawApiDocsPage[]): Promise<void> {
-  await Promise.all(pages.map(writePage));
+  const registryHints: Record<string, string> = Object.fromEntries(
+    pages.flatMap((page) =>
+      page.methods.map((method) => [method.name, page.camelTitle])
+    )
+  );
+  await Promise.all(pages.map((page) => writePage(page, registryHints)));
 }
 
 /**
  * Writes the api docs page and data for the given module to the correct location.
  *
  * @param page The page to write.
+ * @param registryHints Hints for accessing SMF via module registry.
  */
-async function writePage(page: RawApiDocsPage): Promise<void> {
+async function writePage(
+  page: RawApiDocsPage,
+  registryHints: Record<string, string> = {}
+): Promise<void> {
   try {
     await writePageMarkdown(page);
-    await writePageData(page);
+    await writePageData(page, registryHints);
   } catch (error) {
     throw new Error(`Error writing page ${page.title}`, { cause: error });
   }
@@ -98,20 +107,29 @@ async function writePageMarkdown(page: RawApiDocsPage): Promise<void> {
  * Writes the api docs data for the given module to correct location.
  *
  * @param page The page to write.
+ * @param registryHints Hints for accessing SMF via module registry.
  */
-async function writePageData(page: RawApiDocsPage): Promise<void> {
+async function writePageData(
+  page: RawApiDocsPage,
+  registryHints: Record<string, string> = {}
+): Promise<void> {
   const { camelTitle, methods } = page;
   const pageData: Record<string, ApiDocsMethod> = Object.fromEntries(
     await Promise.all(
       methods.map(async (method) => [method.name, await toMethodData(method)])
     )
   );
+  const priorizedRegistryHints = {
+    ...registryHints,
+    // own module > other modules
+    ...Object.fromEntries(methods.map((method) => [method.name, camelTitle])),
+  };
 
   const refreshFunctions: Record<string, string> = Object.fromEntries(
     await Promise.all(
       methods.map(async (method) => [
         method.name,
-        await toRefreshFunction(method),
+        await toRefreshFunction(method, priorizedRegistryHints),
       ])
     )
   );
@@ -213,12 +231,13 @@ export function extractSummaryDefault(description: string): string | undefined {
 }
 
 export async function toRefreshFunction(
-  method: RawApiDocsMethod
+  method: RawApiDocsMethod,
+  registryHints: Record<string, string> = {}
 ): Promise<string> {
   const { name, signatures } = method;
   const signatureData = required(signatures.at(-1), 'method signature');
   const { examples } = signatureData;
 
   const exampleCode = examples.join('\n');
-  return await toRefreshableCode(name, exampleCode);
+  return await toRefreshableCode(name, exampleCode, registryHints);
 }

scripts/shared/refreshable-code.ts

@@ -2,25 +2,38 @@ import { formatTypescript } from '../shared/format';
 
 export async function toRefreshableCode(
   name: string,
-  exampleCode: string
+  exampleCode: string,
+  moduleHints: Record<string, string> = {}
 ): Promise<string> {
-  if (!/^\w*faker\w*\./im.test(exampleCode)) {
-    // No recordable faker calls in examples
-    return 'undefined';
-  }
-
   const exampleLines = exampleCode
     .replaceAll(/ ?\/\/.*$/gm, '') // Remove comments
     .replaceAll(/^import .*$/gm, '') // Remove imports
+    .replaceAll(/\b(?<!\.)(\w+)\((faker\.)?fakerCore/g, (match, p1) => {
+      // Access SMF via module registry if possible
+      if (moduleHints[p1]) {
+        return `fakerRegistry.${moduleHints[p1]}.${match}`;
+      }
+
+      throw new Error(
+        `Unable to find module hint for ${p1} in example code for ${name}`
+      );
+    })
     .replaceAll(
-      // record results of faker calls
-      /^(\w*faker\w*\..+(?:(?:.|\n..)*\n[^ ])?\)(?:\.\w+)?);?$/gim,
+      // record results of relevant calls
+      // Keep in sync with docs/.vitepress/components/api-docs/refreshable-code.vue
+      /^((?<callBase>\w*faker\w*)\.(?<consumeToEOL>.+)(?<multiline>(?<consumeIndented>\n +.*)+(?<finalLine>\n[^ \n]+))?\)(?<nestedProperty>\.\w+)?);?$/gim,
       `try { result.push($1); } catch (error: unknown) { result.push(error instanceof Error ? error.name : 'Error'); }\n`
     );
 
+  if (!exampleLines.includes('try { result.push(')) {
+    // No recordable calls in examples
+    return 'undefined';
+  }
+
   const fullMethod = `async (): Promise<unknown[]> => {
 await enableFaker();
 const result: unknown[] = [];
+${/(?<!\.)fakerCore/.test(exampleCode) ? 'const fakerCore = faker.fakerCore;' : ''}
 
 ${exampleLines}
 

src/definitions/definitions.ts

@@ -29,29 +29,49 @@ export type LocaleEntry<TCategoryDefinition extends Record<string, unknown>> = {
 } & Record<string, unknown>; // Unsupported & custom entries
 
 /**
- * The definitions as used by the translations/locales.
+ * The internal types for the definitions.
  */
-export type LocaleDefinition = {
-  metadata?: MetadataDefinition;
-  airline?: AirlineDefinition;
-  animal?: AnimalDefinition;
-  book?: BookDefinition;
-  color?: ColorDefinition;
-  commerce?: CommerceDefinition;
-  company?: CompanyDefinition;
-  database?: DatabaseDefinition;
-  date?: DateDefinition;
-  finance?: FinanceDefinition;
-  food?: FoodDefinition;
-  hacker?: HackerDefinition;
-  internet?: InternetDefinition;
-  location?: LocationDefinition;
-  lorem?: LoremDefinition;
-  music?: MusicDefinition;
-  person?: PersonDefinition;
-  phone_number?: PhoneNumberDefinition;
-  science?: ScienceDefinition;
-  system?: SystemDefinition;
-  vehicle?: VehicleDefinition;
-  word?: WordDefinition;
-} & Record<string, Record<string, unknown>>;
+type RawLocaleDefinition = {
+  metadata: MetadataDefinition;
+  airline: AirlineDefinition;
+  animal: AnimalDefinition;
+  book: BookDefinition;
+  color: ColorDefinition;
+  commerce: CommerceDefinition;
+  company: CompanyDefinition;
+  database: DatabaseDefinition;
+  date: DateDefinition;
+  finance: FinanceDefinition;
+  food: FoodDefinition;
+  hacker: HackerDefinition;
+  internet: InternetDefinition;
+  location: LocationDefinition;
+  lorem: LoremDefinition;
+  music: MusicDefinition;
+  person: PersonDefinition;
+  phone_number: PhoneNumberDefinition;
+  science: ScienceDefinition;
+  system: SystemDefinition;
+  vehicle: VehicleDefinition;
+  word: WordDefinition;
+};
+
+/**
+ * Helper type to undo `LocaleEntry<T>` wrapping.
+ */
+type DefinedLocaleEntry<T> = T extends LocaleEntry<infer U> ? U : never;
+
+/**
+ * Helper type containing the well known locale definitions as used by this library, assuming all values are present.
+ *
+ * This type is mainly used for `resolveLocaleData()` to enable auto completion.
+ */
+export type DefinedLocaleDefinition = {
+  [K in keyof RawLocaleDefinition]: DefinedLocaleEntry<RawLocaleDefinition[K]>;
+};
+
+/**
+ * The extensible definitions as used by the translations/locales.
+ */
+export type LocaleDefinition = Partial<RawLocaleDefinition> &
+  Record<string, Record<string, unknown>>;

src/index.ts

@@ -84,9 +84,11 @@ export type { SystemModule } from './modules/system';
 export type { VehicleModule } from './modules/vehicle';
 export type { WordModule } from './modules/word';
 export type { Randomizer } from './randomizer';
+export { fakerRegistry } from './registry';
 export { SimpleFaker, simpleFaker } from './simple-faker';
 export { mergeLocales } from './utils/merge-locales';
 export {
   generateMersenne32Randomizer,
   generateMersenne53Randomizer,
 } from './utils/mersenne';
+export { resolveLocaleData } from './utils/resolve-locale-data';

src/registry.ts

@@ -0,0 +1,19 @@
+import type { FakerCore } from '.';
+import { utilsModule as utils } from './utils/registry';
+
+// TODO @ST-DDT 2026-04-12: This file will be auto generated in a future PR.
+
+/**
+ * Global Registry for the Faker library, containing all (SMF-aware) module registries.
+ */
+type FakerRegistry = Record<
+  string,
+  Record<string, (fakerCore: FakerCore, ...args: unknown[]) => unknown>
+>;
+
+/**
+ * Global Registry for the Faker library, containing all (SMF-aware) module registries.
+ */
+export const fakerRegistry = {
+  utils,
+} satisfies FakerRegistry;

src/utils/registry.ts

@@ -0,0 +1,9 @@
+import { resolveLocaleData } from './resolve-locale-data';
+
+// TODO @ST-DDT 2026-04-12: Add future SMF utils
+/**
+ * Registry Module containing (SMF-aware) utility functions for the Faker library.
+ */
+export const utilsModule = {
+  resolveLocaleData,
+};

src/utils/resolve-locale-data.ts

@@ -0,0 +1,59 @@
+import type { FakerCore } from '../core';
+import type { DefinedLocaleDefinition } from '../definitions/definitions';
+import { assertLocaleData } from '../internal/locale-proxy';
+
+/**
+ * Returns the locale data for the given category and entry.
+ *
+ * If the category or entry is missing or explicitly absent, an error is thrown.
+ *
+ * @template TCategory The category to get the locale data from.
+ * @template TEntry The entry to get the locale data from.
+ *
+ * @param core The core to get the locale data from.
+ * @param category  The category to get the locale data from.
+ * @param entry The entry to get the locale data from.
+ *
+ * @example
+ * resolveLocaleData(fakerCore, 'food', 'fruit'); // ['apple', 'apricot', ...]
+ * faker.helpers.arrayElement(resolveLocaleData(fakerCore, 'food', 'fruit')); // 'cherry'
+ *
+ * @since 10.5.0
+ */
+export function resolveLocaleData<
+  const TCategory extends keyof DefinedLocaleDefinition,
+  const TEntry extends keyof DefinedLocaleDefinition[TCategory],
+>(
+  core: FakerCore,
+  category: TCategory,
+  entry: TEntry
+): DefinedLocaleDefinition[TCategory][TEntry];
+/**
+ * Returns the locale data for the given category and entry.
+ *
+ * If the category or entry is missing or explicitly absent, an error is thrown.
+ *
+ * @param core The core to get the locale data from.
+ * @param category  The category to get the locale data from.
+ * @param entry The entry to get the locale data from.
+ *
+ * @example
+ * resolveLocaleData(fakerCore, 'food', 'fruit'); // ['apple', 'apricot', ...]
+ * faker.helpers.arrayElement(resolveLocaleData(fakerCore, 'food', 'fruit')); // 'cherry'
+ *
+ * @since 10.5.0
+ */
+export function resolveLocaleData(
+  core: FakerCore,
+  category: string,
+  entry: string
+): unknown;
+export function resolveLocaleData(
+  core: FakerCore,
+  category: string,
+  entry: string
+): unknown {
+  const value = core.locale[category]?.[entry];
+  assertLocaleData(value, category, entry);
+  return value;
+}

test/scripts/apidocs/__snapshots__/page.spec.ts.snap

@@ -1,5 +1,23 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`toRefreshFunction > should handle SMF calls 1`] = `
+"async (): Promise<unknown[]> => {
+  await enableFaker();
+  const result: unknown[] = [];
+  const fakerCore = faker.fakerCore;
+
+  try {
+    result.push(
+      fakerRegistry.utils.resolveLocaleData(fakerCore, 'food', 'fruit')
+    );
+  } catch (error: unknown) {
+    result.push(error instanceof Error ? error.name : 'Error');
+  }
+
+  return result;
+}"
+`;
+
 exports[`toRefreshFunction > should handle multiline calls 1`] = `
 "async (): Promise<unknown[]> => {
   await enableFaker();

test/scripts/apidocs/__snapshots__/verify-jsdoc-tags.spec.ts.snap

@@ -32,6 +32,7 @@ exports[`check docs completeness > all modules and methods are present 1`] = `
       "generateMersenne32Randomizer",
       "generateMersenne53Randomizer",
       "mergeLocales",
+      "resolveLocaleData",
     ],
   ],
   [