Merge branch 'next' into refactor/person/sex

.devcontainer/devcontainer.json

@@ -2,7 +2,7 @@
 // README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
 {
   "name": "FakerJs",
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:22@sha256:dc2c3654370fe92a55daeefe9d2d95839d85bdc1f68f7fd4ab86621f49e5818a",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:22@sha256:9791f4aa527774bc370c6bd2f6705ce5a686f1e6f204badd8dfaacce28c631ae",
 
   // Features to add to the dev container. More info: https://containers.dev/features.
   // "features": {},

.github/workflows/ci.yml

@@ -211,7 +211,7 @@ jobs:
         run: pnpm vitest run --coverage
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@015f24e6818733317a2da2edd6290ab26238649a # v5.0.7
+        uses: codecov/codecov-action@1e68e06f1dbfde0e4cefc87efeba9e4643565303 # v5.1.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true

.gitignore

@@ -80,6 +80,11 @@ versions.json
 /dist
 /docs/.vitepress/cache
 /docs/.vitepress/dist
+/docs/api/*.ts
+!/docs/api/api-types.ts
+/docs/api/*.md
+!/docs/api/index.md
+/docs/api/api-search-index.json
 /docs/public/api-diff-index.json
 
 # Faker

LICENSE

@@ -1,45 +1,6 @@
-Faker - Copyright (c) 2022-2024
+MIT License
 
-This software consists of voluntary contributions made by many individuals.
-For exact contribution history, see the revision history
-available at https://github.com/faker-js/faker
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-===
-
-From: https://github.com/faker-js/faker/commit/a9f98046c7d5eeaabe12fc587024c06d683800b8
-To: https://github.com/faker-js/faker/commit/29234378807c4141588861f69421bf20b5ac635e
-
-Based on faker.js, copyright Marak Squires and contributor, what follows below is the original license.
-
-===
-
-faker.js - Copyright (c) 2020
-Marak Squires
-http://github.com/marak/faker.js/
-
-faker.js was inspired by and has used data definitions from:
-
- * https://github.com/stympy/faker/ - Copyright (c) 2007-2010 Benjamin Curtis
- * http://search.cpan.org/~jasonk/Data-Faker-0.07/ - Copyright 2004-2005 by Jason Kohles
+Copyright 2022-2025 FakerJS Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

cypress/e2e/example-refresh.cy.ts

@@ -0,0 +1,32 @@
+describe('example-refresh', () => {
+  it('should refresh the example', () => {
+    // given
+    cy.visit('/api/faker.html#constructor');
+    cy.get('.refresh').first().as('refresh');
+    cy.get('@refresh').next().find('code').as('codeBlock');
+    cy.get('@codeBlock').then(($el) => {
+      const originalCodeText = $el.text();
+
+      cy.get('@refresh')
+        .click()
+        .should('not.be.disabled') // stays disabled on error
+        .then(() => {
+          cy.get('@codeBlock').then(($el) => {
+            const newCodeText = $el.text();
+            expect(newCodeText).not.to.equal(originalCodeText);
+
+            cy.get('@refresh')
+              .click()
+              .should('not.be.disabled') // stays disabled on error
+              .then(() => {
+                cy.get('@codeBlock').then(($el) => {
+                  const newCodeText2 = $el.text();
+                  expect(newCodeText2).not.to.equal(originalCodeText);
+                  expect(newCodeText2).not.to.equal(newCodeText);
+                });
+              });
+          });
+        });
+    });
+  });
+});

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

@@ -0,0 +1,14 @@
+export function formatResult(result: unknown): string {
+  return result === undefined
+    ? 'undefined'
+    : typeof result === 'bigint'
+      ? `${result}n`
+      : JSON.stringify(result, undefined, 2)
+          .replaceAll('\\r', '')
+          .replaceAll('<', '&lt;')
+          .replaceAll(
+            /(^ *|: )"([^'\n]*?)"(?=,?$|: )/gm,
+            (_, p1, p2) => `${p1}'${p2.replace(/\\"/g, '"')}'`
+          )
+          .replaceAll(/\n */g, ' ');
+}

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

@@ -8,6 +8,7 @@ export interface ApiDocsMethod {
   readonly throws: string | undefined; // HTML
   readonly signature: string; // HTML
   readonly examples: string; // HTML
+  readonly refresh: (() => Promise<unknown[]>) | undefined;
   readonly seeAlsos: string[];
   readonly sourcePath: string; // URL-Suffix
 }

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

@@ -1,8 +1,11 @@
 <script setup lang="ts">
+import { computed, ref, useTemplateRef } from 'vue';
 import { sourceBaseUrl } from '../../../api/source-base-url';
 import { slugify } from '../../shared/utils/slugify';
+import { formatResult } from './format';
 import type { ApiDocsMethod } from './method';
 import MethodParameters from './method-parameters.vue';
