feat: add first standalone module functions

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

@@ -28,7 +28,7 @@ function initRefresh(): Element[] {
     // Keep in sync with ref scripts/shared/refreshable-code.ts
     if (
       domLines[lineIndex]?.children.length === 0 ||
-      !/^\w*faker\w*\.|^distributor\(/i.test(
+      !/^\w*faker\w*\.|^\w+\(fakerCore|^distributor\(/i.test(
         domLines[lineIndex]?.textContent ?? ''
       )
     ) {

scripts/apidocs/output/page.ts

@@ -28,18 +28,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 standalone functions 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 });
   }
@@ -103,20 +112,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 standalone functions 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 prioritizedRegistryHints = {
+    ...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, prioritizedRegistryHints),
       ])
     )
   );
@@ -218,12 +236,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,16 +2,32 @@ import { formatTypescript } from '../shared/format';
 
 export async function toRefreshableCode(
   name: string,
-  exampleCode: string
+  exampleCode: string,
+  moduleHints: Record<string, string> = {}
 ): Promise<string> {
   const exampleLines = exampleCode
     .replaceAll(/ ?\/\/.*$/gm, '') // Remove comments
     .replaceAll(/^import .*$/gm, '') // Remove imports
     .replaceAll(
-      // record results of relevant calls
       // Keep in sync with docs/.vitepress/components/api-docs/refreshable-code.vue
-      /^(\w*faker\w*\..+(?:(?:.|\n..)*\n[^ ])?\)(?:\.\w+)?|distributor\(.+\));?$/gim,
-      `try { result.push($1); } catch (error: unknown) { result.push(error instanceof Error ? error.name : 'Error'); }\n`
+      /\b(?<!\.)(\w+)\((faker\.)?fakerCore/g,
+      (match, p1) => {
+        // Access standalone functions via module registry if possible
+        // firstName(fakerCore) -> fakerRegistry.person.firstName(fakerCore)
+        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 relevant calls
+      // Keep in sync with docs/.vitepress/components/api-docs/refreshable-code.vue
+      /^((?<callBase>\w*faker\w*\.|distributor\()(?<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'); console.log('Error in example for ${name}:', error); }\n`
     );
 
   if (!exampleLines.includes('try { result.push(')) {
@@ -22,9 +38,18 @@ export async function toRefreshableCode(
   const fullMethod = `async (): Promise<unknown[]> => {
 await enableFaker();
 const result: unknown[] = [];
+${/(?<!\.)fakerCore/.test(exampleCode) ? 'const fakerCore = faker.fakerCore;' : ''}
+${
+  // TODO @ST-DDT 2026-04-23: Remove when past is transformed into standalone function
+  exampleCode.includes('past(fakerCore')
+    ? 'fakerRegistry.date = { past: (fakerCore) => new SimpleFaker(fakerCore).date.past() };'
+    : ''
+}
 
 ${exampleLines}
 
+${exampleCode.includes('setDefaultRefDate(') ? 'faker.setDefaultRefDate(); // Reset' : ''}
+
 return result;
 }`;
   try {

src/index.ts

@@ -87,6 +87,7 @@ 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 {

src/registry.ts

@@ -0,0 +1,16 @@
+import type { FakerRegistry } from './registry.types';
+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 module registries with their standalone module functions.
+ *
+ * You normally don't need to access this registry unless you want to call `fake()` or other custom code needing to lookup standalone functions.
+ *
+ * @example
+ * fake(fakerCore, 'The date is {{utils.getDefaultRefDate}}', [ fakerRegistry, fakerCore.locale.raw ]);
+ */
+export const fakerRegistry = {
+  utils,
+} as const satisfies FakerRegistry;

src/registry.types.ts

@@ -0,0 +1,11 @@
+import type { FakerCore } from './core';
+
+/**
+ * Global Registry for the Faker library, containing all module registries.
+ */
+export type FakerRegistry = Record<string, ModuleRegistry>;
+
+/**
+ * Per module registry containing the module's standalone functions.
+ */
+export type ModuleRegistry = Record<string, (fakerCore: FakerCore) => unknown>;

src/simple-faker.ts

@@ -7,8 +7,8 @@ import { SimpleHelpersModule } from './modules/helpers';
 import { SimpleLocationModule } from './modules/location';
 import { NumberModule } from './modules/number';
 import { StringModule } from './modules/string';
-
-export const DEFAULT_REF_DATE_SOURCE: () => Date = () => new Date();
+import { getDefaultRefDate } from './utils/get-default-ref-date';
+import { setDefaultRefDate as utilsSetDefaultRefDate } from './utils/set-default-ref-date';
 
 /**
  * This is a simplified Faker class that doesn't need any localized data to generate its output.
@@ -42,7 +42,7 @@ export class SimpleFaker {
    * Gets a new reference date used to generate relative dates.
    */
   get defaultRefDate(): () => Date {
-    return this.fakerCore.config.defaultRefDate ?? DEFAULT_REF_DATE_SOURCE;
+    return () => getDefaultRefDate(this.fakerCore);
   }
 
   /**
@@ -81,11 +81,7 @@ export class SimpleFaker {
   setDefaultRefDate(
     dateOrSource: string | Date | number | (() => Date) = () => new Date()
   ): void {
-    if (typeof dateOrSource === 'function') {
-      this.fakerCore.config.defaultRefDate = dateOrSource;
-    } else {
-      this.fakerCore.config.defaultRefDate = () => new Date(dateOrSource);
-    }
+    utilsSetDefaultRefDate(this.fakerCore, dateOrSource);
   }
 
   readonly datatype: DatatypeModule = new DatatypeModule(this);

src/utils/get-default-ref-date.ts

@@ -0,0 +1,39 @@
+import type { FakerCore } from '../core';
+
+export const DEFAULT_REF_DATE_SOURCE: () => Date = () => new Date();
+
+/**
+ * Gets a new reference date used to generate relative dates.
+ *
+ * If `fakerCore.config.defaultRefDate` is defined, it will be used to get the default reference date. Otherwise, the current date will be used.
+ *
+ * @param fakerCore The FakerCore instance to get it from.
+ *
+ * @returns The newly created default reference date.
+ *
+ * @example
+ * fakerCore.randomizer.seed(1234);
+ *
+ * // Default behavior
+ * // setDefaultRefDate(fakerCore);
+ * past(fakerCore); // Changes based on the current date/time
+ *
+ * // Use a static ref date
+ * setDefaultRefDate(fakerCore, new Date('2020-01-01'));
+ * past(fakerCore); // Reproducible '2019-07-03T08:27:58.118Z'
+ *
+ * // Use a ref date that changes every time it is used
+ * let clock = new Date("2020-01-01").getTime();
+ * setDefaultRefDate(fakerCore, () => {
+ *   clock += 1000; // +1s
+ *   return new Date(clock);
+ * });
+ *
+ * getDefaultRefDate(fakerCore) // 2020-01-01T00:00:01Z
+ * getDefaultRefDate(fakerCore) // 2020-01-01T00:00:02Z
+ *
+ * @since 10.5.0
+ */
+export function getDefaultRefDate(fakerCore: FakerCore): Date {
+  return fakerCore.config.defaultRefDate?.() ?? DEFAULT_REF_DATE_SOURCE();
+}

src/utils/registry.ts

@@ -0,0 +1,11 @@
+import type { ModuleRegistry } from '../registry.types';
+import { getDefaultRefDate } from './get-default-ref-date';
+import { setDefaultRefDate } from './set-default-ref-date';
+
+/**
+ * Registry module containing all standalone utility functions for the Faker library.
+ */
+export const utilsModule = {
+  getDefaultRefDate,
+  setDefaultRefDate,
+} as const satisfies ModuleRegistry;

src/utils/set-default-ref-date.ts

@@ -0,0 +1,46 @@
+import type { FakerCore } from '../core';
+
+/**
+ * Sets the `refDate` source to use if no `refDate` date is passed to the date methods.
+ *
+ * @param fakerCore The FakerCore instance to use.
+ * @param dateOrSource The function or the static value used to generate the `refDate` date instance.
+ * The function must return a new valid `Date` instance for every call.
+ * Defaults to `() => new Date()`.
+ *
+ * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
+ * @see faker.seed(): For generating reproducible values.
+ *
+ * @example
+ * fakerCore.randomizer.seed(1234);
+ *
+ * // Default behavior
+ * // setDefaultRefDate(fakerCore);
+ * past(fakerCore); // Changes based on the current date/time
+ *
+ * // Use a static ref date
+ * setDefaultRefDate(fakerCore, new Date('2020-01-01'));
+ * past(fakerCore); // Reproducible '2019-07-03T08:27:58.118Z'
+ *
+ * // Use a ref date that changes every time it is used
+ * let clock = new Date("2020-01-01").getTime();
+ * setDefaultRefDate(fakerCore, () => {
+ *   clock += 1000; // +1s
+ *   return new Date(clock);
+ * });
+ *
+ * getDefaultRefDate(fakerCore) // 2020-01-01T00:00:01Z
+ * getDefaultRefDate(fakerCore) // 2020-01-01T00:00:02Z
+ *
+ * @since 10.5.0
+ */
+export function setDefaultRefDate(
+  fakerCore: FakerCore,
+  dateOrSource: string | Date | number | (() => Date) = () => new Date()
+): void {
+  if (typeof dateOrSource === 'function') {
+    fakerCore.config.defaultRefDate = dateOrSource;
+  } else {
+    fakerCore.config.defaultRefDate = () => new Date(dateOrSource);
+  }
+}

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

@@ -14,6 +14,7 @@ exports[`toRefreshFunction > should handle multiline calls 1`] = `
     );
   } catch (error: unknown) {
     result.push(error instanceof Error ? error.name : 'Error');
+    console.log('Error in example for test:', error);
   }
 
   return result;
@@ -29,12 +30,14 @@ exports[`toRefreshFunction > should handle multiple calls 1`] = `
     result.push(faker.number.int());
   } catch (error: unknown) {
     result.push(error instanceof Error ? error.name : 'Error');
+    console.log('Error in example for test:', error);
   }
 
   try {
     result.push(faker.number.int());
   } catch (error: unknown) {
     result.push(error instanceof Error ? error.name : 'Error');
+    console.log('Error in example for test:', error);
   }
 
   return result;
@@ -50,6 +53,7 @@ exports[`toRefreshFunction > should handle properties after calls 1`] = `
     result.push(faker.airline.airport().name);
   } catch (error: unknown) {
     result.push(error instanceof Error ? error.name : 'Error');
+    console.log('Error in example for test:', error);
   }
 
   return result;
@@ -65,6 +69,7 @@ exports[`toRefreshFunction > should handle single line calls with semicolon 1`]
     result.push(faker.number.int());
   } catch (error: unknown) {
     result.push(error instanceof Error ? error.name : 'Error');
+    console.log('Error in example for test:', error);
   }
 
   return result;
@@ -80,6 +85,24 @@ exports[`toRefreshFunction > should handle single line calls without semicolon 1
     result.push(faker.number.int());
   } catch (error: unknown) {
     result.push(error instanceof Error ? error.name : 'Error');
+    console.log('Error in example for test:', error);
+  }
+
+  return result;
+}"
+`;
+
+exports[`toRefreshFunction > should handle standalone functions calls 1`] = `
+"async (): Promise<unknown[]> => {
+  await enableFaker();
+  const result: unknown[] = [];
+  const fakerCore = faker.fakerCore;
+
+  try {
+    result.push(fakerRegistry.utils.getDefaultRefDate(fakerCore));
+  } catch (error: unknown) {
+    result.push(error instanceof Error ? error.name : 'Error');
+    console.log('Error in example for test:', error);
   }
 
   return result;

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

@@ -38,7 +38,9 @@ exports[`check docs completeness > all modules and methods are present 1`] = `
     [
       "generateMersenne32Randomizer",
       "generateMersenne53Randomizer",
+      "getDefaultRefDate",
       "mergeLocales",
+      "setDefaultRefDate",
     ],
   ],
   [