Validated Type-Safe HTTP Requests with Zod

Common errors

• ReferenceError: z is not defined

  cause The Zod library, `zod`, is not installed or imported.
  fix Ensure `npm install zod` is run and `import { z } from 'zod';` is present in your file.

• TypeError: (0 , zod_request__WEBPACK_IMPORTED_MODULE_0__.fetch) is not a function

  cause Attempting to use `zod-request` with CommonJS `require()` syntax in an ESM-only environment, or a misconfigured bundler.
  fix Ensure your project uses ESM imports (`import { fetch } from 'zod-request';`) and your `package.json` specifies `"type": "module"` if running directly in Node.js, or configure your bundler (Webpack/Rollup/Vite) correctly.

• ZodError: Invalid input

  cause The incoming HTTP response body or outgoing request body does not match the defined Zod schema.
  fix Inspect the actual payload using network tools or `console.error(error)` in the catch block to debug schema discrepancies. Adjust your Zod schema to accurately reflect the data structure.

• TypeError: fetch is not a function

  cause The native `fetch` API is not available in the current environment (e.g., older Node.js versions) or the `zod-request` `fetch` was not correctly imported.
  fix Ensure your Node.js version is >=18.0.0. Verify `import { fetch } from 'zod-request';` is at the top of your file.

Warnings

• gotcha zod-request requires `zod` as a peer dependency for schema definition. Forgetting to install it will lead to runtime errors.
  Fix: npm install zod
• gotcha As a relatively new library (v0.2.2), `zod-request`'s API surface might evolve rapidly. Monitor release notes for potential breaking changes in minor versions.
  Fix: Always pin to exact versions (e.g., '0.2.2') or use tilde (e.g., '~0.2.2') for minor updates, and review changelogs before upgrading.
• gotcha Response body validation only occurs when methods like `response.json()` or `response.formData()` are called. Using `response.unsafeJson()` bypasses Zod validation entirely.
  Fix: Always use `response.json()`, `response.text()`, etc., when validation is desired. Only use `response.unsafeJson()` if you explicitly want to skip validation for that response.
• gotcha Incorrectly defining `schema.body` for request payloads or `schema.response` for response payloads will lead to validation failures or unexpected type inference.
  Fix: Ensure `schema.body` matches the expected request payload type and `schema.response` accurately describes the expected response body structure, using appropriate Zod methods like `z.object`, `z.array`, `z.string`, etc.

Install

• npm install zod-request npm
• yarn add zod-request yarn
• pnpm add zod-request pnpm

Imports

• fetch
  wrong:

  const { fetch } = require('zod-request')

  correct:

  import { fetch } from 'zod-request'

  The primary enhanced fetch function, providing Zod validation. zod-request is primarily an ESM library, though bundlers can transpile for CJS.
• Response

  import type { Response } from 'zod-request'

  Type import for the enhanced Response object returned by `zod-request`'s fetch, useful for explicit type annotations.
• RequestInit

  import type { RequestInit } from 'zod-request'

  Type import for the extended RequestInit options, which includes the `schema` property for defining Zod validation schemas.

Quickstart

Demonstrates how to fetch and validate an array of to-do items from a public API using Zod schemas for response validation.

import { fetch } from 'zod-request';
import { z } from 'zod';

const todoSchema = z.object({
  userId: z.number(),
  id: z.number(),
  title: z.string(),
  completed: z.boolean()
});

async function fetchTodos() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/todos', {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json'
      },
      schema: {
        response: z.array(todoSchema)
      }
    });

    const data = await response.json();
    console.log('Fetched data length:', data.length);
    console.log('First item:', data[0]);
    // Example of accessing data safely, TypeScript will infer the type based on todoSchema
    if (data.length > 0) {
      console.log('First todo title:', data[0].title);
    }
  } catch (error) {
    console.error('Error fetching todos:', error);
  }
}

fetchTodos();