List All URLs (GET /urls)

Response envelope. Wrapping the page in an object that carries the data plus its paging metadata: { data, page, limit, total }. The total is the count of all rows, so the client can render "page 2 of 7" via Math.ceil(total / limit).

Stable ordering. A deterministic sort with a tiebreaker — ORDER BY created_at DESC, id DESC — so page boundaries don't shift. Without the id tiebreaker, two rows sharing the same createdAt could swap order between requests and a row could appear on two pages or vanish between them.

Why a Bare Array Isn't Enough

A list endpoint is more than SELECT * FROM urls, and three decisions are why.

First, the response shape. The client paging through results has to know which page it asked for and how many rows exist in total, or it can't render "page 2 of 7" — so we return the envelope, not a bare array. Each item in data exposes five fields:

shortUrl is derived — it isn't stored. We build it from shortCode in the handler so the client gets a ready-to-use link, and lock the whole shape with a Fastify response schema, which validates our output and serializes it fast.

Second, the paging math is caller-controlled, so it gets a schema. page is integer, minimum: 1 (default 1); limit is integer, minimum: 1, maximum: 100 (default 20). With additionalProperties: false, anything malformed — page=0, limit=101, an unknown param — is rejected with 400 { error, message } before the handler runs. The maximum: 100 cap matters: without it a caller could ask for limit=1000000 and turn one request into a full-table scan. That 400 is normalized into our { error, message } shape by the app.setErrorHandler from chapter 8.

Third, route order — the trap from chapter 13. We registered /:code as the bare catch-all, placed last so static paths win. /urls is another static path: if the list route were registered after the catch-all, Fastify would read GET /urls as a redirect for the code "urls" and return 404. The fix is the same rule — register the specific static route first:

With listRoute before redirectRoute, Fastify's radix router prefers the specific static /urls over the /:code parameter. We don't trust it — we lock it with a test, which is exactly the failure the start branch is about to demonstrate.

Step 1: The Failing Tests (Red)

Check out the start branch, install, and bring up the database:

The start branch ships the tests first and no implementation. The Docker-free unit suite injects the in-memory UrlService and covers nine cases against GET /urls: the empty page, newest-first ordering with every item field, page boundaries, the last partial page, the three 400-rejection cases, and the route-ordering proof. The one to watch is the last:

It asserts GET /urls returns 200, carries no Location header, and has an array in data — i.e. it's the list, not a redirect or a 404. On the start branch, with no list route registered, the /:code catch-all grabs /urls, finds no code "urls", and returns 404. That single assertion is what motivates the route-ordering fix.

The integration suite mirrors the rest against the real database, wiring PrismaUrlRepository to prove the same envelope and ordering land from Postgres. Its closing case ties the whole section together — shorten a URL, hit it twice, then list, and the listed item reports clicks: 2, end to end through Postgres.

Run both suites:

The red is honest and uniform: every list case expected 200 (or 400) and received 404. With no /urls route registered, the /:code catch-all answers every request and finds no code "urls". The surrounding suites stay green, so this is a missing endpoint, not a broken app — the red is purely behavioural.

Step 2: Add list to the Seam (Green)

Switch to the finish branch:

The new capability goes behind the same UrlStore interface every route already depends on. We add one method — list({ page, limit }) — plus the shared types it returns. findByCode only ever needed the original URL string, but listing has to surface the whole record, so we add a richer UrlRecord shape.

The in-memory store now keeps a single Map<string, UrlRecord> instead of the two parallel maps from chapter 14, so each saved code carries its shortCode, originalUrl, clicks, and createdAt in one record. list sorts newest-first and slices:

The seq counter is what makes the in-memory ordering deterministic. Two save calls in the same millisecond would otherwise get identical createdAt values and sort unpredictably; offsetting each by an increasing seq guarantees a strict newest-first order — the in-memory equivalent of the database's id tiebreaker.

The Prisma store does the paging where it belongs — in SQL.

findMany with skip/take is the limit/offset slice; orderBy: [{ createdAt: "desc" }, { id: "desc" }] is the stable ordering. Both run inside one $transaction so the page and the total come from the same snapshot — if a row were inserted between the two queries, the page and the count could disagree. The transaction makes them consistent.

Step 3: The Thin Handler

The route reads the validated { page, limit }, calls urlStore.list, and maps each record to the response shape — adding the ISO createdAt and the derived shortUrl. Everything else is the schema.

The querystring schema applies the defaults (page=1, limit=20), so by the time request.query reaches the handler both values are always present — no ?? 20 fallbacks in our code. The handler never touches a database directly; it talks only to the UrlStore seam, so the same code runs against the in-memory store in the unit tests and Prisma in integration and production. With the route registered before the catch-all in app.ts, /urls now resolves to the list.

Step 4: Green on Both Suites

Run everything:

Green on both, including the route-ordering test: /urls returns the list, not a redirect, because listRoute is registered before the /:code catch-all.

When you're done, stop the container:

What's Next

The list only shows the surface — code, original URL, click count. Next we add URL stats (GET /urls/:code/stats), returning the full metadata for a single code with a 404 for unknown ones.