Parse JSON Responses With Zod In TypeScript Using Generics

Jul 31, 2025 by Luna Greco 59 views

Parse JSON Response with Zod Inside a TypeScript Function Using Generics

Hey guys! 👋 Ever been in a situation where you're fetching data from various APIs and need a solid way to validate those JSON responses in your TypeScript project? I recently tackled this exact issue and wanted to share my approach, leveraging Zod for schema validation and TypeScript generics for flexibility. Let's dive into how we can parse JSON responses with Zod inside a TypeScript function, making our code cleaner and more robust.

The Challenge: Fetching and Validating JSON

When working with APIs, you often deal with different endpoints, each returning JSON data in its own unique format. To ensure type safety and prevent runtime errors, it's crucial to validate these responses against a predefined schema. Zod, a TypeScript-first schema declaration and validation library, is an excellent tool for this. However, applying Zod validation across multiple fetch calls can become repetitive if you're not careful. You might find yourself passing the same Zod schema to every function call, which isn't very DRY (Don't Repeat Yourself).

The Initial Approach (and Its Drawbacks)

Initially, you might think of creating a generic fetch function that accepts a Zod schema as an argument. This way, you can validate the response against the schema within the function. While this works, it can lead to a lot of boilerplate code. Every time you call the fetch function, you need to explicitly pass the Zod schema, which can become cumbersome, especially when dealing with numerous API calls. Imagine having to write out the schema every single time – yikes! 😩

The Goal: A More Elegant Solution

Our goal is to create a TypeScript function that fetches JSON data and validates it using Zod, but without needing to pass the Zod schema every single time we call the function. We want a solution that's both type-safe and concise, reducing redundancy and making our code more readable. This is where TypeScript generics and some clever function design come into play.

Diving into the Solution: TypeScript Generics and Zod

To achieve our goal, we'll harness the power of TypeScript generics and Zod's schema inference capabilities. Here's the basic idea:

Define a Generic Fetch Function: We'll create a function that uses a generic type parameter to represent the expected shape of the JSON response.
Leverage Zod's infer: We'll use Zod's infer utility to automatically extract the TypeScript type from our Zod schema. This allows us to define the schema once and have the type inferred, avoiding duplication.
Validate and Parse: Inside the function, we'll fetch the data, parse it as JSON, and then use Zod to validate it against the provided schema.
Return a Type-Safe Result: The function will return a promise that resolves to the validated data, ensuring that we're working with the correct type throughout our application.

Step-by-Step Implementation

Let's walk through the implementation step by step. First, we'll define a generic fetch function:

import { z } from 'zod';

async function fetchAndValidate<Schema extends z.ZodType<any, any, any>>(  url: string,
  schema: Schema
): Promise<z.infer<Schema>> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data = await response.json();
  return schema.parse(data) as z.infer<Schema>;
}

In this function:

fetchAndValidate is an async function, which allows us to use await for cleaner asynchronous code.
<Schema extends z.ZodType<any, any, any>> defines a generic type Schema that must extend z.ZodType. This ensures that the schema argument is a valid Zod schema.
url: string is the URL we want to fetch data from.
schema: Schema is the Zod schema we want to validate the response against.
Promise<z.infer<Schema>> is the return type, which is a promise that resolves to the inferred type of the Zod schema. z.infer<Schema> extracts the TypeScript type from the Zod schema.
We fetch the data using the fetch API and check if the response is ok. If not, we throw an error.
We parse the response body as JSON using response.json().
We use schema.parse(data) to validate the data against the Zod schema. If the data doesn't match the schema, Zod will throw an error.
Finally, we return the parsed data, casting it to the inferred type z.infer<Schema>.

Creating Zod Schemas

Next, let's create a couple of Zod schemas for different API responses. This is where we define the structure of the data we expect from our API endpoints.

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

const PostSchema = z.object({
  userId: z.number(),
  id: z.number(),
  title: z.string(),
  body: z.string(),
});

type Post = z.infer<typeof PostSchema>;

Here, we've defined two schemas:

UserSchema validates objects with id (number), name (string), and email (string, must be a valid email format) properties.
PostSchema validates objects representing blog posts, with userId, id (both numbers), title, and body (both strings) properties.
We use z.infer<typeof SchemaName> to automatically infer the TypeScript type from each Zod schema. This is super handy because we don't have to manually define the types ourselves – Zod does it for us! 🎉

Using the Function

Now, let's see how we can use our fetchAndValidate function with these schemas:

