🃏 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.