Validating Domain Models

Lesson: Validating Domain Models and Query Parameters

Welcome back 👋 In the previous lesson, you laid the groundwork for a consistent backend by defining standard success and error envelopes and enforcing them across all API routes. Every endpoint now speaks the same language, whether it succeeds or fails. In this lesson, we build directly on that foundation. You’ll learn how to validate incoming data early, define clear domain models and DTOs, and safely handle common inputs like query parameters. By the end, your /api/products endpoint will still return an empty list—but it will do so only after carefully validating pagination and search inputs, using reusable validation helpers and strongly typed models.

Previously: Establishing a Consistent API Contract

Previously, you focused on how the API responds rather than what it returns. You introduced: A shared ApiSuccess / ApiError contract Centralized success() and error() helpers Predictable response envelopes for all routes, including stubbed ones That work matters here because validation failures are just another kind of response . Thanks to that foundation, invalid input can now be rejected cleanly and consistently, without special cases or ad-hoc JSON.

Why Validation and Domain Models Matter

As this backend grows, it will support products, shopping carts, orders, and state transitions like paying or canceling an order. Each step introduces more data, more relationships, and more opportunities for invalid input. Validation is how you protect the system’s core rules: Query parameters must be well-formed and bounded. Identifiers must look like real IDs. Domain entities must have a single, authoritative shape. Clients must only be allowed to send what they’re responsible for. This lesson introduces the building blocks that make those guarantees possible.

The Product Domain Model: The Backend’s Source of Truth

A backend needs a canonical definition of what a “product” is. This definition lives in src/lib/types/domain.ts and represents the shape the backend itself trusts—typically mirroring database rows. Product domain type: This file defines the authoritative product model used throughout the backend. TypeScript// src/lib/types/domain.ts export type Currency = "USD"; export type ProductStatus = "active" | "archived"; export interface Product { id: string; sku: string; name: string; description: string | null; price_cents: number; currency: Currency; inventory_count: number; status: ProductStatus; created_at: string; updated_at: string; }// src/lib/types/domain.ts export type Currency = "USD"; export type ProductStatus = "active" | "archived"; export interface Product { id: string; sku: string; name: string; description: string | null; price_cents: number; currency: Currency; inventory_count: number; status: ProductStatus; created_at: string; updated_at: string; } This interface represents a complete product, including system-managed fields like id, timestamps, and status. Monetary values are stored as integers in cents (price_cents) to avoid floating-point rounding issues. Currency and ProductStatus are constrained unions, which prevents invalid values from entering the system. This type is what the backend and database agree on—it is not what clients are allowed to send directly.

Join the 1M+ learners on CodeSignal

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

TypeScript

// src/lib/types/domain.ts

export type Currency = "USD";

export type ProductStatus = "active" | "archived";

export interface Product {
  id: string;
  sku: string;
  name: string;
  description: string | null;
  price_cents: number;
  currency: Currency;
  inventory_count: number;
  status: ProductStatus;
  created_at: string;
  updated_at: string;
}

TypeScript

// src/lib/types/dto.ts

import { Currency, ProductStatus } from "./domain";

export interface CreateProductInput {
  sku: string;
  name: string;
  description?: string | null;
  price_cents: number;
  currency?: Currency;
  inventory_count: number;
}

export interface UpdateProductInput {
  name?: string;
  description?: string | null;
  price_cents?: number;
  currency?: Currency;
  inventory_count?: number;
  status?: ProductStatus;
}

// src/lib/types/dto.ts

import { Currency, ProductStatus } from "./domain";

export interface CreateProductInput {
  sku: string;
  name: string;
  description?: string | null;
  price_cents: number;
  currency?: Currency;
  inventory_count: number;
}

export interface UpdateProductInput {
  name?: string;
  description?: string | null;
  price_cents?: number;
  currency?: Currency;
  inventory_count?: number;
  status?: ProductStatus;
}

TypeScript

const UUID_RE =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function isUUID(v: unknown): v is string {
  const s = Array.isArray(v) ? String(v[0] ?? "") : String(v ?? "");
  if (!s) return false;
  return UUID_RE.test(s.trim());
}

const UUID_RE =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function isUUID(v: unknown): v is string {
  const s = Array.isArray(v) ? String(v[0] ?? "") : String(v ?? "");
  if (!s) return false;
  return UUID_RE.test(s.trim());
}

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 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 isEnum<T extends readonly string[]>(
  v: unknown,
  values: T,
): v is T[number] {
  return typeof v === "string" && (values as readonly string[]).includes(v);
}

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 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 isEnum<T extends readonly string[]>(
  v: unknown,
  values: T,
): v is T[number] {
  return typeof v === "string" && (values as readonly string[]).includes(v);
}

TypeScript