async function main() {
  try {
    const user = await fetchAndValidate(
      'https://jsonplaceholder.typicode.com/users/1',
      UserSchema
    );
    console.log('User:', user);

    const post = await fetchAndValidate(
      'https://jsonplaceholder.typicode.com/posts/1',
      PostSchema
    );
    console.log('Post:', post);
  } catch (error) {
    console.error('Error:', error);
  }
}

main();

In this example:

We call fetchAndValidate with the URL of a user endpoint and the UserSchema. The function fetches the data, validates it against the schema, and returns a User object.
We do the same for a post endpoint, using the PostSchema to validate the response.
We log the results to the console. If any error occurs during the process (e.g., the response doesn't match the schema), we catch the error and log it.

The Magic of Generics and `z.infer`

The beauty of this approach lies in the combination of TypeScript generics and Zod's infer utility. By using generics, we've created a flexible function that can handle different response types. The z.infer utility allows us to automatically extract the TypeScript type from our Zod schemas, ensuring type safety without manual type definitions. This keeps our code clean, maintainable, and less prone to errors.

Benefits of This Approach

Type Safety: Zod ensures that the data matches the schema at runtime, and TypeScript ensures type safety at compile time.
DRY Code: We define the schema once and reuse it for both validation and type inference.
Flexibility: The generic function can handle different response types.
Readability: The code is clear and easy to understand.

Leveling Up: A More Streamlined Approach (without passing Zod schema every time)

Now, let’s address the original question: Is there a better way to avoid passing the Zod schema every time we call the function? The answer is a resounding yes! We can achieve this by creating a higher-order function or a wrapper function that encapsulates the schema. This way, we can create specialized fetch functions for each endpoint, each with its own schema baked in.

Creating a Schema-Specific Fetch Function

Here's how we can create a wrapper function that takes a Zod schema and returns a specialized fetch function:

function createFetchAndValidate<Schema extends z.ZodType<any, any, any>>(  schema: Schema
) {
  return async (url: string): Promise<z.infer<Schema>> => {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    return schema.parse(data) as z.infer<Schema>;
  };
}

In this code:

createFetchAndValidate is a higher-order function that takes a Zod schema as an argument.
It returns a new function that takes a URL and returns a promise that resolves to the validated data.
Inside the returned function, we fetch the data, parse it as JSON, and validate it against the schema, just like before.

Using the Schema-Specific Fetch Function

Now, let's see how we can use this to create specialized fetch functions:

const fetchUser = createFetchAndValidate(UserSchema);
const fetchPost = createFetchAndValidate(PostSchema);

async function main() {
  try {
    const user = await fetchUser('https://jsonplaceholder.typicode.com/users/1');
    console.log('User:', user);

    const post = await fetchPost('https://jsonplaceholder.typicode.com/posts/1');
    console.log('Post:', post);
  } catch (error) {
    console.error('Error:', error);
  }
}

main();

Here, we've created two specialized fetch functions:

fetchUser is a function that fetches and validates user data using UserSchema.
fetchPost is a function that fetches and validates post data using PostSchema.
When we call these functions, we no longer need to pass the schema explicitly – it's already baked into the function! 🎉

Benefits of the Streamlined Approach

Reduced Boilerplate: We don't need to pass the schema every time we call the function.
Improved Readability: The code is even cleaner and easier to understand.
Better Organization: We can create specialized fetch functions for each endpoint, making our code more modular.

Additional Tips and Considerations

Error Handling: Zod's parse method throws an error if the data doesn't match the schema. You can use safeParse for a more controlled error handling approach.
Complex Schemas: Zod can handle very complex schemas, including nested objects, arrays, and unions. Explore Zod's documentation for more advanced features.
API Design: Consider designing your APIs to return consistent data formats, which can simplify schema definition and validation.
Caching: For performance optimization, consider caching API responses to avoid unnecessary network requests.

Conclusion: Mastering JSON Parsing with Zod and Generics

In this article, we've explored how to parse JSON responses with Zod inside a TypeScript function using generics. We started with a basic approach and then leveled up to a more streamlined solution that avoids passing the Zod schema every time. By leveraging TypeScript generics and Zod's schema inference capabilities, we can create type-safe, concise, and maintainable code for fetching and validating data from APIs. This approach not only reduces boilerplate but also improves the overall structure and readability of your codebase.

So, the next time you're dealing with JSON responses in your TypeScript project, remember these techniques. They'll help you write cleaner, more robust code and save you from countless headaches down the road. Happy coding, guys! 🚀