Skip to content
Logo

Primitives overview

You reach every primitive through T, which initialize() returns. There is no other way to name one. See Public API for what the package exports.

This page groups the primitives by what you're trying to do. Each one has its own page, and the "All" list in the sidebar has them alphabetically.

Some are left out of the groups on purpose. compute is only available inside .refine(({ compute }) => ...) (see Objects). self is only the placeholder T.recursive(body) passes to body; there is no T.self (see T.recursive).

Things that trip people up early

  • T.string and T.bigint can't be used bare. There's no natural default range for either, so T.string on its own fails when fabricated. Call .whereby({ length }) (or .as(...)) first.
  • Weights don't need to add up to anything. This applies to T.enum, T.choice, and .weighted() on the absence primitives. Each weight is divided by the total of all weights. A weight of 0 turns that outcome off, and it throws if every weight is 0. Negative weights, NaN, and Infinity are invalid.

Scalars

A single value of one JavaScript type. Most are drawn at random; T.symbol creates a new symbol each time.

  • T.string: can't be used bare; needs .whereby({ length })
  • T.number: unbounded when bare, or .whereby({ min, max }); .integer for whole numbers
  • T.bigint: can't be used bare, for the same reason as T.string
  • T.boolean: 50/50, or .weighted({ true, false })
  • T.date: dates within a range, plus .past and .future
  • T.symbol: Symbol(), or .keyed(description)

Literals and choices

Ways to get a value from a fixed set. They differ in whether the value is fixed or drawn, and whether the members are values or schemas.

Picks aMembers areBare form
T.always—any fixed valueyes
T.enumvalueany valueno — .uniform/.weighted
T.choiceschema, then fabricates itany schemano — .uniform/.weighted

Absence

Ways for a value to be not quite there. They are not interchangeable, and most confusion comes from answering the wrong one of these questions:

  • Is the key on the object at all? This is about the enclosing T.object, and means nothing outside one.
  • Once the key is there, is the value null, undefined, or something else? This is about the value itself, so it works anywhere a schema does: a top-level Fabricator, an array element, or an object field.
I want...UseKey present?Value when "absent"Object-only?
A value that is always exactly nullT.null—nullno
A value that is always exactly undefinedT.undefined—undefinedno
A field that's always present, but the value might be undefinedT.undefinable(inner)alwaysundefinedno
A field that's always present, but the value might be nullT.nullable(inner)alwaysnullno
A field that's always present, value might be null or undefinedT.nullish(inner)alwaysnull or undefinedno
A field that's sometimes missing from the object entirelyT.omittable(inner)sometimes(key doesn't exist)yes
A field that might be missing, present-as-undefined, or present with a valueT.optional(inner)sometimes(key doesn't exist) or undefinedyes

T.omittable and T.optional only make sense as fields inside T.object(...). T.nullable, T.nullish, and T.undefinable are ordinary values you can use anywhere.

When a field comes out omitted, null, or undefined, its inner schema isn't fabricated at all. Each field has its own stream, so skipping that draw only affects the same field's next call, never another field. See Reproducibility.

Collections

Ways to fabricate more than one value. They differ in whether every item has the same shape, and whether items are found by index or by key.

PositionsShapeCount
T.arrayindexsame for every elementrandom
T.tupleindexseparate for each slotfixed
T.recordkey (drawn)same for every valuerandom, may collapse

For members that never repeat within one value, see T.unique.array and T.unique.record.

Uniqueness

  • T.unique: builders for values that don't repeat. T.unique.number, .bigint, .string, .date, and .enum never repeat for the life of a Fabricator. T.unique.array and T.unique.record hold distinct members within each value.

Structures

  • T.object: what most schemas are built inside. See Objects for details.
  • T.pick and T.omit: a copy of an object schema with only some of its fields.
  • T.recursive: a schema that refers to itself, for trees, linked structures, or a generic JSON value.
  • T.derive: a value computed from other schemas' fabricated values, without a throwaway object.

Escape hatch

  • T.opaque: a Map, a Set, a URL, a class instance, or anything else fabricator has no primitive for.

Most other primitives also have .as(produce), which replaces how an existing kind is generated with your own function. Use .as() to change a kind that exists, and T.opaque when there's no kind to start from. See T.opaque for the difference, and Custom types for using .as() with a data library.