typescript 44 lines · 8 steps

Validating URL query params with Zod

A Zod schema coerces, defaults, and reshapes raw query strings into a typed product query object.

Explained by highlit
Intermediate validation schema type-inference coercion query-parsing
1import { z } from "zod";
2 
3const ProductQuerySchema = z.object({
4 page: z.coerce.number().int().positive().default(1),
5 perPage: z.coerce.number().int().min(1).max(100).default(20),
6 sort: z.enum(["price_asc", "price_desc", "newest"]).default("newest"),
7 inStock: z
8 .enum(["true", "false"])
9 .transform((v) => v === "true")
10 .optional(),
11 minPrice: z.coerce.number().nonnegative().optional(),
12 maxPrice: z.coerce.number().nonnegative().optional(),
13 tags: z
14 .union([z.string(), z.array(z.string())])
15 .transform((v) => (Array.isArray(v) ? v : [v]))
16 .pipe(z.array(z.string().min(1)))
17 .optional(),
18});
19 
20export type ProductQuery = z.infer<typeof ProductQuerySchema>;
21 
22export function parseProductQuery(raw: URLSearchParams): ProductQuery {
23 const grouped: Record<string, string | string[]> = {};
24 for (const key of new Set(raw.keys())) {
25 const values = raw.getAll(key);
26 grouped[key] = values.length > 1 ? values : values[0];
27 }
28 
29 const result = ProductQuerySchema.safeParse(grouped);
30 if (!result.success) {
31 const issues = result.error.issues.map((i) => ({
32 field: i.path.join("."),
33 message: i.message,
34 }));
35 throw new BadRequestError("Invalid query parameters", issues);
36 }
37 
38 const { minPrice, maxPrice } = result.data;
39 if (minPrice != null && maxPrice != null && minPrice > maxPrice) {
40 throw new BadRequestError("minPrice cannot exceed maxPrice");
41 }
42 
43 return result.data;
44}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Coercion plus defaults let a schema accept messy string input and emit clean, typed values.
  2. 2Deriving a TypeScript type from the schema keeps runtime validation and compile-time types in sync.
  3. 3Cross-field rules that a schema can't express belong in a follow-up check after parsing.

Related explainers

typescript 
import {
  CallHandler,
  ExecutionContext,
  Injectable,

Wrapping responses in a NestJS interceptor

interceptors rxjs response-shaping
Intermediate 7 steps
go 
package main
 
import (
	"errors"

Parsing and validating CLI flags in Go

cli-parsing validation error-handling
Intermediate 8 steps
javascript 
'use server'
 
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'

How a Next.js Server Action updates a post

server-actions authorization validation
Intermediate 7 steps
typescript 
type RetryOptions = {
  retries?: number;
  timeoutMs?: number;
  baseDelayMs?: number;

Retry with timeout and backoff in TypeScript

promises retry exponential-backoff
Intermediate 10 steps
php 
<?php
 
namespace App\Support;
 

Merging query params onto a URL in PHP

url-parsing query-strings immutability
Intermediate 8 steps
typescript 
import { Pipe, PipeTransform, ChangeDetectorRef, NgZone, OnDestroy } from '@angular/core';
 
@Pipe({
  name: 'timeAgo',

A self-refreshing timeAgo pipe in Angular

impure-pipe change-detection timers
Advanced 10 steps

Share this explainer

Here's the card — post it anywhere.

Validating URL query params with Zod — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code