Introduction
Declarative, type‑safe factory for generating realistic test data — what it is, why it helps, and when to use it.
What is it?
Decorated Factory combines lightweight metadata decorators with a fluent builder to describe how your entities should look and then materialize them on demand. You describe fields and relations once; the builder lets you opt‑in to exactly the parts you need for a given test or seeding scenario.
When should you use it?
Use Decorated Factory when you need:
- Realistic, structured data for unit and integration tests without brittle hand‑written mocks.
- Deterministic yet flexible generation (override the few values that matter, keep the rest realistic).
- Reusable blueprints for database seeders and fixtures across services.
- Clear, explicit control over which relations are included in each scenario.
It’s especially helpful in medium/large projects where test data tends to sprawl and duplicate across suites.
Why Decorated Factory?
- Type‑safe paths with great IDE hints for nested fields (e.g.
photos.description). - Lazy relations — nothing is created unless you ask for it.
- No hidden globals — each builder is explicit and predictable.
- Bring‑your‑own Faker — plug any
@faker-js/fakerlocale or custom instance. - Works with plain objects or class instances.
How it works (at a glance)
- Describe fields with decorators that tell the factory how to generate values.
- Declare relationships between entities to form a graph.
- Use a fluent builder to “query” that graph: opt‑in to relations, tweak or exclude fields, and finally materialize data.
This page focuses on the concepts and value proposition. For hands‑on usage, follow the links below.