# valimock

> Generate mock data for Valibot schemas using Faker

Latest version **1.6.0** (published 2026-06-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install valimock
pnpm add valimock
yarn add valimock
bun add valimock
```

## Health

**Score 55/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.6.0 |
| Published | 2026-06-03 |
| First published | 2023-10-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=22 |
| Dependencies | 1 |
| Unpacked size | 246.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 38 |
| Author | Drake Costa |
| Maintainers | saeris |
| Keywords | faker, mocking, valibot |

## Links

- npm: https://www.npmjs.com/package/valimock
- Repository: https://github.com/Saeris/valimock
- Homepage: https://github.com/Saeris/valimock#readme
- Issues: https://github.com/Saeris/valimock/issues
- npm.io page: https://npm.io/package/valimock

## Dependencies (1)

- [randexp](https://npm.io/package/randexp.md) ^0.5.3

## Alternatives

- [pagerjs](https://npm.io/package/pagerjs.md) — 60 weekly downloads
- [whistle.savefor-mock](https://npm.io/package/whistle.savefor-mock.md) — 4 weekly downloads
- [@precisa-saude/fhir-rnds-sandbox](https://npm.io/package/@precisa-saude/fhir-rnds-sandbox.md) — 0 weekly downloads
- [@codegrenade/naija-faker-mcp](https://npm.io/package/@codegrenade/naija-faker-mcp.md) — 0 weekly downloads
- [@hainaio/page-spy-plugin-ospy](https://npm.io/package/@hainaio/page-spy-plugin-ospy.md) — 0 weekly downloads

## Recent versions

- 1.6.0 (latest) — 2026-06-03
- 1.5.4 — 2026-06-03
- 1.5.3 — 2026-06-03
- 1.5.2 — 2026-06-01
- 1.5.1 — 2026-05-31
- 1.5.0 — 2026-05-27
- 1.4.0 — 2025-06-29
- 1.3.1 — 2025-06-23
- 1.3.0 — 2025-06-22
- 1.2.0 — 2025-06-21
- 1.1.1 — 2025-06-21
- 1.1.0 — 2025-05-07
- 0.1.3 — 2024-03-27
- 0.1.2 — 2024-01-03
- 0.1.1 — 2023-11-28
- … 3 more at https://npm.io/package/valimock/versions

## README

<div align="center">

# 🃏 Valimock

[![npm version][npm_badge]][npm]
[![CI status][ci_badge]][ci]

Generate mock data for [Valibot][valibot] schemas using [Faker][faker]

</div>

---

## 📦 Installation

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

```bash
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!

```ts
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__`][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 `type`s 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](#-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+][viteplus] as a unified toolchain (Oxlint + Oxfmt

- tsdown + Vitest) and [Bumpy][bumpy] for versioning and release.

```bash
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`](src/schemas/string/actionHandlers.ts)
and (if the action is a format selector) add the matching generator to
[`src/schemas/string/formatGenerators.ts`](src/schemas/string/formatGenerators.ts).
The property-based block in [`src/__tests__/mockString.spec.ts`](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`][zod-mock]

## 🥂 License

Released under the [MIT license][license] © [Drake Costa][personal-website].

[npm_badge]: https://img.shields.io/npm/v/valimock.svg?style=flat
[npm]: https://www.npmjs.com/package/valimock
[ci_badge]: https://github.com/Saeris/valimock/actions/workflows/ci.yml/badge.svg
[ci]: https://github.com/Saeris/valimock/actions/workflows/ci.yml
[valibot]: https://github.com/fabian-hiller/valibot
[faker]: https://github.com/faker-js/faker
[viteplus]: https://viteplus.dev/
[bumpy]: https://bumpy.varlock.dev/
[tests]: ./src/__tests__/
[zod-mock]: https://github.com/anatine/zod-plugins/tree/main/packages/zod-mock
[license]: ./LICENSE.md
[personal-website]: https://saeris.gg

---
_Source: https://npm.io/package/valimock · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._