Merge branch 'next' into unicorn/prefer-date-now

Author: ST-DDT

.eslintrc.js

@@ -18,6 +18,7 @@ module.exports = defineConfig({
     'plugin:@typescript-eslint/recommended',
     'plugin:@typescript-eslint/recommended-type-checked',
     'plugin:prettier/recommended',
+    'plugin:jsdoc/recommended-typescript-error',
     'plugin:unicorn/recommended',
   ],
   parser: '@typescript-eslint/parser',
@@ -26,7 +27,7 @@ module.exports = defineConfig({
     sourceType: 'module',
     warnOnUnsupportedTypeScriptVersion: false,
   },
-  plugins: ['@typescript-eslint', 'prettier', 'deprecation'],
+  plugins: ['@typescript-eslint', 'prettier', 'deprecation', 'jsdoc'],
   rules: {
     // We may want to use this in the future
     'no-useless-escape': 'off',
@@ -37,19 +38,17 @@ module.exports = defineConfig({
 
     'deprecation/deprecation': 'error',
 
-    'unicorn/no-array-reduce': 'off',
-    'unicorn/no-nested-ternary': 'off',
-    'unicorn/no-null': 'off',
-    'unicorn/no-useless-switch-case': 'off',
-    'unicorn/number-literal-case': 'off',
-    // TODO @Shinigami92 2023-09-23: prefer-at should be turned on when we drop support for Node 14
+    'unicorn/no-nested-ternary': 'off', // incompatible with prettier
+    'unicorn/no-null': 'off', // incompatible with TypeScript
+    'unicorn/number-literal-case': 'off', // incompatible with prettier
+
+    // TODO @Shinigami92 2023-09-23: prefer-at should be turned on when we drop support for Node 14.
     'unicorn/prefer-at': 'off',
-    // TODO @Shinigami92 2023-09-23: prefer-string-replace-all should be turned on when we drop support for Node 14
+    // TODO @Shinigami92 2023-09-23: prefer-string-replace-all should be turned on when we drop support for Node 14.
     'unicorn/prefer-string-replace-all': 'off',
 
-    // TODO @Shinigami92 2023-09-23: All following unicorn rules are turned on by default through the unicorn/recommended set
-    // they should be turned on individually, removed or potentially configured to our needs
-    // But read https://github.com/faker-js/faker/pull/2417 for more
+    // TODO @Shinigami92 2023-09-23: The following rules currently conflict with our code.
+    // Each rule should be checked whether it should be enabled/configured and the problems fixed, or stay disabled permanently.
     'unicorn/better-regex': 'off',
     'unicorn/catch-error-name': 'off',
     'unicorn/consistent-destructuring': 'off',
@@ -61,6 +60,7 @@ module.exports = defineConfig({
     'unicorn/no-array-callback-reference': 'off',
     'unicorn/no-array-for-each': 'off',
     'unicorn/no-array-push-push': 'off',
+    'unicorn/no-array-reduce': 'off',
     'unicorn/no-await-expression-member': 'off',
     'unicorn/no-console-spaces': 'off',
     'unicorn/no-for-loop': 'off',
@@ -70,6 +70,7 @@ module.exports = defineConfig({
     'unicorn/no-new-array': 'off',
     'unicorn/no-object-as-default-parameter': 'off',
     'unicorn/no-process-exit': 'off',
+    'unicorn/no-useless-switch-case': 'off',
     'unicorn/no-zero-fractions': 'off',
     'unicorn/numeric-separators-style': 'off',
     'unicorn/prefer-array-flat-map': 'off',
@@ -134,40 +135,39 @@ module.exports = defineConfig({
       { allowNumber: true, allowBoolean: true },
     ],
     '@typescript-eslint/unbound-method': 'off',
+
+    'jsdoc/no-types': 'error',
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/require-returns': 'off',
+    'jsdoc/sort-tags': [
+      'error',
+      {
+        tagSequence: [
+          { tags: ['template'] },
+          { tags: ['internal'] },
+          { tags: ['param'] },
+          { tags: ['returns'] },
+          { tags: ['throws'] },
+          { tags: ['see'] },
+          { tags: ['example'] },
+          { tags: ['since'] },
+          { tags: ['default'] },
+          { tags: ['deprecated'] },
+        ],
+      },
+    ],
+    'jsdoc/tag-lines': 'off',
+  },
+  settings: {
+    jsdoc: {
+      mode: 'typescript',
+    },
   },
   overrides: [
     {
       files: ['src/**/*.ts'],
-      plugins: ['jsdoc'],
-      extends: ['plugin:jsdoc/recommended-error'],
       rules: {
-        'jsdoc/no-types': 'error',
-        'jsdoc/require-param-type': 'off',
-        'jsdoc/require-returns-type': 'off',
-        'jsdoc/require-returns': 'off',
-        'jsdoc/tag-lines': 'off',
-        'jsdoc/sort-tags': [
-          'error',
-          {
-            tagSequence: [
-              { tags: ['template'] },
-              { tags: ['internal'] },
-              { tags: ['param'] },
-              { tags: ['returns'] },
-              { tags: ['throws'] },
-              { tags: ['see'] },
-              { tags: ['example'] },
-              { tags: ['since'] },
-              { tags: ['default'] },
-              { tags: ['deprecated'] },
-            ],
-          },
-        ],
-      },
-      settings: {
-        jsdoc: {
-          mode: 'typescript',
-        },
+        'jsdoc/require-jsdoc': 'error',
       },
     },
     {

docs/.vitepress/api-pages.ts

@@ -30,5 +30,6 @@ export const apiPages = [
   { text: 'System', link: '/api/system.html' },
   { text: 'Vehicle', link: '/api/vehicle.html' },
   { text: 'Word', link: '/api/word.html' },
+  { text: 'Randomizer', link: '/api/randomizer.html' },
   { text: 'Utilities', link: '/api/utils.html' },
 ];

docs/.vitepress/config.ts

@@ -200,6 +200,10 @@ const config = defineConfig({
             text: 'Frameworks',
             link: '/guide/frameworks',
           },
+          {
+            text: 'Randomizer',
+            link: '/guide/randomizer',
+          },
           {
             text: 'Upgrading to v8',
             link: '/guide/upgrading',

docs/api/ApiIndex.vue

@@ -1,7 +1,7 @@
 <!-- This content is mostly copied over from https://github.com/vuejs/docs/blob/main/src/api/ApiIndex.vue -->
 
 <script setup lang="ts">
-import { computed, onMounted, onUnmounted, ref } from 'vue';
+import { computed, ref } from 'vue';
 import { slugify } from '../.vitepress/shared/utils/slugify';
 import apiSearchIndex from './api-search-index.json';
 import { APIGroup } from './api-types';
@@ -43,37 +43,6 @@ const filtered = computed(() => {
     })
     .filter((i) => i) as APIGroup[];
 });
-
-const apiFilter = ref<HTMLInputElement>();
-
-function apiSearchFocusHandler(event: KeyboardEvent): void {
-  if (event.key === 'Escape') {
-    if (apiFilter.value !== document.activeElement) {
-      query.value = '';
-    } else {
-      apiFilter.value!.blur();
-    }
-  } else if (event.key === 'Enter') {
-    if (apiFilter.value !== document.activeElement) return;
-    if (query.value === '') return;
-    const item = filtered.value[0].items[0];
-    if (!item) return;
-    const header = item.headers[0];
-    if (!header) return;
-    window.location.href = item.link + '#' + slugify(header.anchor);
-  } else if (
-    /^[a-z]$/.test(event.key) &&
-    !event.altKey &&
-    !event.ctrlKey &&
-    !event.shiftKey &&
-    !event.metaKey
-  ) {
-    apiFilter.value!.focus();
-  }
-}
-
-onMounted(() => window.addEventListener('keydown', apiSearchFocusHandler));
-onUnmounted(() => window.removeEventListener('keydown', apiSearchFocusHandler));
 </script>
 
 <template>
@@ -85,7 +54,6 @@ onUnmounted(() => window.removeEventListener('keydown', apiSearchFocusHandler));
         <input
           type="search"
           placeholder="Enter keyword"
-          ref="apiFilter"
           id="api-filter"
           v-model="query"
         />

docs/guide/randomizer.md

@@ -0,0 +1,116 @@
+# Randomizer
+
+The [`Randomizer`](/api/randomizer) interface allows you to use a custom randomness source within Faker.
+
+::: warning Important
+Faker's default `Randomizer` is sufficient in most cases.
+Change this only if you want to use it to achieve a specific goal, such as sharing the same random generator with other instances/tools.
+:::
+
+There are two connected use cases we have considered where this might be needed:
+
+1. Re-Use of the same `Randomizer` within multiple `Faker` instances.
+2. The use of a random number generator from a third party library.
+
+## Using `Randomizer`s
+
+A `Randomizer` has to be set during construction of the instance:
+
+```ts
+import { Faker, Randomizer } from '@faker-js/faker';
+
+const customFaker = new Faker({
+  locale: ...,
+  randomizer: ...,
+});
+```
+
+The following methods take a `Randomizer` as argument:
+
+- [new SimpleFaker(...)](/api/simpleFaker#constructor)
+- [new Faker(...)](/api/faker#constructor)
+
+## Re-Using a `Randomizer`
+
+Sometimes it might be required to generate values in two different locales.
+E.g. a Chinese person might have an English identity to simplify the communication with foreigners.
+While this could also be achieved with two independent `Faker` instances like this:
+
+```ts
+import { fakerEN, fakerZH_TW } from '@faker-js/faker';
+
+fakerZH_TW.seed(5);
+fakerEN.seed(5);
+
+const firstName = fakerZH_TW.person.firstName(); // 炫明
+const alias = fakerEN.person.firstName(); // Arthur
+```
+
+There might be issues regarding reproducibility, when seeding only one of them.
+
+By sharing a `Randomizer` between the two instances, you omit this issue by affecting all instances simultaneously.
+
+::: tip Note
+This gets more important if the seeding happens at a different location than the data generation (e.g. due to nesting).
+:::
+
+```ts
+import { en, Faker, Randomizer, zh_TW } from '@faker-js/faker';
+
+const randomizer: Randomizer = ...;
+
+const customFakerEN = new Faker({
+  locale: en,
+  randomizer,
+});
+
+const customFakerZH_TW = new Faker({
+  locale: [zh_TW, en],
+  randomizer,
+});
+
+randomizer.seed(5);
+// customFakerEN.seed(5); // Redundant
+// customFakerZH_TW.seed(5); // Redundant
+
+const firstName = fakerZH_TW.person.firstName(); // 炫明
+const alias = fakerEN.person.firstName(); // John (different from before, because it is now the second call)
+```
+
+This is also relevant when trying to use faker's random number generator in third party libraries.
+E.g. some libraries that can generate `string`s from a `RegExp` can be customized with a custom random number generator as well,
+and since they will be used in the same context it makes sense to rely on the same randomness source to ensure the values are reproducible.
+
+## Third-Party `Randomizer`s
+
+Sometimes you might want to use a custom/third-party random number generator.
+This can be achieved by implementing your own `Randomizer` and passing it to [supported methods](#using-randomizers).
+
+::: tip Note
+Faker does not ship `Randomizers` for third-party libraries and does not provide support for bridging the gap between libraries.
+The following examples show how the interface can be implemented, but they are not tested for correctness.
+Feel free to submit more `Randomizer` examples for other popular packages.
+:::
+
+### Pure-Rand
+
+The following is an example for a [pure-rand](https://github.com/dubzzz/pure-rand) based `Randomizer`:
+
+```ts
+import { Faker, Randomizer, SimpleFaker } from '@faker-js/faker';
+import { RandomGenerator, xoroshiro128plus } from 'pure-rand';
+
+export function generatePureRandRandomizer(
+  seed: number | number[] = Date.now() ^ (Math.random() * 0x100000000),
+  factory: (seed: number) => RandomGenerator = xoroshiro128plus
+): Randomizer {
+  const self = {
+    next: () => (self.generator.unsafeNext() >>> 0) / 0x100000000,
+    seed: (seed: number | number[]) => {
+      self.generator = factory(typeof seed === 'number' ? seed : seed[0]);
+    },
+  } as Randomizer & { generator: RandomGenerator };
+  self.seed(seed);
+  return self;
+}
+```

package.json

@@ -89,43 +89,43 @@
   "devDependencies": {
     "@actions/github": "~5.1.1",
     "@algolia/client-search": "~4.19.1",
-    "@types/markdown-it": "~13.0.1",
-    "@types/node": "~20.6.2",
-    "@types/sanitize-html": "~2.9.0",
-    "@types/semver": "~7.5.2",
-    "@types/validator": "~13.11.1",
-    "@typescript-eslint/eslint-plugin": "~6.7.0",
-    "@typescript-eslint/parser": "~6.7.0",
-    "@vitest/coverage-v8": "~0.34.4",
-    "@vitest/ui": "~0.34.4",
+    "@types/markdown-it": "~13.0.2",
+    "@types/node": "~20.8.0",
+    "@types/sanitize-html": "~2.9.1",
+    "@types/semver": "~7.5.3",
+    "@types/validator": "~13.11.2",
+    "@typescript-eslint/eslint-plugin": "~6.7.3",
+    "@typescript-eslint/parser": "~6.7.3",
+    "@vitest/coverage-v8": "~0.34.6",
+    "@vitest/ui": "~0.34.7",
     "@vueuse/core": "~10.4.1",
     "conventional-changelog-cli": "~4.1.0",
-    "cypress": "~13.2.0",
-    "esbuild": "~0.19.3",
-    "eslint": "~8.49.0",
+    "cypress": "~13.3.0",
+    "esbuild": "~0.19.4",
+    "eslint": "~8.50.0",
     "eslint-config-prettier": "~9.0.0",
     "eslint-define-config": "~1.23.0",
     "eslint-gitignore": "~0.1.0",
     "eslint-plugin-deprecation": "~2.0.0",
-    "eslint-plugin-jsdoc": "~46.8.1",
+    "eslint-plugin-jsdoc": "~46.8.2",
     "eslint-plugin-prettier": "~5.0.0",
     "eslint-plugin-unicorn": "~48.0.1",
     "eslint-plugin-vitest": "~0.3.1",
-    "glob": "~10.3.4",
+    "glob": "~10.3.10",
     "npm-run-all": "~4.1.5",
     "prettier": "3.0.3",
     "prettier-plugin-organize-imports": "~3.2.3",
-    "rimraf": "~5.0.1",
+    "rimraf": "~5.0.5",
     "sanitize-html": "~2.11.0",
     "semver": "~7.5.4",
     "standard-version": "~9.5.0",
-    "tsx": "~3.12.10",
+    "tsx": "~3.13.0",
     "typedoc": "~0.24.8",
     "typescript": "~4.9.5",
     "validator": "~13.11.0",
     "vite": "~4.4.9",
     "vitepress": "1.0.0-beta.7",
-    "vitest": "~0.34.4",
+    "vitest": "~0.34.6",
     "vue": "~3.3.4"
   },
   "packageManager": "pnpm@8.5.1",