How It Works

Forger is a compile-time transformer plus a runtime factory pipeline. Understanding the split explains both its power (full type awareness) and its constraints (the transformer must run).

The big picture

┌─────────────────────────────────────────────────────────────────────┐
│ COMPILE TIME                                                        │
│                                                                     │
│  Forger.create<Student>(settings)                                   │
│        │                                                            │
│        ▼  the forger transformer (ts-patch / ts-jest / Angular)     │
│  the type argument is walked with the TypeScript TypeChecker        │
│        │                                                            │
│        ▼                                                            │
│  a ForgerElement tree describing the type:                          │
│  { type: Object, children: [                                        │
│      { name: 'name', type: String },                                │
│      { name: 'age',  type: Number },                                │
│      { name: 'birthday', type: Date },                              │
│  ]}                                                                 │
│        │                                                            │
│        ▼  serialized as JSON and injected as a trailing argument    │
│  Forger.create<Student>(settings, circularDepth, «element»)         │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│ RUNTIME                                                             │
│                                                                     │
│  Forger.create receives the element                                 │
│        │                                                            │
│        ▼                                                            │
│  MainFactory.produce(element, settings)                             │
│  picks the first applicable factory (Object, Array, Tuple, String,  │
│  Number, Bool, Date, Enum, Function, Literal, Union) recursively    │
│        │                                                            │
│        ▼                                                            │
│  { name: 'I8SE1ou3ZD', age: 345, birthday: Date(2093, 7, 14) }      │
└─────────────────────────────────────────────────────────────────────┘

Compile time: the transformer

The transformer scans every Forger.create<T>(...) and Forger.createWith<T>(...) call:

It resolves T through the TypeScript TypeChecker — the same machinery the compiler uses.
A chain of type transformers (UnionTransformer, ArrayTransformer, CustomTypeTransformer, PrimitiveTransformer, and friends) converts the type node into a ForgerElement tree. During the walk it resolves inheritance chains, substitutes generic arguments, tracks circular references against the configured depth, and drops properties pinned later by createWith().with(...).
The tree is serialized to JSON and appended to the call as the last argument.

The call you wrote and the call that ships in the bundle are different things — the difference is the injected type description.

Runtime: the factories

Forger.create hands the element to MainFactory. Every factory answers two questions: isApplicable(element) — can it handle this element type — and produce(element, settings) — build the value. MainFactory takes the first applicable factory and recurses into children:

ObjectFactory iterates properties and recurses;
ArrayFactory produces arrayLength fresh elements (each element is regenerated);
UnionFactory and LiteralFactory roll a random member of the allowed set;
StringFactory, NumberFactory, DateFactory follow the limits from SpoofSettings.

Why this design

The alternative — reflecting on types at runtime — does not exist in TypeScript: types are erased during compilation. Libraries that "guess" from constructor metadata are limited to classes with decorators and cannot see interfaces, unions, or literals. By moving type resolution to compile time, Forger sees exactly what the compiler sees: any type, in any project, with no decorators and no registration.

The price is the setup: a build without the transformer produces no type information, and create<T>() returns undefined. Head to Installation for the wiring instructions and Caveats for the full list of sharp edges.

08 September 2026