Generating Unique Short Codes

Injected randomness means passing the random source into the generator as an argument (RandomSource = () => number) instead of calling the global Math.random directly inside the function. In production, the app defaults to Math.random. In tests, we pass a known sequence of numbers. This is the same seam idea from chapter 6 applied to randomness, and it lets us write exact assertions like expect(code).toBe("000000").

A regenerate-on-collision loop draws a candidate code, asks the store if it is taken, and redraws until it finds a free one. This process turns a "probably unique" code into a "definitely unique" one.

Why Inject the Randomness?

A generator that calls Math.random directly is completely random, which makes it hard to test. You cannot write expect(code).toBe("000000") against a value you cannot predict. The common workarounds are unhelpful. You might assert nothing specific, which creates a weak test that passes even when the generator is broken. Or, you might mock the global Math.random, which is brittle and can leak into other tests if you forget to restore it.

Injecting the randomness source solves this problem. The generator takes its source as a parameter that defaults to Math.random:

In production, we pass nothing, so it behaves normally. In tests, we pass a function that returns a scripted sequence of values. This makes the output an exact, predictable string. We get the same code, two different randomness sources, zero flakiness, and no global variables touched.

Step 1: Write the Failing Tests (Red)

Start from the red branch:

The branch ships two failing signals. First is a brand-new unit test for the generator. It imports a module that does not exist yet:

This test acts as the whole specification, written before the code itself. You can read it as a list of properties the generator must satisfy:

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

The sequence helper makes this testing 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 guarantees an exact output.

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

The same injection seam reaches the HTTP layer. Calling buildApp({ random: () => 0 }) threads a deterministic source all the way down to the route. This lets the test assert the exact code "000000" instead of just checking for a generic string. A second test (not shown) builds the app with the default randomness and asserts the shape only. It checks that the code matches /^[0-9A-Za-z]{6}$/ and flows unchanged into shortUrl. This split is deliberate. We pin the exact output where we control the randomness, and we assert the general shape where we do not.

Run it:

The tests fail twice over. The new short-code.test.ts suite cannot even start because there is no ../src/utils/short-code module to import. The route test fails its deep-equality check because it expects 000000, but the route still returns abc123. Both failures point at the gap we are about to close.

There is also a type-level failure. If you run npm run typecheck, TypeScript reports that random is not a known property of BuildAppOptions. The route test is passing an option the app does not accept yet. We will 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 loops over CODE_LENGTH positions. For each position, it calls random() to get a decimal number between 0 and 1. It scales that number by ALPHABET.length (62) and rounds down to an index between 0 and 61. A random value of 0 maps to index 0 ("0"), and a value of 0.999999 maps to index 61 ("z"). This is why the test's six zeros produce "000000" and six near-ones produce "zzzzzz". The function is pure with respect to random. The same sequence in gives the same code out, with no global state and nothing to mock.

generateUniqueShortCode provides the uniqueness guarantee. It draws a candidate code, then loops as long as store.findByCode(code) finds an existing match. It draws a fresh candidate each time until it finds a free code. With an empty store, the first draw is returned immediately. If "000000" is already present, the first draw collides, so the function redraws and returns the next code from the sequence.

Notice what generateUniqueShortCode depends on. It only relies on UrlStore.findByCode, the interface we extracted in chapter 6. It has no idea whether the store is a simple Map or a real database. When chapter 12 swaps the in-memory store for a Prisma-backed database, this collision logic will not change at all. Later, chapter 19 will revisit collisions at the database level, where two concurrent inserts can race for the same code, a problem this single-process loop cannot see.

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

The generator works in isolation, but the route still returns abc123. We need to replace that hardcoded line and thread the optional randomness source through the application wiring. We will do this without changing the route's schema or response shape.

There are two main changes from chapter 6. First, the hardcoded const shortCode = "abc123"; becomes const shortCode = generateUniqueShortCode(urlStore, random);. The route now asks the generator for a fresh, store-checked code. Second, ShortenRouteOptions gains an optional random?: RandomSource property, which is passed straight to the generator. Production omits this option, so the generator falls back to Math.random. The route test injects () => 0 to pin the output. The schema and the response body remain exactly the same. Only the value of shortCode is generated rather than faked.

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

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

Run the full suite:

The tests pass. We have four suites and twelve tests covering the health check, the two shorten contract tests, the three UrlService tests from chapter 6, and the six new generator tests. Running npm run typecheck is also clean now that random is a known option. The fake value 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 will validate the URL and reject malformed input before it ever reaches storage.