Zocker: Zod Schema Test Data Generator

Common errors

• TypeError: (0 , zocker__WEBPACK_IMPORTED_MODULE_1__.zocker) is not a function

  cause Attempting to use `zocker` via CommonJS `require()` or as a default import in an ESM context.
  fix Ensure you are using named imports for `zocker`: `import { zocker } from 'zocker';`. If in a CommonJS environment, consider configuring your project for ESM or use a transpiler.

• TS2307: Cannot find module 'zocker' or its corresponding type declarations.

  cause The 'zocker' package is not installed, or TypeScript cannot locate its type definitions. This can happen with incorrect import paths or mismatched TypeScript configurations.
  fix Verify that `zocker` is installed (`npm install zocker` or `yarn add zocker`). Check your `tsconfig.json` for correct `moduleResolution` (e.g., `bundler` or `node16`) and `module` settings (e.g., `esnext`). Ensure correct import path `from 'zocker'`.

• Error: Zod schema not found (zocker requires a Zod schema to generate data)

  cause This error likely indicates that the `zod` peer dependency is missing or its version is incompatible with `zocker`.
  fix Install `zod` as a dependency: `npm install zod` or `yarn add zod`. Ensure the installed `zod` version matches `zocker`'s peer dependency requirement (e.g., `^3.25.0 || ^4.0.0`).

Warnings

• breaking Version 1.0.0 introduced a complete overhaul of the configuration API, replacing the old Generator-based system with a new fluent API. This change breaks all existing setups, including those without custom generators.
  Fix: Migrate your zocker configuration and data generation calls to the new fluent API as described in the README. The old `configure` and generator functions are no longer available.
• gotcha When using `supply` or `override` methods, incorrect type definitions were present in versions prior to 1.2.1, leading to potential TypeScript errors or unexpected behavior when providing custom generation logic.
  Fix: Upgrade to zocker version 1.2.1 or newer to resolve type definition issues with `supply` and `override`.
• gotcha Support for Zod's `readonly` schemas was introduced in v1.4.0. Using `zocker` with `readonly` schemas in earlier versions might lead to unexpected behavior or incomplete data generation.
  Fix: Ensure you are on zocker version 1.4.0 or higher if your Zod schemas utilize `readonly` modifiers.

Install

• npm install zocker npm
• yarn add zocker yarn
• pnpm add zocker pnpm

Imports

• z

  import { z } from 'zod';

  While a peer dependency, Zod's `z` object is fundamental for defining schemas that Zocker consumes.
• zocker
  wrong:

  import zocker from 'zocker';
  const zocker = require('zocker');

  correct:

  import { zocker } from 'zocker';

  The primary `zocker` function is a named export. ESM-only usage is assumed for v3.0.0 and above. CommonJS `require` is not supported in modern versions.
• ZockerOptions
  wrong:

  import { ZockerOptions } from 'zocker';

  correct:

  import type { ZockerOptions } from 'zocker';

  Type imports for configuration options are common for type-aware tooling.

Quickstart

This quickstart demonstrates how to define a Zod schema and then use `zocker` to generate both single and multiple mock data objects that conform to that schema.

import { z } from 'zod';
import { zocker } from 'zocker';

// Define a Zod schema for a User
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(3).max(50),
  email: z.string().email(),
  age: z.number().int().min(18).max(99),
  isActive: z.boolean(),
  roles: z.array(z.enum(['admin', 'editor', 'viewer'])).min(1),
  createdAt: z.date().default(() => new Date()),
});

// Create a zocker instance for the User schema
const generateUser = zocker(UserSchema);

// Generate a single user object
const user = generateUser();
console.log('Generated User:', user);

// Generate multiple user objects (e.g., 5 users)
const users = zocker(UserSchema, { seed: 123 }).generateMany(5);
console.log('Generated Users (many):', users);