Build it

We will build the code generator, the schema, the create and redirect endpoints with a Redis cache, the click worker, and the cleanup jobs. NestJS 10, Prisma 6, ioredis 5 and Postgres 16. You can practise the base62 helpers and the code-length arithmetic in your browser, with no setup, in the Practice section below.

1. Write the base62 helpers

   toBase62 is here to show option A, and randomCode is option C, the one we use. Use crypto.randomInt, never Math.random, because codes for private links must be unpredictable.

   TypeScriptCopy

   // base62.ts
   import { randomInt } from 'node:crypto';
   
   const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
   const BASE = 62n;
   
   export function toBase62(n: bigint): string {
     if (n < 0n) throw new RangeError('negative');
     if (n === 0n) return '0';
     let out = '';
     while (n > 0n) {
       out = ALPHABET[Number(n % BASE)] + out;     // the remainder is the last digit
       n /= BASE;                                   // bigint division drops the remainder
     }
     return out;
   }
   
   export function fromBase62(s: string): bigint {
     let n = 0n;
     for (const ch of s) {
       const d = ALPHABET.indexOf(ch);
       if (d < 0) throw new RangeError(`not base62: ${ch}`);
       n = n * BASE + BigInt(d);
     }
     return n;
   }
   
   // One unpredictable, unbiased character at a time. 7 chars = 62^7, about 3.5 trillion codes.
   export function randomCode(length = 7): string {
     let code = '';
     for (let i = 0; i < length; i++) code += ALPHABET[randomInt(62)];   // crypto, not Math.random
     return code;
   }

   TypeScriptCopy

   // try-base62.ts: run with npx tsx try-base62.ts
   import { fromBase62, randomCode, toBase62 } from './base62';
   
   console.log(toBase62(125_000_001n), toBase62(125_000_002n));  // a counter: the next code is easy to guess
   console.log(fromBase62('8sud3'));                             // and back again
   console.log(randomCode(), randomCode(10));                    // random: no pattern to follow
   console.log(toBase62(2n ** 63n - 1n).length);                 // the biggest bigint id needs 11 chars

   OutputCopy

   8sud3 8sud4
   125000001n
   Qu9WIao 7GOfbrNhBr
   11

   Your random codes will differ on every run, which is the point.

2. Define the Prisma models

   longUrl is optional because cleanup clears it while the row stays. The composite unique on ownerId and externalRef is what makes retried creates safe. By default Postgres treats NULLs as distinct in a unique index, so links without an externalRef never clash.

   PrismaCopy

   // prisma/schema.prisma (models only)
   model Link {
     id          BigInt    @id @default(autoincrement())
     code        String    @unique @db.VarChar(16)               // case-sensitive: aZ3k9Qx != AZ3k9Qx
     longUrl     String?   @map("long_url")                      // NULL after purge; the code stays taken
     ownerId     BigInt    @map("owner_id")                      // the calling system (API key)
     externalRef String?   @map("external_ref")                  // e.g. a receipt id
     createdAt   DateTime  @default(now()) @map("created_at") @db.Timestamptz
     expiresAt   DateTime? @map("expires_at") @db.Timestamptz    // NULL = never expires
     disabledAt  DateTime? @map("disabled_at") @db.Timestamptz   // abuse takedown
   
     @@unique([ownerId, externalRef])                             // a retried create finds the first link
     @@map("link")
   }
   
   model Click {
     eventId   String   @map("event_id")                         // Redis stream entry id
     clickedAt DateTime @map("clicked_at") @db.Timestamptz
     code      String   @db.VarChar(16)
     userAgent String?  @map("user_agent")
   
     @@id([eventId, clickedAt])                                   // must include the partition key
     @@index([code, clickedAt])
     @@map("click")                                               // partitioned by month: raw SQL below
   }
   
   model ClickDaily {
     code   String   @db.VarChar(16)
     day    DateTime @db.Date                                     // calendar day in the reporting zone
     clicks BigInt
   
     @@id([code, day])
     @@map("click_daily")
   }

