Installation
Fabricator is ESM only and has no runtime dependencies.
Requirements
- A runtime that supports ES modules: Bun, Node, Deno, or a bundler.
- TypeScript is not required, but it is strongly recommended. Fabricator is built for it, and the type of every fabricated value is inferred from its schema. Fabricator's types, and those of its adapters and extensions, need TypeScript 5.4 or later.
Optional: a dynamic data library
By default, fabricator generates arbitrary (fuzzing) values, not realistic ones. T.string.whereby({ length: { max: 20 } }) gives you a random string, not a name. For data that looks real, add the Faker extension:
import { initialize, registry } from "@ghostry/fabricator";
import { fakerExtension } from "@ghostry/fabricator-extension-faker-v10";
const { T } = initialize({
types: registry.extend(fakerExtension({ locale: ["base", "en"] })),
});
const schema = T.faker.person.fullName();
// a T.string that fabricates faker valuesThe extension needs Node 20.19 or later, Bun, or Deno to fabricate. In a browser bundle, pass faker in yourself with create (see When faker loads).
Faker draws from fabricator's randomness, so these fields replay like any other. See the Faker guide for everything it provides.
You can also call any data library yourself with .as(...) or T.opaque. See T.opaque, including how to keep those fields reproducible.
Optional: schema adaptation for runtime validation
Fabricator doesn't validate values against a schema. To use the same shape as a validator too, add the TypeBox adapter:
import { toTypeBox } from "@ghostry/fabricator-adapter-typebox-v0";
const TProduct = toTypeBox(ProductSchema);It targets @sinclair/typebox 0.34.x, which is what the -v0 means. See the TypeBox guide for how each primitive maps by default and how to override that per schema.
Optional: a test harness
@ghostry/harness wraps your test runner's describe/it so each test draws data based on its own name. That data is reproducible and doesn't depend on which other tests ran:
See the Harness guide for setup, and the harness docs for everything else it does.
Optional: extern blocks
@ghostry/extern-extension-fabricator-v0 lets a typed extern block that uses a fabricator schema mock itself. Inside a testing block, it fabricates from its schema, so you don't have to write a mock.
See the Extern guide for the setup.
Optional: a census of real data
A schema's ranges, weights, and distributions are usually guesses. @ghostry/fabricator-census reads a sample of real data and suggests them. It can also build the PostgreSQL queries to collect that sample:
import { census, report } from "@ghostry/fabricator-census";
console.log(report(census.from(rows)));See the Census guide for how to read the suggestions and sample a table.
