Skip to content

Commit 05aa969

Browse files
xDivisionByZeroxxDivisionByZerox
authored
docs: usage page in guides (#1366)
1 parent 7438a8a commit 05aa969

3 files changed

Lines changed: 209 additions & 88 deletions

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,10 @@ export default defineConfig({
130130
text: 'Getting Started',
131131
link: '/guide/',
132132
},
133+
{
134+
text: 'Usage',
135+
link: '/guide/usage',
136+
},
133137
{
134138
text: 'Localization',
135139
link: '/guide/localization',

‎docs/guide/index.md‎

Lines changed: 0 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -37,94 +37,6 @@ or
3737
pnpm add @faker-js/faker --save-dev
3838
```
3939

40-
## Usage
41-
42-
### Node.js
43-
44-
```js
45-
import { faker } from '@faker-js/faker';
46-
// or, if using CommonJS
47-
// const { faker } = require('@faker-js/faker');
48-
49-
const randomName = faker.name.fullName(); // Rowan Nikolaus
50-
const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
51-
```
52-
53-
### Browser
54-
55-
```html
56-
<!-- Since v6 only type=module is supported -->
57-
<script type="module">
58-
import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
59-
60-
// Caitlyn Kerluke
61-
const randomName = faker.name.fullName();
62-
63-
// Rusty@arne.info
64-
const randomEmail = faker.internet.email();
65-
</script>
66-
```
67-
68-
:::tip Note
69-
Using the browser is great for experimenting 👍. However, due to all of the strings Faker uses to generate fake data, **Faker is a large package**. It's `> 5 MiB` minified. **Please avoid deploying the full Faker in your web app.**
70-
:::
71-
72-
### CDN/Deno
73-
74-
```js
75-
import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
76-
77-
const randomName = faker.name.findName(); // Willie Bahringer
78-
const randomEmail = faker.internet.email(); // Tomasa_Ferry14@hotmail.com
79-
```
80-
81-
:::tip Note
82-
It is highly recommended to use version tags when importing libraries in Deno, e.g: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0"`. Add `?dts` to import with type definitions: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0?dts"`.
83-
:::
84-
85-
#### Alternative CDN links
86-
87-
**esm:**
88-
89-
- https://esm.sh/@faker-js/faker
90-
- https://cdn.jsdelivr.net/npm/@faker-js/faker/+esm
91-
92-
**cjs:**
93-
94-
- https://cdn.jsdelivr.net/npm/@faker-js/faker
95-
96-
### TypeScript Support
97-
98-
Since version `v6+` there is native TypeScript support.
99-
100-
In order to have faker working properly, you need to check if these `compilerOptions` are set correctly in your `tsconfig` file:
101-
102-
```json
103-
{
104-
"compilerOptions": {
105-
"esModuleInterop": true,
106-
"moduleResolution": "Node"
107-
}
108-
}
109-
```
110-
111-
And then simply import it like everything else:
112-
113-
```ts
114-
import { faker } from '@faker-js/faker';
115-
```
116-
117-
If you want for whatever reason the versions prior to `v6`,
118-
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.
119-
120-
```ts
121-
// faker.d.ts
122-
declare module '@faker-js/faker' {
123-
import faker from 'faker';
124-
export default faker;
125-
}
126-
```
127-
12840
## Community
12941

13042
If you have questions or need help, reach out to the community via [Discord](https://chat.fakerjs.dev) and [GitHub Discussions](https://github.com/faker-js/faker/discussions).

‎docs/guide/usage.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Usage
2+
3+
## Node.js
4+
5+
Using Faker is as easy as importing it from `@faker-js/faker`.
6+
7+
```js
8+
import { faker } from '@faker-js/faker';
9+
10+
const randomName = faker.name.fullName(); // Rowan Nikolaus
11+
const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
12+
```
13+
14+
Or if you using CommonJS
15+
16+
```js
17+
const { faker } = require('@faker-js/faker');
18+
19+
const randomName = faker.name.fullName(); // Rowan Nikolaus
20+
const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
21+
```
22+
23+
## Browser
24+
25+
```html
26+
<script type="module">
27+
import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
28+
29+
// Caitlyn Kerluke
30+
const randomName = faker.name.fullName();
31+
32+
// Rusty@arne.info
33+
const randomEmail = faker.internet.email();
34+
</script>
35+
```
36+
37+
:::note
38+
Using the browser is great for experimenting 👍. However, due to all of the strings Faker uses to generate fake data, **Faker is a large package**. It's `> 5 MiB` minified. **Please avoid deploying the full Faker in your web app.**
39+
:::
40+
41+
## CDN/Deno
42+
43+
```js
44+
import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
45+
46+
const randomName = faker.name.findName(); // Willie Bahringer
47+
const randomEmail = faker.internet.email(); // Tomasa_Ferry14@hotmail.com
48+
```
49+
50+
:::note
51+
It is highly recommended to use version tags when importing libraries in Deno, e.g: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0"`. Add `?dts` to import with type definitions: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0?dts"`.
52+
:::
53+
54+
### Alternative CDN links
55+
56+
**esm:**
57+
58+
- https://esm.sh/@faker-js/faker
59+
- https://cdn.jsdelivr.net/npm/@faker-js/faker/+esm
60+
61+
**cjs:**
62+
63+
- https://cdn.jsdelivr.net/npm/@faker-js/faker
64+
65+
## TypeScript Support
66+
67+
Faker supports TypeScript out of the box, so you don't have to install any extra packages.
68+
69+
In order to have Faker working properly, you need to check if these `compilerOptions` are set correctly in your `tsconfig` file:
70+
71+
```json
72+
{
73+
"compilerOptions": {
74+
"esModuleInterop": true,
75+
"moduleResolution": "Node"
76+
}
77+
}
78+
```
79+
80+
## Create complex objects
81+
82+
Faker mostly generates values for primitives.
83+
This is because in the real world, most object schemas simply look very different.
84+
So, if you want to create an object, you most likely need to write a factory function for it.
85+
86+
For our example, we use TypeScript to strongly type our model.
87+
The models we will use are described below:
88+
89+
```ts
90+
import type { SexType } from '@faker-js/faker';
91+
92+
type SubscriptionTier = 'free' | 'basic' | 'business';
93+
94+
class User {
95+
_id: string;
96+
avatar: string;
97+
birthday: Date;
98+
email: string;
99+
firstName: string;
100+
lastName: string;
101+
sex: SexType;
102+
subscriptionTier: SubscriptionTier;
103+
}
104+
```
105+
106+
As you can see, your `User` model probably looks completely different from the one you have in your codebase.
107+
One thing to keep an eye on is the `subscriptionTier` property, as it is not simply a string, but only one of the strings defined in the `SubscriptionTier` type (`'free'` or `'basic'` or `'business'`).
108+
Also, in a real scenario, your model should not depend on a type of a third party library (`SexType` in this case).
109+
110+
Let's create our first user factory function:
111+
112+
```ts
113+
import { faker } from '@faker-js/faker';
114+
115+
function createRandomUser(): User {
116+
return {
117+
_id: faker.datatype.uuid(),
118+
avatar: faker.image.avatar(),
119+
birthday: faker.date.birthdate(),
120+
email: faker.internet.email(),
121+
firstName: faker.name.firstName(),
122+
lastName: faker.name.lastName(),
123+
sex: faker.name.sexType(),
124+
subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
125+
};
126+
}
127+
128+
const user = createRandomUser();
129+
```
130+
131+
At this point, we have a perfectly working function that will work for most purposes.
132+
But we can take this a step further.
133+
Currently, all properties are just randomly generated.
134+
This can lead to some undesirable values being produced.
135+
For example: The `sex` property having value `'female'` while `firstName` is `'Bob'`.
136+
137+
Let's refactor our current code:
138+
139+
```ts {4-7,13-16}
140+
import { faker } from '@faker-js/faker';
141+
142+
function createRandomUser(): User {
143+
const sex = this.faker.name.sexType();
144+
const firstName = faker.name.firstName(sex);
145+
const lastName = faker.name.lastName();
146+
const email = faker.internet.email(firstName, lastName);
147+
148+
return {
149+
_id: faker.datatype.uuid(),
150+
avatar: faker.image.avatar(),
151+
birthday: faker.date.birthdate(),
152+
email,
153+
firstName,
154+
lastName,
155+
sex,
156+
subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
157+
};
158+
}
159+
160+
const user = createRandomUser();
161+
```
162+
163+
As you can see, we changed the order in which we generate our values.
164+
First, we generate a `sex` value to use it as input for the generation of `firstName`.
165+
Then we generate the `lastName`.
166+
Here, we could also pass in the `sex` value as argument, but in our use-case there are no special cases in where a female last name would differ from a male one.
167+
By doing this first, we are able to pass both names into the `email` generation function.
168+
This allows the value to be more reasonable based on the provided arguments.
169+
170+
But we can take this even another step further.
171+
Opposite to the `_id` property that uses an `uuid` implementation, which is unique by design, the `email` property potentially isn't.
172+
But, in most use-cases, this would be desirable.
173+
174+
Faker has your back, with another helper method:
175+
176+
```ts {7-9}
177+
import { faker } from '@faker-js/faker';
178+
179+
function createRandomUser(): User {
180+
const sex = this.faker.name.sexType();
181+
const firstName = faker.name.firstName(sex);
182+
const lastName = faker.name.lastName();
183+
const email = faker.helpers.unique(faker.internet.email, [
184+
firstName,
185+
lastName,
186+
]);
187+
188+
return {
189+
_id: faker.datatype.uuid(),
190+
avatar: faker.image.avatar(),
191+
birthday: faker.date.birthdate(),
192+
email,
193+
firstName,
194+
lastName,
195+
sex,
196+
subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
197+
};
198+
}
199+
200+
const user = createRandomUser();
201+
```
202+
203+
By wrapping Faker's `email` function with the [`unique`](../api/helpers.md#unique) helper function, we ensure that the return value of `email` is always unique.
204+
205+
Congratulations, you should now be able to create any complex object you desire. Happy faking 🥳.

0 commit comments

Comments
 (0)