Changelog
for @ghostry/fabricator
Every release of @ghostry/fabricator, newest first.
v0.0.14
Breaking changes
.as(produce)no longer takes a second argument. Moveformatandpattern(onT.string) andmultipleOf(onT.number) to.admits(...):T.string.as(produce, { format: "email" }); // before T.string.as(produce).admits({ format: "email" }); // now- A
T.recursiveschema whose collection ofselfhas a minimum above 0 now throwsUnsatisfiableRecursiveBoundErrorat.whereby(). Atdepth.maxthat collection is always empty, so an adapter requiring at least one child would reject every finite tree. Add.admits({ length: { min: 0 } })to the collection: it still draws at least one child below the limit, and adapters stop requiring one. SeeT.recursive. - An error's
.namenow starts with the package name:"@ghostry/fabricator:UnknownFieldError"instead of"UnknownFieldError".instanceofchecks are unaffected. coverage(schema)builds the schema when you call it, ascombinatorial(schema)already did. A schema that can't be built throws there instead of on the first iteration.
New
T.unique.*builders make values that never repeat.T.unique.enum,T.unique.number(and.integer,.integer.big),T.unique.bigint,T.unique.string, andT.unique.date(and.past,.future) never repeat a value for the life of one built Fabricator.T.unique.array(x)andT.unique.record(key, value)keep members distinct within each value they make.T.unique.array(x).by(key)compares members by a projection.- Running out of values throws
UniqueExhaustedError. A draw that keeps landing on values already made gives up withUniqueRedrawsError, andredrawssets how many tries it gets. A collection whose member can't filllength.maxorsize.maxthrowsUniqueCapacityErrorwhen built. combinatorialandcoveragecycle a unique field instead of running out partway.
capacity(schema)says how many times one new Fabricator canfabricate()before a unique field runs out, as abigint.combinatorial(schema).sizeandcoverage(schema).sizegive the instance count to compare it with..admits(...)sets what adapters accept without changing what is generated. It is onT.string,T.number,T.bigint,T.date,T.array, andT.record. It can only widen: an end that would reject a generated value throwsAdmitsExcludesDrawError, and±Infinitydrops a limit.T.string.whereby({ length: { min: 3, max: 20 } }).admits({ length: { max: 255 } });T.bigintandT.datebounds accept anumber: a safe integer for a bigint, epoch milliseconds for a date. Anything else throwsInvalidBoundError.
For integration authors
Enumeration,Capacity,AdmittedEnds, andInputAdmittedEndsare exported as types.- A bounded kind's
[Meta].admitsholds what.admits(...)set, every end resolved. Read it when present, elsewhereby. toKeyerfrom@ghostry/fabricator/internalgives the keyT.uniquecompares values by.
Internal
- Tests run on
@ghostry/harness.
Docs: T.unique, .admits(...)
v0.0.13
Behavior change
- Bare registry schemas are now a fresh object on every read:
T.boolean,T.date,T.date.past,T.date.future,T.null,T.number,T.number.integer,T.number.integer.sequence,T.symbol,T.undefined.T.number === T.numberis nowfalse. - This matters wherever a schema is used as an identity.
fabricate(T.number)at two unrelated call sites no longer continues one shared Fabricator, and@ghostry/externno longer treats everyT.numberin a test as the same block. To share one, hold it in a variable (const Age = T.number). registry.extend(...)keeps this behavior: extendingT.numberstill gives a fresh schema per read, and still keepsinteger.
For integration authors
isSchemaandisBuildableare exported from@ghostry/fabricator/internal, for checking values from an untyped caller.isSchemarejects a built Fabricator;isBuildableaccepts one.
v0.0.12
New
fabricate(schema)builds and draws in one call. Repeat calls with the same schema continue one Fabricator instead of building again, so a loop overfabricate(S)doesn't shift anything built after it. The cache is per scope, so each test under the harness integration starts fresh.T.pick(object, keys)andT.omit(object, keys)make a new object schema from some of an existing one's fields. A kept computed field still gets the fields it reads from, even ones you dropped: they are fabricated and then left out of the result.initialize({ clock })accepts epoch milliseconds as well as aDate, so a loggedcontext.clockcan be passed straight back. A clock that isn't a valid instant throwsInvalidClockErrorinstead of being silently adjusted.
Fixes
T.date.whereby({ min })or({ max })with only one end set no longer produces an Invalid Date. The open end runs to the edge of the representable range.T.recursiveexpansions now use the same clock as the rest of the construction. Insidewrap({ clock }), or when replaying a trace with a pinned clock, nested levels used the instance's own clock instead.
Internal
- Dependencies were updated.
v0.0.11
Breaking changes
ValueOfis renamed toFabricated, andFabricationis removed from the root export.Fabricated<X>now reads the value type of either a Schema or a built Fabricator, so it replaces both:Fabricated<typeof schema>andFabricated<typeof built>.
Fixes
- Types no longer lose
undefinedwhen your tsconfig hasexactOptionalPropertyTypesoff (the default, sincestrictdoesn't turn it on). Before this fix,T.undefinedread asnever,T.undefinable(x)read as plainx, and someT.recursivetrees failed withTS2615at your own call site.
New exports
- Types for building or reading
wherebyarguments:Distribution,Range,Length,InputLength. T.stringcomposition vocabulary: theComposition,CharacterClass,CharacterSource, andCodepointRangetypes, plus theclassesandunicodevalues, so a composition can mix a built-in class with any code point range ([[3, classes.lowercase], [1, unicode.bmp]]).
For integration authors
- A Schema's phantom
[Produces]brand now holds its value type boxed, asProduced<T>. Anything that matches the brand directly must match{ readonly [Produces]?: Produced<T> }.Producedis exported from@ghostry/fabricator/internal. normalInvis exported from@ghostry/fabricator/internalbesidenormalCdf.
v0.0.10
Performance
- Weighted draws (
T.enum,T.choice,T.boolean.weighted, presence wrappers) now cost O(1) per pick regardless of how many items there are. Equal weights use a single uniform index draw. Unequal weights use Vose's alias method, with the table built once atnew Fabricator(...). sample(list, stream)uses the same bucketed index draw as every other discrete draw.
Behavior change
- Seeded output changes for unequally-weighted
enum/choice/boolean/wrapper draws, because the alias method draws differently. A salt that reproduced a specific value on v0.0.9 may produce a different one here.
v0.0.9
New
.satisfies<T>()on every kind's Schema checks at compile time that the schema's fabricated value is assignable to an existing type. On a mismatch, the error names both sides. For a built Fabricator, or a schema you don't want to edit, use the standalonesatisfies<T>(schemaOrFabricator)and the type-onlySatisfiedBy.T.string.whereby({ length })now accepts a bare count (length: 8), the same asT.array.lengthon bothT.stringandT.arraynow accepts adistribution, which shapes the length draw the same way it does forT.number/T.date.
Fixes
- A built Fabricator passed into a composite (
T.array(built), anobjectfield, atupleslot, and so on) now keeps its precise value type. Before this fix it collapsed tounknown.
Internal
- Length/size draws for
string,array,record, andnumber.integernow all go through one shared discrete sampler. - Dependencies were updated.
v0.0.8
Highlights
New T.derive primitive. A value computed from other schemas' fabricated output, without wrapping them in a throwaway object:
T.derive({
to: T.string,
from: [T.always("hello"), T.string.as(() => "world")],
}).as((parts) => parts.join(":"));
from is a tuple of schemas, each fabricated independently with its own private stream, the same way T.tuple works. to names the result's type and shape for adapters and for .override()'s runtime check. coverage/combinatorial enumerate the enumerable inputs in from and run resolve on each combination. See the reference and Computed fields for the sibling-reading alternative, .refine.
T.enum.uniform/.weighted and T.choice.uniform/.weighted now accept a dynamically built array, not just a literal tuple — so T.enum.uniform(foos.map((f) => f.id)) type-checks. Only a statically empty [] is still a compile error; a runtime check backstops the dynamic case.
New sample/shuffle exports from @ghostry/fabricator — a uniform pick and a Fisher–Yates shuffle over a caller-held list, each taking the Stream a producer is already handed. For drawing inside .as, T.opaque, or a T.derive resolver, where T.enum (path-keyed, enumerable) doesn't apply. sample throws EmptyItemsError on an empty list.
Docs
- New Batches and relationships guide: building an array batch, referencing a pool of ids with
T.enum, owning vs. referencing a parent, and drawing withsample/shuffleinside a producer.
v0.0.7
Breaking changes
wrapambience no longer reaches descendants. Awrap's frame previously governed the receiver, the receiver's ancestors, and anything forked from the receiver while the wrap was open. It now governs only the receiver and its own ancestors — a fork taken off the receiver inside the wrap (including the scope the wrap hands to its own block) draws that instance's own configuration instead of the wrap's. Update any code relying on awrapreaching a fork taken inside its block.
Docs
- New guide: integrating fabricator with
@ghostry/extern.
v0.0.6
Fixes
- Harnessing now composes with an enclosing fabricator scope.
integration(instance)opened each test'swraponinstancedirectly, so an integration composed inside another library's own fabricator scope (e.g. an@ghostry/externtesting integration) would restate from the configured instance and silently discard that enclosing scope while still governing every draw. It now opens oninstance.context.scope()— the frame in effect, or the instance itself when there is none — so the per-test salt composes onto the enclosingwrapinstead of replacing it.
v0.0.5
Breaking changes
- The harnessing contract changed shape.
Integration.around(identity, body)is replaced by a generator-basedframe({ identity })thatyields a wrapper, and each provider now receives{ identity, established }instead of a bareIdentity— matching@ghostry/harness's current contract. Anyone implementing a custom@ghostry/fabricator-compatible integration (rather than usingintegration()as shipped) needs to update to the new shape.
Testing
- Added
Harnessing.conformance.test.ts, which checks fabricator's structural copy of the harness contract directly against@ghostry/harnessitself, so the two can't silently drift apart. - Fixed flaky
CombinatorialandEnumerationtests.
Docs
- Documentation/type conformance pass across
AGENTS.md, the faker guide,api.md, and TSDoc on several primitives.
Companion releases
@ghostry/fabricator-extension-faker-v10@0.0.2and@ghostry/fabricator-adapter-typebox-v0@0.0.2also ship alongside this release — see their own release notes.
v0.0.4
Highlights
wrap ambience now follows the ancestral line. A frame is keyed on the instance wrap was called on, and only calls on that instance's own line of descent resolve against it — the instance itself, anything forked from it, and its own ancestors up to the root. A sibling fork now resolves against its own configuration instead. Previously a wrap reached every instance in the lineage regardless of position, so two unrelated derivations could draw each other's data simply because one of them was mid-wrap.
A nested wrap lays over its receiver, not over the active frame. wrap's overlay now composes exactly the way fork's does — over the instance it was called on, whether or not another frame is already open. Nesting still accumulates when the inner wrap goes through the enclosing scope; it restates from the base when it goes through a receiver bound outside the block, which a destructured wrap always is.
New context.scope(). The configuration in effect, handed back as a usable Instance — the innermost visible frame's own scope, or the instance itself outside any. This is how to compose onto whatever is active when you don't hold the enclosing scope: context.scope().wrap({ salt: layer("b") }, ...). It carries types, limits, algorithm, and clock across too, unlike rebuilding an overlay out of salt by hand. It is a function rather than a getter on purpose, so destructuring it captures the lookup rather than one answer.
New instance.root and instance.ancestry. a.root === b.root answers "same lineage?" — preserved by fork/wrap descent, never shared by two separate initialize() calls. ancestry is the opaque chain of per-instance tokens from the root down, exposed so a caller can reason about which frames an instance's calls resolve against.
initialize({ stack }) is now purely a choice of carrier. Lineage identity is the instance's own root token, not the carrier's, so handing the same stack to two initialize() calls no longer joins them — neither one's reads ever resolve the other's frames.
Breaking changes
Stack.current()is replaced byStack.visible(ancestry). A carrier now holds the whole chain of open frames and reports every frame a given ancestry may resolve against, outermost first; the innermost is the last element. Anyone who supplied a custom carrier toinitialize({ stack })must update it. Both built-in carriers delegate the rule to a singletoVisibleso it cannot drift between them.- Nested
wrapthrough a bound receiver no longer accumulates. Insidewrap({ salt: layer("a") }, ...), a nestedwrap({ salt: layer("b") }, ...)called on the same destructuredwrapused to yield[...base, "a", "b"]and now yields[...base, "b"]. Migrate by going through the enclosingscope.wrap(...), or throughcontext.scope().wrap(...)when the scope isn't in hand. - Sibling forks are now invisible to each other's frames. Any code that relied on a
wrapentered on one fork reaching a sibling fork will draw different data. Calls on a sibling step over a frame they cannot see and keep walking outward, so awrapontenantnested inside one onbaseleavesadmin's calls resolving againstbase's frame. /internalrenames: theRootPinstype is nowConstructionPins, andRandomSource.toRootis nowtoConstructionTrace.
New API
Instance.root— the head of the lineage; a root's ownrootis itself. Typed with an unparameterized registry, since afork({ types })makes the root's registry unrecoverable from the descendant;root.Tis therefore untyped whileroot.Fabricatoris unaffected.Instance.ancestry, and theAncestrytype is now exported alongsideStack, whosevisibletakes one. TheTokenelement type is deliberately not exported: a chain is opaque, its elements compare only by identity, and the ordinary question isa.root === b.root.Context.scope()andContext.depth.depthcounts only the frames this instance's own calls can resolve against —0outside any, and a frame entered on a sibling fork never counts toward it.
Behavior
- The asynchronous carrier stores the full open chain rather than a single frame, building a fresh array per
enter. That is what keeps concurrentwraps isolated: each async context keeps the chain it entered with, and an innerentercannot mutate an outer one's view. context's four value properties are getters, so they are a live view only whilecontextstays an object — destructuring or spreading one calls the getter once and freezes it.scopeis exempt by being a function.
Docs
- The reproducibility guide now recommends
forkas the default and treatswrapas the tool for when the scope cannot reach the code that needs it. Thewrapsection was retitled accordingly, so its anchor changed from#making-a-fork-ambient-wrapto#when-you-cannot-thread-the-scope-wrap— update any external links. - New "Ambience follows the ancestral line" section walking through the sibling case.
- The harness guide gains "Why this uses
wrap", explaining why the integration is the case that exemption was written for, and documents that the instance handed tointegration(...)need not be the oneinitialize()returned. - The API reference gains entries for
Instance.root,Instance.ancestry,context.scope(), andcontext.depth.
Compatibility
Unchanged from 0.0.3: @ghostry/fabricator-adapter-typebox-v0@0.0.1 and @ghostry/fabricator-extension-faker-v10@0.0.1 still have not been republished, and the published adapter imports drive, which 0.0.3 removed from the root export. Their peer range (>=0.0.1 <0.1.0) admits 0.0.4 regardless. Both are updated in-repo; build from source, or pin fabricator to 0.0.2 until they ship.
v0.0.3
Highlights
Reproducibility now rests on one number: the clock. initialize() takes no required configuration. Its clock — by default the wall-clock instant of the call — is the run's entropy, and it sits in every leaf's trace, so every run differs and passing the logged context.clock back reproduces that run exactly. Salt (formerly seed) is explicitly optional and does one job: it differentiates runs, it does not generate them.
File attribution is gone entirely. A construction is no longer keyed by the file it was written in. Each RandomSource owns one construction counter, and each new Fabricator(...) takes the next ordinal from it regardless of which module made the call. Moving or renaming a file no longer changes its data; adding, removing, or reordering constructions on the same instance now shifts the ones after it. fork and wrap each create a fresh source with a fresh counter, which is how work gets partitioned more finely. Fields within one construction remain keyed by structural position, so schema edits still don't shift siblings.
New @ghostry/fabricator/harnessing export. integration(instance) decorates an existing instance as a @ghostry/harness integration, so each test's data follows from the test's own identity — its describe names, its own name, its .each row — with nothing threaded through the body and no salt written by hand. Each test body runs inside its own wrap, so .only, name filters, sharding, and .concurrent cannot shift a neighbor's data. Fabricator declares no dependency and no peer on @ghostry/harness; the contract is satisfied structurally.
New @ghostry/fabricator/adapting export. The adapter contract — what you implement to write a schema adapter — now lives on its own subpath instead of the root export.
Breaking changes
The seed vocabulary is now salt throughout, and the old names are removed rather than aliased:
| Before | After |
|---|---|
initialize({ seed }) |
initialize({ salt }) |
new Fabricator(schema, { seed }) |
new Fabricator(schema, { salt }) |
fork({ seed }) / wrap({ seed }) |
fork({ salt }) / wrap({ salt }) |
instance.seed, context.seed |
instance.salt, context.salt |
Seed type |
Salt type |
clock: "seeded" |
clock: "derived" |
FABRICATOR_SEED, SEED, RANDOM_SEED |
FABRICATOR_SALT only |
drive (root export) |
walk (from /adapting) |
stream.seed keeps its name — the derived seed is still a seed, and salt is one slot fed into it.
The conventional SEED and RANDOM_SEED names are deliberately not read. Exporting one of those is a request for a stable run, which a salt alone can't deliver — clock still varies per process — so honoring them would look like it worked while the data kept moving. FABRICATOR_SEED is not aliased either, so a stale value in a shell or CI config fails loudly by having no effect.
Beyond the renames:
initialize({ attribution })is removed, along with theAttributionandRootKindtypes andInvalidAttributionRootError. There is no replacement option — attribution is simply no longer part of the model.Traceis reshaped to{ salt, clock, path, kind, ordinal }. Therootandfileslots are gone, andordinalis nownumber | null. Traces captured under 0.0.2 will not replay.- A per-construction
saltno longer forks. It used to mint an isolated, unattributed source from exactly that value. It is now a pin on the trace's salt slot and nothing more: the build still takes the next ordinal from the instance's counter and still shifts its neighbors. When you want a build that is genuinely insulated, usefork— one line away. - The adapter contract moved off the root export.
walk(néedrive),Adapter,Adaptations,AdaptationsOf,Recurse, andAdaptationare now imported from@ghostry/fabricator/adapting.Adapting— the parameter type of a kind's.adapt(adapter, produce)producer — stays on., since writing that producer is an ordinary caller's business, not an adapter author's. /internalloses the call-site helpers:resolveCallerFile,directoryOf,normalizeLocation, andrelativize, plus theResolvedAttributionandRootKindtypes.resolveCallerFilewas added in 0.0.2 for wrapping libraries; a wrapping library now partitions withfork/wrapinstead.- Data generated under 0.0.2 will not reproduce under 0.0.3. Every stream seed changed shape, so snapshots and recorded fixtures need regenerating.
Behavior
combinatorialandcoveragenow draw from their own salt withordinal: nullpinned, so they never advance the instance's construction counter and every pass over the returnedIterablerebuilds from the same identity.- New
HarnessingProviderError— raised when thefabricatorprovider is called outside its integration'saround, rather than quietly handing back the base instance and drawing plausible data from the wrong configuration.
Compatibility
@ghostry/fabricator-adapter-typebox-v0@0.0.1 and @ghostry/fabricator-extension-faker-v10@0.0.1 were not republished with this release. Their peer range (>=0.0.1 <0.1.0) still admits 0.0.3, but the published adapter imports drive from the root export, which 0.0.3 removed. Both are updated in-repo; pin fabricator to 0.0.2 until they ship, or build them from source.
Docs
- New Harness guide covering setup, per-test salts, and why a pinned
Datebeatsclock: "derived"for a suite. - New Comparison page.
- Reproducibility substantially rewritten around the clock-first model, with new sections on construction order and env-var salting.
Metadata
sideEffects: falseandengines.node >= 20declared on all three packages.homepagenow points at the docs site; keywords expanded.- README gains a logo and registry badges.
v0.0.2
Highlights
wrap now accepts async blocks. On any runtime with node:async_hooks — Node, Bun, Deno — the ambient frame survives await, and concurrent wrap calls stay isolated from one another. Where async_hooks is unavailable (in practice, a browser bundle), the synchronous LIFO carrier is used instead, and it now rejects an async block with an explanatory error rather than silently resolving a post-await build against the base instance.
New stack option on initialize(). Left unset it picks the right carrier by condition, which is what you want; supplying one lets a test drive a carrier it would not otherwise get. The Stack type is now exported alongside Config, Context, and Overlay.
Internal
Both additions are on the /internal subpath and exist for libraries that wrap fabricator; neither changes the public API.
resolveCallerFile— lets a wrapping library attribute a construction to its own caller rather than to itself, via askiplist of roots that composes onto fabricator's own root.- The
AsFabricatortype — names the Fabricator typeconstruct()produces for a given schema without making a generic call.
Fixes and quality
- Resolved the slow-type diagnostics JSR reported across the primitive registries.
- Worked around a flaky
tsgodeclaration-emit bug. - Switched formatting to
oxfmt. - Docs moved to their own domain: https://docs.ghostry.dev/fabricator/
No breaking changes — every change above is additive.
v0.0.1
Initial release.
Fabricate typed data from composable schemas — full type inference, seeded reproducibility, and fixtures that don't churn when the schema changes.
npm install @ghostry/fabricator
