Merge branch 'next' into fix/locale/fr_CH/location/street_address

cypress/e2e/api.cy.ts

@@ -43,7 +43,7 @@ describe('API Test', () => {
 
         cy.request({
           method: 'HEAD',
-          url: `/api/${link}`,
+          url: link,
           failOnStatusCode: false,
         })
           .should(({ status }) => {

docs/.vitepress/api-pages.ts

@@ -2,6 +2,7 @@
 // Run 'pnpm run generate:api-docs' to update
 export const apiPages = [
   { text: 'Overview', link: '/api/' },
+  { text: 'Faker', link: '/api/faker.html' },
   { text: 'Airline', link: '/api/airline.html' },
   { text: 'Animal', link: '/api/animal.html' },
   { text: 'Color', link: '/api/color.html' },
@@ -28,4 +29,5 @@ export const apiPages = [
   { text: 'System', link: '/api/system.html' },
   { text: 'Vehicle', link: '/api/vehicle.html' },
   { text: 'Word', link: '/api/word.html' },
+  { text: 'Utilities', link: '/api/utils.html' },
 ];

docs/.vitepress/components/api-docs/method.ts

@@ -1,6 +1,5 @@
 export interface Method {
   readonly name: string;
-  readonly title: string;
   readonly description: string; // HTML
   readonly parameters: MethodParameter[];
   readonly returns: string;

docs/.vitepress/components/api-docs/method.vue

@@ -8,6 +8,9 @@ const props = defineProps<{ method: Method }>();
 
 function seeAlsoToUrl(see: string): string {
   const [, module, method] = see.replace(/\(.*/, '').split('\.');
+  if (!method) {
+    return 'faker.html#' + slugify(module);
+  }
   return module + '.html#' + slugify(method);
 }
 </script>

docs/about/announcements/2022-01-14.md

@@ -107,7 +107,7 @@ We were closing issues every other hour. Discussing the `FUNDING.yml` was inevit
 
 When we became aware that this project was the most stable fork of Faker with the most community support, we realized that we needed to deal with the `FUNDING.yml` file and take a stance.
 
-:::tip Short version, please
+::: tip Short version, please
 Jess posted a [concise and thorough writeup](https://github.com/faker-js/faker/discussions/56#discussioncomment-1958057) of the logic behind our actions and decisions.
 
 This was backed by the support of all of the co-maintainers. It's a much less narrative version of this section, so if you want the TLDR and some photos of the transactions, give it a read.
@@ -123,7 +123,7 @@ Ben said that simply, "The funding is attached to the project, not the current m
 
 Unanimously, we agreed that we **wanted absolutely no ability to touch the existing funding** and created a cut-over plan with the support of Open Collective.
 
-:::tip Legacy collective
+::: tip Legacy collective
 There is now a [fakerjs-legacy](https://opencollective.com/fakerjs-legacy) collective. Open Collective transferred all funds into the legacy account and invited Marak and the other maintainer, Brian, into the _legacy_ collective so that they could do whatever they wanted with the funds.
 :::
 

docs/api/ApiIndex.vue

@@ -97,13 +97,11 @@ onUnmounted(() => window.removeEventListener('keydown', apiSearchFocusHandler));
       <div class="api-groups">
         <div v-for="item of section.items" :key="item.text" class="api-group">
           <h3>
-            <a :href="item.link + '.html'">{{ item.text }}</a>
+            <a :href="item.link">{{ item.text }}</a>
           </h3>
           <ul>
             <li v-for="h of item.headers" :key="h.anchor">
-              <a :href="item.link + '.html#' + slugify(h.anchor)">{{
-                h.text
-              }}</a>
+              <a :href="item.link + '#' + slugify(h.anchor)">{{ h.text }}</a>
             </li>
           </ul>
         </div>

docs/guide/localization.md

@@ -10,7 +10,7 @@ However, we also provide pre-built instances for more than 50 other locales.
 
 See below for a list of available locales.
 
-:::tip Note
+::: tip Note
 You can also build your own Faker instances, with custom locales/overwrites.
 :::
 
@@ -33,7 +33,7 @@ The English locales are around 600 KB in size.
 All locales together are around 5 MB in size.
 :::
 
-:::tip Note
+::: tip Note
 Some locales have limited coverage and rely more heavily on the English locale as the source for features they currently do not have.
 However, in most cases, using a specific locale will be beneficial in the long term as specifying a locale reduces the time necessary for startup, which has a compounding effect on testing frameworks that reload the imports every execution.
 :::

docs/guide/upgrading.md

@@ -4,8 +4,7 @@ This is the migration guide for upgrading from v7 to v8.
 
 Since v8 has not yet been released, this is a work in progress list of any major and breaking changes in v8.
 
-::: info
-Not the version you are looking for?
+::: info Not the version you are looking for?
 
 - [Upgrading to v7](https://v7.fakerjs.dev/guide/upgrading.html)
 - [Upgrading to v6](https://v6.fakerjs.dev/migration-guide-v5/)
@@ -16,7 +15,7 @@ Not the version you are looking for?
 
 ### Removed ability to change the locale on existing `Faker` instances
 
-:::tip NOTE
+::: tip Note
 If you are using only the default (`en`) locale, then you don't have to change anything.
 :::
 

docs/guide/usage.md

@@ -37,7 +37,7 @@ For more information about changing and customizing the locales, please refer to
 </script>
 ```
 
-::: info NOTE
+::: info Note
 Using the browser is great for experimenting 👍. However, due to all of the strings Faker uses to generate fake data, **Faker is a large package**. It's `> 5 MiB` minified. **Please avoid deploying the full Faker in your web app.**
 :::
 
@@ -50,7 +50,7 @@ const randomName = faker.person.fullName(); // Willie Bahringer
 const randomEmail = faker.internet.email(); // Tomasa_Ferry14@hotmail.com
 ```
 
-::: info NOTE
+::: info Note
 It is highly recommended to use version tags when importing libraries in Deno, e.g: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0"`. Add `?dts` to import with type definitions: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0?dts"`.
 :::
 
@@ -104,7 +104,7 @@ const secondRandom = faker.number.int();
 console.log(firstRandom === secondRandom);
 ```
 
-::: info NOTE
+::: info Note
 When upgrading to a new version of Faker, you may get different values for the same seed, as the underlying data (lists of names, words etc) may have changed.
 :::
 

scripts/apidoc.ts

@@ -1,10 +1,8 @@
-import { faker } from '../src';
 import { generate } from './apidoc/generate';
 import { initMarkdownRenderer } from './apidoc/signature';
 
 async function build(): Promise<void> {
   await initMarkdownRenderer();
-  faker.setDefaultRefDate(Date.UTC(2023, 0, 1));
   await generate();
 }
 

scripts/apidoc/apiDocsWriter.ts

@@ -2,16 +2,17 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { ProjectReflection } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
-import type { APIGroup, APIItem } from '../../docs/api/api-types';
+import type { APIGroup } from '../../docs/api/api-types';
 import { formatMarkdown, formatTypescript } from './format';
+import { extractSourceBaseUrl } from './typedoc';
+import type { DocsApiDiffIndex, ModuleSummary, Page } from './utils';
 import {
-  extractModuleName,
-  extractSourceBaseUrl,
-  selectApiMethods,
-  selectApiModules,
-} from './typedoc';
-import type { DocsApiDiffIndex, PageIndex } from './utils';
-import { pathDocsDiffIndexFile, pathDocsDir, pathOutputDir } from './utils';
+  diffHash,
+  methodDiffHash,
+  pathDocsDiffIndexFile,
+  pathDocsDir,
+  pathOutputDir,
+} from './utils';
 
 const pathDocsApiPages = resolve(pathDocsDir, '.vitepress', 'api-pages.ts');
 const pathDocsApiSearchIndex = resolve(
@@ -29,6 +30,52 @@ editLink: false
 
 `;
 
+/**
+ * Writes the api docs for the given modules.
+ *
+ * @param moduleName The name of the module to write the docs for.
+ * @param lowerModuleName The lowercase name of the module.
+ * @param comment The module comments.
+ * @param deprecated The deprecation message.
+ * @param methods The methods of the module.
+ */
+export function writeApiDocsModule(
+  moduleName: string,
+  lowerModuleName: string,
+  comment: string,
+  deprecated: string | undefined,
+  methods: Method[]
+): ModuleSummary {
+  writeApiDocsModulePage(
+    moduleName,
+    lowerModuleName,
+    comment,
+    deprecated,
+    methods
+  );
+  writeApiDocsModuleData(lowerModuleName, methods);
+
+  return {
+    text: moduleName,
+    link: `/api/${lowerModuleName}.html`,
+    methods,
+    diff: methods.reduce(
+      (data, method) => ({
+        ...data,
+        [method.name]: methodDiffHash(method),
+      }),
+      {
+        moduleHash: diffHash({
+          name: moduleName,
+          field: lowerModuleName,
+          deprecated,
+          comment,
+        }),
+      }
+    ),
+  };
+}
+
 /**
  * Writes the api page for the given module to the correct location.
  *
@@ -37,7 +84,7 @@ editLink: false
  * @param comment The module comments.
  * @param methods The methods of the module.
  */
-export function writeApiDocsModulePage(
+function writeApiDocsModulePage(
   moduleName: string,
   lowerModuleName: string,
   comment: string,
@@ -94,7 +141,7 @@ export function writeApiDocsModulePage(
  * @param lowerModuleName The lowercase name of the module.
  * @param methods The methods data to save.
  */
-export function writeApiDocsData(
+function writeApiDocsModuleData(
   lowerModuleName: string,
   methods: Method[]
 ): void {
@@ -116,10 +163,9 @@ export function writeApiDocsData(
  *
  * @param pages The pages to write into the index.
  */
-export function writeApiPagesIndex(pages: PageIndex): void {
+export function writeApiPagesIndex(pages: Page[]): void {
   // Write api-pages.ts
   console.log('Updating api-pages.ts');
-  pages.sort((a, b) => a.text.localeCompare(b.text));
   pages.splice(0, 0, { text: 'Overview', link: '/api/' });
   let apiPagesContent = `
     // This file is automatically generated.
@@ -146,33 +192,20 @@ export function writeApiDiffIndex(diffIndex: DocsApiDiffIndex): void {
  *
  * @param project The typedoc project.
  */
-export function writeApiSearchIndex(project: ProjectReflection): void {
-  const apiIndex: APIGroup[] = [];
-
-  const moduleApiSection: APIGroup = {
-    text: 'Module API',
-    items: [],
-  };
-
-  apiIndex.push(moduleApiSection);
-
-  const apiModules = selectApiModules(project);
-
-  moduleApiSection.items = apiModules
-    .map((module) => {
-      const moduleName = extractModuleName(module);
-      const apiSection: APIItem = {
-        text: moduleName,
-        link: moduleName.toLowerCase(),
-        headers: selectApiMethods(module).map((child) => ({
-          anchor: child.name,
-          text: child.name,
+export function writeApiSearchIndex(pages: ModuleSummary[]): void {
+  const apiIndex: APIGroup[] = [
+    {
+      text: 'Module API',
+      items: pages.map((module) => ({
+        text: module.text,
+        link: module.link,
+        headers: module.methods.map((method) => ({
+          anchor: method.name,
+          text: method.name,
         })),
-      };
-
-      return apiSection;
-    })
-    .sort((a, b) => a.text.localeCompare(b.text));
+      })),
+    },
+  ];
 
   writeFileSync(pathDocsApiSearchIndex, JSON.stringify(apiIndex));
 }

scripts/apidoc/fakerClass.ts

@@ -0,0 +1,48 @@
+import type { DeclarationReflection, ProjectReflection } from 'typedoc';
+import { ReflectionKind } from 'typedoc';
+import type { Method } from '../../docs/.vitepress/components/api-docs/method';
+import { writeApiDocsModule } from './apiDocsWriter';
+import { processModuleMethods } from './moduleMethods';
+import { analyzeSignature, toBlock } from './signature';
+import { selectApiSignature } from './typedoc';
+import type { ModuleSummary } from './utils';
+
+export function processFakerClass(project: ProjectReflection): ModuleSummary {
+  const fakerClass = project
+    .getChildrenByKind(ReflectionKind.Class)
+    .filter((clazz) => clazz.name === 'Faker')[0];
+
+  if (!fakerClass) {
+    throw new Error('Faker class not found');
+  }
+
+  return processClass(fakerClass);
+}
+
+function processClass(fakerClass: DeclarationReflection): ModuleSummary {
+  console.log(`Processing Faker class`);
+  const comment = toBlock(fakerClass.comment);
+  const methods: Method[] = [];
+
+  console.debug(`- constructor`);
+  methods.push(processConstructor(fakerClass));
+
+  methods.push(...processModuleMethods(fakerClass, 'faker.'));
+
+  return writeApiDocsModule('Faker', 'faker', comment, undefined, methods);
+}
+
+function processConstructor(fakerClass: DeclarationReflection): Method {
+  const constructor = fakerClass.getChildrenByKind(
+    ReflectionKind.Constructor
+  )[0];
+
+  const signature = selectApiSignature(constructor);
+
+  const method = analyzeSignature(signature, '', 'new Faker');
+
+  return {
+    ...method,
+    name: 'constructor',
+  };
+}

scripts/apidoc/fakerUtilities.ts

@@ -0,0 +1,32 @@
+import type { DeclarationReflection, ProjectReflection } from 'typedoc';
+import { ReflectionKind } from 'typedoc';
+import type { Method } from '../../docs/.vitepress/components/api-docs/method';
+import { writeApiDocsModule } from './apiDocsWriter';
+import { processMethods } from './moduleMethods';
+import { selectApiSignature } from './typedoc';
+import type { ModuleSummary } from './utils';
+
+export function processFakerUtilities(
+  project: ProjectReflection
+): ModuleSummary {
+  const fakerUtilities = project
+    .getChildrenByKind(ReflectionKind.Function)
+    .filter((method) => !method.flags.isPrivate);
+
+  return processUtilities(fakerUtilities);
+}
+
+function processUtilities(
+  fakerUtilities: DeclarationReflection[]
+): ModuleSummary {
+  console.log(`Processing Faker Utilities`);
+  const comment = 'A list of all the utilities available in Faker.js.';
+
+  const methods: Method[] = processMethods(
+    Object.fromEntries(
+      fakerUtilities.map((method) => [method.name, selectApiSignature(method)])
+    )
+  );
+
+  return writeApiDocsModule('Utilities', 'utils', comment, undefined, methods);
+}