Skip to content
Logo

Objects

Most schemas are built inside T.object({ ... }). This page covers what goes beyond a flat list of fields: nested objects, sequences, computed fields, and per-call overrides.

Nesting

A field can be any schema, including another T.object:

T.object({
  name: T.string.whereby({ length: { min: 1, max: 25 } }),
  pricing: T.object({
    currency: T.enum.uniform(["USD", "YEN", "GBP"]),
    amount: T.number.whereby({ min: 0, max: 500 }),
  }),
});

Every field, nested or not, draws from its own stream, set up when the Fabricator is built. See Reproducibility for what that guarantees.

Sequences

T.object({ id: T.number.integer.sequence });

This is a counter that starts at 1 and goes up by one on each .fabricate() call, so ten calls give ids 1 through 10. Each new Fabricator(schema) starts its own count. For a batch of N, use T.array(schema).whereby({ length: N }). See Batches.

Computed fields

A computed field gets its value from the rest of the object, after the rest has been fabricated. You add one with .refine(({ compute }) => ({ ... })), not in T.object directly:

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

compute(source) takes the field's schema, or a bare builder like T.string if you only need to name the type. .as(resolve) finishes it. resolve receives { fabricated } and returns the computed value.

fabricated is the object as it was before this .refine(): every field of the schema you called it on. It doesn't include the other fields computed in the same .refine(). To read one of those, add it in one .refine() and read it in the next.

Computed fields only exist inside .refine(). Putting one in T.object(...) or returning one from .extend(...) is a type error, and it throws FabricatorError.ComputeOutsideRefineError.

Declaring dependencies with .from

Use .from([...]) before .as to name the fields a computed field reads:

const UserSchema = T.object({
  first: T.string.whereby({ length: { min: 1, max: 12 } }),
  last: T.string.whereby({ length: { min: 1, max: 12 } }),
  email: T.string.whereby({ length: { min: 5, max: 30 } }),
}).refine(({ compute }) => ({
  name: compute(T.string)
    .from(["first", "last"])
    .as(({ fabricated }) => `${fabricated.first} ${fabricated.last}`),
}));

fabricated then holds only first and last, and reading any other field is a type error. This matters for T.pick and T.omit. Without .from, a computed field can read every field of the object, so they have to keep fabricating all of them. With .from, they only keep the fields it names.

.from throws if it names a field the object doesn't have.

Replacing a field with a computed one

A .refine() can return a field the object already has. The computed field replaces it in the result, and it reads the original:

const ShoutingUserSchema = UserSchema.refine(({ compute }) => ({
  first: compute(T.string)
    .from(["first"])
    .as(({ fabricated }) => fabricated.first.toUpperCase()),
}));

Every computed field added before this .refine() keeps reading the original first, so name keeps its original spelling, and every one added after reads the uppercased one. To change the original afterwards, use .rebase().

Computed fields are why .refine() is separate from .extend(): they need a second pass, after the ordinary fields are fabricated. See Composition for how extend, refine, and override fit together and what each costs.

To compute a value from schemas that aren't fields of an object, use T.derive.

Per-call overrides

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

Every field you don't name is fabricated as usual by the same Fabricator. An override doesn't create a new schema and doesn't affect any other field's stream. In a nested object like pricing, only the fields you name are replaced, and the rest are still fabricated. To force an omittable or optional field to be left out, pass Omitted:

import { Omitted } from "@ghostry/fabricator";
 
Product.fabricate({ nickname: Omitted });