Validation and Domain Types

Welcome back 👋 In the previous lesson, you established the project’s shared API contract (ApiSuccess, ApiError, ApiResponse) and the response helpers (success, error, parseJson) that make every route return consistent JSON envelopes. That foundation matters here because validation failures should also come back in the exact same structured error shape—just with a VALIDATION_ERROR code. In this lesson, you’ll make the backend’s data shapes more explicit by introducing domain types and a small DTO for product listing inputs. Then you’ll build a tiny validation toolkit for query params and wire it into GET /api/products, so invalid inputs are rejected early with clean, consistent error responses.

Domain Types as the Backend’s Source of Truth

A backend needs a canonical “truth” for what its entities look like internally—especially once the database is involved. In this project, those canonical shapes live in src/lib/types/domain.ts. These types are designed to match the columns we’ll read from PostgreSQL later, so we don’t end up inventing new shapes at every layer. This file defines a Currency type (kept intentionally narrow) and a Product interface that includes pricing, inventory, and status fields you’ll see in real queries and API responses. TypeScriptexport type Currency = 'USD'; Currency is a narrow type instead of a plain string, which makes the system more explicit and prevents “random” currency codes from sneaking in. For this course, we only support 'USD', which keeps the domain model simple while still demonstrating the pattern of constrained values. Even if we expand currency support later, starting narrow is helpful because it forces consistency across the codebase. Now here’s the canonical Product shape. TypeScriptexport interface Product { id: string; sku: string; name: string; description: string | null; price_cents: number; currency: Currency; inventory_count: number; status: 'active' | 'archived'; created_at: string; updated_at: string; } This interface is intentionally “database-shaped.” Fields like price_cents, inventory_count, and timestamps are exactly the kinds of columns we’ll read from PostgreSQL rows. price_cents is an integer rather than a floating dollar amount. This avoids rounding problems that can happen when using floating point math for money. description is string | null, which mirrors how SQL databases commonly represent “no value” for optional text fields. status is a union of 'active' | 'archived'. This is important because status values show up in real filtering and business logic, and the union prevents invalid states like 'deleted' or 'inactive' from compiling. Keeping these fields in the domain model makes it much easier to map DB rows to strongly-typed objects later, and it keeps your API responses aligned with the real data source.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Validation Utilities for Query Params

Query parameters always start as strings (or missing entirely). If you let those raw values flow into your route logic, you’ll quickly end up with messy checks scattered everywhere. Instead, this project centralizes query parsing and validation in src/lib/http/validation.ts.

In this unit, the focus is on three responsibilities:

Type guards (isString, isInt) that check types and constraints.
Parsers (parseOptionalStringParam, parseOptionalIntParam) that read from URLSearchParams, trim/convert, and return a consistent result type.

First, the shared result shape used by the parsers:

TypeScript

export type ValidationResult<T> = { ok: true; value: T } | { ok: false; message: string };

export type ValidationResult<T> = { ok: true; value: T } | { ok: false; message: string };

This is a simple “result object” pattern: either { ok: true, value } or { ok: false, message }.
It avoids throwing errors for validation failures, which keeps route handlers clean and predictable.
The route can decide how to convert a validation failure into an API error envelope (and what HTTP status to use).

Now the isString type guard:

TypeScript

export function isString(
  v: unknown,
  { min = 0, max }: { min?: number; max?: number } = {}
): v is string {
  return typeof v === 'string' && v.length >= min && (max === undefined || v.length <= max);
}

export function isString(
  v: unknown,
  { min = 0, max }: { min?: number; max?: number } = {}
): v is string {
  return typeof v === 'string' && v.length >= min && (max === undefined || v.length <= max);
}

isString checks both type and length constraints. It’s not enough to know something is a string—you often also need to know it isn’t empty, or that it isn’t absurdly long.
The min default of 0 makes it flexible: you can validate “any string” or require at least one character depending on the context.
The optional max prevents cases like a 10,000-character query string from reaching your application logic.
Because it’s a TypeScript type guard (v is string), a successful check can narrow types in code that uses it.

Now the isInt type guard:

TypeScript

export function isInt(
  v: unknown,
  { min, max }: { min?: number; max?: number } = {}
): v is number {
  return Number.isInteger(v) && (min === undefined || (v as number) >= min) && (max === undefined || (v as number) <= max);
}

