149 lines
4.3 KiB
Markdown
149 lines
4.3 KiB
Markdown
# ADR: Change GAME_ROUNDS from strings to numbers
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Date
|
|
|
|
2026-04-28
|
|
|
|
## Context
|
|
|
|
`GAME_ROUNDS` in `packages/shared/src/constants.ts` was typed as `["3", "10"] as const`, making `GameRounds` a string union (`"3" | "10"`). This meant `gameService.ts` had to cast the value with `Number(request.rounds)` deep in business logic — a type conversion happening far from the boundary where data enters the system. The type system was lying: `rounds` was described as a string everywhere but used as a number where it mattered.
|
|
|
|
## Decision
|
|
|
|
Change `GAME_ROUNDS` to `[3, 10] as const` and update the Zod schema to use `z.literal(GAME_ROUNDS)` instead of `z.enum(GAME_ROUNDS)`. The single source of truth remains `constants.ts` — adding a new round count (e.g. `20`) requires only editing that file.
|
|
|
|
## Options considered
|
|
|
|
### Option A — Numbers everywhere ✅
|
|
|
|
Change `GAME_ROUNDS` to `[3, 10] as const`. Use `z.literal(GAME_ROUNDS)` in the schema. Update the frontend component state and `SettingGroup` props. Drop `Number()` cast in the service.
|
|
|
|
Chosen because: JSON carries numbers natively, both ends of the wire are owned by this codebase, and type conversions belong at the boundary — not inside business logic.
|
|
|
|
### Option B — Keep strings, accept the cast
|
|
|
|
Leave `GAME_ROUNDS` as `["3", "10"]`. The `Number()` cast stays in `gameService.ts`.
|
|
|
|
Rejected because: it pushes type conversion into business logic and makes the inferred `GameRequest` type misleading. The cast has to live somewhere — the schema boundary is the right place.
|
|
|
|
### Option C — Coerce at the schema boundary
|
|
|
|
Keep `GAME_ROUNDS` as numbers but use `z.coerce.number().pipe(z.literal(GAME_ROUNDS))` so the frontend can keep sending strings.
|
|
|
|
Rejected because: coercion is for untrusted or uncontrolled inputs (form fields, query params, third-party clients). We control both ends of the wire. Coercing a self-inflicted type mismatch is treating a wound we gave ourselves.
|
|
|
|
## Consequences
|
|
|
|
- `GameRounds` is now `3 | 10` instead of `"3" | "10"`
|
|
- `Number(request.rounds)` cast removed from `gameService.ts`
|
|
- `SettingGroup` in `GameSetup.tsx` now accepts `string | number` options
|
|
- `useState<string>` for rounds changed to `useState<number>`
|
|
- Adding a new round count requires only editing `GAME_ROUNDS` in `constants.ts`
|
|
- `z.enum` cannot be used for number literals — `z.literal` must be used instead (this is a Zod constraint, not a project convention)
|
|
|
|
## Affected files
|
|
|
|
- `packages/shared/src/constants.ts`
|
|
- `packages/shared/src/schemas/game.ts`
|
|
- `apps/api/src/services/gameService.ts`
|
|
- `apps/api/src/services/gameService.test.ts`
|
|
- `apps/api/src/controllers/gameController.test.ts`
|
|
- `apps/web/src/components/game/GameSetup.tsx`
|
|
|
|
## References
|
|
|
|
- [Zod literals](https://zod.dev/?id=literals)
|
|
|
|
---
|
|
|
|
## Setup guide / implementation notes
|
|
|
|
1. In `packages/shared/src/constants.ts`, change:
|
|
|
|
```ts
|
|
export const GAME_ROUNDS = ["3", "10"] as const;
|
|
```
|
|
|
|
to:
|
|
|
|
```ts
|
|
export const GAME_ROUNDS = [3, 10] as const;
|
|
```
|
|
|
|
2. In `packages/shared/src/schemas/game.ts`, change:
|
|
|
|
```ts
|
|
rounds: z.enum(GAME_ROUNDS),
|
|
```
|
|
|
|
to:
|
|
|
|
```ts
|
|
rounds: z.literal(GAME_ROUNDS),
|
|
```
|
|
|
|
3. In `apps/api/src/services/gameService.ts`, change:
|
|
|
|
```ts
|
|
Number(request.rounds),
|
|
```
|
|
|
|
to:
|
|
|
|
```ts
|
|
request.rounds,
|
|
```
|
|
|
|
4. In `apps/api/src/services/gameService.test.ts`, change:
|
|
|
|
```ts
|
|
rounds: "3",
|
|
```
|
|
|
|
to:
|
|
|
|
```ts
|
|
rounds: 3,
|
|
```
|
|
|
|
5. In `apps/api/src/controllers/gameController.test.ts`, change:
|
|
|
|
```ts
|
|
rounds: "3",
|
|
```
|
|
|
|
to:
|
|
|
|
```ts
|
|
rounds: 3,
|
|
```
|
|
|
|
Also add a pinning test before the refactor:
|
|
|
|
```ts
|
|
it("returns 400 when rounds has an invalid value", async () => {
|
|
const res = await request(app)
|
|
.post("/api/v1/game/start")
|
|
.send({ ...validBody, rounds: "invalid" });
|
|
expect(res.status).toBe(400);
|
|
expect(res.body.success).toBe(false);
|
|
});
|
|
```
|
|
|
|
6. In `apps/web/src/components/game/GameSetup.tsx`:
|
|
- Update `SettingGroup` props to accept `string | number`:
|
|
|
|
```ts
|
|
type SettingGroupProps = {
|
|
options: readonly (string | number)[];
|
|
selected: string | number;
|
|
onSelect: (value: string | number) => void;
|
|
};
|
|
```
|
|
|
|
- Update `LABELS` lookup to `LABELS[String(option)]`
|
|
- Change rounds state from `useState<string>` to `useState<number>`
|