Merge branch 'next' into feat/faker-fork-and-dervice

.eslintrc.js

@@ -24,13 +24,13 @@ module.exports = defineConfig({
     sourceType: 'module',
     warnOnUnsupportedTypeScriptVersion: false,
   },
-  plugins: ['@typescript-eslint', 'prettier'],
+  plugins: ['@typescript-eslint', 'prettier', 'deprecation'],
   rules: {
     // We may want to use this in the future
     'no-useless-escape': 'off',
+    'deprecation/deprecation': 'error',
     eqeqeq: ['error', 'always', { null: 'ignore' }],
     'prefer-template': 'error',
-
     '@typescript-eslint/array-type': [
       'error',
       { default: 'array-simple', readonly: 'generic' },
@@ -88,6 +88,7 @@ module.exports = defineConfig({
     {
       files: ['test/*.spec.ts'],
       rules: {
+        'deprecation/deprecation': 'off',
         '@typescript-eslint/restrict-template-expressions': [
           'error',
           {

.github/pull_request_template.md

@@ -1,3 +1,5 @@
-<!-- Please first read https://github.com/faker-js/faker/blob/verify-semantic-pull-requests/CONTRIBUTING.md -->
+<!-- Please run `pnpm run preflight` before opening a Pull Request to ensure that your code fulfills the minimal requirements for our project. -->
 
-<!-- Help us by writing a correct PR title following this guide: https://github.com/faker-js/faker/blob/verify-semantic-pull-requests/CONTRIBUTING.md#committing -->
+<!-- Please first read https://github.com/faker-js/faker/blob/next/CONTRIBUTING.md -->
+
+<!-- Help us by writing a correct PR title following this guide: https://github.com/faker-js/faker/blob/next/CONTRIBUTING.md#committing -->

.github/workflows/commentCodeGeneration.ts

@@ -21,7 +21,7 @@ module.exports = async (
     issue_number: context.issue.number,
   });
 
-  const body = `Uncommitted changes were detected after runnning <code>generate:*</code> commands.\nPlease run <code>pnpm run generate:locales</code>, <code>pnpm run generate:api-docs</code>, and <code>pnpm run test -u</code> to generate/update the related files, and commit them.`;
+  const body = `Uncommitted changes were detected after runnning <code>generate:*</code> commands.\nPlease run <code>pnpm run preflight</code> to generate/update the related files, and commit them.`;
 
   const botComment = comments.find(
     (comment) => comment.user?.type === 'Bot' && comment.body?.includes(body)

CONTRIBUTING.md

@@ -4,7 +4,7 @@ If you want to make `Faker` a better, please read the following contribution gui
 
 # Important
 
-- Please make sure that you run `pnpm install`, `pnpm run build` and `pnpm run test` before making a PR to ensure that everything is working from the start.
+Please make sure that you run `pnpm run preflight` before making a PR to ensure that everything is working from the start.
 
 ## Good to know
 
@@ -21,6 +21,15 @@ The sources are located in the [src](src) directory.
 All fake data generators are divided into namespaces (each namespace being a separate module).
 Most of the generators use the _definitions_, which are just plain JavaScript objects/arrays/strings that are separate for each [locale](src/locales).
 
+## Sourcing data for definitions
+
+If adding new data definitions to Faker, you'll often need to find source data. Note that:
+
+- Faker must not contain copyrighted materials.
+- Facts cannot be copyrighted, so if you are adding or translating a finite, known, list of things such as the names of chemical elements into another language, that's OK.
+- But if you are compiling a list of, for example, popular personal names or cities, don't copy directly from a single source (Wikipedia, 'most popular' articles, government data sites etc). A compilation of facts [can be copyrighted](https://en.wikipedia.org/wiki/Copyright_in_compilation).
+- It's best to refer to multiple sources and use your own judgement/knowledge to make a sample list of data.
+
 ## Building Faker
 
 The project is being built by [esbuild](https://esbuild.github.io) (see [bundle.ts](scripts/bundle.ts))

README.md

@@ -10,18 +10,17 @@
   [![Chat on Discord](https://img.shields.io/badge/chat-discord-blue?style=flat&logo=discord)](https://chat.fakerjs.dev)
   [![Open Collective](https://img.shields.io/opencollective/backers/fakerjs)](https://opencollective.com/fakerjs#section-contributors)
   [![sponsor](https://img.shields.io/opencollective/all/fakerjs?label=sponsors)](https://opencollective.com/fakerjs)
-
 </div>
 
 ## ⚡️ Try it Online
 
-[![](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://fakerjs.dev/new)
+[Open in StackBlitz](https://fakerjs.dev/new)
 
-[API Documentation](https://fakerjs.dev/guide/)
+## 📙 API Documentation
 
----
+[Guide - Getting started](https://fakerjs.dev/guide/)
 
-Please select the version of the documentation you are looking for.
+For detailed API documentation, please select the version of the documentation you are looking for.
 
 | Version |                         Github                         | Website                   |
 | :-----: | :----------------------------------------------------: | :------------------------ |
@@ -57,10 +56,11 @@ npm install --save-dev @faker-js/faker
 ## 🪄 Usage
 
 ```ts
+// ESM
 import { faker } from '@faker-js/faker';
-// import { faker } from '@faker-js/faker/locale/de';
 
-export const USERS: User[] = [];
+// CJS
+const { faker } = require('@faker-js/faker');
 
 export function createRandomUser(): User {
   return {
@@ -74,8 +74,8 @@ export function createRandomUser(): User {
   };
 }
 
-Array.from({ length: 10 }).forEach(() => {
-  USERS.push(createRandomUser());
+export const USERS: User[] = faker.helpers.multiple(generateRandomUser, {
+  count: 5,
 });
 ```
 
@@ -111,7 +111,6 @@ The API covers the following modules:
 | Music    | `faker.music.genre()`                         | R&B                                                                                                |
 | Person   | `faker.person.firstName()`                    | Cameron                                                                                            |
 | Phone    | `faker.phone.phoneNumber()`                   | +1 291-299-0192                                                                                    |
-| Random   | `faker.random.locale()`                       | fr_CA                                                                                              |
 | Science  | `faker.science.unit()`                        | `{ name: 'meter', symbol: 'm' }`                                                                   |
 | System   | `faker.system.directoryPath()`                | /root                                                                                              |
 | Vehicle  | `faker.vehicle.vehicle()`                     | Lamborghini Camry                                                                                  |
@@ -133,18 +132,30 @@ console.log(
 
 Faker has support for multiple locales.
 
-The default language locale is set to English.
-
-Setting a new locale is simple:
+The main `faker` instance uses the English locale.
+But you can also import instances using other locales.
 
 ```ts
-// sets locale to de
-faker.locale = 'de';
+// ESM
+import { fakerDE as faker } from '@faker-js/faker';
+
+// CJS
+const { fakerDE: faker } = require('@faker-js/faker');
 ```
 
-See our documentation for a list of [provided languages](https://fakerjs.dev/guide/localization.html#available-locales)
+See our documentation for a list of [provided languages](https://fakerjs.dev/guide/localization.html#available-locales).
+
+Please note: Not every locale provides data for every module. In our pre-made faker instances,
+we fall back to English in such a case as this is the most complete and most commonly used language.
+If you don't want that or prefer a different fallback, you can also build your own instances.
 
-Please note: not every locale provides data for every module. In our pre-made locales, we fallback to English in such a case as this is the most complete and most commonly used language.
+```ts
+import { Faker, de, de_CH } from '@faker-js/faker';
+
+export const faker = new Faker({
+  locale: [de_CH, de],
+});
+```
 
 ## ⚙️ Setting a randomness seed
 

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

@@ -5,7 +5,7 @@ export interface Method {
   readonly parameters: MethodParameter[];
   readonly returns: string;
   readonly examples: string; // HTML
-  readonly deprecated: boolean;
+  readonly deprecated?: string; // HTML
   readonly since: string;
   readonly sourcePath: string; // URL-Suffix
   readonly seeAlsos: string[];

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

@@ -17,6 +17,7 @@ function seeAlsoToUrl(see: string): string {
     <div v-if="props.method.deprecated" class="warning custom-block">
       <p class="custom-block-title">Deprecated</p>
       <p>This method is deprecated and will be removed in a future version.</p>
+      <span v-html="props.method.deprecated" />
     </div>
 
     <div v-html="props.method.description"></div>

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, ref } from 'vue';
+import { computed, onMounted, onUnmounted, ref } from 'vue';
 import { slugify } from '../.vitepress/shared/utils/slugify';
 import apiSearchIndex from './api-search-index.json';
 import { APIGroup } from './api-types';
@@ -43,6 +43,29 @@ 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 (
+    /^[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>
@@ -54,6 +77,7 @@ const filtered = computed(() => {
         <input
           type="search"
           placeholder="Enter keyword"
+          ref="apiFilter"
           id="api-filter"
           v-model="query"
         />