Primitives

Strings, numbers, and booleans are the atoms of every forged object — and can be forged on their own.

String

const name = Forger.create<string>()!;
// 'I8SE1ou3ZD' — 10 chars, letters + digits + specials by default

By default the charset mixes lowercase, uppercase, digits, and special characters; the length is 10. Both are tunable:

const code = Forger.create<string>({
  stringLength: 4,
  stringNumbers: true,
  stringLowCase: false,
  stringUpCase: false,
  stringSpecial: false,
})!;
// '7392' — digits only

Full option list: String settings.

Number

const age = Forger.create<number>()!;
// 345 — an integer between 1 and 1000 by default

Ranges and fractional output are controlled by number settings:

const price = Forger.create<number>({ numberMin: 10, numberMax: 99, numberFloat: true })!;
// 47.213…

If numberMin exceeds numberMax, Forger fixes the range instead of throwing — the maximum becomes numberMin + 100. Details in Number settings.

Boolean

const flag = Forger.create<boolean>()!;
// true or false, ~50/50

Booleans ignore settings.

null and undefined

Standalone null and undefined type arguments forge to null — there is no meaningful random value for them:

Forger.create<null>();      // null
Forger.create<undefined>(); // null

Inside unions they behave differently: null | number and number | undefined both produce a number, because nullable members are dropped during generation (see Unions).

Assertions on primitives

Generated values are random — assert on type and constraints, not on concrete values:

const age = Forger.create<number>({ numberMax: 100 })!;

expect(typeof age).toBe('number');
expect(age).toBeLessThanOrEqual(100);
expect(age).toBeGreaterThanOrEqual(1);

When a concrete primitive is required, generate it first and reuse the generated value as the expected constant:

const expected = Forger.create<string>()!;
const holder = Forger.createWith<{ value: string }>()
  .with(h => h.value = expected)
  .result()!;

expect(holder.value).toBe(expected);

08 September 2026