export function isInt(
  v: unknown,
  { min, max }: { min?: number; max?: number } = {}
): v is number {
  return Number.isInteger(v) && (min === undefined || (v as number) >= min) && (max === undefined || (v as number) <= max);
}

isInt enforces “integer-ness,” which is crucial for pagination values like page and pageSize.
The optional min and max bounds prevent invalid pagination like page=0 or pageSize=100000.
This guard assumes it is checking a numeric value, so it pairs naturally with a parser that converts the string into a number first.
Keeping this as a reusable guard means every route can enforce the same pagination rules in the same way.

Validating GET /api/products with Shared Parsers

Now we apply the utilities in a real route. The products route lives at src/app/api/products/route.ts, and it already imports parseOptionalStringParam and parseOptionalIntParam. Your job is to use them consistently so the route validates inputs and returns standard error envelopes on invalid values.

Here’s the full GET handler as it exists in the project.

TypeScript

import { NextRequest } from 'next/server';
import { error, success } from '@/lib/http/response';
import { parseOptionalIntParam, parseOptionalStringParam } from '@/lib/http/validation';

export async function GET(req: NextRequest) {
  try {
    const sp = req.nextUrl.searchParams;

    const query = parseOptionalStringParam(sp, 'query', { min: 1, max: 64 });
    if (!query.ok) return error('VALIDATION_ERROR', query.message, undefined, 400);

    const page = parseOptionalIntParam(sp, 'page', { min: 1 });
    if (!page.ok) return error('VALIDATION_ERROR', page.message, undefined, 400);

    const pageSize = parseOptionalIntParam(sp, 'pageSize', { min: 1, max: 100 });
    if (!pageSize.ok) return error('VALIDATION_ERROR', pageSize.message, undefined, 400);

    // Still no persistence in Unit 2 — we just validate and accept the inputs.
    void query;
    void page;
    void pageSize;

    return success([]);
  } catch (e: unknown) {
    return error('INTERNAL_ERROR', (e as Error).message, undefined, 500);
  }
}

import { NextRequest } from 'next/server';
import { error, success } from '@/lib/http/response';
import { parseOptionalIntParam, parseOptionalStringParam } from '@/lib/http/validation';

export async function GET(req: NextRequest) {
  try {
    const sp = req.nextUrl.searchParams;

    const query = parseOptionalStringParam(sp, 'query', { min: 1, max: 64 });
    if (!query.ok) return error('VALIDATION_ERROR', query.message, undefined, 400);

    const page = parseOptionalIntParam(sp, 'page', { min: 1 });
    if (!page.ok) return error('VALIDATION_ERROR', page.message, undefined, 400);

    const pageSize = parseOptionalIntParam(sp, 'pageSize', { min: 1, max: 100 });
    if (!pageSize.ok) return error('VALIDATION_ERROR', pageSize.message, undefined, 400);

    // Still no persistence in Unit 2 — we just validate and accept the inputs.
    void query;
    void page;
    void pageSize;

    return success([]);
  } catch (e: unknown) {
    return error('INTERNAL_ERROR', (e as Error).message, undefined, 500);
  }
}

The route reads req.nextUrl.searchParams and immediately validates every supported param. This is intentional: we want to reject bad inputs before doing any expensive work.
query is treated as an optional string with constraints { min: 1, max: 64 }. If the param is missing, it becomes undefined. If it’s present but empty/too long after trimming, it fails validation.
page is an optional integer with a minimum of 1. This prevents pagination like page=0 or page=-3 from slipping through.
pageSize is an optional integer constrained to 1–100, which prevents clients from requesting enormous pages and accidentally overloading your backend later.
Validation failures are converted into consistent API errors via error('VALIDATION_ERROR', message, undefined, 400). This ties directly back to the previous lesson: the client always receives the same error envelope shape.
The try/catch is a safety net for unexpected failures. Validation failures are not exceptions—they return early—so the catch block is reserved for true “something went wrong” scenarios and responds with INTERNAL_ERROR.
The route still returns success([]) because Unit 2 is about validation, not persistence. The important part is that the route now accepts or rejects input correctly and does so consistently.