🃏 Valimock

Generate mock data for Valibot schemas using Faker

---

📦 Installation

npm install --save-dev valimock @faker-js/faker

yarn add -D valimock @faker-js/faker

Note

Tested against valibot >= 1.4.0 and @faker-js/faker >= 10.0.0. Older versions of either may still work — the peer-dependency ranges remain permissive — but the test matrix runs against current majors.

🔧 Usage

Import and optionally configure a new instance of the Valimock class, then pass along your valibot schema to mock(), that's it!

import { parse, array, union, string, pipe, url, number, maxValue } from "valibot";
import { Valimock } from "valimock";

describe(`example test`, () => {
  it(`should generate valid mock data`, () => {
    const schema = array(union([pipe(string(), url()), pipe(number(), maxValue(20))]));
    const result = new Valimock().mock(schema);
    expect(parse(schema, result)).toStrictEqual(result);
  });
});

Note

For async schemas, you will need to use parseAsync(). Be aware that async schemas generate a Promise and may need to be await'ed depending on usage.

Please see the __tests__ folder for more usage examples of different schema types.

Configuration

new Valimock(options) accepts a partial options object:

option	type	default	purpose
faker	Faker	default Faker instance	Faker instance used for all generation; supply your own to control locale or seeding centrally
seed	number | number[]	undefined	Re-seeds Faker on every mock() call for deterministic output
stringMap	Record<string, () => string>	undefined	Per-key string overrides (when generating strings inside an object). Wins over the built-in format/key-name routing.
customMocks	Record<string, (schema) => unknown>	{}	Generators for Valibot schema types Valimock doesn't yet support. Keyed by schema.type.
recordKeysLength	number	1	How many entries to generate for a record() schema
mapEntriesLength	number	1	How many entries to generate for a map() schema
throwOnUnknownType	boolean	false	When true, throw a MockError for unrecognized schema types instead of warning
onWarn	(message: string) => void	console.warn	Diagnostic sink. Receives unhandled-action notices, retry-budget exhaustion, and generation errors. Set to () => {} to silence.
mockeryMapper	MockeryMapper	built-in defaults	Deprecated. Prefer stringMap or contributing an action handler. Still consulted for backwards compatibility; emits a one-time warning when invoked.

API Coverage

Valimock's string mocking is built around a small pipeline (src/schemas/string/) with a per-action registry. Adding support for a new Valibot action is a one-line addition to the registry. See Contributing below.

Any schema type Valimock doesn't yet support can be handled by supplying a customMocks entry keyed by the schema's type field. When Valimock has no built-in mocker and no matching customMocks entry (notably for v.custom(...)), it emits an onWarn notice and returns undefined rather than silently producing an invalid value. Set throwOnUnknownType: true to turn that into a thrown MockError.

Schemas

Any	Array	Bigint	Blob	Boolean	Custom	Date
✔	✔	✔	✔	✔	➖	✔
Enum	ExactOptional	File	Function	Instance	Intersect	Lazy
✔	✔	✔	✔	✔	✔	✔
Literal	LooseObject	LooseTuple	Map	NaN	Never	Null
✔	✔	✔	✔	✔	✔	✔
Nullable	Nullish	NonNullable	NonNullish	NonOptional	Number	Object
✔	✔	✔	✔	✔	✔	✔
ObjectWithRest	Optional	Picklist	Promise	Record	Set	StrictObject
✔	✔	✔	✔	✔	✔	✔
StrictTuple	String	Symbol	Tuple	TupleWithRest	Undefined	Undefinedable
✔	✔	✔	✔	✔	✔	✔
Union	Unknown	Variant	Void
✔	✔	✔	✔

Legend: ✔ implemented · ⚠ partial · ❌ not implemented · ➖ user-supplied via customMocks

custom schemas run an arbitrary user predicate that Valimock has no general way to satisfy. Provide a matching customMocks entry keyed by the schema's type ("custom", or a more specific tag if you wrap multiple custom() calls in a brand) to produce a value that will pass the predicate.

For environment-dependent schemas (blob, file, function, promise, instance), Valimock returns a structural placeholder when the relevant global isn't available (e.g. Blob / File outside Node ≥18 / browsers / jsdom). The onWarn sink surfaces a notice in those cases.

Validations

Array

empty	includes	length	maxLength	minLength	nonEmpty
✔	❌	✔	✔	✔	✔

Set

size	minSize	maxSize	notSize
✔	✔	✔	✔

BigInt

gtValue	ltValue	maxValue	minValue	value	values
✔	✔	✔	✔	✔	✔

Date

maxValue	minValue	value
✔	✔	✔

Number

finite	gtValue	integer	ltValue	maxValue	minValue	multipleOf	notValue	notValues	safeInteger	value	values
✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔

String

base64	bic	bytes	creditCard	cuid2	decimal	digits	domain	email	emoji	empty	endsWith	excludes
✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔

graphemes	hash	hexColor	hexadecimal	imei	includes	ip	ipv4	ipv6	isbn	isoDate	isoDateTime	isoDateTimeSecond
✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔

isoTime	isoTimeSecond	isoTimestamp	isoWeek	isrc	jwsCompact	length	mac	mac48	mac64	maxBytes	maxGraphemes	maxLength
✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔

maxWords	minBytes	minGraphemes	minLength	minWords	nanoid	nonEmpty	notBytes	notGraphemes	notLength	notValue	notValues	notWords
✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔

octal	regex	rfcEmail	slug	startsWith	ulid	url	uuid	value	values	words
✔	✔	✔	✔	✔	✔	✔	✔	✔	✔	✔

Not yet implemented (string): notEntries. The bytes / graphemes / words families currently treat each unit as .length (correct for ASCII output, approximate for multi-byte content); a future enhancement may distinguish them via Intl.Segmenter.

When Valimock encounters an action it doesn't know how to handle inside a string pipe, it emits an onWarn notice and ignores the action — the generated value satisfies the rest of the constraints but may not match the unhandled one. Override options.onWarn to route those notices into your test reporter or set throwOnUnknownType: true for strict mode.

🤝 Contributing

The project uses Vite+ as a unified toolchain (Oxlint + Oxfmt

• tsdown + Vitest) and Bumpy for versioning and release.

vp install           # install dependencies
vp check --fix       # format + lint + typecheck (with autofixes)
vp test              # run Vitest
yarn bumpy add       # create a bump file for your PR

Adding support for a new Valibot string action is typically a two-line change: register a handler in src/schemas/string/actionHandlers.ts and (if the action is a format selector) add the matching generator to src/schemas/string/formatGenerators.ts. The property-based block in src/__tests__/mockString.spec.ts will exercise the new combination automatically once the action appears in its formats table.

📣 Acknowledgements

Valimock's implementation is based on @anatine/zod-mock

🥂 License

Released under the MIT license © Drake Costa.