Skip to content
Logo

Composition

You can make one schema from another, keep only some of a schema's fields, or override a single call on a Fabricator you already built. All of these work together.

.extend() — add or replace fields

const IdentifiableProductSchema = ProductSchema.extend(({ base }) => ({
  id: T.number.integer.sequence,
}));

This combines the base schema's fields with the ones you return. A new field is added. A field with the same name as an existing one replaces it entirely, even if both are objects; their fields are not merged. base is the original set of fields, in case the new ones need to refer to it. Ignore it if you don't need it.

A computed field that reads a field you replace reads the new one, so extending first changes a name computed from it. The new field's type has to be one that computed field can still take.

.refine() — add fields computed from fabricated data

const WithSlug = ProductSchema.refine(({ compute }) => ({
  slug: compute(T.string)
    .from(["name"])
    .as(({ fabricated }) => fabricated.name.toLowerCase().replace(/\s+/g, "-")),
}));

This works like .extend(), but the new fields are computed from the base schema's fabricated values. See Objects for how compute works. Refine stages chain, so a later .refine() can read a field an earlier one computed. A .refine() can also replace a field with a computed version that reads the original.

.override() — bake fixed values into a schema

const WidgetSchema = ProductSchema.override({
  name: "Widget",
  pricing: { currency: "USD" },
});
 
const widget = new Fabricator(WidgetSchema).fabricate();

This returns a new schema and involves no randomness. The named fields always produce the fixed value. Every other field keeps the same random stream it would have without the override (see Reproducibility). In a nested object like pricing, only the fields you name are fixed. Overrides chain: in .override(a).override(b), b wins where they conflict.

Like .extend(), it changes a field's current version, so a computed field reading that field reads the fixed value. If a .refine() replaced the field, the override fixes the replacement, and fields computed from the original still read the original.

.rebase() — replace a field's original input

const UserSchema = T.object({ name: T.enum.uniform(["ada", "grace"]) })
  .refine(({ compute }) => ({
    greeting: compute(T.string)
      .from(["name"])
      .as(({ fabricated }) => `hi ${fabricated.name}`),
  }))
  .refine(({ compute }) => ({
    name: compute(T.string)
      .from(["name"])
      .as(({ fabricated }) => fabricated.name.toUpperCase()),
  }));
 
const AdaSchema = UserSchema.rebase({ name: T.always("ada") });
new Fabricator(AdaSchema).fabricate(); // { name: "ADA", greeting: "hi ada" }

Once a .refine() has replaced a field, .extend() and .override() only reach the replacement. .rebase() replaces the field's original version instead, so every computed field that reads it gets the new input, and the computed replacement still runs on top of it. It takes schemas, like .extend(), and every other field keeps its random stream.

On a field no .refine() replaced, .rebase() does the same as .extend(). It also reaches a field that T.pick or T.omit left out of the result but still fabricates for a computed field, with one limit. Naming a field the schema doesn't have throws FabricatorError.UnknownFieldError, and passing a computed field throws FabricatorError.ComputeOutsideRefineError.

T.pick and T.omit — keep some fields

const Summary = T.pick(ProductSchema, ["id", "name"]);
const WithoutPricing = T.omit(ProductSchema, ["pricing"]);

Both return a new object schema with fewer fields. If a computed field you kept reads a field you dropped, the dropped field is still fabricated for it but doesn't appear in the result. See T.pick.

.fabricate(overrides) — a per-call override, not a new schema

const Product = new Fabricator(ProductSchema);
const widget = Product.fabricate({ name: "Widget" });

This is the lightweight version of .override(). Instead of making a new schema, it overrides one call on a Fabricator you already built, and every other field is fabricated as usual. See Objects for Omitted and how nested objects are handled.

Extending a subtype

const ElectronicsSchema = ProductSchema.extend(() => ({
  category: T.always("electronics"),
}));
 
const laptop = new Fabricator(ElectronicsSchema).fabricate({ name: "Laptop" });

.extend(), .refine(), .override(), .rebase(), T.pick, and T.omit all return ordinary schemas, so you can combine them with each other and with .fabricate(overrides). Here, a fixed field in the schema (T.always("electronics")) and a per-call override ({ name: "Laptop" }) are just two steps in the same chain.