Skip to content
Logo

Mental model

Fabricator has three layers, always used in this order:

Registry

T, returned by initialize({ types }), holds one builder for each primitive kind: T.string, T.object({ ... }), T.array(T.string), and so on. Calling or accessing a builder produces a Schema.

Schema

A Schema is plain data. It records what kind of value it describes and how that value is configured. Building a Schema never involves randomness. You can pass Schemas around, store them, nest them inside T.object or T.array, and derive new ones with .extend(), .refine(), and .override(). None of that produces a value; it only describes one.

Fabricator

new Fabricator(schema) turns a Schema into a Fabricator, which has a .fabricate() method. Building it sets up the randomness each field will draw from. A Schema is a blueprint, and a Fabricator is ready to produce values from it.

import { initialize } from "@ghostry/fabricator";
 
const { T, Fabricator } = initialize();
 
const UserSchema = T.object({
  name: T.string.whereby({ length: { min: 3, max: 20 } }),
  age: T.number.integer.whereby({ min: 18, max: 99 }),
});
// UserSchema is plain data, and nothing random has happened yet
 
const User = new Fabricator(UserSchema);
// User is ready to produce values with .fabricate()
 
const user = User.fabricate();
// this call draws the values

One instance, one isolated world

initialize({ clock, types, algorithm, salt }) creates one self-contained instance with its own randomness, its own T, and its own Fabricator constructor. Instances share no state, so two initialize() calls never affect each other. That is what makes it safe to give parallel tests their own salts. See Reproducibility for how the isolation works, including what clock controls for T.date.

Why the split matters

A Schema never involves randomness, so you can compose, store, and reuse it without drawing a value by accident. ProductSchema.extend(...) and Product.schema.override({ ... }) only ever produce another schema, however you chain them.

initialize() does record one value before any Schema exists: its clock, which is the current time by default. That is a one-time setup step for the whole instance, not part of any field. Every field's value is still drawn only when .fabricate() is called.