Hands-On Lab & Phase Exit Build, test, reason about, and transfer a production-style collection endpoint
Phase 15 - Filtering, Search, Sorting & Pagination Volume 04 - Professional Backend
v
v
v
Phase 15 turns an unbounded collection endpoint into a validated, queryable, stable, paginated API contract.
Hands-on lab The Phase 15 lab proves that your collection endpoint is bounded, validated, predictable, and useful to a real UI.
Lab A - Query contract • Create tasks-query.schemas.ts.
• Add projectId, assigneeId, status, priority, search, sort, order, page, and pageSize.
• Use coercion for numeric query strings.
• Cap pageSize at 100.
• Reject unknown query parameters with a strict object.
Lab B - Prisma translation • Build a Prisma.TaskWhereInput from only the validated public filters.
• Add case-insensitive title/description search.
• Map allow-listed sort fields explicitly.
• Add id as a stable secondary order.
• Implement skip/take offset pagination.
Lab C - Response contract • Return data + meta instead of a raw array.
• Count using the same where filter.
• Calculate totalPages and previous/next flags.
• Verify an out-of-range page returns an empty data array with truthful metadata.
Lab D - PowerShell smoke matrix Scenario Expected
GET /tasks Defaults applied, <=20 rows?status=IN_PROGRESS&priority;=HIGH Both filters applied
?search=payroll Case-insensitive substring match
?sort=title■=asc Deterministic sorted page
?page=0 400 validation error
?pageSize=1000 400 validation error
?sort=dropTable 400 validation error
?page=999999 200 with empty data + truthful meta
Exercise levels Level Challenge
1 - Follow Implement the reference query contract and pass the smoke tests.
2 - Modify Add dueBefore and dueAfter ISO datetime filters with clear inclusive/exclusive semantics.
3 - Implement Add an unassigned=true filter without allowing contradictory assigneeId + unassigned=true combinations.
4 - Engineer Design the list endpoint for a payroll employee table with department, employment status, search, sortable columns, and either offset or cursor pagination. Justify every query parameter and index candidate before coding.
Architecture oral exam • Why should arbitrary query parameters never be forwarded directly into Prisma?
• Why does stable pagination require deterministic ordering?
• Why is pageSize capped by the backend?
• Why can offset pagination degrade on deep pages?
• When is cursor pagination a better product fit?
• Why can exact total counts be expensive?
• Why is an ordinary B-tree index not enough for arbitrary substring search?
• Why should filters and page often live in the URL?
• What evidence should exist before adding a new database index?
Phase exit checklist • GET /tasks no longer returns an unbounded collection.
• query params are validated and normalized before TasksService.
• public filters translate explicitly to Prisma where input.
• search semantics are documented and intentionally simple.
• sorting is allow-listed and deterministic.
• offset pagination returns useful metadata.
• you can explain when cursor pagination is preferable.
• you understand the cost of count queries.
• index design is tied to observed workload rather than guesswork.
• Next.js can represent collection state with URL search parameters.
v
v
v
v
v
data + pagination metadata
TaskFlow now has a bounded, queryable collection API suitable for real application screens.
Phase 16 begins Volume 05 - Authentication & Security. The next problem is identity: TaskFlow can query data professionally, but it still cannot prove who the caller is. We will first learn authentication concepts before integrating Supabase Auth.
Hands On Lab and Phase Exit matters because it changes a real boundary in TaskFlow. The goal is to understand the inputs, owner, observable output, and failure modes before adding more abstraction.
Restate the goal of “Hands On Lab and Phase Exit” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: query parameters → validated filter/sort → stable query → page/cursor → response metadata. Mark the one boundary this lesson changes.
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
Connect the slice to TaskFlow’s phase artifact: Task list API with filter/search/sort/page contract plus metadata and indexes justified by measured query patterns.. Verify behavior from the outside as a user or API client would.
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
take: limit + 1,
where: cursor ? {
OR: [
{ createdAt: { lt: cursor.createdAt } },
{ createdAt: cursor.createdAt, id: { lt: cursor.id } },
],
} : undefinedDo not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.
Return to the nearest observable boundary: input, network, process log, database, or rendered UI. Compare actual evidence with the predicted path.
Change one variable at a time and reproduce the original failure after the fix; otherwise you have correlation, not diagnosis.
Without copying the final source, create a second small scenario that applies “Hands On Lab and Phase Exit” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Guarantee deterministic ordering with a unique tie-breaker.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Client sends database column names unchecked
Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?
If your explanation is vague, repeat the boundary trace before moving on.Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.