Literals

Literal types — 'asc', 42, true — represent fixed value sets. Forger rolls a random member of the set, which makes literal unions a natural way to forge constrained values.

Literal unions

Every string, numeric, and boolean literal in a union is a candidate, and each call rolls one:

type SortOrder = 'asc' | 'desc';

const order = Forger.create<SortOrder>()!;
// 'asc' or 'desc'

const answer = Forger.create<'yes' | 'no' | 'maybe' | 42 | true>()!;
// any of the five, rolled at runtime

Literal unions are a natural companion to enums: both roll a random member per call, and literal unions can be declared inline — see Enums for the comparison.

Literal properties

A property whose type is a literal union is forged the same way:

interface Query {
  order: 'asc' | 'desc';
  page: 1 | 2 | 3;
}

const query = Forger.create<Query>()!;
// { order: 'desc', page: 2 } — for example

When a test is specifically about one member, pin it:

const descending = Forger.createWith<Query>()
  .with(q => q.order = 'desc')
  .result()!;

Standalone literals

A single non-union literal is a degenerate case: Forger does not resolve it, and the result is null.

const fixed = Forger.create<'always-this-value'>();
// null

There is nothing to generate from a type with exactly one inhabitant anyway — if a constant is needed, declare it directly or pin it with createWith. See Caveats.

Literal unions vs enums

	Literal union	Enum (numeric/string)
Random member per call	yes	yes
Falsy members (`0`, `''`)	reachable	reachable
Enum API (`Status.Draft`)	no	yes
Needs a declaration statement	no (inline allowed)	yes

Prefer literal unions inside test doubles; keep enums where production code benefits from them.

08 September 2026