How do you implement search, filtering and pagination with URL search params in the App Router?

// lib/search-params.ts
// Turn untrusted URL input into a typed, validated query object.
export type RawSearchParams = Record<string, string | string[] | undefined>;
export type ProductQuery = { q: string; categories: string[]; sort: "price" | "name"; page: number };

const first = (v: string | string[] | undefined) => (Array.isArray(v) ? v[0] : v);
const all = (v: string | string[] | undefined) => (v === undefined ? [] : Array.isArray(v) ? v : [v]);
const CATEGORIES = new Set(["lamps", "chairs", "desks"]);

export function parseProductQuery(sp: RawSearchParams): ProductQuery {
  const q = (first(sp.q) ?? "").trim().slice(0, 100);
  const categories = all(sp.category).filter((c) => CATEGORIES.has(c));
  const sort = first(sp.sort) === "price" ? "price" : "name";
  const n = Number.parseInt(first(sp.page) ?? "1", 10);
  const page = Number.isFinite(n) && n > 0 ? n : 1;
  return { q, categories, sort, page };
}

// Build a URL for the same list with some keys changed; null removes a key.
export function withParams(current: URLSearchParams | RawSearchParams, changes: Record<string, string | null>) {
  const next = current instanceof URLSearchParams ? new URLSearchParams(current) : toURLSearchParams(current);
  for (const [k, v] of Object.entries(changes)) (v === null ? next.delete(k) : next.set(k, v));
  const s = next.toString();
  return s ? `?${s}` : "?";
}

function toURLSearchParams(sp: RawSearchParams) {
  const u = new URLSearchParams();
  for (const [k, v] of Object.entries(sp)) for (const x of all(v)) u.append(k, x);
  return u;
}

// app/products/page.tsx
import Link from "next/link";
import { Suspense } from "react";
import { findProducts } from "@/lib/products";
import { parseProductQuery, withParams } from "@/lib/search-params";
import SearchBox from "./search-box";

export default async function ProductsPage({ searchParams }: PageProps<"/products">) {
  const raw = await searchParams;
  const query = parseProductQuery(raw);
  const { items, total, page, pageCount } = await findProducts({ ...query, perPage: 10 });

  return (
    <main>
      <h1>Products</h1>
      <Suspense fallback={<input placeholder="Search products" disabled />}>
        <SearchBox />
      </Suspense>
      <p id="summary">
        {total} results, page {page} of {pageCount}, q=&quot;{query.q}&quot;, categories={query.categories.join("+") || "all"}, sort={query.sort}
      </p>
      <ul>
        {items.map((p) => (
          <li key={p.id}>{p.name} ({p.category}) ${p.price}</li>
        ))}
      </ul>
      <nav aria-label="pagination">
        {page > 1 && <Link href={withParams(raw, { page: String(page - 1) })}>Previous</Link>}{" "}
        {page < pageCount && <Link href={withParams(raw, { page: String(page + 1) })}>Next</Link>}
      </nav>
    </main>
  );
}

// app/products/search-box.tsx
"use client";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
import { useEffect, useRef, useState, useTransition } from "react";

export default function SearchBox() {
  const searchParams = useSearchParams();
  const pathname = usePathname();
  const { replace } = useRouter();
  const [value, setValue] = useState(searchParams.get("q") ?? "");
  const [isPending, startTransition] = useTransition();
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

  useEffect(() => () => clearTimeout(timer.current), []);

  function onChange(next: string) {
    setValue(next);
    clearTimeout(timer.current);
    timer.current = setTimeout(() => {
      const params = new URLSearchParams(searchParams);
      if (next) params.set("q", next);
      else params.delete("q");
      params.delete("page"); // a new search starts at page 1
      startTransition(() => replace(`${pathname}?${params.toString()}`, { scroll: false }));
    }, 300);
  }

  return (
    <label>
      Search{" "}
      <input value={value} onChange={(e) => onChange(e.target.value)} placeholder="Search products" />
      {isPending && <span id="searching"> updating...</span>}
    </label>
  );
}