Generating Unique Short Codes

Regenerate-on-collision loop. Draw a candidate, ask the store whether it's taken, and redraw until one is free. This is what turns "probably unique" into "definitely unique."

Why Inject the Randomness?

A generator that calls Math.random directly is random, and therefore untestable. You can't write expect(code).toBe("000000") against a value you can't predict ahead of time. The usual escape hatches are both bad: assert nothing specific (a weak test that passes even when the generator is broken), or mock the global Math.random (brittle, and the mock leaks into other tests if you forget to restore it).

Injecting the randomness source dissolves the tension. The generator takes its source as a parameter that defaults to Math.random:

In production we pass nothing, so it behaves exactly as you'd expect. In tests we pass a function that returns a scripted sequence of values, which makes the output an exact, asserted string. Same code, two randomness sources, zero flakiness, and not a single global touched.

Step 1: Write the Failing Tests (Red)

Start from the red branch:

The branch ships two failing signals. First, a brand-new unit test for the generator that imports a module that doesn't exist yet:

This test is the whole specification, written before the code. Read it as a list of properties the generator must satisfy:

• Right length. Whatever the randomness, the code is CODE_LENGTH (6) characters.
• Allowed alphabet only. Every character is one of the base62 set, checked both by the regex /^[0-9A-Za-z]{6}$/ and by asserting each char is in ALPHABET.
• Deterministic under a known source. Six draws of 0 give "000000"; six draws of 0.999999 give "zzzzzz". That's the determinism injection buys us.
• Correct value-to-character mapping. 10/62 lands on index 10 ("A"), 36/62 on index 36 ("a"), so the interleaved sequence yields "AaAaAa".
• Unique against the store. With an empty store the first candidate is returned. With the store already holding "000000", the first draw collides, so the function redraws and returns "zzzzzz".

The sequence helper makes all of this possible. It closes over an index and returns the supplied values one per call. Feed it [0] and every call returns 0; feed it twelve values and you script the generator's behavior across two full codes. Because the generator pulls randomness through its parameter, a scripted sequence makes the output an exact, asserted value.

The second red signal is the route test, updated to expect a generated code instead of the hardcoded abc123:

The same injection seam reaches the HTTP layer. buildApp({ random: () => 0 }) threads a deterministic source all the way down to the route, so the test can assert the exact code "000000" instead of just "some string." A second test (not shown) builds the app with the default randomness and asserts shape only: the code matches /^[0-9A-Za-z]{6}$/ and flows unchanged into shortUrl. The split is deliberate. Pin the exact output where you control randomness, and assert the invariants where you don't.

Run it:

Red, twice over. The new short-code.test.ts suite can't even start, because there's no ../src/utils/short-code module to import, and the route test fails its deep-equality check: it wants 000000, but the route still returns abc123. Both failures point at exactly the gap we're about to close.

There's a type-level failure too. Run npm run typecheck and TypeScript reports that random isn't a known property of BuildAppOptions yet, since the route test is already passing an option the app doesn't accept. We fix that in the wiring step.

Step 2: Implement the Generator (Green)

Switch to the finish branch to see the implementation:

The whole generator is one new file:

generateShortCode is a loop over CODE_LENGTH positions. For each one it calls random() to get a float in [0, 1), scales it by ALPHABET.length (62), and floors to an index in [0, 61]. random() === 0 maps to index 0 ("0"), and random() === 0.999999 maps to index 61 ("z"). That's why the test's six zeros produce "000000" and six near-ones produce "zzzzzz". The function is pure with respect to random: same sequence in, same code out, every time, with no global state, no hidden side effects, and nothing to mock.

generateUniqueShortCode is the uniqueness guarantee. It draws a candidate, then loops while store.findByCode(code) returns something other than undefined (meaning the code is already taken), drawing a fresh candidate each time. The first free code wins. With an empty store the first draw is returned immediately; with "000000" already present, the first draw collides, so it redraws and returns the next code the scripted sequence produces.

Notice what generateUniqueShortCode actually depends on: only UrlStore.findByCode, the interface we extracted in chapter 6. It has no idea whether the store is a Map or a database. When chapter 12 swaps the in-memory store for a Prisma-backed one, this collision logic doesn't change a line. Chapter 19 revisits collisions at the database level, where two concurrent inserts can race for the same code, a problem a single-process loop can't see.

Step 3: Wire the Generator into the Route (Refactor)

The generator is correct in isolation, but the route still returns abc123. We replace that one line and thread the optional randomness source through the wiring, without changing the route's schema or response shape.

Two changes from chapter 6. The hardcoded const shortCode = "abc123"; becomes const shortCode = generateUniqueShortCode(urlStore, random);, so the route now asks the generator for a fresh, store-checked code. And ShortenRouteOptions gains an optional random?: RandomSource, passed straight to the generator. Production omits it (the generator falls back to Math.random); the route test injects () => 0 to pin the output. The schema and the response body are byte-for-byte what they were, and only the value of shortCode is now generated rather than faked.

The same optional random flows one level up, through buildApp:

BuildAppOptions now declares random?, and buildApp forwards it: register(shortenRoute, { urlStore, random: opts.random }). That one addition makes the type error from Step 1 go away, so buildApp({ random: () => 0 }) is now valid, and it gives the route test a clean, dependency-injected way to control the output without ever touching the global Math.random. The UrlService from chapter 6 is untouched.

Run the full suite:

Green: four suites, twelve tests, covering the health check, the two shorten contract tests, the three UrlService tests from chapter 6, and the six new generator tests. npm run typecheck is clean too, now that random is a known option. The fake is gone, and every code the route returns is a real, unique, base62 string.

What's Next

The route still happily shortens "not a url" or an empty string, because nothing checks the input. Next we validate the URL and reject malformed input before it ever reaches storage.