🃏 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 at the start of every top-level 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.
stringActions	Record<string, StringActionHandler>	{}	Handlers for string pipe actions Valimock doesn't know, keyed by action type. See Extending string generation.
stringFormats	Record<string, StringFormatGenerator>	{}	Generators for the format names your stringActions handlers record in ctx.format.
customMocks	Record<string, (schema, options, mock) => unknown>	{}	Generators for Valibot schema types Valimock doesn't yet support. Keyed by schema.type; mock recurses into nested schemas with the same instance.
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.

Extending string generation

Libraries that ship their own string actions (v.pipe(v.string(), did())) can teach Valimock to generate matching values without replacing the whole string generator. A stringActions handler runs when its action type is found in a pipe and records what it learned on the StringContext, usually by naming a format; a stringFormats generator with that name then produces the value. Everything else (length bounds, stringMap, key-name heuristics) keeps working around them.

import { Valimock } from "valimock";

const mock = new Valimock({
  stringActions: {
    // `did()` is a validation action with `type: "did"`.
    did: (ctx) => {
      ctx.format = `did`;
    },
    // Handlers can read the action's requirement and stash it for the
    // generator in `ctx.custom`.
    accept: (ctx, action) => {
      ctx.format = `mime`;
      ctx.custom.accept = (action as { requirement: string[] }).requirement;
    }
  },
  stringFormats: {
    did: (ctx) => `did:plc:${ctx.faker.string.alphanumeric(24).toLowerCase()}`,
    mime: (ctx) => ctx.faker.helpers.arrayElement(ctx.custom.accept as string[])
  }
});

Both tables are merged over the built-in registries, so an entry can also override how Valimock handles one of its own actions.

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, or a stringActions entry from userland. 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. The entry receives the schema, the instance options, and a mock function that recurses into nested schemas with the same instance, so container types can be mocked without constructing a second Valimock. 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.