Skip to content
Logo

Changelog

for @ghostry/fabricator

Every release of @ghostry/fabricator, newest first.

v0.0.14

· Release on GitHub

Breaking changes

  • .as(produce) no longer takes a second argument. Move format and pattern (on T.string) and multipleOf (on T.number) to .admits(...):
    T.string.as(produce, { format: "email" }); // before
    T.string.as(produce).admits({ format: "email" }); // now
    
  • A T.recursive schema whose collection of self has a minimum above 0 now throws UnsatisfiableRecursiveBoundError at .whereby(). At depth.max that 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. See T.recursive.
  • An error's .name now starts with the package name: "@ghostry/fabricator:UnknownFieldError" instead of "UnknownFieldError". instanceof checks are unaffected.
  • coverage(schema) builds the schema when you call it, as combinatorial(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, and T.unique.date (and .past, .future) never repeat a value for the life of one built Fabricator.
    • T.unique.array(x) and T.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 with UniqueRedrawsError, and redraws sets how many tries it gets. A collection whose member can't fill length.max or size.max throws UniqueCapacityError when built.
    • combinatorial and coverage cycle a unique field instead of running out partway.
  • capacity(schema) says how many times one new Fabricator can fabricate() before a unique field runs out, as a bigint. combinatorial(schema).size and coverage(schema).size give the instance count to compare it with.
  • .admits(...) sets what adapters accept without changing what is generated. It is on T.string, T.number, T.bigint, T.date, T.array, and T.record. It can only widen: an end that would reject a generated value throws AdmitsExcludesDrawError, and ±Infinity drops a limit.
    T.string.whereby({ length: { min: 3, max: 20 } }).admits({ length: { max: 255 } });
    
  • T.bigint and T.date bounds accept a number: a safe integer for a bigint, epoch milliseconds for a date. Anything else throws InvalidBoundError.

For integration authors

  • Enumeration, Capacity, AdmittedEnds, and InputAdmittedEnds are exported as types.
  • A bounded kind's [Meta].admits holds what .admits(...) set, every end resolved. Read it when present, else whereby.
  • toKeyer from @ghostry/fabricator/internal gives the key T.unique compares values by.

Internal

  • Tests run on @ghostry/harness.

Docs: T.unique, .admits(...)

v0.0.13

· Release on GitHub

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.number is now false.
  • 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/extern no longer treats every T.number in a test as the same block. To share one, hold it in a variable (const Age = T.number).
  • registry.extend(...) keeps this behavior: extending T.number still gives a fresh schema per read, and still keeps integer.

For integration authors

  • isSchema and isBuildable are exported from @ghostry/fabricator/internal, for checking values from an untyped caller. isSchema rejects a built Fabricator; isBuildable accepts one.

v0.0.12

· Release on GitHub

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 over fabricate(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) and T.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 a Date, so a logged context.clock can be passed straight back. A clock that isn't a valid instant throws InvalidClockError instead 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.recursive expansions now use the same clock as the rest of the construction. Inside wrap({ 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

· Release on GitHub

Breaking changes

  • ValueOf is renamed to Fabricated, and Fabrication is 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> and Fabricated<typeof built>.

Fixes

  • Types no longer lose undefined when your tsconfig has exactOptionalPropertyTypes off (the default, since strict doesn't turn it on). Before this fix, T.undefined read as never, T.undefinable(x) read as plain x, and some T.recursive trees failed with TS2615 at your own call site.

New exports

  • Types for building or reading whereby arguments: Distribution, Range, Length, InputLength.
  • T.string composition vocabulary: the Composition, CharacterClass, CharacterSource, and CodepointRange types, plus the classes and unicode values, 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, as Produced<T>. Anything that matches the brand directly must match { readonly [Produces]?: Produced<T> }. Produced is exported from @ghostry/fabricator/internal.
  • normalInv is exported from @ghostry/fabricator/internal beside normalCdf.

v0.0.10

· Release on GitHub

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 at new 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

· Release on GitHub

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 standalone satisfies<T>(schemaOrFabricator) and the type-only SatisfiedBy.
  • T.string.whereby({ length }) now accepts a bare count (length: 8), the same as T.array.
  • length on both T.string and T.array now accepts a distribution, which shapes the length draw the same way it does for T.number/T.date.

Fixes

  • A built Fabricator passed into a composite (T.array(built), an object field, a tuple slot, and so on) now keeps its precise value type. Before this fix it collapsed to unknown.

Internal

  • Length/size draws for string, array, record, and number.integer now all go through one shared discrete sampler.
  • Dependencies were updated.

v0.0.8

· Release on GitHub

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 with sample/shuffle inside a producer.

v0.0.7

· Release on GitHub

Breaking changes

  • wrap ambience no longer reaches descendants. A wrap'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 a wrap reaching a fork taken inside its block.

Docs

v0.0.6

· Release on GitHub

Fixes

  • Harnessing now composes with an enclosing fabricator scope. integration(instance) opened each test's wrap on instance directly, so an integration composed inside another library's own fabricator scope (e.g. an @ghostry/extern testing integration) would restate from the configured instance and silently discard that enclosing scope while still governing every draw. It now opens on instance.context.scope() — the frame in effect, or the instance itself when there is none — so the per-test salt composes onto the enclosing wrap instead of replacing it.

v0.0.5

· Release on GitHub

Breaking changes

  • The harnessing contract changed shape. Integration.around(identity, body) is replaced by a generator-based frame({ identity }) that yields a wrapper, and each provider now receives { identity, established } instead of a bare Identity — matching @ghostry/harness's current contract. Anyone implementing a custom @ghostry/fabricator-compatible integration (rather than using integration() 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/harness itself, so the two can't silently drift apart.
  • Fixed flaky Combinatorial and Enumeration tests.

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.2 and @ghostry/fabricator-adapter-typebox-v0@0.0.2 also ship alongside this release — see their own release notes.

v0.0.4

· Release on GitHub

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 by Stack.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 to initialize({ stack }) must update it. Both built-in carriers delegate the rule to a single toVisible so it cannot drift between them.
  • Nested wrap through a bound receiver no longer accumulates. Inside wrap({ salt: layer("a") }, ...), a nested wrap({ salt: layer("b") }, ...) called on the same destructured wrap used to yield [...base, "a", "b"] and now yields [...base, "b"]. Migrate by going through the enclosing scope.wrap(...), or through context.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 wrap entered 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 a wrap on tenant nested inside one on base leaves admin's calls resolving against base's frame.
  • /internal renames: the RootPins type is now ConstructionPins, and RandomSource.toRoot is now toConstructionTrace.

New API

  • Instance.root — the head of the lineage; a root's own root is itself. Typed with an unparameterized registry, since a fork({ types }) makes the root's registry unrecoverable from the descendant; root.T is therefore untyped while root.Fabricator is unaffected.
  • Instance.ancestry, and the Ancestry type is now exported alongside Stack, whose visible takes one. The Token element type is deliberately not exported: a chain is opaque, its elements compare only by identity, and the ordinary question is a.root === b.root.
  • Context.scope() and Context.depth. depth counts only the frames this instance's own calls can resolve against — 0 outside 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 concurrent wraps isolated: each async context keeps the chain it entered with, and an inner enter cannot mutate an outer one's view.
  • context's four value properties are getters, so they are a live view only while context stays an object — destructuring or spreading one calls the getter once and freezes it. scope is exempt by being a function.

Docs

  • The reproducibility guide now recommends fork as the default and treats wrap as the tool for when the scope cannot reach the code that needs it. The wrap section was retitled accordingly, so its anchor changed from #making-a-fork-ambient-wrap to #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 to integration(...) need not be the one initialize() returned.
  • The API reference gains entries for Instance.root, Instance.ancestry, context.scope(), and context.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

· Release on GitHub

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 the Attribution and RootKind types and InvalidAttributionRootError. There is no replacement option — attribution is simply no longer part of the model.
  • Trace is reshaped to { salt, clock, path, kind, ordinal }. The root and file slots are gone, and ordinal is now number | null. Traces captured under 0.0.2 will not replay.
  • A per-construction salt no 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, use fork — one line away.
  • The adapter contract moved off the root export. walk (née drive), Adapter, Adaptations, AdaptationsOf, Recurse, and Adaptation are 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.
  • /internal loses the call-site helpers: resolveCallerFile, directoryOf, normalizeLocation, and relativize, plus the ResolvedAttribution and RootKind types. resolveCallerFile was added in 0.0.2 for wrapping libraries; a wrapping library now partitions with fork/wrap instead.
  • 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

  • combinatorial and coverage now draw from their own salt with ordinal: null pinned, so they never advance the instance's construction counter and every pass over the returned Iterable rebuilds from the same identity.
  • New HarnessingProviderError — raised when the fabricator provider is called outside its integration's around, 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 Date beats clock: "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: false and engines.node >= 20 declared on all three packages.
  • homepage now points at the docs site; keywords expanded.
  • README gains a logo and registry badges.

v0.0.2

· Release on GitHub

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 a skip list of roots that composes onto fabricator's own root.
  • The AsFabricator type — names the Fabricator type construct() 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 tsgo declaration-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

· Release on GitHub

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

Docs: https://docs.ghostry.dev/fabricator/