feat: introduce standalone module functions (transform script)

Author: ST-DDT

scripts/shared/paths.ts

@@ -25,7 +25,7 @@ export const FILE_PATH_DOCS_LOCALES = resolve(FILE_PATH_DOCS, 'locales');
 /**
  * The path to the src directory.
  */
-const FILE_PATH_SRC = resolve(FILE_PATH_PROJECT, 'src');
+export const FILE_PATH_SRC = resolve(FILE_PATH_PROJECT, 'src');
 /**
  * The path to the locale source files.
  */

scripts/tranform-once.ts

@@ -0,0 +1,284 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { ClassDeclaration, MethodDeclaration, Project } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import { newProcessingError } from './apidocs/processing/error';
+import type { SignatureLikeDeclaration } from './apidocs/processing/signature';
+import { getProject } from './apidocs/project';
+import { required } from './apidocs/utils/value-checks';
+import { formatTypescript } from './shared/format';
+import { FILE_PATH_SRC } from './shared/paths';
+
+const coreName = 'fakerCore';
+
+await generate();
+
+async function generate(): Promise<void> {
+  console.log('Reading project');
+  const project = getProject();
+  console.log('Processing modules');
+  await processModuleClasses(project);
+}
+
+// Modules
+
+export async function processModuleClasses(project: Project): Promise<void> {
+  await processModules(
+    Object.values(
+      getAllClasses(
+        project,
+        (module: string): boolean =>
+          module.endsWith('Module') && !module.startsWith('Simple')
+      )
+    ).toSorted((a, b) => a.getNameOrThrow().localeCompare(b.getNameOrThrow()))
+  );
+}
+
+function getAllClasses(
+  project: Project,
+  filter: (name: string) => boolean = () => true
+): Record<string, ClassDeclaration> {
+  return Object.fromEntries(
+    project
+      .getSourceFiles()
+      .flatMap((file) => file.getClasses())
+      .map((clazz) => [clazz.getNameOrThrow(), clazz] as const)
+      .filter(([name]) => filter(name))
+  );
+}
+
+async function processModules(modules: ClassDeclaration[]): Promise<void> {
+  for (const module of modules) {
+    try {
+      await processModule(module);
+    } catch (error: unknown) {
+      throw newProcessingError({
+        type: 'module',
+        name: getModuleName(module),
+        source: module,
+        cause: error,
+      });
+    }
+  }
+}
+
+async function processModule(module: ClassDeclaration): Promise<void> {
+  const moduleName = getModuleName(module);
+  console.log(`Processing module: ${moduleName}`);
+  await processClassMethods(module, moduleName, getImports(module));
+}
+
+function getModuleName(module: ClassDeclaration): string {
+  return required(module.getName(), 'module name').replace(/Module$/, '');
+}
+
+function getImports(module: ClassDeclaration): string {
+  return module
+    .getSourceFile()
+    .getImportDeclarations()
+    .map((importDecl) => importDecl.getText())
+    .join('\n');
+}
+
+export async function processClassMethods(
+  clazz: ClassDeclaration,
+  moduleName: string,
+  imports: string
+): Promise<void> {
+  await processMethods(getAllMethods(clazz), moduleName, imports);
+}
+
+function getAllMethods(clazz: ClassDeclaration): MethodDeclaration[] {
+  const parents: ClassDeclaration[] = [clazz];
+  let parent: ClassDeclaration | undefined = clazz;
+  while ((parent = parent.getBaseClass()) != null) {
+    parents.unshift(parent);
+  }
+
+  const methods: Record<string, MethodDeclaration> = {};
+
+  for (const parent of parents) {
+    for (const method of parent.getMethods()) {
+      methods[method.getName()] = method;
+    }
+  }
+
+  return Object.values(methods).toSorted((a, b) =>
+    a.getName().localeCompare(b.getName())
+  );
+}
+
+async function processMethods(
+  methods: MethodDeclaration[],
+  moduleName: string,
+  imports: string
+): Promise<void> {
+  for (const method of methods.filter(
+    (method) => !method.hasModifier(SyntaxKind.PrivateKeyword)
+  )) {
+    const name = method.getName();
+    try {
+      await processMethod(moduleName, name, method, imports);
+    } catch (error) {
+      throw newProcessingError({
+        type: 'method',
+        name,
+        source: method,
+        cause: error,
+      });
+    }
+  }
+}
+
+function toKebabCase(str: string): string {
+  return str.replaceAll(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+function toCamelCase(value: string, ...more: string[]): string {
+  return (
+    value.substring(0, 1).toLowerCase() +
+    value.substring(1) +
+    more.map(toPascalCase).join('')
+  );
+}
+
+function toPascalCase(value: string): string {
+  return value.substring(0, 1).toUpperCase() + value.substring(1);
+}
+
+async function processMethod(
+  moduleName: string,
+  name: string,
+  method: MethodDeclaration,
+  imports: string
+): Promise<void> {
+  console.log(`  - ${name}`);
+
+  // Get all signatures (overloads) and implementation
+  const overloads = method.getOverloads();
+  const signatureDeclarations: SignatureLikeDeclaration[] =
+    overloads.length > 0 ? [...overloads, method] : [method];
+
+  const importsByFile: Record<string, Set<string>> = {};
+
+  let fileBody = '';
+
+  const moduleDocsReplacer: (substring: string, ...args: string[]) => string = (
+    _: string,
+    module: string,
+    method: string,
+    closer: string = ', '
+  ) => {
+    if (module === toCamelCase(moduleName)) {
+      return `${method}(${coreName}${closer}`;
+    }
+
+    return `${toCamelCase(module, method)}(${coreName}${closer}`;
+  };
+
+  for (const signature of signatureDeclarations) {
+    let jsdocs = signature.getJsDocs()[0]?.getText().trim() ?? '';
+    let code = signature.getText().trim();
+
+    jsdocs = jsdocs
+      .replace(
+        /(\* @(?!template)|\*\/)/,
+        `* @param ${coreName} The FakerCore to use.\n   $1`
+      )
+      .replace(/(@param .*)\n *\* (@see|@example)/, `$1\n *\n * $2`)
+      // Replace calls to faker.defaultRefDate() in jsdocs (mostly defaults)
+      .replaceAll(
+        /\bfaker\.defaultRefDate\(\)/g,
+        'getDefaultRefDate(fakerCore)'
+      )
+      // Calls to modules in jsdocs (mostly examples)
+      .replaceAll(/\bfaker\.(\w+)\.(\w+)\((\))?/g, moduleDocsReplacer);
+
+    const moduleCallReplacer: (substring: string, ...args: string[]) => string =
+      // eslint-disable-next-line unicorn/consistent-function-scoping
+      (_: string, module: string, method: string, closer: string = ', ') => {
+        if (module === 'this') {
+          module = moduleName;
+        }
+
+        if (module === moduleName && method === name) {
+          return `${name}(${coreName}${closer}`;
+        }
+
+        const asName = code.includes(`${method} =`)
+          ? toCamelCase(module, method)
+          : method;
+
+        (importsByFile[`../${toCamelCase(module)}/${toKebabCase(method)}`] ??=
+          new Set()).add(asName === method ? asName : `${method} as ${asName}`);
+        return `${asName}(${coreName}${closer}`;
+      };
+
+    // Add core parameter and export keyword
+    code = code
+      .replaceAll(
+        new RegExp(`^${name}(<.*>)?\\(`, 'gm'),
+        `export function ${name}$1(${coreName}: FakerCore, `
+      )
+      .replaceAll(', ):', '):');
+
+    // Calls to other modules
+    code = code.replaceAll(
+      /this\.faker\.(\w+)\s*\.(\w+)\((\))?/g,
+      moduleCallReplacer
+    );
+
+    // Calls to own module
+    code = code.replaceAll(/\b(this)\.(\w+)\((\))?/g, moduleCallReplacer);
+
+    // Replace locale data access
+    code = code.replaceAll(
+      /\bthis\.faker\.definitions\.(\w+)\.(\w+)\b/g,
+      "resolveLocaleData(fakerCore, '$1', '$2')"
+    );
+
+    // Replace default reference date access
+    code = code.replaceAll(
+      /\bthis\.faker\.defaultRefDate\(\)/g,
+      'getDefaultRefDate(fakerCore)'
+    );
+
+    // Replace any remaining this.faker with parameter
+    code = code.replaceAll(/\bthis\.faker\b/g, coreName);
+
+    fileBody += `${jsdocs}\n${code}\n`;
+  }
+
+  const fileImports = [
+    "import type { FakerCore } from '../../faker-core'",
+    "import { resolveLocaleData } from '../../utils/resolve-locale-data'",
+    "import { getDefaultRefDate } from '../../utils/get-default-ref-date'",
+    imports,
+    ...Object.entries(importsByFile).map(([file, imports]) => {
+      return `import { ${[...imports].join(', ')} } from '${file}';`;
+    }),
+  ].join('\n');
+
+  let fileContent = `${fileImports}\n\n${fileBody}`;
+
+  fileContent = fileContent.replaceAll(
+    '@default faker.defaultRefDate()',
+    '@default getDefaultRefDate(fakerCore)'
+  );
+
+  // Format the file content
+  try {
+    fileContent = await formatTypescript(fileContent);
+  } catch {
+    // ignore
+  }
+
+  const outputPath = resolve(
+    FILE_PATH_SRC,
+    'modules',
+    moduleName,
+    `${toKebabCase(name)}.ts`
+  );
+
+  writeFileSync(outputPath, fileContent, 'utf8');
+}

src/faker-config.ts

@@ -0,0 +1,13 @@
+/**
+ * Central location for all configuration options of Faker.
+ *
+ * When accessing any of the configuration options, always assume that the option may be unset and provide a default value.
+ */
+export interface FakerConfig {
+  /**
+   * Provides the default reference date, mainly used for relative dates.
+   *
+   * @since 10.4.0
+   */
+  defaultRefDate?: () => Date;
+}

src/faker-core.ts

@@ -0,0 +1,21 @@
+import type { LocaleDefinition } from './definitions';
+import type { FakerConfig } from './faker-config';
+import type { Randomizer } from './randomizer';
+
+/**
+ * Container that is passed to all methods. It contains the locale definitions, the randomizer and the configuration.
+ */
+export interface FakerCore {
+  /**
+   * The locale definitions to use.
+   */
+  readonly definitions: LocaleDefinition;
+  /**
+   * The randomizer used to generate random values.
+   */
+  readonly randomizer: Randomizer;
+  /**
+   * The configuration options for all methods.
+   */
+  readonly config: FakerConfig;
+}

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

@@ -0,0 +1,16 @@
+import type { FakerCore } from '../faker-core';
+
+/**
+ * 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.
+ *
+ * @since 10.4.0
+ */
+export function getDefaultRefDate(fakerCore: FakerCore): Date {
+  return fakerCore.config.defaultRefDate?.() ?? new Date();
+}

src/utils/resolve-locale-data.ts

@@ -0,0 +1,51 @@
+import type { LocaleDefinition } from '../definitions';
+import type { FakerCore } from '../faker-core';
+import { assertLocaleData } from '../internal/locale-proxy';
+
+/**
+ * A proxy for LocaleDefinition that marks all properties as required and throws an error when an entry is accessed that is not defined.
+ */
+export type LocaleProxy = Readonly<{
+  [key in keyof LocaleDefinition]-?: LocaleProxyCategory<LocaleDefinition[key]>;
+}>;
+
+type LocaleProxyCategory<T> = Readonly<{
+  [key in keyof T]-?: LocaleProxyEntry<T[key]>;
+}>;
+
+type LocaleProxyEntry<T> = unknown extends T ? T : Readonly<NonNullable<T>>;
+
+/**
+ * Resolves the locale data for the given category and entry.
+ *
+ * @template TCategory The category of the locale data to resolve.
+ * @template TEntry The entry of the locale data to resolve.
+ *
+ * @param fakerCore The FakerCore instance to get the locale data from.
+ * @param category The category of the locale data to resolve.
+ * @param entry The entry of the locale data to resolve.
+ *
+ * @returns The resolved locale data for the given category and entry.
+ *
+ * @throws {FakerError} If the category or entry is not defined in the locale data.
+ *
+ * @example
+ * arrayElements(fakerCore, resolveLocaleData(fakerCore, 'date', 'weekday')); // 'Sunday'
+ *
+ * @since 10.4.0
+ */
+export function resolveLocaleData<
+  const TCategory extends keyof LocaleProxy,
+  const TEntry extends keyof LocaleProxy[TCategory] & string,
+>(
+  fakerCore: FakerCore,
+  category: TCategory,
+  entry: TEntry
+): LocaleProxy[TCategory][TEntry] {
+  const categoryData = fakerCore.definitions[category];
+  assertLocaleData(categoryData, category);
+
+  const entryData = categoryData[entry];
+  assertLocaleData(entryData, category, entry);
+  return entryData;
+}