zod 4.6.5: z

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify zod.z in pkg:npm/zod@4.6.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/zod@4.6.5
Demonstrate these symbols/APIs:
  - zod.z

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:b4b2cce15f0638e78bb2df47e19d139098086e259576eca2f05f80f15bcec9c0","contract":["z.object and primitive schemas (z.string, z.number, z.boolean) validate structured data and parse conforming inputs","safeParse returns success true with parsed data on valid payloads and success false with structured error issues on failure","z.coerce converts string and number representations to target primitives including numbers, booleans, and dates","z.discriminatedUnion and z.union validate tagged variants and multi-type inputs against matching schema members","schema modifiers including optional, nullable, and default handle absent keys, null values, and default fallbacks","schema refine and transform apply custom predicate validations and data transformations"],"goal":"verify zod.z in pkg:npm/zod@4.6.5","kind":"HOW","packages":["pkg:npm/zod@4.6.5"],"schemaVersion":1,"symbols":["zod.z"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/zod@4.6.5"],"schemaVersion":1,"subject":"pkg:npm/zod@4.6.5","symbols":["zod.z"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-zod-z",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-zod-z",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "zod": "4.6.5"
      }
    },
    "node_modules/zod": {
      "version": "4.6.5",
      "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.5.tgz",
      "integrity": "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q==",
      "license": "MIT",
      "funding": {
        "url": "https://github.com/sponsors/colinhacks"
      }
    }
  }
}

{
  "name": "sample-zod-z",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of zod.z in zod@4.6.5",
  "main": "src/index.mjs",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "zod": "4.6.5"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify zod.z in pkg:npm/zod@4.6.5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/zod@4.6.5"
  ],
  "symbols": [
    "zod.z"
  ]
}

import { z } from "zod";

/**
 * Creates a schema for user profile validation.
 *
 * @returns {import('zod').ZodObject} The UserProfile schema.
 */
export function createUserProfileSchema() {
  return z.object({
    id: z.string().uuid().or(z.number()),
    name: z.string().min(1),
    email: z.string().email(),
    role: z.enum(["admin", "user", "guest"]).default("user"),
    isActive: z.boolean().default(true),
    tags: z.array(z.string()).optional()
  });
}

/**
 * Creates a schema with type coercion for numeric, boolean, and date fields.
 *
 * @returns {import('zod').ZodObject} The coerced config schema.
 */
export function createCoercedConfigSchema() {
  return z.object({
    port: z.coerce.number().int().min(1).max(65535),
    debug: z.coerce.boolean(),
    timeoutMs: z.coerce.number().default(5000),
    startedAt: z.coerce.date()
  });
}

/**
 * Creates a discriminated union schema representing polymorphic notifications.
 *
 * @returns {import('zod').ZodDiscriminatedUnion} The discriminated union schema.
 */
export function createNotificationSchema() {
  return z.discriminatedUnion("type", [
    z.object({
      type: z.literal("email"),
      recipient: z.string().email(),
      subject: z.string()
    }),
    z.object({
      type: z.literal("sms"),
      phoneNumber: z.string().min(5),
      message: z.string()
    }),
    z.object({
      type: z.literal("push"),
      deviceId: z.string(),
      payload: z.record(z.string(), z.unknown())
    })
  ]);
}

/**
 * Validates data against a schema using parse (throws on validation failure).
 *
 * @param {import('zod').ZodTypeAny} schema - Zod schema.
 * @param {unknown} data - Data to parse.
 * @returns {unknown} Parsed and typed data.
 */
export function validate(schema, data) {
  return schema.parse(data);
}

/**
 * Validates data against a schema using safeParse (returns result object).
 *
 * @param {import('zod').ZodTypeAny} schema - Zod schema.
 * @param {unknown} data - Data to validate.
 * @returns {import('zod').SafeParseReturnType<any, any>} Safe parse result.
 */
export function safeValidate(schema, data) {
  return schema.safeParse(data);
}

/**
 * Creates a transformed and refined schema that trims and normalizes string slugs.
 *
 * @returns {import('zod').ZodType} The normalized slug schema.
 */
export function createNormalizedSlugSchema() {
  return z
    .string()
    .trim()
    .toLowerCase()
    .refine((val) => /^[a-z0-9-]+$/.test(val), {
      message: "Slug must only contain alphanumeric characters and hyphens"
    })
    .transform((val) => val.replace(/-+/g, "-"));
}

export { z };
export default z;

import assert from "node:assert/strict";
import { z, createUserProfileSchema, createCoercedConfigSchema, createNotificationSchema, createNormalizedSlugSchema, validate, safeValidate } from "../src/index.mjs";

// 1. z.object and primitive schemas (z.string, z.number, z.boolean) validate structured data and parse conforming inputs
{
  const schema = createUserProfileSchema();
  const validUser = {
    id: 1001,
    name: "Alice",
    email: "alice@example.com",
    role: "admin",
    isActive: true,
    tags: ["developer", "reviewer"]
  };

  const parsed = validate(schema, validUser);
  assert.deepStrictEqual(parsed, validUser, "Parsed user profile must match valid input");

  // Missing required field name throws ZodError
  assert.throws(
    () => validate(schema, { id: 1002, email: "bob@example.com" }),
    (err) => err !== null && typeof err === "object" && Array.isArray(err.issues),
    "Missing required fields must throw validation error"
  );

  // Invalid email format throws ZodError
  assert.throws(
    () => validate(schema, { id: 1003, name: "Charlie", email: "not-an-email" }),
    (err) => err !== null && typeof err === "object" && err.issues.some((i) => i.path.includes("email")),
    "Invalid email format must throw validation error"
  );
}