3. Edit the migration for what Prisma cannot express

   Run npx prisma migrate dev --create-only --name links and open the generated file. Change the end of its CREATE TABLE "click" statement from ); to ) PARTITION BY RANGE ("clicked_at");, keep everything else Prisma wrote, and add the lines below at the end. Create future months with a scheduled job, as in Partitioning.

   SQLCopy

   -- (end of Prisma's generated CREATE TABLE "click" ...)  ) PARTITION BY RANGE ("clicked_at");
   
   -- Monthly partitions plus a safety net. UTC months are fine for raw clicks:
   -- they are only kept 90 days, and click_daily holds the local-day totals.
   CREATE TABLE click_2026_10 PARTITION OF click
     FOR VALUES FROM ('2026-10-01 00:00+00') TO ('2026-11-01 00:00+00');
   CREATE TABLE click_2026_11 PARTITION OF click
     FOR VALUES FROM ('2026-11-01 00:00+00') TO ('2026-12-01 00:00+00');
   CREATE TABLE click_default PARTITION OF click DEFAULT;   -- alert if it ever gets rows
   
   -- Prisma cannot describe these two, and leaves them alone once they exist
   ALTER TABLE link ADD CONSTRAINT link_long_url_len CHECK (length(long_url) <= 2048);
   CREATE INDEX link_purge_idx ON link (expires_at) WHERE long_url IS NOT NULL;

4. Validate input and connect to two Redis servers

   The DTO rejects anything that is not an https URL, which blocks javascript: and data: links. The cache Redis may evict keys; the stream Redis must not, so they are separate servers with different settings (Caching, Queues and jobs).

   TypeScriptCopy

   // create-link.dto.ts
   import { IsBoolean, IsISO8601, IsOptional, IsString, IsUrl, MaxLength } from 'class-validator';
   
   export class CreateLinkDto {
     @IsUrl({ protocols: ['https'], require_protocol: true })   // rejects javascript:, data:, http:
     @MaxLength(2048)
     longUrl!: string;
   
     @IsOptional() @IsBoolean()
     isPrivate?: boolean;             // receipts and other personal pages get a 10-character code
   
     @IsOptional() @IsString() @MaxLength(100)
     externalRef?: string;            // e.g. "receipt-D027-000981": same ref, same link
   
     @IsOptional() @IsISO8601()
     expiresAt?: string;
   }

   TypeScriptCopy

   // redis.providers.ts: two Redis servers with different jobs
   import { Logger, Provider } from '@nestjs/common';
   import Redis, { RedisOptions } from 'ioredis';
   
   export const CACHE = 'CACHE_REDIS';   // allkeys-lru: losing a key only costs one DB read
   export const QUEUE = 'QUEUE_REDIS';   // noeviction + AOF: clicks must not be evicted
   
   const log = new Logger('Redis');
   function connect(url: string, opts: RedisOptions): Redis {
     const r = new Redis(url, {
       enableOfflineQueue: false,        // Redis down: fail at once instead of piling up commands
       maxRetriesPerRequest: 1,
       ...opts,
     });
     r.on('error', (e) => log.warn(`${url}: ${e.message}`));   // keep running; it reconnects by itself
     return r;
   }
   
   export const redisProviders: Provider[] = [
     { provide: CACHE, useFactory: () => connect(process.env.CACHE_REDIS_URL!, { commandTimeout: 50 }) },
     { provide: QUEUE, useFactory: () => connect(process.env.QUEUE_REDIS_URL!, { commandTimeout: 200 }) },
   ];

5. Create links with a retry on clashes

   Prisma raises P2002 when a unique constraint fails. Two different constraints can cause it here: the random code was taken, or the same externalRef was sent again. The code checks for the second case first and returns the existing link.

   TypeScriptCopy

   // links.service.ts (part 1: create)
   import { BadRequestException, GoneException, Inject, Injectable, NotFoundException, ServiceUnavailableException } from '@nestjs/common';
   import { Link, Prisma, PrismaClient } from '@prisma/client';
   import Redis from 'ioredis';
   import { randomCode } from './base62';
   import { CreateLinkDto } from './create-link.dto';
   import { CACHE } from './redis.providers';
   
   export class PrismaService extends PrismaClient {}
   const ALLOWED_HOSTS = new Set(['shop.example.com', 'receipts.example.com']);
   const short = (code: string) => ({ code, shortUrl: `https://s.example.com/${code}` });
   
   @Injectable()
   export class LinksService {
     constructor(private readonly prisma: PrismaService, @Inject(CACHE) private readonly cache: Redis) {}
   
     async create(ownerId: bigint, dto: CreateLinkDto) {
       const url = new URL(dto.longUrl);
       if (!ALLOWED_HOSTS.has(url.hostname)) throw new BadRequestException('Only links to our own sites');
       const expiresAt = dto.expiresAt ? new Date(dto.expiresAt) : null;
       for (let attempt = 0; attempt < 5; attempt++) {
         try {
           const link = await this.prisma.link.create({ data: {
             code: randomCode(dto.isPrivate ? 10 : 7), longUrl: url.href, ownerId, externalRef: dto.externalRef, expiresAt,
           } });
           await this.warm(link);                     // the first click, seconds later, is a cache hit
           return short(link.code);
         } catch (e) {
           if (!(e instanceof Prisma.PrismaClientKnownRequestError && e.code === 'P2002')) throw e;
           if (dto.externalRef) {                     // P2002 on externalRef: a retry of a create that worked
             const prev = await this.prisma.link.findUnique({
               where: { ownerId_externalRef: { ownerId, externalRef: dto.externalRef } },
             });
             if (prev) return short(prev.code);
           }
           // otherwise the random code was already taken: loop and draw a new one
         }
       }
       throw new ServiceUnavailableException('Could not allocate a code, try again');
     }

   TypeScriptCopy

   // links.controller.ts: internal API, one API key per calling system
   import { Body, Controller, Post, Req, UseGuards } from '@nestjs/common';
   import { ApiKeyGuard, ApiKeyRequest } from './api-key.guard';   // hashes the key, sets req.client
   import { CreateLinkDto } from './create-link.dto';
   import { LinksService } from './links.service';
   
   @Controller('v1/links')
   @UseGuards(ApiKeyGuard)
   export class LinksController {
     constructor(private readonly links: LinksService) {}
   
     @Post()
     create(@Req() req: ApiKeyRequest, @Body() dto: CreateLinkDto) {
       return this.links.create(req.client.id, dto);       // 201 with { code, shortUrl }
     }
   }

6. Resolve codes with cache-aside, negative caching and expiry

   Every Redis call has a .catch, so a Redis problem becomes a cache miss, never an error page. disable deletes the key, so a takedown works on the next click.

   TypeScriptCopy

   // links.service.ts (part 2: resolve, inside LinksService)
     async resolve(code: string): Promise<string> {
       const key = `link:${code}`;
       const hit = await this.cache.get(key).catch(() => null);      // Redis down = a miss, not an error
       if (hit === '!') throw new NotFoundException();               // cached "no such code"
       if (hit) return hit;
   
       const link = await this.prisma.link.findUnique({ where: { code } });   // unique index lookup
       if (!link) {
         await this.cache.set(key, '!', 'EX', 300).catch(() => null);         // scanners stop at Redis
         throw new NotFoundException();
       }
       if (!link.longUrl || link.disabledAt || (link.expiresAt && link.expiresAt <= new Date())) {
         throw new GoneException();                                  // 410: existed once, gone now
       }
       await this.warm(link);
       return link.longUrl;
     }
   
     async disable(code: string) {                                   // abuse takedown
       await this.prisma.link.update({ where: { code }, data: { disabledAt: new Date() } });
       await this.cache.del(`link:${code}`);                         // effective on the next click
     }
   
     private async warm(link: Link) {
       let ttl = 86_400 + Math.floor(Math.random() * 3600);          // 1 day + jitter (see Caching)
       if (link.expiresAt) ttl = Math.min(ttl, Math.floor((link.expiresAt.getTime() - Date.now()) / 1000));
       if (link.longUrl && ttl > 0) await this.cache.set(`link:${link.code}`, link.longUrl, 'EX', ttl).catch(() => null);
     }
   }

7. Write the redirect endpoint

   The shape check runs before any lookup, so junk paths such as /wp-login.php cost nothing. The click is recorded with a promise that nobody awaits, so the customer never waits for analytics.

   TypeScriptCopy

   // redirect.controller.ts: the only controller on the short domain
   import { Controller, Get, Headers, Inject, NotFoundException, Param, Res } from '@nestjs/common';
   import { Response } from 'express';
   import Redis from 'ioredis';
   import { LinksService } from './links.service';
   import { QUEUE } from './redis.providers';
   
   const CODE = /^[0-9A-Za-z]{7,10}$/;            // 7 for offers, 10 for private links
   
   @Controller()
   export class RedirectController {
     constructor(private readonly links: LinksService, @Inject(QUEUE) private readonly queue: Redis) {}
   
     @Get(':code')
     async go(@Param('code') code: string, @Headers('user-agent') ua = '', @Res() res: Response) {
       if (!CODE.test(code)) throw new NotFoundException();      // cheap reject: no Redis, no DB
       const url = await this.links.resolve(code);               // throws 404 or 410
   
       // Record the click without awaiting it. Analytics must never slow down or break a redirect.
       this.queue
         .xadd('clicks', 'MAXLEN', '~', '2000000', '*', 'code', code, 'ts', String(Date.now()), 'ua', ua.slice(0, 200))
         .catch(() => { /* clicksDropped.inc(): a metric, not an error for the user */ });
   
       res.setHeader('Cache-Control', 'private, max-age=90');    // a double tap within 90 s stays on the phone
       res.redirect(302, url);                                    // 302: later clicks still come to us
     }
   }

8. Write the click worker

   Run it as its own process, not inside the API. The CTE inserts the raw clicks and counts only the rows that were really inserted, so a replay after a crash cannot double the daily numbers. If a worker is gone for good, another copy can take over its pending entries with XAUTOCLAIM.

   TypeScriptCopy

   // click-worker.ts: its own process; give each copy a stable WORKER_NAME
   import Redis from 'ioredis';
   import { PrismaClient } from '@prisma/client';
   
   const redis = new Redis(process.env.QUEUE_REDIS_URL!);
   const prisma = new PrismaClient();
   const GROUP = 'click-writers', ME = process.env.WORKER_NAME ?? 'clicks-1';
   const REPORT_TZ = process.env.REPORT_TZ ?? 'UTC';   // the business's day, e.g. 'Asia/Jakarta'
   type Entry = [id: string, fields: string[] | null];
   
   async function main() {
     await redis.xgroup('CREATE', 'clicks', GROUP, '0', 'MKSTREAM')
       .catch((e) => { if (!String(e).includes('BUSYGROUP')) throw e; });   // group already exists
     let from = '0';                     // '0' = my unacked entries from before a crash; '>' = new ones
     for (;;) {
       const res = (await redis.xreadgroup('GROUP', GROUP, ME, 'COUNT', 500, 'BLOCK', 5000,
         'STREAMS', 'clicks', from)) as [string, Entry[]][] | null;
       const entries = res?.[0]?.[1] ?? [];
       if (entries.length === 0) { from = '>'; continue; }
       const rows = entries.filter((e): e is [string, string[]] => e[1] !== null).map(([id, kv]) => {
         const f = Object.fromEntries(kv.flatMap((v, i) => (i % 2 ? [] : [[v, kv[i + 1]]])));
         return { id, code: f.code ?? '', at: new Date(Number(f.ts)).toISOString(), ua: f.ua ?? '' };
       });
       // One statement: insert the raw clicks, then count ONLY the rows really inserted.
       // A replayed entry hits ON CONFLICT, is not RETURNed, and is never counted twice.
       await prisma.$executeRaw`
         WITH ins AS (
           INSERT INTO click (event_id, clicked_at, code, user_agent)
           SELECT id, at, code, NULLIF(ua, '')
           FROM unnest(${rows.map((r) => r.id)}::text[], ${rows.map((r) => r.at)}::timestamptz[],
                       ${rows.map((r) => r.code)}::text[], ${rows.map((r) => r.ua)}::text[]) AS t(id, at, code, ua)
           ON CONFLICT DO NOTHING
           RETURNING code, clicked_at)
         INSERT INTO click_daily (code, day, clicks)
         SELECT code, (clicked_at AT TIME ZONE ${REPORT_TZ}::text)::date, count(*) FROM ins GROUP BY 1, 2
         ON CONFLICT (code, day) DO UPDATE SET clicks = click_daily.clicks + EXCLUDED.clicks`;
       await redis.xack('clicks', GROUP, ...entries.map(([id]) => id));   // ack only after the commit
     }
   }
   main();

9. Clean up, and read the stats

   Run the purge in a loop until it updates 0 rows. Dropping a partition removes a month of clicks almost instantly and leaves nothing for vacuum (Postgres ops).

   SQLCopy

   -- Nightly, in a loop until it updates 0 rows: forget the URL of links that
   -- expired over 30 days ago, 5,000 rows per transaction. The code row stays,
   -- so the code is never handed out again to a different page.
   UPDATE link SET long_url = NULL
   WHERE id IN (
     SELECT id FROM link
     WHERE long_url IS NOT NULL
       AND expires_at < now() - interval '30 days'
     ORDER BY expires_at
     LIMIT 5000
   );
   
   -- Monthly: raw clicks older than 90 days go; click_daily keeps the totals.
   SET lock_timeout = '3s';                            -- give up rather than block redirects
   ALTER TABLE click DETACH PARTITION click_2026_07;   -- brief strong lock: run at night
   DROP TABLE click_2026_07;
   
   -- The stats endpoint reads only the small daily table
   SELECT day, clicks
   FROM click_daily
   WHERE code = 'aZ3k9Qx'
     AND day >= current_date - 30                     -- the last 30 days
   ORDER BY day;

10. Try it

    With the API on port 3000, create a link and follow it. The output below is from a test run.

    TerminalCopy

    curl -s -X POST localhost:3000/v1/links -H 'content-type: application/json' \
      -H 'x-api-key: dev-key' \
      -d '{"longUrl":"https://shop.example.com/offers/festival?utm_source=sms","expiresAt":"2026-10-20T18:00:00Z"}'
    
    curl -si localhost:3000/SLz0YAz | head -4
    redis-cli -p 6379 TTL link:SLz0YAz        # cache warmed on create

    OutputCopy

    {"code":"SLz0YAz","shortUrl":"https://s.example.com/SLz0YAz"}
    HTTP/1.1 302 Found
    X-Powered-By: Express
    Cache-Control: private, max-age=90
    Location: https://shop.example.com/offers/festival?utm_source=sms
    (integer) 86752

    On the stream Redis, XINFO GROUPS clicks shows a lag field: the number of clicks not yet read by the worker. That is the number to alert on.