soc221b/zod-schema-faker

README

zod-schema-faker

Generate mock data from zod schemas. Powered by @faker-js/faker and randexp.js.

Features

Support zod v3, v4 and mini
Support almost all zod types
Support for custom zod types
Extensive tests

Installation

npm install --save-dev zod-schema-faker @faker-js/faker randexp

Usage

Setup

v3:

import { install } from 'zod-schema-faker' // alias: 'zod-schema-faker/v3'

install()

v4 or mini:

import { setFaker } from 'zod-schema-faker/v4'
import { faker } from '@faker-js/faker'

setFaker(faker)

Fake Built-in types

import { fake } from 'zod-schema-faker'

const Player = z.object({
  username: z.string(),
  xp: z.number(),
})

const data = fake(Player)
console.log(data) // { username: "billie", xp: 100 }

Input vs. Output

v4 or mini: fake() returns the schema input (z.input<T>), which is what parse() accepts. To get the output (z.output<T>), decode or parse the fake data.

sequenceDiagram
  participant unknown
  participant input as z.input#lt;T#gt;
  participant output as z.output#lt;T#gt;
  unknown->>output: z.parse()
  unknown->>input: fake()
  input->>output: z.decode()
  output->>input: z.encode()

const schema = z.string().transform(val => val.length)

const input = fake(schema) // 'billie'
const output = z.decode(schema, input) // 6

Fake Custom types

v3:

import { installCustom, fake, getFaker, ZodTypeFaker } from 'zod-schema-faker'

// define a custom zod schema
const pxSchema = z.custom<`${number}px`>(val => {
  return typeof val === 'string' ? /^\d+px$/.test(val) : false
})

// define a custom faker
class ZodPxFaker extends ZodTypeFaker<typeof pxSchema> {
  fake(): `${number}px` {
    return `${getFaker().number.int({ min: 0 })}px`
  }
}

// call installCustom() to register custom faker
installCustom(pxSchema, ZodPxFaker)

// generate fake data based on schema
const data = fake(pxSchema) // '100px'

v4 or mini:

import { custom, fake, Fake, getFaker } from 'zod-schema-faker/v4'

// define a custom zod schema
const pxSchema = z.custom<`${number}px`>(val => {
  return typeof val === 'string' ? /^\d+px$/.test(val) : false
})

// define a custom faker
const fakePxSchema: Fake<typeof pxSchema> = () => {
  return (getFaker().number.int({ min: 1, max: 100 }) + 'px') as `${number}px`
}

// call custom() to register custom faker
custom(pxSchema, fakePxSchema)

// generate fake data based on schema
const data = fake(pxSchema) // '100px'

API

v3

Core APIs

function install(): void: Install fakers for built-in types, must be called before using fake.
function fake<T extends z.ZodType>(schema: T): z.infer<T>: Generate fake data based on schema.
class ZodSchemaFakerError

Random Utility APIs

function seed(value?: number): void: Sets the seed to use.
function setFaker(faker: Faker): void: Use given faker instance instead of the default one.
function getFaker(): Faker: Get the faker instance. Defaults to fakerEN.
function randexp(pattern: string | RegExp, flags?: string): string: Create random strings that match a given regular expression.

Customization APIs - see example for details

class ZodTypeFaker: Base class for fakers.
function installCustom<T extends z.ZodTypeAny>(schema: T, faker: typeof ZodTypeFakerConcrete<T>): void: Install fakers for custom schemas, must be called before using fake.

v4

Core APIs

function fake<T extends core.$ZodType>(schema: T): core.input<T>: Generate fake input data based on schema.

Random Utility APIs

function seed(value?: number): void: Sets the seed or generates a new one. This method is intended to allow for consistent values in tests, so you might want to use hardcoded values as the seed.
function setFaker(faker: Faker): void: Set the faker instance to use.
function getFaker(): Faker: Get the faker instance.
function randexp(pattern: string | RegExp, flags?: string): string: Create random strings that match a given regular expression.

Customization APIs

function custom<T extends core.$ZodType>(schema: T, fake: Fake<T>): void: Generate fake data based on schema.
type Fake<T extends core.$ZodType> = (schema: T, context: Context, rootFake: RootFake) => core.input<T>: Custom fake function.

Unsupported

v3

.refine ❌
.superRefine ❌

v4

.codec 🚧
.intersection 🚧
.refine ❌
.stringbool custom 🚧
.stringFormat custom 🚧
.superRefine ❌

About

Distributed under the MIT license. See LICENSE for more information.