// 2. safeParse returns success true with parsed data on valid payloads and success false with structured error issues on failure
{
  const schema = createUserProfileSchema();
  const successResult = safeValidate(schema, {
    id: "123e4567-e89b-12d3-a456-426614174000",
    name: "Valid UUID User",
    email: "uuid-user@example.com"
  });

  assert.strictEqual(successResult.success, true, "safeValidate on conforming payload must return success: true");
  assert.strictEqual(successResult.data.name, "Valid UUID User");
  assert.strictEqual(successResult.data.role, "user", "Default role 'user' must be applied");
  assert.strictEqual(successResult.data.isActive, true, "Default isActive true must be applied");

  const failureResult = safeValidate(schema, {
    id: "invalid-id-format",
    name: "",
    email: "bad-email",
    role: "superadmin"
  });

  assert.strictEqual(failureResult.success, false, "safeValidate on non-conforming payload must return success: false");
  assert.ok(Array.isArray(failureResult.error.issues), "safeValidate failure must contain issues array");
  assert.ok(failureResult.error.issues.length >= 3, "Failure must report issues for invalid fields");
}

// 3. z.coerce converts string and number representations to target primitives including numbers, booleans, and dates
{
  const configSchema = createCoercedConfigSchema();
  const rawInput = {
    port: "8080",
    debug: "true",
    timeoutMs: "3000",
    startedAt: "2026-08-23T00:00:00.000Z"
  };

  const parsedConfig = validate(configSchema, rawInput);
  assert.strictEqual(parsedConfig.port, 8080, "port must be coerced from string to number");
  assert.strictEqual(parsedConfig.debug, true, "debug must be coerced from string to boolean true");
  assert.strictEqual(parsedConfig.timeoutMs, 3000, "timeoutMs must be coerced from string to number");
  assert.ok(parsedConfig.startedAt instanceof Date, "startedAt must be coerced to Date instance");
  assert.strictEqual(parsedConfig.startedAt.toISOString(), "2026-08-23T00:00:00.000Z");

  // Invalid number string throws error
  assert.throws(
    () => validate(configSchema, { port: "not-a-number", debug: true, startedAt: new Date() }),
    (err) => err !== null && typeof err === "object"
  );
}

// 4. z.discriminatedUnion and z.union validate tagged variants and multi-type inputs against matching schema members
{
  const notifSchema = createNotificationSchema();

  const emailNotif = {
    type: "email",
    recipient: "alerts@example.com",
    subject: "System Health Alert"
  };
  const parsedEmail = validate(notifSchema, emailNotif);
  assert.deepStrictEqual(parsedEmail, emailNotif, "Discriminated union must correctly validate email variant");

  const smsNotif = {
    type: "sms",
    phoneNumber: "+15551234567",
    message: "Security code: 123456"
  };
  const parsedSms = validate(notifSchema, smsNotif);
  assert.deepStrictEqual(parsedSms, smsNotif, "Discriminated union must correctly validate sms variant");

  const pushNotif = {
    type: "push",
    deviceId: "device-xyz-987",
    payload: { action: "sync", retryCount: 2 }
  };
  const parsedPush = validate(notifSchema, pushNotif);
  assert.deepStrictEqual(parsedPush, pushNotif, "Discriminated union must correctly validate push variant");

  // Unknown discriminator type fails validation
  const unknownTypeResult = safeValidate(notifSchema, { type: "carrier-pigeon", recipient: "bird" });
  assert.strictEqual(unknownTypeResult.success, false, "Unknown discriminator value must fail validation");
}

// 5. schema modifiers including optional, nullable, and default handle absent keys, null values, and default fallbacks
{
  const modifierSchema = z.object({
    requiredField: z.string(),
    optionalField: z.string().optional(),
    nullableField: z.number().nullable(),
    defaultedField: z.string().default("fallback-value")
  });

  const parsedWithoutOptional = validate(modifierSchema, {
    requiredField: "present",
    nullableField: null
  });

  assert.strictEqual(parsedWithoutOptional.requiredField, "present");
  assert.strictEqual(parsedWithoutOptional.optionalField, undefined);
  assert.strictEqual(parsedWithoutOptional.nullableField, null);
  assert.strictEqual(parsedWithoutOptional.defaultedField, "fallback-value");

  const parsedWithValues = validate(modifierSchema, {
    requiredField: "present",
    optionalField: "custom-opt",
    nullableField: 42,
    defaultedField: "custom-default"
  });

  assert.strictEqual(parsedWithValues.optionalField, "custom-opt");
  assert.strictEqual(parsedWithValues.nullableField, 42);
  assert.strictEqual(parsedWithValues.defaultedField, "custom-default");
}

// 6. schema refine and transform apply custom predicate validations and data transformations
{
  const slugSchema = createNormalizedSlugSchema();

  const transformed = validate(slugSchema, "   Hello---World--2026   ");
  assert.strictEqual(transformed, "hello-world-2026", "Slug must be trimmed, lowercased, and duplicate hyphens collapsed");

  const invalidSlugResult = safeValidate(slugSchema, "invalid_slug_with_underscores!");
  assert.strictEqual(invalidSlugResult.success, false, "Slug with invalid characters must fail refinement");
  assert.ok(
    invalidSlugResult.error.issues.some((i) => i.message.includes("alphanumeric")),
    "Refine error message must be included in issues"
  );
}

console.log("All zod.z contract assertions passed successfully.");