export function parseOptionalIntParam(
  searchParams: URLSearchParams,
  key: string,
  { min, max }: { min?: number; max?: number } = {},
): { ok: true; value: number | undefined } | { ok: false; message: string } {
  const raw = searchParams.get(key);
  if (raw === null) return { ok: true, value: undefined };

  const trimmed = raw.trim();
  if (trimmed.length === 0)
    return { ok: false, message: `${key} must be an integer` };

  const parsed = Number(trimmed);
  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
    return { ok: false, message: `${key} must be an integer` };
  }

  if (!isInt(parsed, { min, max })) {
    if (min !== undefined && parsed < min)
      return { ok: false, message: `${key} must be >= ${min}` };
    if (max !== undefined && parsed > max)
      return { ok: false, message: `${key} must be <= ${max}` };
  }

  return { ok: true, value: parsed };
}

TypeScript

import type { LoaderFunctionArgs } from "@remix-run/node";
import { error, success } from "@/lib/http/response";
import { isString, parseOptionalIntParam } from "@/lib/http/validation";
import type { Product } from "@/lib/types/domain";

export async function loader({ request }: LoaderFunctionArgs) {
  try {
    const searchParams = new URL(request.url).searchParams;
    const query = searchParams.get("query") ?? undefined;

    if (query !== undefined && !isString(query, { max: 100 })) {
      return error(
        "VALIDATION_ERROR",
        "query must be <= 100 characters",
        undefined,
        400,
      );
    }

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

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

    // Database wiring comes in Unit 3.
    void page;
    void pageSize;

    return success<Product[]>([]);
  } catch (e: unknown) {
    const message = e instanceof Error ? e.message : "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

import type { LoaderFunctionArgs } from "@remix-run/node";
import { error, success } from "@/lib/http/response";
import { isString, parseOptionalIntParam } from "@/lib/http/validation";
import type { Product } from "@/lib/types/domain";

export async function loader({ request }: LoaderFunctionArgs) {
  try {
    const searchParams = new URL(request.url).searchParams;
    const query = searchParams.get("query") ?? undefined;

    if (query !== undefined && !isString(query, { max: 100 })) {
      return error(
        "VALIDATION_ERROR",
        "query must be <= 100 characters",
        undefined,
        400,
      );
    }

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

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

    // Database wiring comes in Unit 3.
    void page;
    void pageSize;

    return success<Product[]>([]);
  } catch (e: unknown) {
    const message = e instanceof Error ? e.message : "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

TypeScript

// src/lib/types/dto.ts

import { Currency, ProductStatus } from "./domain";

export interface CreateProductInput {
  sku: string;
  name: string;
  description?: string | null;
  price_cents: number;
  currency?: Currency;
  inventory_count: number;
}

export interface UpdateProductInput {
  name?: string;
  description?: string | null;
  price_cents?: number;
  currency?: Currency;
  inventory_count?: number;
  status?: ProductStatus;
}

TypeScript

const UUID_RE =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function isUUID(v: unknown): v is string {
  const s = Array.isArray(v) ? String(v[0] ?? "") : String(v ?? "");
  if (!s) return false;
  return UUID_RE.test(s.trim());
}

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 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 isEnum<T extends readonly string[]>(
  v: unknown,
  values: T,
): v is T[number] {
  return typeof v === "string" && (values as readonly string[]).includes(v);
}

TypeScript

import type { LoaderFunctionArgs } from "@remix-run/node";
import { error, success } from "@/lib/http/response";
import { isString, parseOptionalIntParam } from "@/lib/http/validation";
import type { Product } from "@/lib/types/domain";

export async function loader({ request }: LoaderFunctionArgs) {
  try {
    const searchParams = new URL(request.url).searchParams;
    const query = searchParams.get("query") ?? undefined;

    if (query !== undefined && !isString(query, { max: 100 })) {
      return error(
        "VALIDATION_ERROR",
        "query must be <= 100 characters",
        undefined,
        400,
      );
    }

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

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

    // Database wiring comes in Unit 3.
    void page;
    void pageSize;

    return success<Product[]>([]);
  } catch (e: unknown) {
    const message = e instanceof Error ? e.message : "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

TypeScript

export function parseOptionalIntParam(
  searchParams: URLSearchParams,
  key: string,
  { min, max }: { min?: number; max?: number } = {},
): { ok: true; value: number | undefined } | { ok: false; message: string } {
  const raw = searchParams.get(key);
  if (raw === null) return { ok: true, value: undefined };

  const trimmed = raw.trim();
  if (trimmed.length === 0)
    return { ok: false, message: `${key} must be an integer` };

  const parsed = Number(trimmed);
  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
    return { ok: false, message: `${key} must be an integer` };
  }

  if (!isInt(parsed, { min, max })) {
    if (min !== undefined && parsed < min)
      return { ok: false, message: `${key} must be >= ${min}` };
    if (max !== undefined && parsed > max)
      return { ok: false, message: `${key} must be <= ${max}` };
  }

  return { ok: true, value: parsed };
}

Lesson: Validating Domain Models and Query Parameters

Previously: Establishing a Consistent API Contract

Why Validation and Domain Models Matter

The Product Domain Model: The Backend’s Source of Truth

Join the 1M+ learners on CodeSignal

DTOs: Separating Client Input from Domain Truth

Validation Utilities: Small, Reusable Guards

String, integer, and enum guards

Parsing Optional Integer Query Parameters Safely

Validating Query Parameters in /api/products

Recap