README

zod-schema-faker

Generate mock data from zod schemas. Powered by @faker-js/faker and randexp.js.

Features

Support zod v3, v4 and mini
Support almost all zod types
Support for custom zod types
Extensive tests

Installation

npm install --save-dev zod-schema-faker @faker-js/faker randexp

Usage

Setup

v3:

import { install } from 'zod-schema-faker' // alias: 'zod-schema-faker/v3'

install()

v4 or mini:

import { setFaker } from 'zod-schema-faker/v4'
import { faker } from '@faker-js/faker'

setFaker(faker)

Fake Built-in types

import { fake } from 'zod-schema-faker'

const Player = z.object({
  username: z.string(),
  xp: z.number(),
})

const data = fake(Player)
console.log(data) // { username: "billie", xp: 100 }

Input vs. Output

v4 or mini: fake() returns the schema input (z.input<T>), which is what parse() accepts. To get the output (z.output<T>), decode or parse the fake data.

sequenceDiagram
  participant unknown
  participant input as z.input#lt;T#gt;
  participant output as z.output#lt;T#gt;
  unknown->>output: z.parse()
  unknown->>input: fake()
  input->>output: z.decode()
  output->>input: z.encode()

const schema = z.string().transform(val => val.length)

const input = fake(schema) // 'billie'
const output = z.decode(schema, input) // 6

Fake Custom types

v3:

import { installCustom, fake, getFaker, ZodTypeFaker } from 'zod-schema-faker'

// define a custom zod schema
const pxSchema = z.custom<`${number}px`>(val => {
  return typeof val === 'string' ? /^\d+px$/.test(val) : false
})

// define a custom faker
class ZodPxFaker extends ZodTypeFaker<typeof pxSchema> {
  fake(): `${number}px` {
    return `${getFaker().number.int({ min: 0 })}px`
  }
}

// call installCustom() to register custom faker
installCustom(pxSchema, ZodPxFaker)

// generate fake data based on schema
const data = fake(pxSchema) // '100px'

v4 or mini:

import { custom, fake, Fake, getFaker } from 'zod-schema-faker/v4'

// define a custom zod schema
const pxSchema = z.custom<`${number}px`>(val => {
  return typeof val === 'string' ? /^\d+px$/.test(val) : false
})

// define a custom faker
const fakePxSchema: Fake<typeof pxSchema> = () => {
  return (getFaker().number.int({ min: 1, max: 100 }) + 'px') as `${number}px`
}

// call custom() to register custom faker
custom(pxSchema, fakePxSchema)

// generate fake data based on schema
const data = fake(pxSchema) // '100px'

API

v3

Core APIs

function install(): void: Install fakers for built-in types, must be called before using fake.
function fake<T extends z.ZodType>(schema: T): z.infer<T>: Generate fake data based on schema.
class ZodSchemaFakerError

Random Utility APIs

function seed(value?: number): void: Sets the seed to use.
function setFaker(faker: Faker): void: Use given faker instance instead of the default one.
function getFaker(): Faker: Get the faker instance. Defaults to fakerEN.
function randexp(pattern: string | RegExp, flags?: string): string: Create random strings that match a given regular expression.

Customization APIs - see example for details

class ZodTypeFaker: Base class for fakers.
function installCustom<T extends z.ZodTypeAny>(schema: T, faker: typeof ZodTypeFakerConcrete<T>): void: Install fakers for custom schemas, must be called before using fake.

v4

Core APIs

function fake<T extends core.$ZodType>(schema: T): core.input<T>: Generate fake input data based on schema.

Random Utility APIs

function seed(value?: number): void: Sets the seed or generates a new one. This method is intended to allow for consistent values in tests, so you might want to use hardcoded values as the seed.
function setFaker(faker: Faker): void: Set the faker instance to use.
function getFaker(): Faker: Get the faker instance.
function randexp(pattern: string | RegExp, flags?: string): string: Create random strings that match a given regular expression.

Customization APIs

function custom<T extends core.$ZodType>(schema: T, fake: Fake<T>): void: Generate fake data based on schema.
type Fake<T extends core.$ZodType> = (schema: T, context: Context, rootFake: RootFake) => core.input<T>: Custom fake function.

Unsupported

v3

.refine ❌
.superRefine ❌

v4

.codec 🚧
.intersection 🚧
.refine ❌
.stringbool custom 🚧
.stringFormat custom 🚧
.superRefine ❌

About

Distributed under the MIT license. See LICENSE for more information.