API Reference

Any Zod schema to generate a value from.

Per-call GenerateOptions (`seed`, `overrides`, …).

World-wide settings (WorldOptions); the `seed` fixes determinism.

Any 32-bit integer. The same seed always produces the same sequence.

withSchema<TSchema, TSource, TRelations>(schema: TSchema, opts?: SchemaOpts<TSchema, TSource, TRelations>): this

Register a schema with optional matchers, relations, or a source binding. Primary (no from:): world.withSchema(PersonSchema, { matchers: { email: (ctx) => ... } }) Relational (with relations:): world.withSchema(FileSchema, { relations: { owner: PersonSchema }, matchers: { ownerId: (ctx) => ctx.related("owner").personId }, }) Derived (with from:): world.withSchema(SummarySchema, { from: PersonSchema, matchers: { id: (ctx) => ctx.source.personId }, }) The same output schema can be registered multiple times, each with a different `from:` binding, to represent multiple source types.

withGenerators(map: Record<string, KeyGenerator>): this

Register additional key-based generators. Calls are additive. Keys are matched case-insensitively against field names.

withKeyMap<T>(schema: T, map: SchemaKeyMap<T>): this

Bind field generators to a specific schema (legacy API, kept for compat).

generate<TSchema>(schema: TSchema, options?: GenerateOptions<output<TSchema>>): output<TSchema>

Generate a value from a Zod schema. - Object schema → single generated object - z.array(schema) → array respecting min/max/length constraints - Registered derived schemas → one record per source

get<TSchema>(schema: TSchema, predicate?: Partial<input<TSchema>>): output<TSchema>

Find an existing stored record matching `predicate`, or generate one. Search the registry for the first stored record (insertion order) for which every key in `predicate` matches the record's value — shallow keys by value, nested-object values by deep equality. If one is found it is returned by reference. Otherwise a new record is generated via the `generate` overrides path with `predicate` supplied as `overrides` (so the predicate wins over matchers), stored in the registry for `schema`, and returned. An absent or empty predicate matches everything: returns the first stored record if any exist, else generates-and-stores one. Deterministic for a given seed and idempotent for a repeated predicate.

populate<TSchema>(schema: TSchema, count: number, factory?: { … }): this

Pre-generate `count` instances of the schema and store them in the registry. Returns `this` for fluent chaining. An optional per-record `factory` may be supplied. When given, it is invoked once per record with the 0-based index and must return `GenerateOptions` (`overrides`, `transform`, etc.) for that record. The returned options flow through the normal generate pipeline.

populateFrom<TDerived, TSource>(derivedSchema: TDerived, sourceSchema: TSource, predicate?: { … }, factory?: { … }): this

