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 { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { ValidationPipe } from '@nestjs/common';
import { ApiProperty } from '@nestjs/swagger';

Wiring validation and Swagger docs in NestJS

validation openapi decorators
Intermediate 8 steps
typescript 
import { Component, Input } from '@angular/core';
 
interface Order {
  id: string;

How Angular ICU plurals localize an order summary

i18n pluralization standalone-component
Intermediate 8 steps
typescript 
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, catchError, concatMap, finalize } from 'rxjs';
import { DataSource, QueryRunner } from 'typeorm';
 

Wrapping requests in a transaction with NestJS

interceptors transactions rxjs
Advanced 7 steps
typescript 
type CsvColumn<T> = {
  header: string;
  value: (row: T) => string | number | boolean | null | undefined;
};

Building a type-safe CSV writer in TypeScript

generics serialization escaping
Intermediate 7 steps
typescript 
import { parsePhoneNumberFromString, CountryCode } from 'libphonenumber-js';
 
export interface NormalizedPhone {
  e164: string;

Normalizing phone numbers to E.164 in TypeScript

validation normalization error-handling
Intermediate 7 steps
php 
<?php
 
namespace App\Http\Controllers;
 

Broadcasting typing indicators in Laravel

websockets authorization presence-channels
Intermediate 9 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