Skip to content

FakerService

katanakit-js / 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.

import { useFakeSeed, useFakeUuid } from "katanakit-js";
const seed = await useFakeSeed(); // random, but loggable/replayable
await useFakeSeed(seed); // replays the same sequence
await useFakeUuid();
useFakeBoolean(): Promise<boolean>;

Defined in: core/services/faker.service.ts:234

Generates a random boolean.

Promise<boolean>

true or false.


useFakeCompanyName(): Promise<string>;

Defined in: core/services/faker.service.ts:186

Generates a fake company name.

Promise<string>

A company name.


useFakeDate(from?, to?): Promise<Date>;

Defined in: core/services/faker.service.ts:252

Generates a random date within an optional range.

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).

Promise<Date>

A Date instance.

const hiredAt = await useFakeDate(
new Date("2020-01-01"),
new Date("2025-12-31"),
);

useFakeEmail(): Promise<string>;

Defined in: core/services/faker.service.ts:136

Generates a fake email address.

Promise<string>

An email address.


useFakeFirstName(): Promise<string>;

Defined in: core/services/faker.service.ts:156

Generates a fake first name.

Promise<string>

A first name.


useFakeFullName(): Promise<string>;

Defined in: core/services/faker.service.ts:146

Generates a fake full name.

Promise<string>

A full name, e.g. "Ada Lovelace".


useFakeLastName(): Promise<string>;

Defined in: core/services/faker.service.ts:166

Generates a fake last name.

Promise<string>

A last name.


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 Parameter Description
T Item type produced by the factory.
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).

Promise<T[]>

A promise resolving to the generated array.

const vehicles = await useFakeList(() => useFakeVehicle(), 5);
const relations = await useFakeList(
(index) => ({ user: users[index % users.length] }),
10,
);

useFakeNumber(min?, max?): Promise<number>;

Defined in: core/services/faker.service.ts:224

Generates an integer within an inclusive range.

Parameter Type Default value Description
min? number 0 Lower bound (default: 0).
max? number 100 Upper bound (default: 100).

Promise<number>

A random integer between min and max.

const age = await useFakeNumber(18, 65);

useFakePhone(): Promise<string>;

Defined in: core/services/faker.service.ts:176

Generates a fake phone number.

Promise<string>

A phone number string.


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.

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).

Promise<number>

The seed that was set.

import { useFakeSeed, useFakeUuid } from "katanakit-js";
const seed = await useFakeSeed(); // random, but loggable/replayable
await useFakeSeed(seed); // replays the same sequence
await useFakeUuid();

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.

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.

Promise<Date>

The reference date now in effect.

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-01

useFakeText(words?): Promise<string>;

Defined in: core/services/faker.service.ts:207

Generates lorem-ipsum text.

Parameter Type Default value Description
words? number 12 Number of words (default: 12).

Promise<string>

A space-separated string of words.


useFakeUrl(): Promise<string>;

Defined in: core/services/faker.service.ts:196

Generates a fake URL.

Promise<string>

An absolute URL.


useFakeUuid(): Promise<string>;

Defined in: core/services/faker.service.ts:126

Generates a v4 UUID.

Promise<string>

A random UUID string.

const id = await useFakeUuid();

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).

Promise<{ brand: string; color: string; fuel: string; model: string; plate: string; type: string; vin: string; }>

A FakeVehicle object.

const vehicle = await useFakeVehicle();
// { brand: "Jeep", model: "Wrangler", plate: "HJ47FNP", ... }

static getInstance(): FakerService;

Defined in: core/services/faker.service.ts:46

Returns the shared instance (Singleton).

FakerService