Iterate the source bucket and call `world.generate(derivedSchema, { source })` once per source record (filtered by `predicate` if supplied). The optional `factory` receives the source record itself (`z.infer<TSource>`, contrast `populate`'s index-based factory) and returns `GenerateOptions<TDerived>` that flow through the delegated `generate` call. Idempotence comes from the per-`(derivedSchema, identity(source))` upsert: re-running `populateFrom` with the same arguments leaves the derived bucket unchanged. The source bucket is snapshotted at call start — mid-loop inserts to it are visible only to the next `populateFrom` call. Always writes (like `populate`): a factory return containing `store: false` is silently stripped. Returns `this` for fluent chaining.

explain<TSchema>(schema: TSchema): ExplainResult<TSchema>

Read-only debug helper: for each top-level field of `schema`, report which step of the resolution pipeline (matcher → withKeyMap → withGenerators → exact-key → key-pattern → schema-based) would resolve the field, and a short reason. Returns a structured `ExplainResult` with a `toString()` formatter for human-readable output. PRNG-neutral and registry-neutral — calling `explain` does not consume the world PRNG, does not write to the registry, and does not advance any generation counter.

trace(): WorldTrace

Return the provenance structure for everything generated so far in this world's lifetime — a plain, JSON-serializable WorldTrace. Emits one TraceNode per stored registry record (in registration order), each carrying the record's stable id, its value, and its registration polarity (`node<regId>` for primary, `derived<regId>` for derived, with `derivedFrom` set on derived nodes). `seed` echoes the world's root seed. Provenance capture is opt-in via `createWorld({ trace: true })`. At the current stub every node's `fields` and the trace's `edges` are empty (field and relation-edge capture land in later cards), so an enabled trace returns the same shape as a default one.

generate<S>(schema: S, options?: GenerateOptions<output<S>>): output<S>

Generates a value using the full world engine (honoring matchers and registry).

Seed for this call's PRNG; same seed + schema yields the same value.

Probability (0–1) that an optional field is present.

Default `[min, max]` length for unconstrained arrays.

Maximum recursion depth for self-referential / nested schemas.

Locale supplying names, words, and other locale-specific data.

Partial values deep-merged onto the generated result, overriding any field. An array override sets the array element count: the result has exactly `override.length` elements, and `overrides[i]` deep-merges onto the i-th generated base element (un-overridden siblings preserved; a sparse hole / `undefined` slot leaves that element fully generated). The override length wins even over an explicit `.length(N)`; schema bounds (`.length()` / `.min()` / `.max()`) and `defaultArrayLength` govern only the no-override count.

Post-processor applied to the generated value before it is returned/stored.

When `false`, suppress the registry write for this `world.generate` call — useful for ephemeral generation (search-bucket envelopes, paginated responses, one-off fixtures). Propagates through nested generation so inner registered schemas are also not stored. Ignored by `world.get` (its create path must always store) and by `world.populate` (its purpose is to populate the registry). Default `true`.

When `false`, bypass the derived-schema upsert keyed by `(schema, source)`: generate a fresh record even if a derived record already exists for this source. Has no effect on schemas without `from:`. Default `true` (upsert).

Custom field-name generators, matched case-insensitively by field name.

Opt in to provenance capture for World.trace. When omitted (or `false`), `world.trace()` still returns the registry projection — one TraceNode per stored record — but no per-field or relation-edge provenance is captured. (At the current stub the flag is plumbing only: field and edge capture land in later cards, so an enabled trace returns the same shape as a default one.)

Identity field on the source record used to key the per-pair derived-schema upsert. When omitted, identity falls back to reference equality on `source`. Declared at registration only — not overridable per `generate` call.

Locale-level Zipf exponent applied at open-corpus `pickZipf` call sites when no per-corpus override is present. Resolved at the data-generator call site as `overrides[corpusName] ?? frequencyExponent ?? 1.0`, so locales authored without this field continue to behave unchanged.

Per-corpus Zipf exponent overrides (keyed by data-generator corpus name, e.g. `lastNames`, `firstNamesMale`). Wins over `frequencyExponent` for the matching corpus; closed/enumerable lists ignore this map entirely.

pickZipf<T>(items: readonly T[], s: number): T

Zipf-distributed pick from a freq-sorted array via a closed-form inverse-CDF draw — one `random()`, no rejection loop. `s = 0` reproduces `pick`; `s = 1` is classic Zipf. See B51 report §3 for the formula.

logUniform(min: number, max: number): number

Closed-form log-uniform draw on `[min, max]` — one `random()`, no rejection. Formula: `min * Math.pow(max / min, u)` for `u = random()`. Caller MUST ensure `min > 0`; cross-zero handling lives in the per-key generators. See B54 research report §5 / B57 R8.

geometric(p: number): number

Truncated-geometric draw with parameter `p ∈ (0, 1)` — one `random()`, no rejection. Returns a non-negative integer offset from 0: `Math.floor(Math.log(1 - u) / Math.log(1 - p))`. Callers add `min` if desired. See B54 research report §3 / B57 R8.

Dotted field path within the record (e.g. `"user.email"`).

The value produced for this field. JSON-serializable.

Which pipeline rung resolved the value.

The PRNG fork key used to seed this field.

Whether an `options.overrides` entry won over the pipeline value.

Sibling field / relation keys this field's value depended on.

Friendly `` `${typeName}#${index}` `` id (1-based index), e.g. `"person#1"`.

For derived records, the friendly id of the source node (e.g. `"person#1"`).