+import RefreshButton from './refresh-button.vue';
 
 const { method } = defineProps<{ method: ApiDocsMethod }>();
 const {
@@ -14,10 +17,113 @@ const {
   throws,
   signature,
   examples,
+  refresh,
   seeAlsos,
   sourcePath,
 } = method;
 
+const code = useTemplateRef('code');
+const codeBlock = computed(() => code.value?.querySelector('div pre code'));
+const codeLines = ref<Element[]>();
+
+function initRefresh(): Element[] {
+  if (codeBlock.value == null) {
+    return [];
+  }
+  const domLines = codeBlock.value.querySelectorAll('.line');
+  let lineIndex = 0;
+  const result: Element[] = [];
+  while (lineIndex < domLines.length) {
+    // Skip empty and preparatory lines (no '^faker.' invocation)
+    if (
+      domLines[lineIndex]?.children.length === 0 ||
+      !/^\w*faker\w*\./i.test(domLines[lineIndex]?.textContent ?? '')
+    ) {
+      lineIndex++;
+      continue;
+    }
+
+    // Skip to end of the invocation (if multiline)
+    while (
+      domLines[lineIndex] != null &&
+      !/^([^ ].*)?\)(\.\w+)?;? ?(\/\/|$)/.test(
+        domLines[lineIndex]?.textContent ?? ''
+      )
+    ) {
+      lineIndex++;
+    }
+
+    if (lineIndex >= domLines.length) {
+      break;
+    }
+
+    const domLine = domLines[lineIndex];
+    result.push(domLine);
+    lineIndex++;
+
+    // Purge old results
+    if (domLine.lastElementChild?.textContent?.startsWith('//')) {
+      // Inline comments
+      domLine.lastElementChild.remove();
+    } else {
+      // Multiline comments
+      while (domLines[lineIndex]?.children[0]?.textContent?.startsWith('//')) {
+        domLines[lineIndex].previousSibling?.remove(); // newline
+        domLines[lineIndex].remove(); // comment
+        lineIndex++;
+      }
+    }
+
+    // Add space between invocation and comment (if missing)
+    const lastElementChild = domLine.lastElementChild;
+    if (
+      lastElementChild != null &&
+      !lastElementChild.textContent?.endsWith(' ')
+    ) {
+      lastElementChild.textContent += ' ';
+    }
+  }
+
+  return result;
+}
+
+async function onRefresh(): Promise<void> {
+  if (refresh != null && codeBlock.value != null) {
+    codeLines.value ??= initRefresh();
+
+    const results = await refresh();
+
+    // Remove old comments
+    codeBlock.value
+      .querySelectorAll('.comment-delete-marker')
+      .forEach((el) => el.remove());
+
+    // Insert new comments
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      const domLine = codeLines.value[i];
+      const prettyResult = formatResult(result);
+      const resultLines = prettyResult.split('\\n');
+
+      if (resultLines.length === 1) {
+        domLine.insertAdjacentHTML('beforeend', newCommentSpan(resultLines[0]));
+      } else {
+        for (const line of resultLines.reverse()) {
+          domLine.insertAdjacentHTML('afterend', newCommentLine(line));
+        }
+      }
+    }
+  }
+}
+
+function newCommentLine(content: string): string {
+  return `<span class="line comment-delete-marker">\n${newCommentSpan(content)}</span>`;
+}
+
+function newCommentSpan(content: string): string {
+  return `<span class="comment-delete-marker" style="--shiki-light:#6A737D;--shiki-dark:#6A737D">// ${content}</span>`;
+}
+
 function seeAlsoToUrl(see: string): string {
   const [, module, methodName] = see.replace(/\(.*/, '').split('\.');
 
@@ -51,8 +157,14 @@ function seeAlsoToUrl(see: string): string {
 
     <div v-html="signature" />
 
-    <h3>Examples</h3>
-    <div v-html="examples" />
+    <h3 class="inline">Examples</h3>
+    <RefreshButton
+      class="refresh"
+      v-if="refresh != null"
+      style="margin-left: 0.5em"
+      :refresh="onRefresh"
+    />
+    <div ref="code" v-html="examples" />
 
     <div v-if="seeAlsos.length > 0">
       <h3>See Also</h3>
@@ -107,4 +219,8 @@ svg.source-link-icon {
   display: inline;
   margin-left: 0.3em;
 }
+
+h3.inline {
+  display: inline-block;
+}
 </style>

docs/.vitepress/components/api-docs/refresh-button.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+
+// This should probably use emit instead, but emit cannot be awaited
+const { refresh } = defineProps<{ refresh: () => Promise<void> }>();
+
+const spinning = ref(false);
+
+async function onRefresh() {
+  spinning.value = true;
+  await Promise.all([refresh(), delay(100)]);
+  spinning.value = false;
+}
+
+// Extra delay to make the spinning effect more visible
+// Some examples barely/don't change, so the spinning is the only visible effect
+function delay(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+</script>
+
+<template>
+  <button
+    class="refresh"
+    title="Refresh Examples"
+    :disabled="spinning"
+    @click="onRefresh"
+  >
+    <div :class="{ spinning: spinning }" />
+  </button>
+</template>
+
+<style scoped>
+button.refresh {
+  border: 1px solid var(--vp-code-copy-code-border-color);
+  border-radius: 4px;
+  width: 40px;
+  height: 40px;
+  font-size: 25px;
+  vertical-align: middle;
+}
+
+button.refresh div {
+  background-image: url('refresh.svg');
+  background-position: 50%;
+  background-size: 20px;
+  background-repeat: no-repeat;
+  width: 100%;
+  height: 100%;
+}
+
+button.refresh:hover {
+  background-color: var(--vp-code-copy-code-bg);
+  opacity: 1;
+}
+
+div.spinning {
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+</style>

docs/.vitepress/config.ts

@@ -133,6 +133,7 @@ async function enableFaker() {
 e.g. 'faker.food.description()' or 'fakerZH_CN.person.firstName()'
 For other languages please refer to https://fakerjs.dev/guide/localization.html#available-locales
 For a full list of all methods please refer to https://fakerjs.dev/api/\`, logStyle);
+  enableFaker = () => imported; // Init only once
   return imported;
 }
 `,

eslint.config.ts

@@ -24,6 +24,7 @@ const config: ReturnType<typeof tseslint.config> = tseslint.config(
       '.github/workflows/commentCodeGeneration.ts',
       '.prettierrc.js',
       'docs/.vitepress/components/shims.d.ts',
+      'docs/.vitepress/components/api-docs/format.ts',
       'docs/.vitepress/shared/utils/slugify.ts',
       'docs/.vitepress/theme/index.ts',
       'eslint.config.js',