FakerService
katanakit-js / FakerService
Class: FakerService
Section titled “Class: FakerService”Defined in: core/services/faker.service.ts:36
FakerService — generic fake data for tests, seeds and forms.
Applies the Singleton pattern (one shared instance via
FakerService.getInstance) and the Facade pattern: each public
method hides the lazy @faker-js/faker load behind one call. The optional
peer dependency is imported through dynamic import() on first use, so it
never enters the initial bundle and consumers who don’t use it don’t
install it.
Every public method uses the use* prefix per CONTRIBUTING.md; the
module level useFake* functions below are thin wrappers kept for
call-site ergonomics.
Example
Section titled “Example”import { useFakeSeed, useFakeUuid } from "katanakit-js";
const seed = await useFakeSeed(); // random, but loggable/replayableawait useFakeSeed(seed); // replays the same sequenceawait useFakeUuid();Methods
Section titled “Methods”useFakeBoolean()
Section titled “useFakeBoolean()”useFakeBoolean(): Promise<boolean>;Defined in: core/services/faker.service.ts:234
Generates a random boolean.
Returns
Section titled “Returns”Promise<boolean>
true or false.
useFakeCompanyName()
Section titled “useFakeCompanyName()”useFakeCompanyName(): Promise<string>;Defined in: core/services/faker.service.ts:186
Generates a fake company name.
Returns
Section titled “Returns”Promise<string>
A company name.
useFakeDate()
Section titled “useFakeDate()”useFakeDate(from?, to?): Promise<Date>;Defined in: core/services/faker.service.ts:252
Generates a random date within an optional range.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
from? |
string | number | Date |
Lower bound (default: 1970-01-01). |
to? |
string | number | Date |
Upper bound (default: faker’s reference date, see useFakeSetDefaultRefDate — the current time when unset). |
Returns
Section titled “Returns”Promise<Date>
A Date instance.
Example
Section titled “Example”const hiredAt = await useFakeDate( new Date("2020-01-01"), new Date("2025-12-31"),);useFakeEmail()
Section titled “useFakeEmail()”useFakeEmail(): Promise<string>;Defined in: core/services/faker.service.ts:136
Generates a fake email address.
Returns
Section titled “Returns”Promise<string>
An email address.
useFakeFirstName()
Section titled “useFakeFirstName()”useFakeFirstName(): Promise<string>;Defined in: core/services/faker.service.ts:156
Generates a fake first name.
Returns
Section titled “Returns”Promise<string>
A first name.
useFakeFullName()
Section titled “useFakeFullName()”useFakeFullName(): Promise<string>;Defined in: core/services/faker.service.ts:146
Generates a fake full name.
Returns
Section titled “Returns”Promise<string>
A full name, e.g. "Ada Lovelace".
useFakeLastName()
Section titled “useFakeLastName()”useFakeLastName(): Promise<string>;Defined in: core/services/faker.service.ts:166
Generates a fake last name.
Returns
Section titled “Returns”Promise<string>
A last name.
useFakeList()
Section titled “useFakeList()”useFakeList<T>(factory, count): Promise<T[]>;Defined in: core/services/faker.service.ts:298
Builds an array of fake items from a factory (sync or async).
Type Parameters
Section titled “Type Parameters”| Type Parameter | Description |
|---|---|
T |
Item type produced by the factory. |
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
factory |
(index) => T | Promise<T> |
Called once per item; receives the zero-based index. |
count |
number |
Number of items to generate (non-negative integer). |
Returns
Section titled “Returns”Promise<T[]>
A promise resolving to the generated array.
Example
Section titled “Example”const vehicles = await useFakeList(() => useFakeVehicle(), 5);const relations = await useFakeList( (index) => ({ user: users[index % users.length] }), 10,);useFakeNumber()
Section titled “useFakeNumber()”useFakeNumber(min?, max?): Promise<number>;Defined in: core/services/faker.service.ts:224
Generates an integer within an inclusive range.
Parameters
Section titled “Parameters”| Parameter | Type | Default value | Description |
|---|---|---|---|
min? |
number |
0 |
Lower bound (default: 0). |
max? |
number |
100 |
Upper bound (default: 100). |
Returns
Section titled “Returns”Promise<number>
A random integer between min and max.
Example
Section titled “Example”const age = await useFakeNumber(18, 65);useFakePhone()
Section titled “useFakePhone()”useFakePhone(): Promise<string>;Defined in: core/services/faker.service.ts:176
Generates a fake phone number.
Returns
Section titled “Returns”Promise<string>
A phone number string.
useFakeSeed()
Section titled “useFakeSeed()”useFakeSeed(seed?): Promise<number>;Defined in: core/services/faker.service.ts:88
Seeds the faker instance for reproducible output, or rolls a new random seed.
The sequence depends on the seed, the number of calls made since it was set and the faker major version — keep the call order stable for stable output.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
seed? |
number |
Optional numeric seed. Omit it to generate a fresh random seed (log the returned value and pass it back later to replay the exact run). |
Returns
Section titled “Returns”Promise<number>
The seed that was set.
Example
Section titled “Example”import { useFakeSeed, useFakeUuid } from "katanakit-js";
const seed = await useFakeSeed(); // random, but loggable/replayableawait useFakeSeed(seed); // replays the same sequenceawait useFakeUuid();useFakeSetDefaultRefDate()
Section titled “useFakeSetDefaultRefDate()”useFakeSetDefaultRefDate(refDate?): Promise<Date>;Defined in: core/services/faker.service.ts:110
Pins the reference date faker uses for relative date helpers, so date-dependent output stays reproducible next to useFakeSeed.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
refDate? |
string | number | Date | (() => Date) |
Static date (Date, ISO string or epoch ms) or a factory returning a fresh Date on every call. Omit it to reset to the current time. |
Returns
Section titled “Returns”Promise<Date>
The reference date now in effect.
Example
Section titled “Example”import { useFakeSeed, useFakeSetDefaultRefDate, useFakeDate,} from "katanakit-js";
await useFakeSeed(42);await useFakeSetDefaultRefDate("2026-01-01");await useFakeDate(); // reproducible between 1970-01-01 and 2026-01-01useFakeText()
Section titled “useFakeText()”useFakeText(words?): Promise<string>;Defined in: core/services/faker.service.ts:207
Generates lorem-ipsum text.
Parameters
Section titled “Parameters”| Parameter | Type | Default value | Description |
|---|---|---|---|
words? |
number |
12 |
Number of words (default: 12). |
Returns
Section titled “Returns”Promise<string>
A space-separated string of words.
useFakeUrl()
Section titled “useFakeUrl()”useFakeUrl(): Promise<string>;Defined in: core/services/faker.service.ts:196
Generates a fake URL.
Returns
Section titled “Returns”Promise<string>
An absolute URL.
useFakeUuid()
Section titled “useFakeUuid()”useFakeUuid(): Promise<string>;Defined in: core/services/faker.service.ts:126
Generates a v4 UUID.
Returns
Section titled “Returns”Promise<string>
A random UUID string.
Example
Section titled “Example”const id = await useFakeUuid();useFakeVehicle()
Section titled “useFakeVehicle()”useFakeVehicle(): Promise<{ brand: string; color: string; fuel: string; model: string; plate: string; type: string; vin: string;}>;Defined in: core/services/faker.service.ts:271
Generates a generic fake vehicle (brand, model, type, fuel, color, vin, plate).
Returns
Section titled “Returns”Promise<{
brand: string;
color: string;
fuel: string;
model: string;
plate: string;
type: string;
vin: string;
}>
A FakeVehicle object.
Example
Section titled “Example”const vehicle = await useFakeVehicle();// { brand: "Jeep", model: "Wrangler", plate: "HJ47FNP", ... }getInstance()
Section titled “getInstance()”static getInstance(): FakerService;Defined in: core/services/faker.service.ts:46
Returns the shared instance (Singleton).
Returns
Section titled “Returns”FakerService