1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
# Usage
## Node.js
Using Faker is as easy as importing it from `@faker-js/faker`.
```js
import { faker } from '@faker-js/faker';
// or, if desiring only a specific locale
// import { faker } from '@faker-js/faker/locale/de'
const randomName = faker.person.fullName(); // Rowan Nikolaus
const randomEmail = faker.internet.email(); // [email protected]
```
:::tip Note
Using the first import statement will load every locale into memory.
As such, start-up times and performance may be slow.
Thus, by declaring a locale in the import, one can increase performance and reduce the time on start-up.
:::
Or if you're using CommonJS:
```js
const { faker } = require('@faker-js/faker');
const randomName = faker.person.fullName(); // Rowan Nikolaus
const randomEmail = faker.internet.email(); // [email protected]
```
## Browser
```html
<script type="module">
import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
// Caitlyn Kerluke
const randomName = faker.person.fullName();
// [email protected]
const randomEmail = faker.internet.email();
</script>
```
::: info NOTE
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.**
:::
## CDN/Deno
```js
import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
const randomName = faker.person.fullName(); // Willie Bahringer
const randomEmail = faker.internet.email(); // [email protected]
```
::: info NOTE
It is highly recommended to use version tags when importing libraries in Deno, e.g: `import { faker } from "https://cdn.skypack.dev/@faker-js/[email protected]"`. Add `?dts` to import with type definitions: `import { faker } from "https://cdn.skypack.dev/@faker-js/[email protected]?dts"`.
:::
### 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
Faker supports TypeScript out of the box, so you don't have to install any extra packages.
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"
}
}
```
## Create complex objects
Faker mostly generates values for primitives.
This is because in the real world, most object schemas simply look very different.
So, if you want to create an object, you most likely need to write a factory function for it.
For our example, we use TypeScript to strongly type our model.
The models we will use are described below:
```ts
import type { SexType } from '@faker-js/faker';
type SubscriptionTier = 'free' | 'basic' | 'business';
interface User {
_id: string;
avatar: string;
birthday: Date;
email: string;
firstName: string;
lastName: string;
sex: SexType;
subscriptionTier: SubscriptionTier;
}
```
As you can see, your `User` model probably looks completely different from the one you have in your codebase.
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'`).
Also, in a real scenario, your model should not depend on a type of a third party library (`SexType` in this case).
Let's create our first user factory function:
```ts
import { faker } from '@faker-js/faker';
interface User { ... }
function createRandomUser(): User {
return {
_id: faker.datatype.uuid(),
avatar: faker.image.avatar(),
birthday: faker.date.birthdate(),
email: faker.internet.email(),
firstName: faker.person.firstName(),
lastName: faker.person.lastName(),
sex: faker.person.sexType(),
subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
};
}
const user = createRandomUser();
```
At this point, we have a perfectly working function that will work for most purposes.
But we can take this a step further.
Currently, all properties are just randomly generated.
This can lead to some undesirable values being produced.
For example: The `sex` property having value `'female'` while `firstName` is `'Bob'`.
Let's refactor our current code:
```ts {4-7,13-16}
import { faker } from '@faker-js/faker';
function createRandomUser(): User {
const sex = faker.person.sexType();
const firstName = faker.person.firstName(sex);
const lastName = faker.person.lastName();
const email = faker.internet.email(firstName, lastName);
return {
_id: faker.datatype.uuid(),
avatar: faker.image.avatar(),
birthday: faker.date.birthdate(),
email,
firstName,
lastName,
sex,
subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
};
}
const user = createRandomUser();
```
As you can see, we changed the order in which we generate our values.
First, we generate a `sex` value to use it as input for the generation of `firstName`.
Then we generate the `lastName`.
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.
By doing this first, we are able to pass both names into the `email` generation function.
This allows the value to be more reasonable based on the provided arguments.
But we can take this even another step further.
Opposite to the `_id` property that uses an `uuid` implementation, which is unique by design, the `email` property potentially isn't.
But, in most use-cases, this would be desirable.
Faker has your back, with another helper method:
```ts {7-9}
import { faker } from '@faker-js/faker';
function createRandomUser(): User {
const sex = faker.person.sexType();
const firstName = faker.person.firstName(sex);
const lastName = faker.person.lastName();
const email = faker.helpers.unique(faker.internet.email, [
firstName,
lastName,
]);
return {
_id: faker.datatype.uuid(),
avatar: faker.image.avatar(),
birthday: faker.date.birthdate(),
email,
firstName,
lastName,
sex,
subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
};
}
const user = createRandomUser();
```
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.
Congratulations, you should now be able to create any complex object you desire. Happy faking 🥳.
|
