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.stringandT.bigintcan't be used bare. There's no natural default range for either, soT.stringon 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 of0turns that outcome off, and it throws if every weight is0. Negative weights,NaN, andInfinityare 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 });.integerfor whole numbersT.bigint: can't be used bare, for the same reason asT.stringT.boolean: 50/50, or.weighted({ true, false })T.date: dates within a range, plus.pastand.futureT.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 a | Members are | Bare form | |
|---|---|---|---|
T.always | — | any fixed value | yes |
T.enum | value | any value | no — .uniform/.weighted |
T.choice | schema, then fabricates it | any schema | no — .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... | Use | Key present? | Value when "absent" | Object-only? |
|---|---|---|---|---|
A value that is always exactly null | T.null | — | null | no |
A value that is always exactly undefined | T.undefined | — | undefined | no |
A field that's always present, but the value might be undefined | T.undefinable(inner) | always | undefined | no |
A field that's always present, but the value might be null | T.nullable(inner) | always | null | no |
A field that's always present, value might be null or undefined | T.nullish(inner) | always | null or undefined | no |
| A field that's sometimes missing from the object entirely | T.omittable(inner) | sometimes | (key doesn't exist) | yes |
A field that might be missing, present-as-undefined, or present with a value | T.optional(inner) | sometimes | (key doesn't exist) or undefined | yes |
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.
| Positions | Shape | Count | |
|---|---|---|---|
T.array | index | same for every element | random |
T.tuple | index | separate for each slot | fixed |
T.record | key (drawn) | same for every value | random, 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.enumnever repeat for the life of a Fabricator.T.unique.arrayandT.unique.recordhold distinct members within each value.
Structures
T.object: what most schemas are built inside. See Objects for details.T.pickandT.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: aMap, aSet, aURL, 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.
