diff --git a/.eslintrc.js b/.eslintrc.js index 8ab899ae5f1..26c86424233 100644 --- a/.eslintrc.js +++ b/.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', { diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 988d8cd5a07..8ec56cca333 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,3 +1,5 @@ - + - + + + diff --git a/.github/workflows/commentCodeGeneration.ts b/.github/workflows/commentCodeGeneration.ts index 74a8092735a..f456e563a4e 100644 --- a/.github/workflows/commentCodeGeneration.ts +++ b/.github/workflows/commentCodeGeneration.ts @@ -21,7 +21,7 @@ module.exports = async ( issue_number: context.issue.number, }); - const body = `Uncommitted changes were detected after runnning generate:* commands.\nPlease run pnpm run generate:locales, pnpm run generate:api-docs, and pnpm run test -u to generate/update the related files, and commit them.`; + const body = `Uncommitted changes were detected after runnning generate:* commands.\nPlease run pnpm run preflight to generate/update the related files, and commit them.`; const botComment = comments.find( (comment) => comment.user?.type === 'Bot' && comment.body?.includes(body) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 665030879d5..35ed17d11fe 100644 --- a/CONTRIBUTING.md +++ b/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)) diff --git a/README.md b/README.md index 01cb6d103fc..5aea0cea14f 100644 --- a/README.md +++ b/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) - ## ⚡️ 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 diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts index 52cb24957bf..562d1ecf8d9 100644 --- a/docs/.vitepress/components/api-docs/method.ts +++ b/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[]; diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue index 8bff111f36a..6753cefd733 100644 --- a/docs/.vitepress/components/api-docs/method.vue +++ b/docs/.vitepress/components/api-docs/method.vue @@ -17,6 +17,7 @@ function seeAlsoToUrl(see: string): string {

Deprecated

This method is deprecated and will be removed in a future version.

+
diff --git a/docs/api/ApiIndex.vue b/docs/api/ApiIndex.vue index 882c4a69e14..048f20fd391 100644 --- a/docs/api/ApiIndex.vue +++ b/docs/api/ApiIndex.vue @@ -1,7 +1,7 @@