diff options
| -rw-r--r-- | CONTRIBUTING.md | 54 | ||||
| -rw-r--r-- | README.md | 279 |
2 files changed, 140 insertions, 193 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65e70c47..b840ac80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,3 +20,57 @@ If you want to make `Faker` a better, please read the following contribution gui 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). + +## Building Faker + +The project is being built by [esbuild](https://esbuild.github.io) (see [bundle.ts](scripts/bundle.ts)) + +```shell +pnpm install +pnpm run build +``` + +## Testing + +Before you can run the tests, you need to install all dependencies and build the project, because some tests depend on the bundled content. + +```shell +pnpm install +pnpm run build + +pnpm run test +# or +pnpm run coverage +``` + +You can view a generated code coverage report at `coverage/index.html`. + +## Adding new locale or updating existing one + +After adding new or updating existing locale data, you need to run `pnpm run generate:locales` to generate/update the related files. + +## Developing the docs + +Before running the docs, build the Faker dist, it's used inside of certain routes. + +```shell +pnpm run build + +pnpm run docs:dev +``` + +## Building and serving the docs statically + +If you changed something heavily in the docs, like auto-generating content, you should check the docs statically, because it could differ from the dev version. +Before running the docs, build the Faker dist, it's used inside of certain routes. + +```shell +pnpm run build + +pnpm run docs:build # Output docs to /dist +pnpm run docs:serve # Serve docs from /dist +``` + +## Deploying documentation + +See the [netlify.toml](netlify.toml) for configuration. @@ -3,160 +3,105 @@ <h1>Faker</h1> <p>Generate massive amounts of fake (but realistic) data for testing and development.</p> - [](https://chat.fakerjs.dev) - [](https://github.com/faker-js/faker/actions/workflows/ci.yml) - [](https://codecov.io/gh/faker-js/faker) [](https://www.npmjs.com/package/@faker-js/faker) [](https://www.npmjs.com/package/@faker-js/faker) + [](https://github.com/faker-js/faker/actions/workflows/ci.yml) + [](https://codecov.io/gh/faker-js/faker) + [](https://chat.fakerjs.dev) [](https://opencollective.com/fakerjs#section-contributors) [](https://opencollective.com/fakerjs) </div> -### Try it Online ⚡️ - -[fakerjs.dev/new](https://fakerjs.dev/new) +## ⚡️ Try it Online [](https://fakerjs.dev/new) [API Documentation](https://fakerjs.dev/guide/) -## Installation - -Please replace your `faker` dependency with `@faker-js/faker`. This is the official, stable fork of Faker. - -```shell -npm install @faker-js/faker --save-dev -``` - -or yarn - -```shell -yarn add @faker-js/faker -D -``` - -or pnpm - -```shell -pnpm install @faker-js/faker -D -``` - -### Browser - -```html -<script src="faker.js" type="text/javascript"></script> -<script> - const randomName = faker.name.findName(); // Caitlyn Kerluke - const randomEmail = faker.internet.email(); // [email protected] - const randomPhoneNumber = faker.phone.phoneNumber(); // (746) 637-3344 x8083 -</script> -``` +## 🚀 Features -### Node.js +- 💌 Addresses - Generate valid looking Addresses, Zip Codes, Street Names, States, and Countries! +- ⏰ Time-based Data - Past, present, future, recent, soon... whenever! +- 🌏 Localization - Set a locale to generate realistic looking Names, Addresses, and Phone Numbers. +- 💸 Finance - Create stubbed out Account Details, Transactions, and Crypto Addresses. +- 👠 Products - Generate Prices, Product Names, Adjectives, and Descriptions. +- 👾 Hacker Jargon - “Try to reboot the SQL bus, maybe it will bypass the virtual application!” +- 🧍 Names - Generate virtual humans with a complete online and offline identity. +- 🔢 Numbers - Of course, we can also generate random numbers and strings. -```js -const { faker } = require('@faker-js/faker'); +## 📦 Install -const randomName = faker.name.findName(); // Rowan Nikolaus -const randomEmail = faker.internet.email(); // [email protected] -const randomPhoneNumber = faker.phone.phoneNumber(); // (279) 329-8663 x30233 +```bash +npm install --save-dev @faker-js/faker ``` -### CDN/Deno - -```js -import { faker } from 'https://cdn.skypack.dev/@faker-js/faker'; - -const randomName = faker.name.findName(); // Willie Bahringer -const randomEmail = faker.internet.email(); // [email protected] -const randomPhoneNumber = faker.phone.phoneNumber(); // 938-672-1359 x418 -``` - -#### Alternative CDN links - -**esm:** - -- https://esm.sh/@faker-js/faker -- https://cdn.jsdelivr.net/npm/@faker-js/faker/+esm - -**cjs:** - -- https://cdn.jsdelivr.net/npm/@faker-js/faker - -### TypeScript Support - -Since version `v6+` there is native TypeScript support. - -In order to have faker working properly, you need to check if these `compilerOptions` are set correctly in your `tsconfig` file: - -```json -{ - "compilerOptions": { - "esModuleInterop": true, - "moduleResolution": "Node" - } -} -``` - -And then simply import it like everything else: +## 🪄 Usage ```ts import { faker } from '@faker-js/faker'; -``` +// import { faker } from '@faker-js/faker/locale/de'; + +export const USERS: User[] = []; + +export function createRandomUser(): User { + return { + userId: faker.datatype.uuid(), + username: faker.internet.userName(), + email: faker.internet.email(), + avatar: faker.image.avatar(), + password: faker.internet.password(), + birthdate: faker.date.birthdate(), + registeredAt: faker.date.past(), + }; +} -If you want for whatever reason the versions prior to `v6`, -you can use `@types/faker` and rebind the declarations to the `@faker-js/faker` package with a `faker.d.ts` file in your e.g. src folder. +Array.from({ length: 10 }).forEach(() => { + USERS.push(createRandomUser()); +}); +``` + +## 💎 Modules + +An in-depth overview of the API methods is available in the [documentation](https://fakerjs.dev/guide/). +The API covers the following modules: + +| Module | Example | Output | +| -------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| Address | `faker.address.city()` | Lake Raoulfort | +| Animal | `faker.animal.cat()` | Norwegian Forest Cat | +| Color | `faker.color.rgb()` | #cdfcdc | +| Commerce | `faker.commerce.product()` | Polo t-shirt | +| Company | `faker.company.companyName()` | Zboncak and Sons | +| Database | `faker.database.engine()` | MyISAM | +| Datatype | `faker.datatype.uuid()` | 7b16dd12-935e-4acc-8381-b1e457bf0176 | +| Date | `faker.date.past()` | Sat Oct 20 2018 04:19:38 GMT-0700 (Pacific Daylight Time) | +| Finance | `faker.finance.amount()` | ¥23400 (After setting locale) | +| Git | `faker.git.commitMessage()` | feat: add products list page | +| Hacker | `faker.hacker.phrase()` | Try to reboot the SQL bus, maybe it will bypass the virtual application! | +| Helpers | `faker.helpers.arrayElement(['a', 'b', 'c'])` | b | +| Image | `faker.image.cats()` | https://loremflickr.com/640/480/cats <img src="https://loremflickr.com/640/480/cats" height="100"> | +| Internet | `faker.internet.domainName()` | muddy-neuropathologist.net | +| Lorem | `faker.lorem.paragraph()` | Porro nulla id vero perspiciatis nulla nihil. ... | +| Music | `faker.music.genre()` | R&B | +| Name | `faker.name.firstName()` | Cameron | +| Phone | `faker.phone.phoneNumber()` | +1 291-299-0192 | +| Random | `faker.random.locale()` | fr_CA | +| System | `faker.system.directoryPath()` | /root | +| Vehicle | `faker.vehicle.vehicle()` | Lamborghini Camry | +| Word | `faker.word.adjective()` | adorable | + +### Templates + +Faker contains a generator method `faker.fake` for combining faker API methods using a mustache string format. ```ts -// faker.d.ts -declare module '@faker-js/faker' { - import faker from 'faker'; - export default faker; -} -``` - -## API - -An in-depth overview of the API methods is available in the [documentation](https://fakerjs.dev/guide/). The API covers the following modules: - -| Module | Example | Output | -| -------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Address | `faker.address.city()` | Lake Raoulfort | -| Animal | `faker.animal.type()` | Dog, cat, snake, bear, lion, etc. | -| Commerce | `faker.commerce.product()` | Polo t-shirt | -| Company | `faker.company.companyName()` | Zboncak and Sons | -| Database | `faker.database.engine()` | MyISAM | -| Datatype | `faker.datatype.uuid()` | 7b16dd12-935e-4acc-8381-b1e457bf0176 | -| Date | `faker.date.past()` | Sat Oct 20 2018 04:19:38 GMT-0700 (Pacific Daylight Time) | -| Finance | `faker.finance.amount()` | ¥23400 (After setting locale) | -| Git | `faker.git.commitMessage()` | feat: add products list page | -| Hacker | `faker.hacker.phrase()` | Try to reboot the SQL bus, maybe it will bypass the virtual application! | -| Helpers | `faker.helpers.arrayElement(['a', 'b', 'c'])` | `'b'` | -| Image | `faker.image.avatar()` | `https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/233.jpg` <img src="https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/233.jpg" width="64"/> | -| Internet | `faker.internet.color()` | #630c7b | -| Lorem | `faker.lorem.paragraph()` | Word, words, sentences, slug (lorem-ipsum), paragraph(s), text, lines | -| Music | `faker.music.genre()` | R&B | -| Name | `faker.name.firstName()` | Cameron | -| Phone | `faker.phone.phoneNumber()` | +1 291-299-0192 | -| Random | `faker.random.locale()` | fr_CA | -| System | `faker.system.directoryPath()` | C:\Documents\Newsletters\ | -| Vehicle | `faker.vehicle.vehicle()` | 2011 Dodge Caravan | - -### faker.fake() - -Faker contains a super useful generator method `faker.fake` for combining faker API methods using a mustache string format. - -**Example:** - -```js console.log( - faker.fake('{{name.lastName}}, {{name.firstName}} {{name.suffix}}') + faker.fake('Hello {{name.prefix}} {{name.lastName}}, how are you today?') ); ``` -This will interpolate the format string with the value of methods `name.lastName()`, `name.firstName()`, and `name.suffix()` - -## Localization +## 🌏 Localization Faker has support for multiple locales. @@ -164,27 +109,20 @@ The default language locale is set to English. Setting a new locale is simple: -```js +```ts // sets locale to de faker.locale = 'de'; ``` See our documentation for a list of [provided languages](https://fakerjs.dev/api/localization.html#localization) -### Individual Localization Packages - -Faker supports incremental loading of locales. - -```js -// loads only de locale -const { faker } = require('@faker-js/faker/locale/de'); -``` +Please note that not every locale provides data for every module. In out pre-made locales, we fallback to english in such a case as this is the most complete and most common used language. -## Setting a randomness seed +## ⚙️ Setting a randomness seed If you want consistent results, you can set your own seed: -```js +```ts faker.seed(123); const firstRandom = faker.datatype.number(); @@ -197,7 +135,7 @@ const secondRandom = faker.datatype.number(); console.log(firstRandom === secondRandom); ``` -## Sponsors +## 🤝 Sponsors Faker is an MIT-licensed open source project with its ongoing development made possible entirely by the support of these awesome backers @@ -209,71 +147,26 @@ Faker is an MIT-licensed open source project with its ongoing development made p  -## Contributing +## ✨ Contributing Please make sure to read the [Contributing Guide](https://github.com/faker-js/faker/blob/main/CONTRIBUTING.md) before making a pull request. -### Building Faker - -The project is being built by [esbuild](https://esbuild.github.io) (see [bundle.ts](scripts/bundle.ts)) - -```shell -pnpm install -pnpm run build -``` - -### Testing - -```shell -pnpm install -pnpm run build - -pnpm run test -# or -pnpm run coverage -``` - -You can view a code coverage report generated in `coverage/index.html`. - -### Developing the docs - -```shell -# build the Faker dist -# it's used inside of certain routes -pnpm run build - -pnpm run docs:dev -``` - -### Building and serving the docs statically - -```shell -# build the Faker dist -# it's used inside of certain routes -pnpm run build +## 📘 Credits -pnpm run docs:build # Output docs to /dist -pnpm run docs:serve # Serve docs from /dist -``` - -### Deploying Documentation +Thanks to all the people who already contributed to Faker! -The website is kindly hosted for free by the Netlify team under their Open Source plan. See the [netlify.toml](netlify.toml) for configuration. +<a href="https://github.com/faker-js/faker/graphs/contributors"><img src="https://opencollective.com/fakerjs/contributors.svg?width=800" /></a> -### Thank you +The [fakerjs.dev](https://fakerjs.dev) website is kindly hosted by the Netlify Team. Also the search functionality is powered by [algolia](https://www.algolia.com). -Thank you to all the people who already contributed to Faker! +## 📝 Changelog -<a href="https://github.com/faker-js/faker/graphs/contributors"><img src="https://opencollective.com/fakerjs/contributors.svg?width=800" /></a> +Detailed changes for each release are documented in the [release notes](https://github.com/faker-js/faker/blob/main/CHANGELOG.md). -## What happened to the original faker.js? +## 📜 What happened to the original faker.js? Read the [team update](https://fakerjs.dev/update.html) (January 14th, 2022). -## Changelog - -Detailed changes for each release are documented in the [release notes](https://github.com/faker-js/faker/blob/main/CHANGELOG.md). - -## License +## 🔑 License [MIT](https://github.com/faker-js/faker/blob/main/LICENSE) |